# git diff: Usage, Options & Common CI Errors

> git diff shows changes between commits, the index, and the working tree. Reference for --staged, --name-only, --exit-code, and using it to gate CI steps.

Source: https://latchkey.dev/learn/command-reference/git-diff  
Updated: 2026-06-25

git diff shows exactly what changed between any two states of your repository.

Diff is the core inspection tool. --exit-code and --name-only make it a precise gate in pipelines.

## What it does

git diff compares two sources - working tree vs index, index vs HEAD, or any two commits/branches - and prints the line-level differences.

## Common usage

```Terminal
git diff                      # working tree vs index
git diff --staged             # index vs HEAD (a.k.a. --cached)
git diff main..feature
git diff --name-only HEAD~1
git diff --quiet || echo "changes present"
```

## Options

| Flag | What it does |
| --- | --- |
| --staged / --cached | Compare the index against HEAD |
| --name-only | List changed file names only |
| --name-status | Names plus add/modify/delete status |
| --stat | Summary of changes per file |
| --exit-code / --quiet | Exit non-zero if differences exist |

## Common errors in CI

A frequent gotcha: git diff alone ignores staged changes - use --staged to compare the index. With --exit-code, the command returns 1 when there are differences, which scripts may misread as failure; handle it deliberately (e.g. as a "needs formatting" signal).

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git diff: Usage, Options & Common CI Errors?

Diff is the core inspection tool. --exit-code and --name-only make it a precise gate in pipelines.

### What it does?

git diff compares two sources - working tree vs index, index vs HEAD, or any two commits/branches - and prints the line-level differences.

### Common errors in CI?

A frequent gotcha: git diff alone ignores staged changes - use --staged to compare the index. With --exit-code, the command returns 1 when there are differences, which scripts may misread as failure; handle it deliberately (e.g. as a "needs formatting" signal).

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt