Introduction

If you want to list files in a local Git repository, the correct command depends on what you mean by "files". Git can show tracked files, untracked files, ignored files, or the contents of a specific commit. The most useful everyday command is git ls-files, but it is only one part of the picture.

List Tracked Files

To list files that Git currently tracks in the working tree, use:

git ls-files

This prints paths known to the index, which is usually what people want when they ask for repository files. It is fast and script-friendly because it outputs only file paths.

You can also filter by path prefix:

git ls-files src/

That is useful in larger repositories when you want only one directory subtree.

List Untracked Files

Tracked files are not the whole story. If you want files Git sees locally but has not started tracking, use:

git ls-files --others --exclude-standard

--exclude-standard matters because it applies normal ignore rules from .gitignore, global ignores, and .git/info/exclude. Without it, the output is often much noisier than expected.

List Ignored Files

Sometimes the question is really "what files exist here but Git is ignoring". That command is:

git ls-files --others --ignored --exclude-standard

This is handy when debugging why a file is not showing up in git status.

List Files From a Specific Commit

If you want the files stored in HEAD or another commit, use git ls-tree:

git ls-tree -r --name-only HEAD

That is different from git ls-files:

• 'git ls-files focuses on the index and working tree view'
• 'git ls-tree shows the tree object stored in a commit'

This distinction matters when the working tree contains staged or deleted changes that do not match the last commit.

Compare With git status

git status --short is often a better human-facing overview than git ls-files, because it includes change state along with file paths.

git status --short

Use git status when you want a work summary. Use git ls-files when you want precise file lists for scripting or inspection.

Practical Examples

List tracked files that match a pattern:

git ls-files '*.mdx'

List deleted tracked files:

git ls-files --deleted

List modified tracked files relative to the index:

git ls-files --modified

These switches are useful in automation, but they are also great for debugging strange repository state locally.

When the Command Appears to "Miss" Files

If a file is present on disk but missing from git ls-files, ask:

1. Is it untracked
2. Is it ignored
3. Am I looking for working-tree files or committed files

Those three questions usually explain the difference immediately.

Another common issue is running the command outside the repository root or inside the wrong repository when several nested projects exist on a machine.

Common Pitfalls

• Using git ls-files and expecting untracked files to appear.
• Forgetting --exclude-standard when listing untracked or ignored files.
• Confusing committed-tree listing with working-tree listing.
• Using git status output in scripts when git ls-files would be cleaner.
• Running file-list commands from the wrong repository or submodule.

Summary

• Use git ls-files to list tracked files in the local repository.
• Use git ls-files --others --exclude-standard for untracked files.
• Use git ls-tree -r --name-only HEAD for files stored in a specific commit.
• Pick the command based on whether you care about tracked, untracked, ignored, or committed files.
• When results look wrong, first check whether the file is ignored or simply untracked.