Seemingly inconsistent checkout behaviour

Dear People of Git,

I had some trouble getting out of a detached HEAD state using git checkout. I’ve solved it now but the behaviour of checkout when doing so leaves me a bit puzzled.

I’d expect the behaviour of the commands below to be equivalent:

   git checkout origin/main

vs

   git config checkout.defaultRemote origin
   git checkout main

But they are not; the former leaves the HEAD detached while the latter sets it to main. I failed to find an explanation in the git-checkout documentation, which seems to indicate that checkout always updates HEAD.

Could someone clarify what's going on?

A bit more elaborate transcript of what I did is below.

Thanks in advance!

Kind regards, Bart Kuster

---

# Checkout a commit to get into detached HEAD state $ git checkout aac02b81d735d5f15b3b3c61a84ccb79a8a90145 HEAD is now at aac02b8 Merge branch 'main' of https://repo into main $ git checkout origin/main HEAD is now at aac02b8 Merge branch 'main' of https://repo into main $ git status HEAD detached at aac02b8 (...) $ git config checkout.defaultRemote origin $ git checkout main On branch main (...) $ git status On branch main $

On Tue, Oct 11 2022, Bart Kuster wrote:

They're not equivalent, the documentation that describes it is the discussion of the --guess option.

I.e. these are equivalent:

	git checkout main
	git checkout --guess main

And the latter of those resolves to (in this case):

	git checkout -b main -t origin/main

The "in this case" being that it's actually (pseudocode):

	git checkout -b main -t $(find-the-only-remote-that-has-a-branch-named main)/main

And the "checkout.defaultRemote=origin" is a setting that disambiguates that "find the only" down to "origin", if you happen to have multiple such remotes.

But I'm still unclear on the "I had some trouble getting out of a detached HEAD state using git checkout" part of your question, isn't the:

	git config checkout.defaultRemote origin
	git checkout main

Exactly what you want then?

If you're trying to get a "non-detached remote tracking branch", i.e. to have this somehow checkout a branch:

	git checkout origin/main

Then there's no such thing. We treat them specially, and don't allow you to check them out as a normal branch, so when you do so you end up with a detached HEAD pointing to wherever that branch points to. IOW:

	git checkout origin/main

Is always the same as:

	git checkout origin/main^{}

Given that you have an "origin" remote, a "main" branch, it's not ambiguous, or the right config blah blah.

That's also documented somewhere, but I didn't dig up where that is...

On Tue, Oct 11 2022, Ævar Arnfjörð Bjarmason wrote:

Thanks for your quick reply! I understand the situation now.

What put me on the wrong track, is that git checkout <remote>/<branch> is not explicitly discussed in the git-checkout documentation, leading me to believe the default use case would apply to it while it does not. The last part of your explanation clarifies what's really going on. Thanks!