From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 16 Jul 2010 20:43:23 GMT
Subject: Re: [RFC PATCH 2/5] Documentation/reset: separate options by mode
Message-ID: <7v7hkvrwd0.fsf@alter.siamese.dyndns.org>
In-Reply-To: <0bfc95a7c144ccc811b58321a33caf89d20495e1.1279273256.git.trast@student.ethz.ch>

Thomas Rast <trast@student.ethz.ch> writes:

> Remove all but -q from the OPTIONS section, and instead explain the
> options separated by usage mode, since they only apply to one each.
>
> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
>
> fixup! Documentation/reset: separate options by mode
> ---
>  Documentation/git-reset.txt |   58 +++++++++++++++++++++++-------------------
>  1 files changed, 32 insertions(+), 26 deletions(-)
>
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> index dbb810d..46b2d2a 100644
> --- a/Documentation/git-reset.txt
> +++ b/Documentation/git-reset.txt
> @@ -8,29 +8,38 @@ git-reset - Reset current HEAD to the specified state
>  SYNOPSIS
>  --------
>  [verse]
> -'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>]
>  'git reset' [-q] [<commit>] [--] <paths>...
>  'git reset' --patch [<commit>] [--] [<paths>...]
> +'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>]
>  
>  DESCRIPTION
>  -----------
> +Sets the current branch to the specified <commit> and optionally
> +resets the index and working tree to match.  The <commit> defaults to
> +HEAD in all forms.

With a careless reading of this paragraph, I got an impression that HEAD
is always affected, but I happen to know that is not the case ;-).

 - "reset" is primarily about resetting the index and the --soft option
   can be used to optionally not to do this.

   . with paths, the command is about fixing up the index contents for
     given specific paths, to prepare for the next commit.  HEAD is not
     moved.

   . without paths, the command is about changing what commit to build
     your next commit on, i.e. HEAD is moved.

> +'git reset' [-q] [<commit>] [--] <paths>...::
> +	This form resets the index entries for all <paths> to their
> +	state at the <commit>.  (It does not affect the worktree, nor
> +	the current branch.)
> ++
> +This means that `git reset <paths>` is the opposite of `git add
> +<paths>`, provided that the <paths> were already tracked.

The above is a clearer description of "with-path" mode than what we
currently have.  I doubt that we need ", provided that...", though.  

"git reset HEAD frotz" from a head commit without frotz gets rid of frotz
from the index, no?