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

Terminal

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 tracked

Options

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.

Related guides

git status: Usage, Options & Common CI Errorsgit status shows staged, unstaged, and untracked changes plus branch state. Reference for -s, --porcelain, -b… git add: Usage, Options & Common CI Errorsgit add stages changes for the next commit. Reference for -A, -p, --update, and the pathspec and ignored-file… git update-index: Usage, Options & Common CI Errorsgit update-index edits the index directly, including assume-unchanged and skip-worktree. Reference for these… git grep: Usage, Options & Common CI Errorsgit grep searches tracked file contents fast, respecting the index and revisions. Reference for -n, -l, -i, -…