On Thu, Aug 28, 2025 at 4:00 PM Julia Evans <julia@xxxxxxx> wrote:
>
> > 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.
This makes sense, and: I think some of how I learned more Git was to
read the manuals, look up things I wasn't familiar with, and then play
with them :) So in a sense my wishful thinking is about sign-posting
"here's this other nook to explore if you're curious" (knowing that
~70% or or more simply won't be).
> 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 :)
I would say that it's more general in part because it can be: the data
model allows it without any extra effort (not a jab at the
programming, which was probably not easy!). But I'm in a tangent now
and the latest version is probably fine by me. I just don't want to
lose the signposts for explorers.
--
D. Ben Knoble
