git - How is a stash entry a child commit of HEAD commit and index's commit?

Question

Manpage of git stash says

A stash entry is represented as a commit whose tree records the state of the working directory, and its first parent is the commit at HEAD when the entry was created. The tree of the second parent records the state of the index when the entry is made, and it is made a child of the HEAD commit. The ancestry graph looks like this:

       .----W
      /    /
-----H----I

where H is the HEAD commit, I is a commit that records the state of the index, and W is a commit that records the state of the working tree.

In the example, is the stash entry represented by commit W?

What does it mean by the stash entry's commit W having two parents I and H?

Is W the result of (two-way or three-way) merging the two commits I and H?

Thanks.

Answer 1

In the example, is the stash entry represented by commit W?

Yes—or more properly, no, it's represented by commit W and commit I, but W suffices to find I. Either of W or I suffices to find H, and git stash will find all three commits automatically.

What does it mean by the stash entry's commit W having two parents I and H?

Nothing special. That just makes it easier—very very slightly easier—for git stash apply and other git stash functions to find both I and H.

Not shown in the documentation is the third commit of a stash. This third commit is optional; it is present only if you used -a / --all or -u / --include-untracked. The third commit is the third parent of W. The stash code will test to see if that third parent exists, in order to decide whether the stash is a two-commit stash or a three-commit stash.

(The third commit, if present, has the form of a root commit, as it has no parent. It's also peculiar in that it holds exactly and only files that were untracked, and maybe also ignored depending on which flag you used, without holding any of the work-tree files at all. I typically call the third commit U.)

Is W the result of (two-way or three-way) merging the two commits I and H?

No. The stash code is merely using (abusing?) the form that merge commits use, but for a different purpose: to wedge two, or sometimes three, commits into an easy-to-inspect form for the stash code to inspect. The special name refs/stash can then hold the hash ID of the W commit, from which the other commit(s) are located.

(The git stash code makes use of special temporary index files to make the W and U commits. Making the I commit is easier: it just runs git write-tree and git commit-tree directly.)