Permalink
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>
273 lines (206 sloc)
10.6 KB
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |