What exactly is the "stage number" in git revisions

user_491605 0
Viewed 32

In the git revisions documentation it says:

[:], e.g. :0:README, :README A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path, names a blob object in the index at the given path. A missing stage number (and the colon that follows it) names a stage 0 entry. During a merge, stage 1 is the common ancestor, stage 2 is the target branch’s version (typically the current branch), and stage 3 is the version from the branch which is being merged.

To me this does not clarify what stage number :0, :1, :2 and :3 mean. The documentation mentions the case, when a merge is being done. But it does not mention what they mean when no merge is in progress.

Trying it out, it seems to me ":0" is the currently staged index. Is that correct?

  • Does the meaning of ":0" etc. change when a merge is in progress?
  • What do the number mean when no merge is currently in progress?
git
1 Answers

These numbers all represent "slots" in the index / staging area. There are two situations to distinguish:

Merge conflict

When paused during a merge conflict, when Git rewrites your conflicted files for you, if you ask about a conflicted file, :0: is empty; that is why, after you edit the working tree version you have to add it, to get the fixed version into the index so that it goes into the merge commit.

Meanwhile:

  • :1: is the state of this file in the LCA (the merge-base)
  • :2: is the ours version
  • :3: is the theirs version

So, assuming you know what a merge is, you can conclude from this that Git attempted to apply both the diff :1:-:2: and the diff :1:-:3: to :1: to form the new file to go into the merge commit, and couldn't do it without human assistance (hence the "conflict").

Otherwise

Otherwise, :0: is the index version of a file and the others are all empty (and trying to fetch one will result in an error message).

user_3419940
Related