Documentation/stash: remove mention of git reset --hard

[git.git] / Documentation / howto / revert-a-faulty-merge.txt

Date: Fri, 19 Dec 2008 00:45:19 -0800
From: Linus Torvalds <torvalds@linux-foundation.org>, Junio C Hamano <gitster@pobox.com>
Subject: Re: Odd merge behaviour involving reverts
Abstract: Sometimes a branch that was already merged to the mainline
 is later found to be faulty.  Linus and Junio give guidance on
 recovering from such a premature merge and continuing development
 after the offending branch is fixed.
Message-ID: <7vocz8a6zk.fsf@gitster.siamese.dyndns.org>
References: <alpine.LFD.2.00.0812181949450.14014@localhost.localdomain>
Content-type: text/asciidoc

How to revert a faulty merge
============================

Alan <alan@clueserver.org> said:

    I have a master branch.  We have a branch off of that that some
    developers are doing work on.  They claim it is ready. We merge it
    into the master branch.  It breaks something so we revert the merge.
    They make changes to the code.  they get it to a point where they say
    it is ok and we merge again.

    When examined, we find that code changes made before the revert are
    not in the master branch, but code changes after are in the master
    branch.

and asked for help recovering from this situation.

The history immediately after the "revert of the merge" would look like
this:

 ---o---o---o---M---x---x---W
               /
       ---A---B

