Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Plumbing Commands

git ls-files --stage command

Reference for git ls-files --stage: see the mode, blob ID and stage number of every index entry, spot merge-conflict stages 1, 2 and 3, and compare with ls-tree.

git ls-files --stage (or -s) lists the contents of the index with full detail: file mode, blob object ID, stage number and path. The index is the staging area, so this shows exactly what git commit would record, not what is in your working directory.

The stage number is the key extra. Normal entries have stage 0. During a conflicted merge the index holds up to three entries for each conflicted path: stage 1 is the common ancestor, stage 2 is "ours" and stage 3 is "theirs". This command is the clearest window into that state.

Terminal
git ls-files --stage
git ls-files -s -- src/
git ls-files -u

Try it

Bash Modes and blob IDs in the index

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 The three stages of 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

Terminal
git ls-files --stage [-z] [--abbrev[=<n>]] [--debug] [--] [<pathspec>...]
git ls-files --unmerged [<pathspec>...]

Each line: <mode> SP <blob-id> SP <stage> TAB <path>.

Name Description
-s, --stage Show mode, object ID and stage for all entries.
-u, --unmerged Show only entries with a stage other than 0 (implies --stage).
-z NUL-terminated output with unquoted names.
--abbrev[=<n>] Shorten the object IDs.
--debug Add timestamps, size and device information per entry.
--eol Show line-ending information for the index and working tree.
<pathspec>... Limit the output; see Pathspec.

Returns: one line per index entry.

Mode Meaning
100644 Regular file
100755 Executable file
120000 Symbolic link
160000 Gitlink (a submodule's commit)
Stage Meaning
0 Normal, merged entry
1 Common ancestor (base)
2 "Ours" (the current branch)
3 "Theirs" (the branch being merged)

Usage notes

  • A conflicted path is missing from stage 0. git commit refuses to run until you git add or git rm the path, which replaces the three entries with one stage-0 entry.
  • Missing stages tell the story. Only stages 2 and 3: both sides added the file. Stages 1 and 3: we deleted it. Stages 1 and 2: they deleted it.
  • Read a stage directly: git show :2:path prints "ours", :3:path "theirs". The :N:path form is explained in rev:path syntax.
  • The index is a flat list. There are no tree entries; directories appear only as part of the path. Compare with git ls-tree, which reads a committed tree.
  • Equal blob IDs mean equal content. That is a cheap way to check whether two paths are identical, or whether an entry changed relative to a commit.
  • Submodules show as mode 160000 with the commit ID that the superproject records.
  • Sparse index: in a sparse checkout, a directory outside the cone may appear as a single entry (a sparse directory); use git ls-files --sparse to see it.