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

From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Aug 29, 2025, 13:48 UTC
Message-ID: <CALnO6CDJ72-vDYuf_9LzQ-U+Rc_em77WNO2nqNgQ-Cy=T=g3Kg@mail.gmail.com>
In-Reply-To: <2efb789d-db2d-4dae-ae81-373bd231c3c6@app.fastmail.com>

On Thu, Aug 28, 2025 at 4:00 PM Julia Evans <julia@jvns.ca> wrote:

Show 11 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.

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).

Show 13 quoted lines

> 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