On Mon, Apr 13, 2009 at 04:56:22AM -0400, Jeff King wrote:
> > I think "the apporachable part" aka "synopsis" should be kept the way it
> > is, but we should clarify in the description when the most general form is
> > different from the white lie we feed to newbies.
>
> Hmm. I tried something in this direction, but I actually think it ended
> up more confusing.
I meant to attach a patch here so you could judge for yourself, but I
forgot. I am preparing a patch series which I think is better, but for
reference, here is what I came up with before:
---
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 223ea9c..344c57a 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -131,15 +131,20 @@ the conflicted merge in the specified paths.
the index will be used.
<branch>::
- Branch to checkout (when no paths are given); may be any object
- ID that resolves to a commit. Defaults to HEAD.
+ If "-b" is not given, specifies the branch to checkout. If it
+ names a non-branch (i.e., a name that, when prepended with
+ "refs/heads/", does not exist) but does point to a
+ valid commit object, then the HEAD becomes 'detached', and you
+ are no longer on any branch. As a special case, the `"@\{-N\}"`
+ syntax for the N-th last branch checks out the branch (instead
+ of detaching). You may also specify `-` which is synonymous
+ with `"@\{-1\}"`.
+
-When this parameter names a non-branch (but still a valid commit object),
-your HEAD becomes 'detached'.
+If "-b" is given, specifies the start point of the newly created
+branch. Specifying a non-branch is irrelevant here, since git will
+checkout the newly created branch, not the start point.
+
-As a special case, the `"@\{-N\}"` syntax for the N-th last branch
-checks out the branch (instead of detaching). You may also specify
-`-` which is synonymous with `"@\{-1\}"`.
+In either case, if the parameter is omitted, it defaults to HEAD.
Detached HEAD
--
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