# git add: Usage, Options & Common CI Errors

> git add stages changes for the next commit. Reference for -A, -p, --update, and the pathspec and ignored-file errors that bite automated commits in CI.

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

git add moves changes from your working tree into the staging area (the index).

Staging is how you choose exactly what goes into the next commit. The flags control scope; pathspecs control precision.

## What it does

git add records the current content of files into the index so they will be part of the next commit. It does not commit anything by itself.

## Common usage

```Terminal
git add file.txt
git add .            # everything under the current directory
git add -A           # all changes incl. deletions, whole tree
git add -u           # only already-tracked files
git add -p           # interactively stage hunks
```

## Options

| Flag | What it does |
| --- | --- |
| -A / --all | Stage adds, modifications, and deletions everywhere |
| -u / --update | Stage changes to tracked files only |
| -p / --patch | Choose hunks interactively |
| -f / --force | Add files that .gitignore would skip |
| -n / --dry-run | Show what would be added |

## Common errors in CI

fatal: pathspec 'X' did not match any files - the path does not exist or is ignored. Check the working directory and whether .gitignore excludes it; use git add -f to override an ignore, or git status to see the real paths.

## 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 add: Usage, Options & Common CI Errors?

Staging is how you choose exactly what goes into the next commit. The flags control scope; pathspecs control precision.

### What it does?

git add records the current content of files into the index so they will be part of the next commit. It does not commit anything by itself.

### Common errors in CI?

fatal: pathspec 'X' did not match any files - the path does not exist or is ignored. Check the working directory and whether .gitignore excludes it; use git add -f to override an ignore, or git status to see the real paths.

---

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