mirror of
https://github.com/git/git
synced 2024-08-25 10:45:59 +00:00
![Philip Oakley](/assets/img/avatar_default.png)
The asciidoctor doc-tool stack does not always respect the 'tab = 8 spaces' rule expectation, particularly for the Git-for-Windows generated html pages. This follows on from the 'doc: fix merge-base ASCII art tab spacing' fix. Use just spaces within the block of the ascii art. All other *.txt ascii art containing three dashes has been checked. Asciidoctor correctly formats the other art blocks that do contain tabs. Signed-off-by: Philip Oakley <philipoakley@iee.org Signed-off-by: Junio C Hamano <gitster@pobox.com>
274 lines
11 KiB
Plaintext
274 lines
11 KiB
Plaintext
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
|