Re: [PATCH 2/4] doc: git-reset: clarify intro

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> From user feedback, there were several points of confusion:
>
> - What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
>   ("I have no clue what the index is", "I've been using git for 20 years
>   and still don't know what a tree-ish is"). Avoid using these terms
>   where it makes sense.
> - What "optionally modifying index and working tree to match" means
>   ("to match what?" "optionally based on what?")
>   Remove this from the intro, we can say it later when giving more
>   details.
> - One user suggested that "The <tree-ish>/<commit> defaults to HEAD
>   in all forms." should be repeated later on, since it's easy to miss.
>   Instead say that HEAD is the default in each case later.
>
> Another issue is that `git reset` consistently describes the action
> it does as "Reset ...", commands should not use their name to describe
> themselves, and that the word "mode" is used to mean several different
> things on this page.
>
> Address these by being more clear about two use cases for `git reset`
> ("to undo operations" and "to update staged files"), and explaining what
> the conditions are for each case instead of forcing the user to figure
> out the pattern is in first form vs the other 3 forms.
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-reset.adoc | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
> index 9843682e81..876187dc83 100644
> --- a/Documentation/git-reset.adoc
> +++ b/Documentation/git-reset.adoc
> @@ -3,7 +3,7 @@ git-reset(1)
>  
>  NAME
>  ----
> -git-reset - Reset current HEAD to the specified state
> +git-reset - Set HEAD to point at the specified commit

The command has dual-purpose, and it is a bit disturbing that the
other one is not even mentioned in the original or in the updated
text.  "The other three forms" is about resetting the index without
moving HEAD at all.  Would this work better, I wonder?

    Reset HEAD or index back to a known state

> +`git reset [<mode>] <commit>` changes which commit HEAD points to.
> +This makes it possible to undo various Git operations, for example
> +commit, merge, rebase, and pull.

Good.  These are prime examples of when resetting to a known state
is useful.

> +However, when you specify files or directories or pass `--patch`,
> +`git reset` will instead update the staged version of the specified
> +files without updating HEAD.

I see no however here.

Other forms are not about flipping HEAD to any state we used to have
before.  Instead, they are about populating index entries from the
state taken from an arbitrary tree-ish.

You can view them as enhanced variants of "git reset --mixed HEAD"
(read it as "unstage all changes").  They are enhanced in the sense
that unlike "git reset --mixed HEAD", the treeish the index entries
are taken from does not have to be HEAD, and also in the sense that
unlike "git reset --mixed HEAD", you can limit the index entries to
be affected to a subset of paths.  I am not sure it would make it
easier to understand to explain them in terms of "reset --mixed HEAD"
but I am reasonably sure that it would appear confusing until a
reader realizes that the command has two very disinct mode, one that
is primarily about HEAD, the other that is primarily about index.

>  `git reset [<mode>] [<commit>]`::
>  	This form resets the current branch head to _<commit>_ and