Package: git-imerge
git-imerge -- incremental merge and rebase for GitPerform a merge between two branches incrementally. If conflicts are encountered, figure out exactly which pairs of commits conflict, and present the user with one pairwise conflict at a time for resolution.git-imergehas two primary design goals:Reduce the pain of resolving merge conflicts to its unavoidable minimum, by finding and presenting the smallest possible conflicts: those between the changes introduced by one commit from each branch.Allow a merge to be saved, tested, interrupted, published, and collaborated on while it is in progress.I think that it is easiest to understand the concept of incremental merging visually, and therefore I recommend the video of mygit-imerge presentation from the GitMerge 2013 conference(20 min) as a good place to start. The full slides for that talk are available in this repository underdoc/presentations/GitMerge-2013. At the same conference, I was interviewed aboutgit-imergeby Thomas Ferris Nicolaisen for hisGitMinutes Podcast #12.To learn how to use thegit-imergetool itself, I suggest the blog articlegit-imerge: A Practical Introductionand also typinggit-imerge --helpandgit-imerge SUBCOMMAND --help. If you want more information, the theory and benefits of incremental merging are described in minute detail in a series of blog articles [1], as are the benefits of retaining history when doing a rebase [2].Multiple incremental merges can be in progress at the same time. Each incremental merge has a name, and its progress is recorded in the Git repository as references underrefs/imerge/NAME. The current state of an incremental merge can be visualized using thediagramcommand.An incremental merge can be interrupted and resumed arbitrarily, or even pushed to a server to allow somebody else to work on it.git-imergecomes with a Bash completion script,completions/git-imerge, which is installed automatically when installinggit-imerge.Requirementsgit-imergerequires:A Python interpreter; eitherPython 3.x, version 3.3 or later.Python 2.x, version 2.6 or later. If you are using Python 2.6.x, then you have to install theargparsemodule yourself, as it was only added to the standard library in Python 2.7.A recent version of Git.Bash completion requires Git's completion being available.Installationgit-imergeis available on PyPI_, so you can install it withpip:$ pip install git-imergeor usingsetup.pyif you have downloaded the source package locally:$ python setup.py installInstructionsTo start a merge or rebase operation usinggit-imerge, you use commands that are similar to the correspondinggitcommands:git-imergecommandgitanalogueEffectgit-imerge merge BRANCHgit merge BRANCHMergeBRANCHinto the current branchgit-imerge rebase BRANCHgit rebase BRANCHRebase the current branch on top ofBRANCHgit-imerge revert COMMITgit revert COMMITAdd a new commit that undoes the effect ofCOMMITgit-imerge revert COMMIT1..COMMIT2git revert COMMIT1..COMMIT2Add new commits that undo the effects ofCOMMIT1..COMMIT2git-imerge drop COMMITgit rebase --onto COMMIT^ COMMITEntirely delete commitCOMMITfrom the history of the current branchgit-imerge drop COMMIT1..COMMIT2git rebase --onto COMMIT1 COMMIT2Entirely delete commitsCOMMIT1..COMMIT2from the history of the current branchgit-imerge dropis also analogous to runninggit rebase --interactive, then deleting the specified commit(s) from the history. Both thedropand therevertsubcommands are included in git-imerge because the equivalent git operations can conflict, so they both can benefit from using the incremental merge approach.)A few more options are available if you start the incremental merge usinggit imerge start:$ git-imerge start --name=NAME --goal=GOAL [--first-parent] BRANCHwhereNAMEis the name for this merge (and also the default name of the branch to which the results will be saved).GOALdescribes how you want to simplify the results (see next section).After the incremental merge is started, you will be presented with any conflicts that have to be resolved. The basic procedure is similar to performing an incremental merge usinggit:while not done:
    <fix the conflict that is presented to you>
    <"git add" the files that you changed>
    git-imerge continueWhen you have resolved all of the conflicts, you finish the incremental merge by typing:git-imerge finishThat should be enough to get you going. All of these subcommands have additional options; to learn about them type:git-imerge --help
