git add: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

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

Frequently asked questions

git add: Usage, Options & Common CI Errors?