Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Revisions and Pathspecs

Naming files: rev:path and :N:path

Reference for Git colon syntax: HEAD:file for a blob in a commit, :file for the index, :2:file for a conflict stage, plus ./relative paths and common uses.

A colon joins a revision and a path into the name of one object inside that commit. HEAD:src/app.js is the file src/app.js as it was at HEAD. If the path is a directory, the name refers to a tree instead of a blob. This is how you read an old version of a file without checking anything out.

With nothing before the colon, the name points into the index. :file is the staged version of a file, and during a conflict the index holds up to three versions at stages 1, 2 and 3, written :1:file, :2:file and :3:file. These names work anywhere a command expects an object: git show, git cat-file, git diff, git checkout-index and git merge-file.

Terminal
git show HEAD~2:README.md
git show :README.md
git show :2:README.md

Try it

Bash Old versions and the staged version of a file

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 conflicted file

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
<rev>:<path>      # blob or tree at <path> in the tree of <rev>
<rev>:./<path>    # <path> relative to the current directory
:<path>           # index entry at stage 0
:<n>:<path>       # index entry at stage n (0 to 3)
Part Meaning
<rev> Any revision that peels to a tree: a commit, tag, branch, HEAD~2, a tree ID.
<path> Slash-separated path from the repository root, without a leading slash.
./ or ../ after the colon Resolve the path from the current directory instead of the root.
:0:, :1:, :2:, :3: Stage 0 is the normal, merged entry. Stage 1 is the common ancestor, 2 is "ours" (the branch you are on), 3 is "theirs" (the branch being merged).

Errors and edge cases: a missing path gives fatal: path 'x' does not exist in 'HEAD', or ... exists on disk, but not in 'HEAD' when the file only exists in your working tree. During a rebase the meaning of stages 2 and 3 is swapped compared with a merge, because the branch being replayed is "theirs".

Usage notes

  • Reading old files: git show v1.0:config/app.php > /tmp/old.php writes the old contents without touching your tree. Use git restore --source=v1.0 -- config/app.php when you do want it back in place.
  • Paths are from the repository root unless you start them with ./ or ../. A bare HEAD:README.md from a subdirectory still looks at the top level.
  • A directory name gives a tree. git cat-file -t HEAD:docs prints tree, and git ls-tree HEAD:docs lists it. The empty path HEAD: is the root tree.
  • Compare two versions of one file with git diff HEAD~3:a.txt HEAD:a.txt. Both sides may be blob names, even with different paths, which is a handy way to diff a renamed file by hand.
  • Index names are for conflicts. In a conflict, git diff :2:file :3:file compares "ours" and "theirs" directly; git checkout --ours -- file and --theirs use the same stages.
  • Stage numbers appear in the plumbing output. git ls-files -u and git ls-files --stage show stage 1, 2 and 3 entries for unmerged paths.
  • Colons in :/text are different. :/fix typo is a search for a commit message, not a path; see :/text and ^{/text}.
  • Shell quoting: HEAD:path with spaces needs quotes, and ! or ^ in a path may need escaping in your shell.