git-ls-files Tutorial

What you will learn

• Understand the core purpose of git-ls-files Tutorial
• Master the basic usage and common options of git-ls-files Tutorial
• Explains how to use git-ls-files to list tracked paths from the index and working tree.
• Understand key concepts: When it is a good fit
• Know when to use this feature and when to avoid it

Start with a problem

You're working in a Git repository and need to perform a specific task — but you're not sure which command or option is the right fit, or what this command can and cannot do.

The short version

git-ls-files is used to list tracked paths from the index and working tree.

When it is a good fit

• when you need to list tracked paths from the index and working tree
• when you want this step to be repeatable instead of ad hoc
• when you need a clearer mental model of what Git is recording or updating

Basic example

git ls-files

What to watch most closely

Plumbing commands are closer to Git internals, so check whether a safer high-level command already solves the problem.

A safer working habit

Treat it as a read-only inspection tool first, then move to write-oriented usage only when necessary.

Useful angles for understanding it

• Inspect lower-level objects and refs
• Write scripts or debug advanced issues
• Verify internal repository state

Related reading

Read it alongside git status, git log, and git show so it is easier to see how the command changes history, refs, the index, or the working tree.

What problem this command solves in a workflow

git ls-files solves the problem of "what files are tracked in the index?". It lists all file paths that Git is tracking from the index, providing a quick way to understand the repository's file tracking state.

Typical use cases

• Get a quick list of all tracked files in the repo by running git ls-files — simpler and more concise than git status.
• Process all tracked files in a script by using git ls-files to output a file list for downstream commands.
• Use git ls-files --others --ignored to see files excluded by .gitignore, useful for debugging ignore rules.

Diagram view

Index contents

Index file entriesTracking stateIgnore rules

→git ls-files

Outputs

Tracked file listUntracked filesIgnored filesStaged state

ls-files only reads index information without changing anything. It is a pure query tool for understanding file tracking state.

Special cases and boundaries

• git ls-files is a pure read-only command — it never modifies the index, working tree, or any repository content.
• By default it only shows tracked files; use --others to show untracked files, and --deleted to show files deleted from the working tree but still in the index.
• Output paths are relative to the repository root, regardless of the current working directory.
• Unlike git status, ls-files does not compare the working tree against the index — it only shows what the index contains.
• When used in scripts, prefer -z for null-delimited output to avoid parsing errors from filenames with spaces or special characters.

Try it yourself

1. Practice the git-ls-files command in a test repository and observe state changes before and after
2. Experiment with different options and compare the output differences
3. Simulate a real scenario where you would need to use this, and walk through the full process

Further reading

Keep going on the same topic:

• git log Tutorial
• git-ls-tree Tutorial
• git-merge-base Tutorial