Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section

From: Julia Evans <julia@jvns.ca>
Date: Aug 28, 2025, 19:59 UTC
Message-ID: <2efb789d-db2d-4dae-ae81-373bd231c3c6@app.fastmail.com>
In-Reply-To: <CALnO6CDpsgTnC95CzjOL5MuhFNAnYYSQCR-jC_n5JYLEu0BTow@mail.gmail.com>

Show 5 quoted lines

> Wishful thinking (see glossary comments): I wish we could teach them
> about "tree-ish"s here rather than stop using useful shorthands
> altogether. Of course, then we have to wonder where we can use the
> shorthand and where we must do the "spell it out (give an
> abbreviation)" dance. Hm.

What I find hard about documenting cases like this is identifying the use case for providing so much flexibility ("you can pass any tree, not just a commit!), since personally I've never passed anything to `git checkout` other than a commit.

I've been trying to think of examples of cases where it's useful to pass a tree instead of a commit. I can see that it's possible to run something like this

$ git checkout HEAD:Documentation/ git-commit.adoc

to restore `file.txt` into a different directory than it was originally. This seems cool in theory but it's hard for me to see why it's useful, which makes it hard for me to document. What I would tell a friend is "<tree-ish> 99% of the time just means "commit or something which resolves to a commit, but Git has made it more general for a reason I don't understand", but of course that's not the right thing to say in the Git documentation :)