From: Junio C Hamano <junkio@cox.net>
Date: Sat, 3 Feb 2007 06:40:49 +0000 (-0800)
Subject: Why is it bad to rewind a branch that has already been pushed out?
X-Git-Tag: v1.5.0-rc4~66
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=a9d1836b100d988bb292086eeab1ab826b3959f1;p=git.git

Why is it bad to rewind a branch that has already been pushed out?

I was reading the tutorial and noticed that we say this:

    Also, don't use "git reset" on a publicly-visible branch that
    other developers pull from, as git will be confused by history
    that disappears in this way.

I do not think this is a good explanation.  For example, if we
do this:

(1) I build a series and push it out.

	---o---o---o---j

(2) Alice clones from me, and builds two commits on top of it.

	---o---o---o---j---a---a

(3) I rewind one and build a few, and push them out.

	---o---o---o...j
                    \
                     h---h---h---h

(4) Alice pulls from me again:

	---o---o---o---j---a---a---*
                    \             /
                     h---h---h---h

Contrary to the description, git will happily have Alice merge
between the two branches, and never gets confused.

Maybe I did not want to have 'j' because it was an incomplete
solution to some problem, and Alice may have fixed it up with
her changes, while I abandoned that approach I started with 'j',
and worked on something completely unrelated in the four 'h'
commits.  In such a case, the merge Alice would make would be
very sensible, and after she makes the merge if I pull from her,
the world will be perfect.  I started something with 'j' and
dropped the ball, Alice picked it up and perfected it while I
went on to work on something else with 'h'.  This would be a
perfect example of distributed parallel collaboration.  There is
nothing confused about it.

The case the rewinding becomes problematic is if the work done
in 'h' tries to solve the same problem as 'j' tried to solve in
a different way.  Then the merge forced on Alice would make her
pick between my previous attempt with her fixups (j+a) and my
second attempt (h).  If 'a' commits were to fix up what 'j'
started, presumably Alice already studied and knows enough about
the problem so she should be able to make an informed decision
to pick between what 'j+a' and 'h' do.

A lot worse case is if Alice's work is not at all related to
what 'j' wanted to do (she did not mean to pick up from where I
left off -- she just wanted to work on something different).
Then she would not be familiar enough with what 'j' and 'h'
tried to achieve, and I'd be forcing her to pick between the
two.  Of course if she can make the right decision, then again
that is a perfect example of distributed collaboration, but that
does not change the fact that I'd be forcing her to clean up my
mess.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index ea3418909..5fc5be5a2 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -458,9 +458,9 @@ $ git reset --hard HEAD^ # reset your current branch and working
 Be careful with that last command: in addition to losing any changes
 in the working directory, it will also remove all later commits from
 this branch.  If this branch is the only branch containing those
-commits, they will be lost.  (Also, don't use "git reset" on a
-publicly-visible branch that other developers pull from, as git will
-be confused by history that disappears in this way.)
+commits, they will be lost.  Also, don't use "git reset" on a
+publicly-visible branch that other developers pull from, as it will
+force needless merges on other developers to clean up the history.
 
 The git grep command can search for strings in any version of your
 project, so