git ls-files Command: List Tracked Files in CI

By Kaveh Alemi·Latchkey

git ls-files prints the files Git knows about in the index, with filters for state.

When a CI step needs to operate on exactly the files Git tracks (and skip vendored or ignored ones), ls-files is faster and safer than find because it already respects .gitignore.

Common flags

(default) - list cached (tracked) files
-m / --modified - list files modified in the working tree
-o --exclude-standard - list untracked files honoring .gitignore
-d / --deleted - list deleted files
-z - NUL-separate output for safe handling of unusual filenames
-- <pathspec> - restrict to matching paths

Example

shell

# Lint only tracked shell scripts, NUL-safe
git ls-files -z -- '*.sh' | xargs -0 -r shellcheck

In CI

ls-files is the reliable way to enumerate tracked files for linters and formatters because it ignores build artifacts and gitignored paths automatically. Pair -z with xargs -0 so filenames with spaces do not break the pipeline.

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

Key takeaways

git ls-files lists only tracked files, automatically skipping ignored artifacts.
Use -z with xargs -0 to handle unusual filenames safely.
It is a cleaner input for linters than find, which does not know about .gitignore.

Frequently asked questions

git ls-files Command: List Tracked Files in CI?