From: Chris Rorvick <chris@rorvick.com>
Date: Tue, 18 Dec 2012 03:33:09 GMT
Subject: Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
Message-ID: <CAEUsAPa1XMeymEXbLu=iy8VTdLO=iPUeVN3QPH+FbQecL8XnsA@mail.gmail.com>
In-Reply-To: <7vvcc0i0rz.fsf@alter.siamese.dyndns.org>

On Mon, Dec 17, 2012 at 7:53 PM, Junio C Hamano <gitster@pobox.com> 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>...::