Jay Soffian <jaysoffian@xxxxxxxxx> 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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html