On Mon, Dec 17, 2012 at 7:53 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote:
> Here is a work-in-progress relative to Chris's 83c9989
> (Documentation/git-checkout.txt: document 70c9ac2 behavior,
> 2012-12-17).
It sounds pretty good to me.
> @@ -54,12 +61,17 @@ $ git checkout <branch>
> that is to say, the branch is not reset/created unless "git checkout" is
> successful.
>
> -'git checkout' [--detach] [<commit>]::
> +'git checkout' --detach [<commit>]::
> +'git checkout' <commit>::
>
> - Update the index and working tree to reflect the specified
> - commit and set HEAD to point directly to <commit> (see
> - "DETACHED HEAD" section.) Passing `--detach` forces this
> - behavior even if <commit> is a branch.
> + Prepare to work on top of <commit>, by detaching HEAD at it
> + (see "DETACHED HEAD" section), and updating the index and the
> + files in the working tree. Local modifications to the files
> + in the working tree are kept, so that the resulting working
> + tree will be the state recorded in the commit plus the local
> + modifications.
> ++
> +Passing `--detach` forces this behavior even if <commit> is a branch.
>
> 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
>
I like Johannes' suggestion of using "<branch>" in the --detach case
instead of "<commit>" as I think it makes the reason for the
separation more obvious at a glance. On top of your changes, maybe
something like:
--->8---
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index dcf1a32..4fdf41a 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -61,8 +61,8 @@ $ git checkout <branch>
that is to say, the branch is not reset/created unless "git checkout" is
successful.
-'git checkout' --detach [<commit>]::
'git checkout' <commit>::
+'git checkout' --detach [<branch>]::
Prepare to work on top of <commit>, by detaching HEAD at it
(see "DETACHED HEAD" section), and updating the index and the
@@ -71,7 +71,8 @@ successful.
tree will be the state recorded in the commit plus the local
modifications.
+
-Passing `--detach` forces this behavior even if <commit> is a branch.
+Passing `--detach` forces this behavior in the case of a <branch>, or
+the current branch if one is not specified.
'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
--
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