> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nrwl/nx/llms.txt
> Use this file to discover all available pages before exploring further.

# Affected Builds

> Run tasks only for projects affected by a code change. Nx uses the project graph and git history to determine the minimal set of work required.

As your workspace grows, running all tasks for all projects on every PR becomes too slow. The `nx affected` command solves this by:

* Determining the minimum set of projects affected by your change
* Running tasks only on those projects

This reduces CI compute significantly, and the benefit compounds when paired with [remote caching](/features/cache-task-results) and [distributed task execution](/features/ci-orchestration).

## How Nx determines affected projects

Nx combines two sources of information:

1. **Git diff** — Nx checks which files changed between the base and head commits
2. **Project graph** — Nx maps those files to projects, then traverses the graph to find all downstream dependents

For example, if you change a shared utility library, every application and library that depends on it (directly or transitively) is marked as affected.

## Run affected tasks

Replace `run-many` with `affected` in your commands:

```bash theme={null}
# Run tests only for affected projects
npx nx affected -t test

# Run build and lint for affected projects
npx nx affected -t build lint
```

You can also visualize which projects are affected:

```bash theme={null}
npx nx graph --affected
```

## Control the comparison range with --base and --head

By default, Nx compares against your `main` branch. You can override this:

```bash theme={null}
# Compare a PR branch to main
npx nx affected -t build --base=origin/main --head=$PR_BRANCH_NAME

# Re-run what was affected by the last commit on main
npx nx affected -t build --base=origin/main~1 --head=origin/main
```

You can also set these as environment variables:

```bash theme={null}
NX_BASE=origin/main~1
NX_HEAD=origin/main
```

<Tip>
  The recommended CI approach is to set `--base` to the latest successful commit on `main`. This ensures all changes since the last successful CI run are accounted for, even if multiple commits landed between runs.
</Tip>

## Use affected in CI

Here is a GitHub Actions example using `nrwl/nx-set-shas` to automatically resolve the correct base SHA:

```yaml theme={null}
# .github/workflows/ci.yml
name: CI

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          filter: tree:0

      - uses: nrwl/nx-set-shas@v4

      - run: npm ci

      - run: npx nx affected -t lint test build
```

The `nrwl/nx-set-shas` action sets `NX_BASE` to the last successful CI commit on the base branch, so only work that has not already passed is re-run.

## Configure smart dependency update detection

By default, Nx marks **all** projects as affected when the package manager lock file changes. To opt into more precise behavior that only marks projects depending on the updated packages:

```json theme={null}
// nx.json
{
  "pluginsConfig": {
    "@nx/js": {
      "projectsAffectedByDependencyUpdates": "auto"
    }
  }
}
```

The `projectsAffectedByDependencyUpdates` option accepts `"auto"`, `"all"`, or an array of project specifiers.

## Ignore files from affected detection

Nx respects two ignore files:

* `.gitignore` — any patterns listed here are excluded from affected detection
* `.nxignore` — an optional Nx-specific ignore file with the same glob syntax

## Not using git?

Pass `--files` to specify changed files explicitly:

```bash theme={null}
npx nx affected -t build --files=libs/mylib/src/index.ts
```