[RFC/PATCH 0/2] Documentation: kicking the "reset --hard" habit

STALE3735d

4 messages, 2 authors, 2016-06-15 · open the first message on its own page

[RFC/PATCH 0/2] Documentation: kicking the "reset --hard" habit

From: Jonathan Nieder <hidden>
Date: 2016-06-15 22:49:56

Hi,

Kira on IRC reminded me that our introductory documentation does
not explain how to use the new reset --keep and --merge primitives.

Sadly, at least the user manual change suggested below is probably
not suitable, since reset --keep and --merge have not been around
since git 1.5.3 days.  Ideas for working around that and other
comments would be welcome.

Jonathan Nieder (2):
  Documentation: suggest "reset --merge" more often
  Documentation: suggest "reset --keep" more often

 Documentation/git-bisect-lk2009.txt               |    2 +-
 Documentation/git-bisect.txt                      |    2 +-
 Documentation/git-checkout.txt                    |    2 +-
 Documentation/git-merge.txt                       |    2 +-
 Documentation/git-rerere.txt                      |    2 +-
 Documentation/git-reset.txt                       |   13 ++++++-----
 Documentation/gitcore-tutorial.txt                |    6 ++--
 Documentation/gitworkflows.txt                    |    2 +-
 Documentation/howto/maintain-git.txt              |    4 +-
 Documentation/howto/separating-topic-branches.txt |    2 +-
 Documentation/user-manual.txt                     |   22 ++++++++++++++------
 11 files changed, 34 insertions(+), 25 deletions(-)

[RFC/PATCH 1/2] Documentation: suggest "reset --merge" more often

From: Jonathan Nieder <hidden>
Date: 2016-06-15 22:49:56

With its new semantics, "git reset --merge" is more suitable for
undoing a failed merge than "git reset --hard" is.  It is especially
nice if you forget that you are in a merge and make a change or two:

  git merge something-complicated
  ... notice conflicts, walk away ...
  vi foo.c
  git commit; # fails because the index has unmerged entries
  git reset --merge

The modern (post-1.7.0) semantics of git reset --merge ensure that
the changes to foo.c will be preserved by this sequence of commands,
unless foo.c was one of the files with conflicts.

So in the spirit of ed4a6baa (Documentation: suggest `reset --merge`
in How Merge Works section, 2010-01-23), recommend it in place of
"reset --hard".

One caveat: for habitual adders-to-index, "git reset --merge" is
no better than "git reset --hard" (though still no worse).

  vi foo.c
  git add -u
  git diff --cached --check; # fails because conflict markers are present
  git reset --merge; # equivalent to git reset --hard

Signed-off-by: Jonathan Nieder <redacted>
---
 Documentation/git-merge.txt   |    2 +-
 Documentation/git-reset.txt   |    9 +++++----
 Documentation/user-manual.txt |    9 ++++++++-
 3 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 84043cc..498931b 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt

@@ -213,7 +213,7 @@ After seeing a conflict, you can do two things:
 
  * Decide not to merge.  The only clean-ups you need are to reset
    the index file to the `HEAD` commit to reverse 2. and to clean
-   up working tree changes made by 2. and 3.; `git-reset --hard` can
+   up working tree changes made by 2. and 3.; `git reset --merge` can
    be used for this.
 
  * Resolve the conflicts.  Git will mark the conflicts in

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index fd72976..1d0d9e6 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt

@@ -179,7 +179,7 @@ $ git pull                         <1>
 Auto-merging nitfol
 CONFLICT (content): Merge conflict in nitfol
 Automatic merge failed; fix conflicts and then commit the result.
-$ git reset --hard                 <2>
+$ git reset --merge                <2>
 $ git pull . topic/branch          <3>
 Updating from 41223... to 13134...
 Fast-forward

@@ -189,9 +189,10 @@ $ git reset --hard ORIG_HEAD       <4>
 <1> Try to update from the upstream resulted in a lot of
 conflicts; you were not ready to spend a lot of time merging
 right now, so you decide to do that later.
-<2> "pull" has not made merge commit, so "git reset --hard"
-which is a synonym for "git reset --hard HEAD" clears the mess
-from the index file and the working tree.
+<2> "pull" has not made merge commit, so "git reset --merge"
+which is a synonym for "git reset --merge HEAD" clears the mess
+from the index file and the working tree.  "git reset --hard"
+would work as well.
 <3> Merge a topic branch into the current branch, which resulted
 in a fast-forward.
 <4> But you decided that the topic branch is not ready for public

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index fc56da6..9120ad5 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -1372,12 +1372,19 @@ Undoing a merge
 ---------------
 
 If you get stuck and decide to just give up and throw the whole mess
-away, you can always return to the pre-merge state with
+away, you can always return to the last commit's state with
 
 -------------------------------------------------
 $ git reset --hard HEAD
 -------------------------------------------------
 