git-imerge SUBCMD --helpSimplifying resultsWhen the incremental merge is finished, you can simplify its results in various ways before recording it in your project's permanent history by using either thefinishorsimplifycommand. The "goal" of the incremental merge can be one of the following:merge— keep only a simple merge of the second branch into the first branch, discarding all intermediate merges. The end result is similar to what you would get fromgit checkout BRANCH1
  git merge BRANCH2rebase— keep the versions of the commits from the second branch rebased onto the first branch. The end result is similar to what you would get fromgit checkout BRANCH2
  git rebase BRANCH1rebase-with-history— likerebase, except that it retains the old versions of the rebased commits in the history. It is equivalent to merging the commits fromBRANCH2intoBRANCH1, one commit at a time. In other words, it transforms this:o---o---o---o          BRANCH1
       \
        A---B---C---D    BRANCH2into this:o---o---o---o---A'--B'--C'--D'   NEW_BRANCH
       \         /   /   /   /
        --------A---B---C---DIt is safe to rebase an already-published branch using this
approach.  See [2] for more information.full— don't simplify the incremental merge at all: do all of the intermediate merges and retain them all in the permanent history. In other words, it transforms this:o---o---1---2---3      BRANCH1
       \
        A---B---C---D    BRANCH2into this:o---o---1---2---3
       \   \   \   \
        A---A1--A2--A3
         \   \   \   \
          B---B1--B2--B3
           \   \   \   \
            C---C1--C2--C3
             \   \   \   \
              D---D1--D2--D3    NEW_BRANCHThis approach retains the complete history and ancestry information, which gives the maximum flexibility for conducting future merges. On the other hand, it clutters up the permanent Git history considerably.border— this experimental goal retains the rebase ofBRANCH2ontoBRANCH1and also the rebase ofBRANCH1ontoBRANCH2, plus a merge commit that includes both branches. In other words, it transforms this:o---o---1---2---3      BRANCH1
       \
        A---B---C---D    BRANCH2into this:o---o---1---2---3
       \           \
        A           A2
         \           \
          B           B2
           \           \
            C           C2
             \           \
              D---D1--D2--D3    NEW_BRANCHThis approach leaves more history than a simple merge or rebase, possibly making future merges easier.border-with-history— this experimental goal retains therebase-with-history ofBRANCH2ontoBRANCH1and also the rebase (without history) ofBRANCH1ontoBRANCH2, plus a merge commit that includes both branches. In other words, it transforms this:o---o---1---2---3      BRANCH1
       \
        A---B---C---D    BRANCH2into this:o---o---1---2---3
       \           \
        A-----------A3
         \           \
          B-----------B3
           \           \
            C-----------C3
             \           \
              D---D1--D2--D3    NEW_BRANCHThis approach leaves more history and ancestry information than a simple merge or rebase, possibly making future merges easier.border-with-history2— this experimental goal retains therebase-with-historyofBRANCH1ontoBRANCH2and also therebase-with-historyofBRANCH2ontoBRANCH1, plus a merge commit that includes both branches. In other words, it transforms this:o---o---1---2---3      BRANCH1
       \
        A---B---C---D    BRANCH2into this:o---o---1---2---3
       \   \   \   \
        A--- --- ---A3
         \   \   \   \
          B--- --- ---B3
           \   \   \   \
            C--- --- ---C3
             \   \   \   \
              D---D1--D2--D3    NEW_BRANCHThis approach leaves more history and ancestry information than a simple merge or rebase, possibly making future merges easier.Technical notesSuspending/resumingWhengit-imergeneeds to ask the user to do a merge manually, it creates a temporary branchrefs/heads/imerge/NAMEto hold the result. If you want to suspend an incremental merge to do something else before continuing, all you need to do is abort any pending merge usinggit merge --abortand switch to your other branch. When you are ready to resume the incremental merge, just typegit imerge continue.If you need to completely abort an in-progress incremental merge, first remove the temporary branchesgit-imergecreates usinggit-imerge remove, then checkout the branch you were in before you started the incremental merge withgit checkout ORIGINAL_BRANCH.Storagegit-imergerecords all of the intermediate state about an incremental merge in the Git object database as a bunch of references underrefs/imerge/NAME, whereNAMEis the name of the imerge:refs/imerge/NAME/statepoints to a blob that describes the current state of the imerge in JSON format; for example,The tips of the two branches that are being mergedThe current "blocker" merges (merges that the user will have to do by hand), if anyThe simplification goalThe name of the branch to which the result will be written.refs/imerge/NAME/manual/I-Jandrefs/imerge/NAME/auto/I-Jrefer to the manual and automatic merge commits, respectively, that have been done so far as part of the incremental merge.IandJare integers indicating the location(I,J)of the merge in the incremental merge diagram.Transferring an in-progress imerge between repositoriesIt might sometimes be convenient to transfer an in-progress incremental merge from one Git repository to another. For example, you might want to make a backup of the current state, or continue an imerge at home that you started at work, or ask a colleague to do a particular pairwise merge for you. Since all of the imerge state is stored in the Git object database, this can be done by pushing/fetching the references named in the previous section. For example,$ git push --prune origin +refs/imerge/NAME/*:refs/imerge/NAME/*or$ git fetch --prune origin +refs/imerge/NAME/*:refs/imerge/NAME/*Please note that these commandsoverwriteany state that already existed in the destination repository. There is currently no support for combining the work done by two people in parallel on an incremental merge, so for now you'll just have to take turns.Interaction withgit rereregit rerereis a nice tool that records how you resolve merge conflicts, and if it sees the same conflict again it tries to automatically reuse the same resolution.Sincegit-imergeattempts so many similar test merges, it is easy to imaginerereregetting confused. Moreover,git-imergerelies on a merge resolving (or not resolving) consistently if it is carried out more than once. Havingrererestore extra information behind the scenes could therefore confusegit-imerge.Indeed, in testing it appeared that during incremental merges, the interaction ofgit-imergewithrererewas sometimes causing merge conflicts to be resolved incorrectly. Therefore,git-imergeexplicitly turns rerere off temporarily whenever it runs anygitcommands.Log messages for pairwise merge commitsWhengit imerge continueorgit imerge recordfinds a resolved merge in the working tree, it commits that merge then incorporates it into the incremental merge. Usually it just uses Git's autogenerated commit message for such commits. If you want to be prompted to edit such commit messages, you can either specify--editon the command line or change the default in your configuration:$ git config --global imerge.editmergemessages trueTestinggit-imergeusestoxto run tests. To run the test suite with the system's default Python:$ toxTo run with a specific Python version, such as 3.7, pass the-eargument totox:$ tox -e py37Licensegit-imergeis released as open-source software under the GNU General Public License (GPL), version 2 or later. See fileCOPYINGfor more information.References[1]http://softwareswirl.blogspot.com/2012/12/the-conflict-frontier-of-nightmare-merge.htmlhttp://softwareswirl.blogspot.com/2012/12/mapping-merge-conflict-frontier.htmlhttp://softwareswirl.blogspot.com/2012/12/real-world-conflict-diagrams.htmlhttp://softwareswirl.blogspot.com/2013/05/git-incremental-merge.htmlhttp://softwareswirl.blogspot.com/2013/05/one-merge-to-rule-them-all.htmlhttp://softwareswirl.blogspot.com/2013/05/incremental-merge-vs-direct-merge-vs.htmlhttp://softwareswirl.blogspot.com/2013/05/git-imerge-practical-introduction.html[2]http://softwareswirl.blogspot.com/2009/04/truce-in-merge-vs-rebase-war.htmlhttp://softwareswirl.blogspot.com/2009/08/upstream-rebase-just-works-if-history.htmlhttp://softwareswirl.blogspot.com/2009/08/rebase-with-history-implementation.html