Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Inspecting History

git ls-files command

Reference for git ls-files: list tracked, modified, deleted, untracked and ignored files, show stage numbers and object IDs, and script with -z.

git ls-files prints file names from the index (the staging area) and, depending on options, compares them with the working tree. With no options it lists every tracked path. With the right flags it lists modified, deleted, untracked or ignored files, which makes it a favorite building block for scripts and for answering "what does Git know about this directory?".

It is a plumbing command: output is stable, one path per line, and paths are relative to the current directory unless you use --full-name.

Terminal
git ls-files [-c] [-d] [-m] [-o] [-i] [-s] [-u] [-k] [<options>] [--] [<pathspec>...]

Try it

Bash Tracked, modified, deleted and untracked

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Stage numbers during a conflict

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Option Description
-c, --cached Show tracked files (the default).
-d, --deleted Show tracked files that are missing from the working tree.
-m, --modified Show tracked files whose content or mode differs from the index; deleted files also appear.
-o, --others Show untracked files.
-i, --ignored With -c or -o, show only ignored files; requires an exclude option.
--exclude-standard Use .gitignore, .git/info/exclude and the global excludes file. Without an exclude option -o lists ignored files too.
-s, --stage Show <mode> <object> <stage><TAB><path>.
-u, --unmerged Like -s but only conflicted entries (stages 1, 2, 3).
-k, --killed Files that would have to be removed for a checkout to succeed.
-t Prefix each line with a status tag (H cached, M unmerged, R removed, C modified, K killed, ? other).
-v Like -t, but lowercase letters mark assume-unchanged files.
-z Separate entries with NUL and do not quote odd file names.
--eol Show the line-ending info for the index (i/) and working tree (w/).
--full-name Print paths relative to the repository root instead of the current directory.
--deduplicate Remove duplicate names (for example -m -d listing a deleted file twice).
--recurse-submodules Include files of checked-out submodules.
--format=<fmt> Custom output using %(objectname), %(path), %(stage) and similar.
-- <pathspec> Limit the listing; see pathspec.

Usage notes

  • Output lists the index, not HEAD. A file added with git add but not yet committed appears; a file removed with git rm --cached does not. To list a commit's files, use git ls-tree.
  • -m includes deleted files because a missing file is also "different"; combine with --deduplicate or use -d separately.
  • A conflicted file occurs up to three times with different stage numbers. Count unique names with sort -u.
  • Without -z, names with unusual characters are quoted in C style ("caf\303\251.txt"), unless core.quotePath is off. Scripts should always use -z.
  • On a bare repository there is no index, so the command fails.
  • git ls-files -o --exclude-standard is a quick list of files you might still want to git add; git clean -n previews what a cleanup would delete.
  • Run in a subdirectory, the command lists only that directory's content, with paths relative to it.