dotnet-affected

The tool determines which projects need to be rebuilt or retested by following these steps:

1. Discovery: It finds all .csproj, .fsproj, and .vbproj files in the repository.
2. Graph Building: It uses MSBuild to create a ProjectGraph representing project dependencies.
3. Change Detection: It runs git diff to identify changed files and maps them to their respective projects. It also detects changes to Directory.Packages.props to identify NuGet package changes.
4. Impact Analysis: It uses the ProjectGraph to find all projects transitively affected by the changed projects or packages.

For example, if Project A is a dependency of Project B, and Project A changes, dotnet-affected will mark both Project A and Project B as affected.

By default, the tool compares your current working directory against HEAD. You can specify different comparison points using the --from and --to flags (supports branch names or commit SHAs).

• Compare HEAD against working directory: dotnet affected
• Compare a specific branch against HEAD: dotnet affected --from <branch-name>
• Compare two specific branches/commits: dotnet affected --from <branch-A> --to <branch-B>

# Compares HEAD against working directory
dotnet affected

# Compares HEAD against branch chore/target-net7
dotnet affected --from chore/target-net7

# Compares main against branch chore/target-net7
dotnet affected --from chore/target-net7 --to main

Use these flags to observe the tool's behavior without generating actual output files.

Dry Running

Adding the --dry-run flag causes dotnet-affected to write its output (the content of the affected.proj file) to stdout instead of creating a file.

$ dotnet affected --dry-run

Assume Changes

Use --assume-changes <project-name> to simulate changes to a specific project. This allows you to see what would be affected if that project were modified.

$ dotnet-affected --dry-run --assume-changes dotnet-affected.Tests

To automate builds and tests for only the affected projects, dotnet-affected can output an MSBuild Traversal SDK project file. You can then run standard dotnet commands against this generated file.

1. Generate the traversal project (e.g., affected.proj): dotnet affected
2. Run tests against the generated file: dotnet test affected.proj

When using an MSBuild Project SDK obtained via NuGet, you must specify a version. You can do this in two ways:

1. Directly in the Project file: Append the version to the SDK attribute.
2. Via global.json: Omit the version from the SDK attribute and define it in a global.json file under msbuild-sdks. This is recommended for synchronizing versions across a whole solution.

Note: Since MSBuild 15.6, SDKs are automatically downloaded as NuGet packages.

<!-- Option 1: Append version to package name -->
<Project Sdk="Microsoft.Build.Traversal/2.0.12">
    ...
</Project>

<!-- Option 2: Use global.json -->
{
    "msbuild-sdks": {
        "Microsoft.Build.Traversal": "2.0.12"
    }
}

By default, dotnet-affected searches the --repository-path recursively for project files. If you want to limit discovery to only the projects included in a specific Solution file, use the --solution-path option.

Note: If your Solution file is not located at the root of your Git repository, you must still provide the --repository-path to point to the .git directory.

dotnet affected --repository-path /home/lchaia/monorepo --solution-path /home/lchaia/monorepo/my-big-project/MyBigProjectSolution.sln

You can install dotnet-affected as a .NET tool using the dotnet tool install command. While you can install it globally using the --global flag, it is recommended to use local tools to ensure all developers and CI environments share the same version.

dotnet tool install dotnet-affected

You can execute dotnet-affected directly within an MSBuild workflow by including its tasks in a .props file. This allows you to run dotnet build on a specific props file to build only the affected projects.

<Project Sdk="DotnetAffected.Tasks/3.0.0;Microsoft.Build.Traversal/3.2.0">
    <Target Name="_DotnetAffectedCheck" AfterTargets="DotnetAffectedCheck">
        <!-- Print all affected projects -->
        <Message Text="  >> %(ProjectReference.Identity)" Importance="high"/>
    </Target>
</Project>

Then run:

dotnet build ci.props

The dotnet-affected tool determines which projects in a .NET solution are affected by a set of changes (e.g., between Git commits). It can output the results to the console or generate files in specific formats like traversal, text, or json.

# Example usage (conceptual)
dotnet-affected --format json --output-dir ./artifacts --output-name my-changes