Re: [PATCH] git-reset.txt: Be clearer about the symbolic ref nature of HEAD

From: Drew Northup <drew.northup@maine.edu>
Date: Aug 24, 2011, 11:34 UTC
Message-ID: <1314185698.13674.8.camel@drew-northup.unet.maine.edu>
In-Reply-To: <f903e0bb1c14cb083c263deb165dc9495ab4c60e.1314179720.git.git@drmicha.warpmail.net>

On Wed, 2011-08-24 at 11:56 +0200, Michael J Gruber wrote:

Show 13 quoted lines

> "git reset" updates the ref which HEAD points to (or HEAD itself, if
> detached), due to being a symbolic ref (unless detached). Therefore,
> "updating/resetting HEAD" is a possible source of confusion especially when
> compared with "git checkout", and the change in
> d537c74 (git-reset.txt: make modes description more consistent, 2010-09-15)
> did not quite help.
> 
> Clean up after d537c74 (myself) and try to be even clearer about which
> ref is changed by "git reset". Avoid the term "symbolic ref", because who can
> tell *HEAD from HEAD from &HEAD?
> 
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---

Looks reasonable to me.

Show 28 quoted lines

>  Documentation/git-reset.txt |    7 ++++---
>  1 files changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> index b2832fc..96c964d 100644
> --- a/Documentation/git-reset.txt
> +++ b/Documentation/git-reset.txt
> @@ -15,7 +15,7 @@ SYNOPSIS
>  DESCRIPTION
>  -----------
>  In the first and second form, copy entries from <commit> to the index.
> -In the third form, set the current branch head (HEAD) to <commit>, optionally
> +In the third form, set the current branch head (which HEAD points to) to <commit>, optionally
>  modifying index and working tree to match.  The <commit> defaults to HEAD
>  in all forms.
>  
> @@ -44,8 +44,9 @@ you can use it to selectively reset hunks. See the ``Interactive Mode''
>  section of linkgit:git-add[1] to learn how to operate the `\--patch` mode.
>  
>  'git reset' [--<mode>] [<commit>]::
> -	This form resets the current branch head to <commit> and
> -	possibly updates the index (resetting it to the tree of <commit>) and
> +	This form resets the current branch head (which HEAD points to) to <commit>;
> +	if HEAD points to a commit (aka detached HEAD) then HEAD is reset to <commit>.
> +	This form also possibly updates the index (resetting it to the tree of <commit>) and
>  	the working tree depending on <mode>, which
>  	must be one of the following:
>  +

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59