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

> git ls-files lists files in the index. Reference for listing tracked, ignored, or modified files to drive lint, format, and change-aware CI steps.

Source: https://latchkey.dev/learn/command-reference/git-ls-files-command-reference  
Updated: 2026-06-26

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
```

> `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 ls-files Command: List Tracked Files in CI?

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.

### 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.

---

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