Benjamin Bergman writes:
> From a33659535cb0eac92bed42d5e494dbb8f5d9ab20 Mon Sep 17 00:00:00 2001
> From: Benjamin Bergman
> Date: Tue, 10 Sep 2013 16:00:29 -0500
> Subject: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis
> to correct command
These (except the first one that is a separator in the format-patch output)
go to your e-mail headers, not to the body of the message.
>
> Detailed description of `--detach` states that it is default for
> `` but needs to be specified for ``. The old man page
> synopsis showed the reverse.
> ---
Please sign-off your patch.
> -'git checkout' [-q] [-f] [-m] []
> -'git checkout' [-q] [-f] [-m] [--detach] []
> +'git checkout' [-q] [-f] [-m] [--detach] []
> +'git checkout' [-q] [-f] [-m] []
I am actually on the fence on this change.
The original shows two operations that do different things (one goes
to a named branch, the other goes to the state in which the HEAD is
detached at the named commit).
With the updated synopsis, even with the first form, if the user
uses --detach, the end result is like the second one. I personally
find the synopsis with the patch a bit more confusing, not less.
Can we update the second form (without touching the one that shows
"how to check out a named branch" at all) in a different way to
clarify? E.g.
'git checkout' [-q] [-f] [-m] [ | --detach ]
might be one way. If you want to detach at a named commit, you can
directly give the commit object name; a branch name usually can be
used as a commit object name, but that use conflicts with the more
usual "check out that branch" usage, so you need to give --detach
explicitly if you use a branch name to name that commit you want to
detach at. One drawback this has is that it does not capture that
you could say --detach (even though you do not have to) when using a
form that is _not_ a branch name to name your commit, e.g.
git checkout --detach master^0
... thinks a bit more ...
Or we can split the "detaching" usage into two, which is how the
DESCRIPTION section does. I.e.
'git checkout' [-q] [-f] [-m] []
-'git checkout' [-q] [-f] [-m] --detach []
+'git checkout' [-q] [-f] [-m] --detach []
+'git checkout' [-q] [-f] [-m]
'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] ] [ to say
that it is accepted (even though it is not necessary.
> 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] ] []
> 'git checkout' [-f|--ours|--theirs|-m|--conflict=
