git ls-files: Usage, Options & Common CI Errors
git ls-files shows which files are in the index - and, with flags, which are untracked or modified.
ls-files is plumbing for "what does Git see here". It is the precise way to enumerate tracked or untracked paths.
What it does
git ls-files prints the names of files registered in the index. Flags expand it to show untracked, modified, ignored, or stage-conflicted files.
Common usage
git ls-files # all tracked files
git ls-files --others --exclude-standard # untracked (respecting .gitignore)
git ls-files --modified # changed tracked files
git ls-files --error-unmatch path # exit non-zero if not trackedOptions
| Flag | What it does |
|---|---|
| --others / -o | Show untracked files |
| --exclude-standard | Apply .gitignore and friends |
| --modified / -m | Show modified tracked files |
| --cached / -c | Show staged files (default) |
| --error-unmatch | Error if a given path is not tracked |
Common errors in CI
error: pathspec 'X' did not match any file(s) known to git (with --error-unmatch) is the intended signal that a path is not tracked - useful as a guard. Note --others alone includes ignored files; add --exclude-standard to honor .gitignore.
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.
- 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