Re: [PATCH 1/5] doc: git-checkout: clarify intro

From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Aug 29, 2025, 13:39 UTC
Message-ID: <CALnO6CBvsWZe77ireTxBoPBuHem1J3Qrn9H6GZvA-w59ytAqVw@mail.gmail.com>
In-Reply-To: <xmqqa53jqaen.fsf@gitster.g>

On Thu, Aug 28, 2025 at 7:44 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 19 quoted lines

>
> "Julia Evans" <julia@jvns.ca> writes:
>
> >> I think we've dropped the bit about the default interpretation of "git
> >> checkout <something>". Maybe
> >>
> >>     When you run `git checkout <something>`, Git tries to guess whether
> >>     `<something>` is intended to be a branch, a commit, or a set of file(s),
> >>     and then switches branches, switches commits, or restores the files.
> >>
> >>     By default, Git interprets `<something>` as a _<tree-ish>_.
> >>     [explain what choosing a tree-ish means for the user?]
> >>
> >>     [Your notes on disambiguation as before]
> >
> > Thanks, will fix. Though I don't think it's accurate that
> > Git will treat <something> as a <tree-ish> in this context, since
> > `git checkout <tree>` is not valid. Will find a different wording.
> > (I get "fatal: Cannot switch branch to a non-commit")

Interesting. A docs bug! :) AFAICT it comes from 19e5656345 (checkout.txt: document a common case that ignores ambiguation rules, 2016-09-07). I was a novice then and don't know the behavior from that period, nor did I bother to find out whether "tree-ish" matched the behavior at the time and has changed or was simply wrong from the start. Good catch.

Show 6 quoted lines

> True.  "git checkout foo" is disambiguated by seeing if 'foo' can be
> interpreted as a commit-ish, and if not, if there is a path 'foo' in
> the working tree.  Otherwise we'd get an ambiguity error.  A commit-ish
> that is nameed by giving a branch name and other commit-ish then trigger
> a bit different codepaths (the former results in checking out a branch,
> the latter detached HEAD).

Yep, makes sense.

-- 
D. Ben Knoble