git ls-files

Tracked, ignored, untracked — slice it however.

🎯 What & why

git ls-files prints files Git knows about, sliced by state: cached, modified, deleted, untracked, ignored, unmerged. The Swiss army knife for scripting against the index.

🧠 Mental model

It is a query against the index (and optionally the working tree and exclude rules). Each flag toggles a category; combine with --exclude-standard to honor .gitignore.

🛠️ Synopsis

git ls-files [-c|-d|-m|-o|-i|-s|-u] [--exclude-standard] [--with-tree=<tree>] [-z] [<path>...]

🎚️ Switches & options

Flag	What it does
`-c, --cached`	Show files in the index (the default)
`-d, --deleted`	Show files deleted from the working tree but still in the index
`-m, --modified`	Show files modified in the working tree vs the index
`-o, --others`	Show untracked files (combine with --exclude-standard)
`-i, --ignored`	Show ignored files (requires an exclude flag like --exclude-standard)
`-s, --stage`	Show <mode> <sha> <stage>\t<path> — gold for scripting
`-u, --unmerged`	Show files with merge conflicts (stage > 0)
`--exclude-standard`	Apply .gitignore, .git/info/exclude, and core.excludesFile
`--with-tree=<tree>`	Pretend the index matches <tree> for the query
`-z`	NUL-terminate output for safe piping into xargs -0

💡 Use cases

Enumerate tracked files for a linter or formatter to chew through
Find merge-conflicted paths programmatically with -u
Script over file modes/SHAs without parsing git ls-tree
List untracked-but-not-ignored files in CI to fail builds on stray artifacts

🧪 Examples

All tracked files

git ls-files

Untracked, ignoring .gitignore'd noise

git ls-files -o --exclude-standard

Mode + SHA + path (script-friendly)

git ls-files -s

Pipe safely to a tool

git ls-files -z | xargs -0 wc -l

🎓 Recommendations

Always pair -o/-i with --exclude-standard unless you really want raw 'others' including ignored junk
Use -z + xargs -0 in any script that might encounter spaces or newlines in filenames
Reach for -s when you need blob SHAs without the cost of git ls-tree HEAD

🪤 Common pitfalls

-i without an exclude flag is an error in modern Git; always combine with --exclude-standard
-c is the default, so plain 'git ls-files' won't show untracked files — beginners often miss this

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.