[1.8.0] git checkout refs/heads/foo checks out branch foo

Proposal:

'git checkout refs/heads/foo' (or 'git checkout heads/foo' for that
matter) does not check out the branch, but instead detaches HEAD at
foo. This is quite counter-intuitive (at least to me) and the same
functionality can be achieved by using e.g. foo~0. Change the behavior
so that the branch is actually checked out. This also applies to
e.g. 'git rebase master refs/heads/topic', which currently rebases a
detached HEAD. There are probably other examples as well that I'm not
aware of.


Risks:

Existing scripts may depend on the current behavior. It seems unlikely
that many users depend on it. Most likely, they use foo~0 or foo^0
instead.


Migration plan:

Make 'git checkout refs/head/foo' emit a warning in the next 1.7.x
explaining that its semantics will change in 1.8.0. Then change the
behavior in 1.8.0 and remove the warning.

On Mon, Feb 07, 2011 at 06:01:51AM -0500, Martin von Zweigbergk wrote:

'git checkout refs/heads/foo' (or 'git checkout heads/foo' for that
matter) does not check out the branch, but instead detaches HEAD at
foo. This is quite counter-intuitive (at least to me) and the same
functionality can be achieved by using e.g. foo~0. Change the behavior
so that the branch is actually checked out. This also applies to
e.g. 'git rebase master refs/heads/topic', which currently rebases a
detached HEAD. There are probably other examples as well that I'm not
aware of.

I have seen that behavior claimed as intentional, but I agree it is
unintuitive. In most other places referring to a ref by a short name or
a fully qualified name is equivalent (except with respect to
disambiguating short names, of course).

Existing scripts may depend on the current behavior. It seems unlikely
that many users depend on it. Most likely, they use foo~0 or foo^0
instead.

As cool and clever as the foo^0 behavior is once you understand it, I
think it is a horribly confusing thing for non-experts. As part of this
proposal, should we perhaps offer "git checkout --detach" as the
easy-on-the-eyes way of intentionally detaching?

-Peff

Hallo Martin,

On Mon, Feb 07, 2011 at 06:01:51AM -0500, Martin von Zweigbergk wrote:

Proposal:

'git checkout refs/heads/foo' (or 'git checkout heads/foo' for that
matter) does not check out the branch, but instead detaches HEAD at
foo. This is quite counter-intuitive (at least to me) and the same
functionality can be achieved by using e.g. foo~0. Change the behavior
so that the branch is actually checked out. This also applies to
e.g. 'git rebase master refs/heads/topic', which currently rebases a
detached HEAD. There are probably other examples as well that I'm not
aware of.

Just to clarify: You are not proposing that 'git checkout origin/master'
would also not checkout to a detached head, right? Because that is a
feature I am using frequently to test branches that have been pushed by
another developer to a remote server. If that would create a new local
branch that would be confusing.

Cheers Heiko

Heya,

On Mon, Feb 7, 2011 at 21:59, Jeff King [off-list ref] wrote:

As cool and clever as the foo^0 behavior is once you understand it, I
think it is a horribly confusing thing for non-experts. As part of this
proposal, should we perhaps offer "git checkout --detach" as the
easy-on-the-eyes way of intentionally detaching?

Now _that_ is an excellent usability improvement, assuming we want to
encourage detaching HEAD... do we?

-- 
Cheers,

Sverre Rabbelier

Sverre Rabbelier wrote:

Now _that_ is an excellent usability improvement, assuming we want to
encourage detaching HEAD... do we?

Yes.

-- 8<
Subject: commit: document --detach synonym for "git checkout foo^{commit}"

For example, one might use this when making a temporary merge to test
that two topics work well together.

This patch just documents the option.  It is not meant for application
without an implementation and tests for the option.

Suggested-by: Jeff King <redacted>
Signed-off-by: Jonathan Nieder <redacted>
---
 Documentation/git-checkout.txt |   13 +++++++++++--
 1 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 880763d..698ae6c 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -9,6 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git checkout' [-q] [-f] [-m] [<branch>]
+'git checkout' [-q] [-f] [-n] [--detach] [<commit>]
 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 'git checkout' --patch [<tree-ish>] [--] [<paths>...]

@@ -22,9 +23,10 @@ branch.
 
 'git checkout' [<branch>]::
 'git checkout' -b|-B <new_branch> [<start point>]::
+'git checkout' [--detach] [<commit>]::
 
 	This form switches branches by updating the index, working
-	tree, and HEAD to reflect the specified branch.
+	tree, and HEAD to reflect the specified branch or commit.
 +
 If `-b` is given, a new branch is created as if linkgit:git-branch[1]
 were called and then checked out; in this case you can

@@ -115,6 +117,13 @@ explicitly give a name with '-b' in such a case.
 	Create the new branch's reflog; see linkgit:git-branch[1] for
 	details.
 
+--detach::
+	Rather than checking out a branch to work on it, check out a
+	commit for inspection and discardable experiments.
+	This is the default behavior of "git checkout <commit>" when
+	<commit> is not a branch name.  See the "DETACHED HEAD" section
+	below for details.
+
 --orphan::
 	Create a new 'orphan' branch, named <new_branch>, started from
 	<start_point> and switch to it.  The first commit made on this

@@ -204,7 +213,7 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
 
 
 
-Detached HEAD
+DETACHED HEAD
 -------------
 
 It is sometimes useful to be able to 'checkout' a commit that is

-- 
1.7.4

On Mon, 7 Feb 2011, Heiko Voigt wrote:

Hallo Martin,

On Mon, Feb 07, 2011 at 06:01:51AM -0500, Martin von Zweigbergk wrote:

quoted

Proposal:

'git checkout refs/heads/foo' (or 'git checkout heads/foo' for that
matter) does not check out the branch, but instead detaches HEAD at
foo. This is quite counter-intuitive (at least to me) and the same
functionality can be achieved by using e.g. foo~0. Change the behavior
so that the branch is actually checked out. This also applies to
e.g. 'git rebase master refs/heads/topic', which currently rebases a
detached HEAD. There are probably other examples as well that I'm not
aware of.

Just to clarify: You are not proposing that 'git checkout origin/master'
would also not checkout to a detached head, right? Because that is a
feature I am using frequently to test branches that have been pushed by
another developer to a remote server. If that would create a new local
branch that would be confusing.

Nope, I'm not proposing that. I wouldn't want that either.

/Martin