Re: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command
From: Jonathan Nieder <hidden>
Date: 2016-06-15 22:58:44
Possibly related (same subject, not in this thread)
- 2016-06-15 · [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command · Benjamin Bergman <hidden>
Hi, Junio C Hamano wrote:
quoted hunk ↗ jump to hunk
--- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt@@ -9,7 +9,8 @@ SYNOPSIS -------- [verse] 'git checkout' [-q] [-f] [-m] [<branch>] -'git checkout' [-q] [-f] [-m] [--detach] [<commit>] +'git checkout' [-q] [-f] [-m] --detach [<branch>] +'git checkout' [-q] [-f] [-m] [--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' [-p|--patch] [<tree-ish>] [--] [<paths>...]@@ -62,7 +63,7 @@ that is to say, the branch is not reset/created unless "git checkout" is successful. 'git checkout' --detach [<branch>]:: -'git checkout' <commit>:: +'git checkout' [--detach] <commit>::
Looks sensible. [...]
quoted hunk ↗ jump to hunk
@@ -71,10 +72,13 @@ successful. tree will be the state recorded in the commit plus the local modifications. + -Passing `--detach` forces this behavior in the case of a <branch> (without -the option, giving a branch name to the command would check out the branch, -instead of detaching HEAD at it), or the current commit, -if no <branch> is specified. +Even though a branch name can be used to name a commit, you have to +explicitly say `git checkout --detach <branch>` when you want to +detach HEAD at the tip of the branch (`git checkout <branch>` will +check out that branch without detaching HEAD). Omitting <branch>, +i.e. `git checkout --detach` detaches HEAD at the tip of the current +branch. When naming the commit in a form other than just a branch +name, e.g. `master^0`, `HEAD~4`, `c2f3bf071e`, you can omit --detach.
Hm. I agree that the old explanation is overly convoluted, but I don't
think the replacement is clear enough yet. The "Even though a branch
name can be used to name a commit," part forced me to pause for too
long --- why is this telling me that a branch can be used to name a
commit, and in what context?
I think the main problem with the old text is that it tried to say too
much in one sentence.
The explanation lower down of the --detach option does this rather
well:
--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.
How about splitting this into multiple paragraphs, like so? In the
suggestion below I also cleaned up the language a little.
git checkout --detach [<branch>], git checkout [--detach] <commit>
Prepare to work on top of <commit>, by detaching [...]
When the <commit> argument is a branch name, the --detach
option can be used to detach HEAD at the tip of the
branch ('git checkout <branch>' would check out that
branch without detaching HEAD).
Omitting <branch> detaches HEAD at the tip of the
current branch.
I'd leave out the last sentence about commits other than branch names,
since it is already implied by the [--detach] in the syntax.
Thanks and hope that helps,
Jonathan