/incremental-build

name: incremental-build
description: "Fix MSBuild incremental/no-op builds: 'nothing changed but it rebuilds anyway'. USE FOR: targets re-executing on subsequent builds, missing Inputs/Outputs or FileWrites, volatile output paths, untracked writes, glob changes, Visual Studio Fast Up-to-Date Check (FUTDC); 'Building target completely' vs 'Skipping target' in binlog. DO NOT USE FOR: within-build duplicates (find-repeated-work-within-one-build), first-build slowness (build-perf-baseline), parallelism (build-parallelism), slow evaluation (eval-performance), non-MSBuild systems."
license: MIT

Required diagnosis output

For every diagnose or explain request, the final answer must explicitly cover all of these points, even when the immediate cause is simply missing `Inputs`/`Outputs`:

• the target and exact root-cause evidence;
• the actual input/output timestamp comparison;
• missing, deleted, cleaned, or rewritten outputs;
• complete inputs, including dynamic or volatile inputs;
• evaluated input/output paths and one-to-one mapping when item lists are batched;
• two identical no-change builds and the expected second-build skip/out-of-date evidence.

Do not edit unless the user asks for a fix. If a check cannot be run, label it as an unverified check rather than omitting it or claiming success. When `Inputs` or `Outputs` are absent, report timestamp comparison or one-to-one mapping as **not applicable — the incremental mechanism is not engaged**, not as an unverified comparison.

How MSBuild Incremental Build Works

MSBuild's incremental build mechanism allows targets to be skipped when their outputs are already up to date, dramatically reducing build times on subsequent runs.

• **Targets with `Inputs` and `Outputs` attributes**: MSBuild compares the timestamps of all files listed in `Inputs` against all files listed in `Outputs`. If every output file is newer than every input file, the target is skipped entirely.
• **Without `Inputs`/`Outputs`**: The target runs every time the build is invoked. This is the default behavior and the most common cause of slow incremental builds.
• **Timestamp-based comparison**: MSBuild uses file system timestamps (last write time) to determine staleness. It does not use content hashes. This means touching a file (updating its timestamp without changing content) will trigger a rebuild.

<!-- This target is incremental: skipped if Output is newer than all Inputs -->
<Target Name="Transform"
        Inputs="@(TransformFiles)"
        Outputs="@(TransformFiles->'$(OutputPath)%(Filename).out')">
  <!-- work here -->
</Target>

<!-- This target always runs because it has no Inputs/Outputs -->
<Target Name="PrintMessage">
  <Message Text="This runs every build" />
</Target>

Why Incremental Builds Break (Top Causes)

1. **Missing Inputs/Outputs on custom targets** — Without both attributes, the target always runs. This is the single most common cause of unnecessary rebuilds.

2. **Volatile properties in Outputs path** — If the output path includes something that changes between builds (e.g., a timestamp, build number, or random GUID), MSBuild will never find the previous output and will always rebuild.

3. **File writes outside of tracked Outputs** — If a target writes files that aren't listed in its `Outputs`, MSBuild doesn't know about them. The target may be skipped (because its declared outputs are up to date), but downstream targets may still be triggered.

4. **Missing FileWrites registration** — Files created during the build but not registered in the `FileWrites` item group won't be cleaned by `dotnet clean`. Over time, stale files can confuse incremental checks.

5. **Glob changes** — When you add or remove source files, the item set (e.g., `@(Compile)`) changes. Since these items feed into `Inputs`, the set of inputs changes and triggers a rebuild. This is expected behavior but can be surprising.

6. **Property changes** — Properties that feed into `Inputs` or `Outputs` paths (e.g., `$(Configuration)`, `$(TargetFramework)`) will cause rebuilds when changed. Switching between Debug and Release is a full rebuild by design.

7. **NuGet package updates** — Changing a package version updates `project.assets.json` and potentially many resolved assembly paths. This changes the inputs to `ResolveAssemblyReferences` and `CoreCompile`, triggering a rebuild.

8. **Build server VBCSCompiler cache invalidation** — The Roslyn compiler server (`VBCSCompiler`) caches compilation state. If the server is recycled (timeout, crash, or manual kill), the next build may be slower even though MSBuild's incremental checks pass, because the compiler must repopulate its in-memory caches.

Diagnosing "Why Did This Rebuild?"

Use binary logs (binlogs) to understand exactly why targets ran instead of being skipped.

Before recommending a fix, report this compact checklist for each target that reran:

1. **Actual timestamp comparison** — name the newest resolved input and oldest resolved output, with their last-write times, and state which input is newer. 2. **Output existence** — confirm every declared output exists before the second build and is not deleted, cleaned, or rewritten by another target. 3. **Complete inputs** — verify `Inputs` includes every file that should invalidate the output, including volatile or generated dependencies. If a producer touches an input on every build, check whether its content changes. Fix unnecessary rewrites in the producer (for example, write only when content changes); if relevant content really changes, the dependent target must rerun. Exclude a file only with evidence that it cannot affect the output, never just because it changes often. 4. **Stable resolved paths** — expand properties and relative paths for both builds; outputs must resolve to the same location and must not contain timestamps, build numbers, or GUIDs. 5. **One-to-one mapping when batched** — for item transforms, map each input identity to its exp