* Re: [PATCH] git-checkout.txt: improve detached HEAD documentation
2011-02-17 19:46 [PATCH] git-checkout.txt: improve detached HEAD documentation Jay Soffian
@ 2011-02-17 19:48 ` Jay Soffian
2011-02-17 20:47 ` Nicolas Pitre
2011-02-17 21:49 ` Junio C Hamano
2 siblings, 0 replies; 9+ messages in thread
From: Jay Soffian @ 2011-02-17 19:48 UTC (permalink / raw)
To: git; +Cc: Jay Soffian, Nicolas Pitre, Junio C Hamano
On Thu, Feb 17, 2011 at 2:46 PM, Jay Soffian <jaysoffian@gmail.com> wrote:
> The detached HEAD state is a source of much confusion for users
> new to git. Here we try to document it better.
>
> Reworked from http://article.gmane.org/gmane.comp.version-control.git/138440
The patch may be difficult to read, so here's the man output after
applying the patch:
DETACHED HEAD
HEAD normally refers to a named branch (e.g. "master"). Meanwhile, each
branch refers to a specific commit-id. Let's look at a repo with three
commits and with "master" checked out:
HEAD (refers to master)
v
a---b---c master (refers to c)
When a commit is created in this state, the branch is updated to the
new commit-id. Let's add a commit:
HEAD (refers to master)
v
a---b---c---d master (refers to d)
It is sometimes useful to be able to checkout a commit that is not at
the tip of any named branch, or even to create a new commit that is not
referenced by a named branch. Let's look at what happens when we
checkout commit b:
$ git checkout master^^
HEAD (refers to b)
v
a---b---c---d master (refers to d)
Notice that HEAD now refers directly to commit b. In git terminology,
this is known as having a detached HEAD. It means simply that HEAD
refers to a specific commit-id, as opposed to referring to a named
branch. Let's add a commit while HEAD is detached:
HEAD (refers to e)
v
e
/
a---b---c---d master (refers to d)
We have created a new commit, but it is referenced only by HEAD. We can
of course add yet another commit in this state:
HEAD (refers to f)
v
e---f
/
a---b---c---d master (refers to d)
In fact, we can perform all the normal git operations. But, let's look
at what happens when we then checkout master:
$ git checkout master
e---f HEAD (refers to master)
/ v
a---b---c---d master (refers to d)
It is important to realize that at this point nothing refers to commits
e and f. Eventually these commits will be deleted by the routine git
garbage collection process, unless we create a reference before that
happens. If we have not yet moved away from commit f, any of these will
create a reference to it:
$ git checkout -b foo # (1)
$ git branch foo # (2)
$ git tag foo # (3)
(1) creates a new branch "foo", which refers to f, and then updates
HEAD to refer to "foo". In other words, we'll no longer be in detached
HEAD state after (1).
(2) similarly creates a new branch "foo", which refers to f, but leaves
HEAD detached.
(3) creates a new tag "foo", which refers to f, leaving HEAD detached.
If we have moved away from commit f, then we must first recover its id
(typically by using git reflog), and then we can create a reference to
it. For example, to see the last two commits to which HEAD referred, we
can use:
$ git log -g -2 HEAD
^ permalink raw reply [flat|nested] 9+ messages in thread* Re: [PATCH] git-checkout.txt: improve detached HEAD documentation
2011-02-17 19:46 [PATCH] git-checkout.txt: improve detached HEAD documentation Jay Soffian
2011-02-17 19:48 ` Jay Soffian
@ 2011-02-17 20:47 ` Nicolas Pitre
2011-02-17 21:49 ` Junio C Hamano
2 siblings, 0 replies; 9+ messages in thread
From: Nicolas Pitre @ 2011-02-17 20:47 UTC (permalink / raw)
To: Jay Soffian; +Cc: git, Junio C Hamano
On Thu, 17 Feb 2011, Jay Soffian wrote:
> The detached HEAD state is a source of much confusion for users
> new to git. Here we try to document it better.
>
> Reworked from http://article.gmane.org/gmane.comp.version-control.git/138440
Excellent!
> Requested-by: Nicolas Pitre <nico@fluxnic.net>
> Signed-off-by: Jay Soffian <jaysoffian@gmail.com>
Acked-by: Nicolas Pitre <nico@fluxnic.net>
> ---
> Nicolas only asked me to contribute this a full year ago, not too
> bad. :)
Better late than never.
> Documentation/git-checkout.txt | 108 +++++++++++++++++++++++++++++++---------
> 1 files changed, 85 insertions(+), 23 deletions(-)
>
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index 880763d..21abd2a 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -206,40 +206,102 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
>
> Detached HEAD
> -------------
> +HEAD normally refers to a named branch (e.g. "master"). Meanwhile, each
> +branch refers to a specific commit-id. Let's look at a repo with three
> +commits and with "master" checked out:
>
> -It is sometimes useful to be able to 'checkout' a commit that is
> -not at the tip of one of your branches. The most obvious
> -example is to check out the commit at a tagged official release
> -point, like this:
> +------------
> + HEAD (refers to master)
> + v
> +a---b---c master (refers to c)
> +------------
> +
> +When a commit is created in this state, the branch is updated to the new
> +commit-id. Let's add a commit:
>
> ------------
> -$ git checkout v2.6.18
> + HEAD (refers to master)
> + v
> +a---b---c---d master (refers to d)
> ------------
>
> -Earlier versions of git did not allow this and asked you to
> -create a temporary branch using the `-b` option, but starting from
> -version 1.5.0, the above command 'detaches' your HEAD from the
> -current branch and directly points at the commit named by the tag
> -(`v2.6.18` in the example above).
> +It is sometimes useful to be able to checkout a commit that is not at
> +the tip of any named branch, or even to create a new commit that is not
> +referenced by a named branch. Let's look at what happens when we
> +checkout commit b:
>
> -You can use all git commands while in this state. You can use
> -`git reset --hard $othercommit` to further move around, for
> -example. You can make changes and create a new commit on top of
> -a detached HEAD. You can even create a merge by using `git
> -merge $othercommit`.
> +------------
> +$ git checkout master^^
>
> -The state you are in while your HEAD is detached is not recorded
> -by any branch (which is natural --- you are not on any branch).
> -What this means is that you can discard your temporary commits
> -and merges by switching back to an existing branch (e.g. `git
> -checkout master`), and a later `git prune` or `git gc` would
> -garbage-collect them. If you did this by mistake, you can ask
> -the reflog for HEAD where you were, e.g.
> + HEAD (refers to b)
> + v
> +a---b---c---d master (refers to d)
> +------------
> +
> +Notice that HEAD now refers directly to commit b. In git terminology,
> +this is known as having a detached HEAD. It means simply that HEAD
> +refers to a specific commit-id, as opposed to referring to a named
> +branch. Let's add a commit while HEAD is detached:
>
> ------------
> -$ git log -g -2 HEAD
> + HEAD (refers to e)
> + v
> + e
> + /
> +a---b---c---d master (refers to d)
> +------------
> +
> +We have created a new commit, but it is referenced only by HEAD. We can
> +of course add yet another commit in this state:
> +
> +------------
> + HEAD (refers to f)
> + v
> + e---f
> + /
> +a---b---c---d master (refers to d)
> +------------
> +
> +In fact, we can perform all the normal git operations. But, let's look
> +at what happens when we then checkout master:
> +
> ------------
> +$ git checkout master
>
> + e---f HEAD (refers to master)
> + / v
> +a---b---c---d master (refers to d)
> +------------
> +
> +It is important to realize that at this point nothing refers to commits
> +e and f. Eventually these commits will be deleted by the routine git
> +garbage collection process, unless we create a reference before that
> +happens. If we have not yet moved away from commit f, any of these will
> +create a reference to it:
> +
> +------------
> +$ git checkout -b foo # (1)
> +$ git branch foo # (2)
> +$ git tag foo # (3)
> +------------
> +
> +(1) creates a new branch "foo", which refers to f, and then updates HEAD
> +to refer to "foo". In other words, we'll no longer be in detached HEAD
> +state after (1).
> +
> +(2) similarly creates a new branch "foo", which refers to f, but leaves
> +HEAD detached.
> +
> +(3) creates a new tag "foo", which refers to f, leaving HEAD detached.
> +
> +If we have moved away from commit f, then we must first recover its id
> +(typically by using git reflog), and then we can create a reference to
> +it. For example, to see the last two commits to which HEAD referred, we
> +can use:
> +
> +------------
> +$ git log -g -2 HEAD
> +------------
>
> EXAMPLES
> --------
> --
> 1.7.4.1.29.g21713
>
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] git-checkout.txt: improve detached HEAD documentation
2011-02-17 19:46 [PATCH] git-checkout.txt: improve detached HEAD documentation Jay Soffian
2011-02-17 19:48 ` Jay Soffian
2011-02-17 20:47 ` Nicolas Pitre
@ 2011-02-17 21:49 ` Junio C Hamano
2011-02-18 0:14 ` Nicolas Pitre
2011-02-20 5:21 ` Jay Soffian
2 siblings, 2 replies; 9+ messages in thread
From: Junio C Hamano @ 2011-02-17 21:49 UTC (permalink / raw)
To: Jay Soffian; +Cc: git, Nicolas Pitre
Jay Soffian <jaysoffian@gmail.com> writes:
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index 880763d..21abd2a 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -206,40 +206,102 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
>
> Detached HEAD
> -------------
> +HEAD normally refers to a named branch (e.g. "master"). Meanwhile, each
> +branch refers to a specific commit-id. Let's look at a repo with three
s/commit-id/commit/; we don't say "commit-id" anywhere else in this
document. Also, it is Ok to be loose and colloquial in the manual and it
is fine to say "commit ID" from time to time, but not in this section, one
of the primary purpose of which is to illustrate distinction between
pointing at something that points at a commit (i.e. branch) and pointing
directly at a commit (i.e. detached).
> +commits and with "master" checked out:
>
> +------------
> + HEAD (refers to master)
> + v
> +a---b---c master (refers to c)
> +------------
> +
> +When a commit is created in this state, the branch is updated to the new
> +commit-id. Let's add a commit:
... updated to point the new commit. 'git commit' creates a new
commit 'd', makes it a child of 'c' and moves 'master' branch to
point at 'd'. HEAD also points at 'd' as the result of 'master'
moving to the new commit.
I'd also suggest avoiding "Let's add" and instead be more specific (see
the above example).
> ------------
> + HEAD (refers to master)
> + v
> +a---b---c---d master (refers to d)
> ------------
>
> +It is sometimes useful to be able to checkout a commit that is not at
> +the tip of any named branch, or even to create a new commit that is not
> +referenced by a named branch. Let's look at what happens when we
> +checkout commit b:
I think it is a regression from the original text to omit mention of tags
and replace the first example of the section with a more advanced use case
of jumping to the middle of a branch; it is far more likely that a user
would want to detach at a specific release point.
You can rectify it by tagging 'c' as a release point and detaching the
HEAD at that tag without losing the clarity of the following description.
While doing so, it would be better to update the labels in the
illustration with s/master/master branch/ and s/[abcde]/commit &/ as well,
e.g.
HEAD (refers to branch 'master')
|
V
a---b---c---d branch 'master' (refers to commit 'd')
^
|
tag 'v2.0' (refers to commit 'c')
> +------------
> +$ git checkout master^^
>
> + HEAD (refers to b)
Perhaps s/refers/& directly/ to emphasize the difference in the
illustration.
> + v
> +a---b---c---d master (refers to d)
> +------------
> +
> +Notice that HEAD now refers directly to commit b. In git terminology,
> +this is known as having a detached HEAD. It means simply that HEAD
> +refers to a specific commit-id, as opposed to referring to a named
> +branch. Let's add a commit while HEAD is detached:
I'd suggest dropping "In git terminology,"; the reader knows that is what
is being explained when he opened the documentation.
We often say "detach the HEAD from a branch", "detach the HEAD at commit
'b'", but I don't think we say "we have a detached HEAD". Same comments
from a few section before apply to "commit-id" and "Let's add".
We often say "we detach HEAD at commit 'b'" and/or "we detach HEAD
from the 'master' branch", to describe this state. The HEAD directly
points at the commit 'b', as opposed to referring to it indirectly
through the "current" branch it points at. From this state, 'git
commit' will create a new commit 'e', makes it a child of 'b', and
moves HEAD to directly point at it.
> +$ git checkout master
>
> + e---f HEAD (refers to master)
> + / v
> +a---b---c---d master (refers to d)
> +------------
> +
> +It is important to realize that at this point nothing refers to commits
> +e and f. Eventually these commits will be deleted by the routine git
> +garbage collection process, unless we create a reference before that
> +happens. If we have not yet moved away from commit f, any of these will
> +create a reference to it:
> +
> +------------
> +$ git checkout -b foo # (1)
> +$ git branch foo # (2)
> +$ git tag foo # (3)
> +------------
> +
> +(1) creates a new branch "foo", which refers to f, and then updates HEAD
> +to refer to "foo". In other words, we'll no longer be in detached HEAD
> +state after (1).
Somehow it feels funny to say "after (1)" in the section marked as such.
"after doing so", perhaps?
Also mimick the way how git-reset.txt, everyday.txt etc. tell AsciiDoc to
produce pretty labels that refer to parts in an illustration, with <1>,
<2>, etc.
> +If we have moved away from commit f, then we must first recover its id
s/id/object name/;
Other than these three points, the description from "It is important" up
to this point looks good.
> +(typically by using git reflog), and then we can create a reference to
> +it. For example, to see the last two commits to which HEAD referred, we
> +can use:
> +
> +------------
> +$ git log -g -2 HEAD
> +------------
A documentation written for people who do not know how to extract commit
object names out of reflog, it is insufficient to give the command line
example without giving a few lines of example output. Instead of "log -g",
it probably is easier to use "git reflog -2" for this purpose.
Thanks.
^ permalink raw reply [flat|nested] 9+ messages in thread* Re: [PATCH] git-checkout.txt: improve detached HEAD documentation
2011-02-17 21:49 ` Junio C Hamano
@ 2011-02-18 0:14 ` Nicolas Pitre
2011-02-18 0:25 ` Junio C Hamano
2011-02-20 5:21 ` Jay Soffian
1 sibling, 1 reply; 9+ messages in thread
From: Nicolas Pitre @ 2011-02-18 0:14 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Jay Soffian, git
On Thu, 17 Feb 2011, Junio C Hamano wrote:
> Jay Soffian <jaysoffian@gmail.com> writes:
>
> > +It is sometimes useful to be able to checkout a commit that is not at
> > +the tip of any named branch, or even to create a new commit that is not
> > +referenced by a named branch. Let's look at what happens when we
> > +checkout commit b:
>
> I think it is a regression from the original text to omit mention of tags
> and replace the first example of the section with a more advanced use case
> of jumping to the middle of a branch; it is far more likely that a user
> would want to detach at a specific release point.
>
> You can rectify it by tagging 'c' as a release point and detaching the
> HEAD at that tag without losing the clarity of the following description.
> While doing so, it would be better to update the labels in the
> illustration with s/master/master branch/ and s/[abcde]/commit &/ as well,
> e.g.
>
>
> HEAD (refers to branch 'master')
> |
> V
> a---b---c---d branch 'master' (refers to commit 'd')
> ^
> |
> tag 'v2.0' (refers to commit 'c')
While I agree with the above, I think this is still a good idea to keep
this example using a non-tagged commit as well. Perhaps not the first
one as you say.
Nicolas
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] git-checkout.txt: improve detached HEAD documentation
2011-02-18 0:14 ` Nicolas Pitre
@ 2011-02-18 0:25 ` Junio C Hamano
0 siblings, 0 replies; 9+ messages in thread
From: Junio C Hamano @ 2011-02-18 0:25 UTC (permalink / raw)
To: Nicolas Pitre; +Cc: Jay Soffian, git
Nicolas Pitre <nico@fluxnic.net> writes:
> On Thu, 17 Feb 2011, Junio C Hamano wrote:
> ...
>> You can rectify it by tagging 'c' as a release point and detaching the
>> HEAD at that tag without losing the clarity of the following description.
>> While doing so, it would be better to update the labels in the
>> illustration with s/master/master branch/ and s/[abcde]/commit &/ as well,
>> e.g.
>>
>>
>> HEAD (refers to branch 'master')
>> |
>> V
>> a---b---c---d branch 'master' (refers to commit 'd')
>> ^
>> |
>> tag 'v2.0' (refers to commit 'c')
>
> While I agree with the above, I think this is still a good idea to keep
> this example using a non-tagged commit as well. Perhaps not the first
> one as you say.
Just to make sure, I wasn't opposed to the idea of showing the history
after building a few commits on top of the point you started from, to
explain why you might want to re-attach the about-to-be-orphaned commits
to the DAG anchored by refs.
IOW, detach at v2.0 tag, experiment with a few commits to fix things up,
and then when things go well, make it a maitenance branch, or something.
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH] git-checkout.txt: improve detached HEAD documentation
2011-02-17 21:49 ` Junio C Hamano
2011-02-18 0:14 ` Nicolas Pitre
@ 2011-02-20 5:21 ` Jay Soffian
2011-02-22 5:56 ` Junio C Hamano
1 sibling, 1 reply; 9+ messages in thread
From: Jay Soffian @ 2011-02-20 5:21 UTC (permalink / raw)
To: git; +Cc: Jay Soffian, Nicolas Pitre, Junio C Hamano
The detached HEAD state is a source of much confusion for users
new to git. Here we try to document it better.
Reworked from http://article.gmane.org/gmane.comp.version-control.git/138440
Requested-by: Nicolas Pitre <nico@fluxnic.net>
Signed-off-by: Jay Soffian <jaysoffian@gmail.com>
---
Incorporated Junio's feedback. Though this is a bit clearer, I think it's
starting to make the man page quite long due to the taller ascii
art (adding the tag plus the stem to the arrows adds 4 lines to each
picture).
I don't have any more time to allocate to this patch. I think it's a vast
improvement as is, and you should feel free to make any corrections/edits you
see fit so that it may be applied.
Documentation/git-checkout.txt | 145 +++++++++++++++++++++++++++++++++------
1 files changed, 122 insertions(+), 23 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 880763d..8a252dc 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -206,40 +206,139 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
Detached HEAD
-------------
+HEAD normally refers to a named branch (e.g. 'master'). Meanwhile, each
+branch refers to a specific commit. Let's look at a repo with three
+commits, one of them tagged, and with branch 'master' checked out:
-It is sometimes useful to be able to 'checkout' a commit that is
-not at the tip of one of your branches. The most obvious
-example is to check out the commit at a tagged official release
-point, like this:
+------------
+ HEAD (refers to branch 'master')
+ |
+ v
+a---b---c branch 'master' (refers to commit 'c')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
+------------
+
+When a commit is created in this state, the branch is updated to refer to
+the new commit. Specifically, 'git commit' creates a new commit 'd', whose
+parent is commit 'c', and then updates branch 'master' to refer to new
+commit 'd'. HEAD still refers to branch 'master' and so indirectly now refers
+to commit 'd':
------------
-$ git checkout v2.6.18
+$ edit; git add; git commit
+
+ HEAD (refers to branch 'master')
+ |
+ v
+a---b---c---d branch 'master' (refers to commit 'd')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
------------
-Earlier versions of git did not allow this and asked you to
-create a temporary branch using the `-b` option, but starting from
-version 1.5.0, the above command 'detaches' your HEAD from the
-current branch and directly points at the commit named by the tag
-(`v2.6.18` in the example above).
+It is sometimes useful to be able to checkout a commit that is not at
+the tip of any named branch, or even to create a new commit that is not
+referenced by a named branch. Let's look at what happens when we
+checkout commit 'b' (here we show three ways this may be done):
-You can use all git commands while in this state. You can use
-`git reset --hard $othercommit` to further move around, for
-example. You can make changes and create a new commit on top of
-a detached HEAD. You can even create a merge by using `git
-merge $othercommit`.
+------------
+$ git checkout v2.0 # or
+$ git checkout b # or
+$ git checkout master^^
+
+ HEAD (refers to commit 'b')
+ |
+ v
+a---b---c---d branch 'master' (refers to commit 'd')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
+------------
-The state you are in while your HEAD is detached is not recorded
-by any branch (which is natural --- you are not on any branch).
-What this means is that you can discard your temporary commits
-and merges by switching back to an existing branch (e.g. `git
-checkout master`), and a later `git prune` or `git gc` would
-garbage-collect them. If you did this by mistake, you can ask
-the reflog for HEAD where you were, e.g.
+Notice that regardless of which checkout command we use, HEAD now refers
+directly to commit 'b'. This is known as being in detached HEAD state.
+It means simply that HEAD refers to a specific commit, as opposed to
+referring to a named branch. Let's see what happens when we create a commit:
------------
-$ git log -g -2 HEAD
+$ edit; git add; git commit
+
+ HEAD (refers to commit 'e')
+ |
+ v
+ e
+ /
+a---b---c---d branch 'master' (refers to commit 'd')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
------------
+There is now a new commit 'e', but it is referenced only by HEAD. We can
+of course add yet another commit in this state:
+
+------------
+$ edit; git add; git commit
+
+ HEAD (refers to commit 'f')
+ |
+ v
+ e---f
+ /
+a---b---c---d branch 'master' (refers to commit 'd')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
+------------
+
+In fact, we can perform all the normal git operations. But, let's look
+at what happens when we then checkout master:
+
+------------
+$ git checkout master
+
+ HEAD (refers to branch 'master')
+ e---f |
+ / v
+a---b---c---d branch 'master' (refers to commit 'd')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
+------------
+
+It is important to realize that at this point nothing refers to commit
+'f'. Eventually commit 'f' (and by extension commit 'e') will be deleted
+by the routine git garbage collection process, unless we create a reference
+before that happens. If we have not yet moved away from commit 'f',
+any of these will create a reference to it:
+
+------------
+$ git checkout -b foo <1>
+$ git branch foo <2>
+$ git tag foo <3>
+------------
+
+<1> creates a new branch 'foo', which refers to commit 'f', and then
+updates HEAD to refer to branch 'foo'. In other words, we'll no longer
+be in detached HEAD state after this command.
+
+<2> similarly creates a new branch 'foo', which refers to commit 'f',
+but leaves HEAD detached.
+
+<3> creates a new tag 'foo', which refers to commit 'f',
+leaving HEAD detached.
+
+If we have moved away from commit 'f', then we must first recover its object
+name (typically by using git reflog), and then we can create a reference to
+it. For example, to see the last two commits to which HEAD referred, we
+can use either of these commands:
+
+------------
+$ git reflog -2 HEAD # or
+$ git log -g -2 HEAD
+------------
EXAMPLES
--------
--
1.7.4.1.52.g8e1b
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] git-checkout.txt: improve detached HEAD documentation
2011-02-20 5:21 ` Jay Soffian
@ 2011-02-22 5:56 ` Junio C Hamano
2011-02-22 15:19 ` Jay Soffian
0 siblings, 1 reply; 9+ messages in thread
From: Junio C Hamano @ 2011-02-22 5:56 UTC (permalink / raw)
To: Jay Soffian; +Cc: git, Nicolas Pitre
Jay Soffian <jaysoffian@gmail.com> writes:
> +It is sometimes useful to be able to checkout a commit that is not at
> +the tip of any named branch, or even to create a new commit that is not
> +referenced by a named branch. Let's look at what happens when we
> +checkout commit 'b' (here we show three ways this may be done):
>
> +------------
> +$ git checkout v2.0 # or
> +$ git checkout b # or
> +$ git checkout master^^
I'd drop the second one, as "b" is not something the end user would type
from the command line (you could say "b's commit ID" but the string 'b' is
not it, unless it is a tag or something, in which case the first one that
uses 'v2.0' already illustrates it), and adjust "three" accordingly.
Other than that, I think this version is a vast improvement over what we
have.
Thanks.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] git-checkout.txt: improve detached HEAD documentation
2011-02-22 5:56 ` Junio C Hamano
@ 2011-02-22 15:19 ` Jay Soffian
0 siblings, 0 replies; 9+ messages in thread
From: Jay Soffian @ 2011-02-22 15:19 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, Nicolas Pitre
On Tue, Feb 22, 2011 at 12:56 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Jay Soffian <jaysoffian@gmail.com> writes:
>
>> +It is sometimes useful to be able to checkout a commit that is not at
>> +the tip of any named branch, or even to create a new commit that is not
>> +referenced by a named branch. Let's look at what happens when we
>> +checkout commit 'b' (here we show three ways this may be done):
>>
>> +------------
>> +$ git checkout v2.0 # or
>> +$ git checkout b # or
>> +$ git checkout master^^
>
> I'd drop the second one, as "b" is not something the end user would type
> from the command line (you could say "b's commit ID" but the string 'b' is
> not it, unless it is a tag or something, in which case the first one that
> uses 'v2.0' already illustrates it)
Ah, in my mind, b _is_ the commit-ID. In your mind, b is the commit.
Fair enough, drop it.
> and adjust "three" accordingly. Other than that, I think this version is
> a vast improvement over what we have.
Would you mind amending what you've got so I don't have to resend?
Thanks,
j.
^ permalink raw reply [flat|nested] 9+ messages in thread