Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

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

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

> +`--soft`::
> +	Leaves your working directory unchanged. The index is left unchanged,

Why not "leave your working tree files and the index unchanged"?

> +	so everything in your current commit will be staged.

Hmph, if a reader still has the "stage the changes" mental model,
then this would be true only when you are resetting to HEAD~1 (this
is one of the reasons why I am hesitant to overuse the verb
"stage").  If you are going to HEAD~5, such a reader would say that
the changes made by the past 5 commits are staged, not just the
commit you are on before resetting.

> +	For example, if you have no staged changes, you can use
> +	`git reset --soft HEAD~5; git commit`
> +	to combine the last 5 commits into 1 commit.

Another thing that may be worth mentioning is that you can do this
even with local changes in the working tree, because you do not give
"-a" to the final "git commit".

>  `--hard`::
> -	Resets the index and working tree. Any changes to tracked files in the
> -	working tree since _<commit>_ are discarded.  Any untracked files or
> -	directories in the way of writing any tracked files are simply deleted.
> +	Overwrites all files and directories with the version from _<commit>_,
> +	and may overwrite untracked files.
> +	Updates the index to match the new HEAD, so nothing will be staged.

One thing that may be worth saying is that the paths in the working
tree that are tracked in the index that are not in <commit> will
disappear.

>  `--merge`::
> +	Mainly exists for backwards compatibility: `git merge --abort` is the
> +	usual way to abort a merge. See linkgit:git-merge[1] for the differences.

There are operations that are not "git merge" that can leave the
index in an unmerged state, and you do not want to use "git merge
--abort" to get out of such a state, I would imagine.  So I have a
feeling that we are better off without these two lines.

>  	Resets the index and updates the files in the working tree that are
>  	different between _<commit>_ and `HEAD`, but keeps those which are
>  	different between the index and working tree (i.e. which have changes
>  	which have not been added).
>  	If a file that is different between _<commit>_ and the index has
>  	unstaged changes, reset is aborted.
> -+
> -In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
> -but carries forward unmerged index entries.

I do not mind losing this.  Unlike the time back when these two
lines were written, nobody knows (and more importantly, nobody has
to know) what "read-tree -u -m" does, these days.

>  `--keep`::
>  	Resets index entries and updates files in the working tree that are

Thanks.