+If you have changes that should be preserved in files not touched by
+the merge, instead use
+
+-------------------------------------------------
+$ git reset --merge HEAD
+-------------------------------------------------
+
 Or, if you've already committed the merge that you want to throw away,
 
 -------------------------------------------------

-- 
1.7.2.3.557.gab647.dirty

[RFC/PATCH 2/2] Documentation: suggest "reset --keep" more often

From: Jonathan Nieder <hidden>
Date: 2016-06-15 22:49:56

Practically speaking, a "reset --hard" fulfills two purposes:

 1. erase uncommitted changes (in the index and worktree)
 2. checkout a different commit without changing which branch
    HEAD is attached to

The relatively new "git reset --keep" command does (2) without
(1), which makes it simpler to use for use cases that amount to
"rewind HEAD".

Signed-off-by: Jonathan Nieder <redacted>
---
 Documentation/git-bisect-lk2009.txt               |    2 +-
 Documentation/git-bisect.txt                      |    2 +-
 Documentation/git-checkout.txt                    |    2 +-
 Documentation/git-rerere.txt                      |    2 +-
 Documentation/git-reset.txt                       |    4 ++--
 Documentation/gitcore-tutorial.txt                |    6 +++---
 Documentation/gitworkflows.txt                    |    2 +-
 Documentation/howto/maintain-git.txt              |    4 ++--
 Documentation/howto/separating-topic-branches.txt |    2 +-
 Documentation/user-manual.txt                     |   13 +++++++------
 10 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt
index 8a2ba37..b581da8 100644
--- a/Documentation/git-bisect-lk2009.txt
+++ b/Documentation/git-bisect-lk2009.txt

@@ -1188,7 +1188,7 @@ should not forget to remove the patch once the testing is done before
 exiting from the script.
 
 (Note that instead of a patch you can use "git cherry-pick BFC" to
-apply the fix, and in this case you should use "git reset --hard
+apply the fix, and in this case you should use "git reset --keep
 HEAD^" to revert the cherry-pick after testing and before returning
 from the script.)

diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index c39d957..43582a8 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt

@@ -158,7 +158,7 @@ For example:
 $ git bisect good/bad			# previous round was good or bad.
 Bisecting: 337 revisions left to test after this
 $ git bisect visualize			# oops, that is uninteresting.
-$ git reset --hard HEAD~3		# try 3 revisions before what
+$ git reset --keep HEAD~3		# try 3 revisions before what
 					# was suggested
 ------------

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 22d3611..f92fe3f 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -223,7 +223,7 @@ current branch and directly points at the commit named by the tag
 (`v2.6.18` in the example above).
 
 You can use all git commands while in this state.  You can use
-`git reset --hard $othercommit` to further move around, for
+`git reset --keep $othercommit` to further move around, for
 example.  You can make changes and create a new commit on top of
 a detached HEAD.  You can even create a merge by using `git
 merge $othercommit`.

diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index db99d47..4ed4262 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt

@@ -132,7 +132,7 @@ top of the tip before the test merge:
 ------------
 	$ git checkout topic
 	$ git merge master
-	$ git reset --hard HEAD^ ;# rewind the test merge
+	$ git reset --keep HEAD^ ;# rewind the test merge
 	$ ... work on both topic and master branches
 	$ git checkout master
 	$ git merge topic

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 1d0d9e6..301419c 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt

@@ -148,7 +148,7 @@ Undo a commit, making it a topic branch::
 +
 ------------
 $ git branch topic/wip     <1>
-$ git reset --hard HEAD~3  <2>
+$ git reset --keep HEAD~3  <2>
 $ git checkout topic/wip   <3>
 ------------
 +

@@ -163,7 +163,7 @@ Undo commits permanently::
 +
 ------------
 $ git commit ...
-$ git reset --hard HEAD~3   <1>
+$ git reset --keep HEAD~3   <1>
 ------------
 +
 <1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad

diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index c27d086..14bdceb 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt

@@ -1182,9 +1182,9 @@ work." commit.
 
 ------------
 $ git checkout mybranch
-$ git reset --hard master^2
+$ git reset --keep master^2
 $ git checkout master
-$ git reset --hard master^
+$ git reset --keep master^
 ------------
 
 After rewinding, the commit structure should look like this:

@@ -1660,7 +1660,7 @@ we just did and start over.  We would want to get the master
 branch before these two merges by resetting it to 'master~2':
 
 ------------
-$ git reset --hard master~2
+$ git reset --keep master~2
 ------------
 
 You can make sure `git show-branch` matches the state before

diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 1ef55ff..4a35a92 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt

@@ -301,7 +301,7 @@ topics on 'next':
 [caption="Recipe: "]
 =====================================
 * `git checkout next`
-* `git reset --hard master`
+* `git reset --keep master`
 * `git merge ai/topic_in_next1`
 * `git merge ai/topic_in_next2`
 * ...

diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index d527b30..f0c9e1b 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt

@@ -166,7 +166,7 @@ by doing the following:
 
    then replace some parts with the new patch, and reapplying:
 
-     $ git reset --hard ai/topic~$n
+     $ git reset --keep ai/topic~$n
      $ git am -3 -s 000*.txt
 
    The full test suite is always run for 'maint' and 'master'

@@ -212,7 +212,7 @@ by doing the following:
  - Rebuild "pu" to merge the tips of topics not in 'next'.
 
      $ git checkout pu
-     $ git reset --hard next
+     $ git reset --keep next
      $ git merge ai/topic     ;# repeat for all remaining topics
      $ make test

diff --git a/Documentation/howto/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.txt
index 6d3eb8e..b54826f 100644
--- a/Documentation/howto/separating-topic-branches.txt
+++ b/Documentation/howto/separating-topic-branches.txt

@@ -80,7 +80,7 @@ The last diff better not to show anything other than cleanups
 for crufts.  Then I can finally clean things up:
 
         $ git branch -D topic
-        $ git reset --hard HEAD^ ;# nuke pretend merge
+        $ git reset --keep HEAD^ ;# nuke pretend merge
 
                                 "topicB"
                o---o---o---o---o

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 9120ad5..427717d 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -143,7 +143,7 @@ If you decide that you'd rather see version 2.6.17, you can modify
 the current branch to point at v2.6.17 instead, with
 
 ------------------------------------------------
-$ git reset --hard v2.6.17
+$ git reset --keep v2.6.17
 ------------------------------------------------
 
 Note that if the current branch head was your only reference to a

@@ -531,13 +531,13 @@ says "bisect".  Choose a safe-looking commit nearby, note its commit
 id, and check it out with:
 
 -------------------------------------------------
-$ git reset --hard fb47ddb2db...
+$ git reset --keep fb47ddb2db...
 -------------------------------------------------
 
 then test, run "bisect good" or "bisect bad" as appropriate, and
 continue.
 
-Instead of "git bisect visualize" and then "git reset --hard
+Instead of "git bisect visualize" and then "git reset --keep
 fb47ddb2db...", you might just want to tell git that you want to skip
 the current commit:

@@ -1388,7 +1388,7 @@ $ git reset --merge HEAD
 Or, if you've already committed the merge that you want to throw away,
 
 -------------------------------------------------
-$ git reset --hard ORIG_HEAD
+$ git reset --keep ORIG_HEAD
 -------------------------------------------------
 
 However, this last command can be dangerous in some cases--never

@@ -2011,7 +2011,8 @@ error: failed to push to 'ssh://yourserver.com/~you/proj.git'
 
 This can happen, for example, if you:
 
-	- use `git reset --hard` to remove already-published commits, or
+	- use `git reset --hard` or `git reset --keep` to remove
+	  already-published commits, or
 	- use `git commit --amend` to replace already-published commits
 	  (as in <<fixing-a-mistake-by-rewriting-history>>), or
 	- use `git rebase` to rebase any already-published commits (as

@@ -2585,7 +2586,7 @@ patches, then reset the state to before the patches:
 
 -------------------------------------------------
 $ git format-patch origin
-$ git reset --hard origin
+$ git reset --keep origin
 -------------------------------------------------
 
 Then modify, reorder, or eliminate patches as preferred before applying

-- 
1.7.2.3.557.gab647.dirty

Re: [RFC/PATCH 1/2] Documentation: suggest "reset --merge" more often

From: Stephen Boyd <hidden>
Date: 2016-06-15 22:49:57

On 10/29/10 01:38, Jonathan Nieder wrote:

With its new semantics, "git reset --merge" is more suitable for
undoing a failed merge than "git reset --hard" is.  It is especially
nice if you forget that you are in a merge and make a change or two:

  git merge something-complicated
  ... notice conflicts, walk away ...
  vi foo.c
  git commit; # fails because the index has unmerged entries
  git reset --merge

The modern (post-1.7.0) semantics of git reset --merge ensure that
the changes to foo.c will be preserved by this sequence of commands,
unless foo.c was one of the files with conflicts.

So in the spirit of ed4a6baa (Documentation: suggest `reset --merge`
in How Merge Works section, 2010-01-23), recommend it in place of
"reset --hard".

One caveat: for habitual adders-to-index, "git reset --merge" is
no better than "git reset --hard" (though still no worse).

  vi foo.c
  git add -u
  git diff --cached --check; # fails because conflict markers are present
  git reset --merge; # equivalent to git reset --hard

Would it also be a good idea to fill in the hint in git status for the
in_merge case with similar information?

`h`	back out one level
`j`	next message in thread
`k`	previous message in thread
`l`	drill in
`Esc`	close help / fold thread tree
`?`	toggle this help