Skip to contentSkip to conversation

reset.txt: update the title line to cover all use cases

PATCH In review Nguyễn Thái Ngọc Duy 2 participants 2 messages Apr 19, 2019 – Apr 21, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 reset.txt: update the title line to cover all use cases

git-reset could be used in three different ways:

- move HEAD to somewhere, optionally (not) update worktree/index
- "move" HEAD to HEAD, mainly to update worktree/index
- just update the index from some tree-ish

The second case is frankly a (neat) corner case of the first one. But it makes it impossible for me to summarize git-reset in one line. Without it at least I could write "reset HEAD or the index".

And even "reset all the things" is not correct because reseting worktree selectively is the job of git-checkout, not git-reset. Sigh.

This patch is not meant to be taken seriously. It's to raise the issue with git-reset documentation, and maybe someone could come up with a better summary line for git-reset. Because the current line only covers the first (original) case.

PS. We also need to update git-reset to mentino about its ability to clear branch state.

---
 Documentation/git-reset.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-reset.txt +1 -1
index 26e746c53f..e12d8edee6 100644
@@ -3,7 +3,7 @@ git-reset(1)
 
 NAME
 ----
-git-reset - Reset current HEAD to the specified state
+git-reset - Reset "something"
 
 SYNOPSIS
 --------
Signature · 1 line
2.21.0.854.ge34a79f761
#1 lore raw
Quoted 6 lines · Nguyễn Thái Ngọc Duy

git-reset could be used in three different ways:

- move HEAD to somewhere, optionally (not) update worktree/index
- "move" HEAD to HEAD, mainly to update worktree/index
- just update the index from some tree-ish

Quoted 6 lines

The second case is frankly a (neat) corner case of the first one. But it makes it impossible for me to summarize git-reset in one line. Without it at least I could write "reset HEAD or the index".

And even "reset all the things" is not correct because reseting worktree selectively is the job of git-checkout, not git-reset. Sigh.

I am not so sure if the current one is too bad. The primary action of the command is to reset the current HEAD to point at a specified commit, and everything else it does is to make things consistent (in other words, in line with having the HEAD at the given commit) with respect to different requirements. The "soft" reset wants to keep the index and the working tree intact, the "merge" reset wants to undo what a mergy operation would have done to the index and the working tree if it started from a clean state, etc. And "reset the HEAD" is quite approiprate for a single line summary of what the command does. It perfectly is fine as long as the differences brought in by having various "modes" are sufficiently described, I would think.

Quoted 13 lines
Documentation/git-reset.txt +1 -1
index 26e746c53f..e12d8edee6 100644
@@ -3,7 +3,7 @@ git-reset(1)
 
 NAME
 ----
-git-reset - Reset current HEAD to the specified state
+git-reset - Reset "something"
 
 SYNOPSIS
 --------