where A and B are on the side development that was not so good, M is the
merge that brings these premature changes into the mainline, x are changes
unrelated to what the side branch did and already made on the mainline,
and W is the "revert of the merge M" (doesn't W look M upside down?).
IOW, `"diff W^..W"` is similar to `"diff -R M^..M"`.

Such a "revert" of a merge can be made with:

    $ git revert -m 1 M

After the developers of the side branch fix their mistakes, the history
may look like this:

 ---o---o---o---M---x---x---W---x
               /
       ---A---B-------------------C---D

where C and D are to fix what was broken in A and B, and you may already
have some other changes on the mainline after W.

If you merge the updated side branch (with D at its tip), none of the
changes made in A or B will be in the result, because they were reverted
by W.  That is what Alan saw.

Linus explains the situation:

    Reverting a regular commit just effectively undoes what that commit
    did, and is fairly straightforward. But reverting a merge commit also
    undoes the _data_ that the commit changed, but it does absolutely
    nothing to the effects on _history_ that the merge had.

    So the merge will still exist, and it will still be seen as joining
    the two branches together, and future merges will see that merge as
    the last shared state - and the revert that reverted the merge brought
    in will not affect that at all.

    So a "revert" undoes the data changes, but it's very much _not_ an
    "undo" in the sense that it doesn't undo the effects of a commit on
    the repository history.

    So if you think of "revert" as "undo", then you're going to always
    miss this part of reverts. Yes, it undoes the data, but no, it doesn't
    undo history.

In such a situation, you would want to first revert the previous revert,
which would make the history look like this:

 ---o---o---o---M---x---x---W---x---Y
               /
       ---A---B-------------------C---D

where Y is the revert of W.  Such a "revert of the revert" can be done
with:

    $ git revert W

This history would (ignoring possible conflicts between what W and W..Y
changed) be equivalent to not having W or Y at all in the history:

 ---o---o---o---M---x---x-------x----
               /
       ---A---B-------------------C---D

and merging the side branch again will not have conflict arising from an
earlier revert and revert of the revert.

 ---o---o---o---M---x---x-------x-------*
               /                       /
       ---A---B-------------------C---D

Of course the changes made in C and D still can conflict with what was
done by any of the x, but that is just a normal merge conflict.

On the other hand, if the developers of the side branch discarded their
faulty A and B, and redone the changes on top of the updated mainline
after the revert, the history would have looked like this:

 ---o---o---o---M---x---x---W---x---x
               /                 \
       ---A---B                   A'--B'--C'

If you reverted the revert in such a case as in the previous example:

 ---o---o---o---M---x---x---W---x---x---Y---*
               /                 \         /
       ---A---B                   A'--B'--C'

where Y is the revert of W, A' and B' are rerolled A and B, and there may
also be a further fix-up C' on the side branch.  `"diff Y^..Y"` is similar
to `"diff -R W^..W"` (which in turn means it is similar to `"diff M^..M"`),
and `"diff A'^..C'"` by definition would be similar but different from that,
because it is a rerolled series of the earlier change.  There will be a
lot of overlapping changes that result in conflicts.  So do not do "revert
of revert" blindly without thinking..

 ---o---o---o---M---x---x---W---x---x
               /                 \
       ---A---B                   A'--B'--C'

In the history with rebased side branch, W (and M) are behind the merge
base of the updated branch and the tip of the mainline, and they should
merge without the past faulty merge and its revert getting in the way.

To recap, these are two very different scenarios, and they want two very
different resolution strategies:

 - If the faulty side branch was fixed by adding corrections on top, then
   doing a revert of the previous revert would be the right thing to do.

 - If the faulty side branch whose effects were discarded by an earlier
   revert of a merge was rebuilt from scratch (i.e. rebasing and fixing,
   as you seem to have interpreted), then re-merging the result without
   doing anything else fancy would be the right thing to do.
   (See the ADDENDUM below for how to rebuild a branch from scratch
   without changing its original branching-off point.)

However, there are things to keep in mind when reverting a merge (and
reverting such a revert).

For example, think about what reverting a merge (and then reverting the
revert) does to bisectability. Ignore the fact that the revert of a revert
is undoing it - just think of it as a "single commit that does a lot".
Because that is what it does.

When you have a problem you are chasing down, and you hit a "revert this
merge", what you're hitting is essentially a single commit that contains
all the changes (but obviously in reverse) of all the commits that got
merged. So it's debugging hell, because now you don't have lots of small
changes that you can try to pinpoint which _part_ of it changes.

But does it all work? Sure it does. You can revert a merge, and from a
purely technical angle, Git did it very naturally and had no real
troubles. It just considered it a change from "state before merge" to
"state after merge", and that was it. Nothing complicated, nothing odd,
nothing really dangerous. Git will do it without even thinking about it.

So from a technical angle, there's nothing wrong with reverting a merge,
but from a workflow angle it's something that you generally should try to
avoid.

If at all possible, for example, if you find a problem that got merged
into the main tree, rather than revert the merge, try _really_ hard to
bisect the problem down into the branch you merged, and just fix it, or
try to revert the individual commit that caused it.

Yes, it's more complex, and no, it's not always going to work (sometimes
the answer is: "oops, I really shouldn't have merged it, because it wasn't
ready yet, and I really need to undo _all_ of the merge"). So then you
really should revert the merge, but when you want to re-do the merge, you
now need to do it by reverting the revert.

ADDENDUM

Sometimes you have to rewrite one of a topic branch's commits *and* you can't
change the topic's branching-off point.  Consider the following situation:

 P---o---o---M---x---x---W---x
  \         /
   A---B---C

where commit W reverted commit M because it turned out that commit B was wrong
and needs to be rewritten, but you need the rewritten topic to still branch
from commit P (perhaps P is a branching-off point for yet another branch, and
you want be able to merge the topic into both branches).

The natural thing to do in this case is to checkout the A-B-C branch and use
"rebase -i P" to change commit B.  However this does not rewrite commit A,
because "rebase -i" by default fast-forwards over any initial commits selected
with the "pick" command.  So you end up with this:

 P---o---o---M---x---x---W---x
  \         /
   A---B---C   <-- old branch
    \
     B'---C'   <-- naively rewritten branch

To merge A-B'-C' into the mainline branch you would still have to first revert
commit W in order to pick up the changes in A, but then it's likely that the
changes in B' will conflict with the original B changes re-introduced by the
reversion of W.

However, you can avoid these problems if you recreate the entire branch,
including commit A:

   A'---B'---C'  <-- completely rewritten branch
  /
 P---o---o---M---x---x---W---x
  \         /
   A---B---C

You can merge A'-B'-C' into the mainline branch without worrying about first
reverting W.  Mainline's history would look like this:

   A'---B'---C'------------------
  /                              \
 P---o---o---M---x---x---W---x---M2
  \         /
   A---B---C

But if you don't actually need to change commit A, then you need some way to
recreate it as a new commit with the same changes in it.  The rebase command's
--no-ff option provides a way to do this:

    $ git rebase [-i] --no-ff P

The --no-ff option creates a new branch A'-B'-C' with all-new commits (all the
SHA IDs will be different) even if in the interactive case you only actually
modify commit B.  You can then merge this new branch directly into the mainline
branch and be sure you'll get all of the branch's changes.

You can also use --no-ff in cases where you just add extra commits to the topic
to fix it up.  Let's revisit the situation discussed at the start of this howto:

 P---o---o---M---x---x---W---x
  \         /
   A---B---C----------------D---E   <-- fixed-up topic branch

At this point, you can use --no-ff to recreate the topic branch:

    $ git checkout E
    $ git rebase --no-ff P

yielding

   A'---B'---C'------------D'---E'  <-- recreated topic branch
  /
 P---o---o---M---x---x---W---x
  \         /
   A---B---C----------------D---E

You can merge the recreated branch into the mainline without reverting commit W,
and mainline's history will look like this:

   A'---B'---C'------------D'---E'
  /                              \
 P---o---o---M---x---x---W---x---M2
  \         /
   A---B---C