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

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

[Jonathan Nieder]

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

[Jonathan Nieder]

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 <jrnieder@gmail.com>
---
 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

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

[Stephen Boyd]

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?

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

[Jonathan Nieder]

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 <jrnieder@gmail.com>
---
 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 0/2] Documentation: kicking the "reset --hard" habit

[Matthieu Moy]

Jonathan Nieder <jrnieder@gmail.com> writes:

> 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.

Do we really want to keep the user manual compatible with 1.5.3
forever? It's nice to keep the user manual usable by slightly outdated
Gits, but 1.5.3 starts being really old, and older docs are still
available on the web (like
http://www.kernel.org/pub/software/scm/git/docs/v1.5.3.8/git.html ).

git reset --merge appeared in Git 1.6.2, it sounds reasonable to say
the current user manual works from this version.

git reset --keep appeared in 1.7.1, hence far more recently. But I
think it can still be mentionned at least as an alternative to --hard.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

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

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Jonathan Nieder <jrnieder@gmail.com> writes:
>
>> 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.
>
> Do we really want to keep the user manual compatible with 1.5.3
> forever? It's nice to keep the user manual usable by slightly outdated
> Gits, but 1.5.3 starts being really old,...

1.5.6 is more than 2 years old (June 18th, 2008), 1.5.3 is more than 3
years old (September 2nd, 2007).  In git timescale, they are becoming
prehistoric.

Even though the knowledge of the conceptual structure and the philosophy
learned with old versions like 1.5.X series would still apply to today's
git, at the UI level facing the end users, there are vast differences
(some may call that improvements ;-) between them and today's git.

I am tempted to say we should 1.5.X series behind, and name one that is
still relatively old like 1.6.3 (May 2009) or 1.6.4 (July 2009) the oldest
vintage we currently recognise as a proper member of our family.

What is the oldest version of git that is shipped with _current_ distros,
by the way?

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

[Matthieu Moy]

Junio C Hamano <gitster@pobox.com> writes:

> What is the oldest version of git that is shipped with _current_ distros,
> by the way?

Debian stable has 1.5.6.5. Since there should be a Debian release
within the next few months, that should be an upper bound on how old a
package can get in a release (well, unless for RedHat users maybe).

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Oldest Currently Distributed Git {Re: [RFC/PATCH 0/2] Documentation: kicking the "reset --hard" habit}

[Drew Northup]

On Sun, 2010-10-31 at 15:04 +0100, Matthieu Moy wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
> > What is the oldest version of git that is shipped with _current_ distros,
> > by the way?
> 
> Debian stable has 1.5.6.5. Since there should be a Debian release
> within the next few months, that should be an upper bound on how old a
> package can get in a release (well, unless for RedHat users maybe).
> 

EPEL for RHEL5 is 1.5.5.6 (plus security/bugfix patches).
RHEL5 itself doesn't have git (as if it did it wouldn't be in EPEL).

We await RHEL6--granted it will take a while to upgrade things to that
point after it comes out.

-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

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

[Ævar Arnfjörð Bjarmason]

On Sat, Oct 30, 2010 at 01:55, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:

>> 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.
>
> Do we really want to keep the user manual compatible with 1.5.3
> forever? It's nice to keep the user manual usable by slightly outdated
> Gits, but 1.5.3 starts being really old, and older docs are still
> available on the web (like
> http://www.kernel.org/pub/software/scm/git/docs/v1.5.3.8/git.html ).

I didn't know we even did this with our user manual. When I read
manuals for version X (e.g. PostgreSQL, Emacs or libc versions) I
fully expect the features described to only work on the documented
version unless otherwise noted.

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

[J. Bruce Fields]

On Sun, Oct 31, 2010 at 05:25:20PM +0000, Ævar Arnfjörð Bjarmason wrote:
> On Sat, Oct 30, 2010 at 01:55, Matthieu Moy
> <Matthieu.Moy@grenoble-inp.fr> wrote:
> 
> >> 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.
> >
> > Do we really want to keep the user manual compatible with 1.5.3
> > forever? It's nice to keep the user manual usable by slightly outdated
> > Gits, but 1.5.3 starts being really old, and older docs are still
> > available on the web (like
> > http://www.kernel.org/pub/software/scm/git/docs/v1.5.3.8/git.html ).
> 
> I didn't know we even did this with our user manual. When I read
> manuals for version X (e.g. PostgreSQL, Emacs or libc versions) I
> fully expect the features described to only work on the documented
> version unless otherwise noted.

Yeah, previous versions of the user manual are still around if people
need them.  For a book or an independent website a wider range of
versions would make more sense, but for documentation destributed with
the git source I think we can afford to be more aggressive.

If we think information about old versions is really important maybe
someone could find a way to incorporate it in a way that doesn't intrude
into the main text too much (e.g. footnotes or an appendix.)

--b.