mirror of
https://github.com/mhagger/git-imerge.git
synced 2024-09-21 04:28:11 +03:00
143 lines
5.0 KiB
ReStructuredText
143 lines
5.0 KiB
ReStructuredText
==================================================
|
|
git-imerge -- incremental merge and rebase for git
|
|
==================================================
|
|
|
|
Perform the 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-imerge`` has 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.
|
|
|
|
The best thing to read to get started is `git-imerge: A Practical
|
|
Introduction`_. If you want more information, the theory and benefits
|
|
of incremental merging are described in minute detail in a series of
|
|
blog posts [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 under ``refs/imerge/NAME``. The current
|
|
state of an incremental merge can (crudely) be visualized using the
|
|
``diagram`` command.
|
|
|
|
An incremental merge can be interrupted and resumed arbitrarily, or
|
|
even pushed to a server to allow somebody else to work on it.
|
|
|
|
**git-imerge is experimental! If it breaks, you get to keep the
|
|
pieces. For example, it is strongly recommended that you make a clone
|
|
of your git repository and run the script on the clone rather than the
|
|
original. Feedback and bug reports are welcome!**
|
|
|
|
|
|
Using results
|
|
=============
|
|
|
|
When an incremental merge is finished, you can discard the
|
|
intermediate merge commits and create a simpler history to record
|
|
permanently in your project repository using either the ``finish`` or
|
|
``simplify`` command. The incremental merge can be simplified in one
|
|
of three ways:
|
|
|
|
``merge``
|
|
keep only a simple merge of the second branch into the first
|
|
branch, discarding all intermediate merges. The result is similar
|
|
to what you would get from ::
|
|
|
|
git checkout BRANCH1
|
|
git merge BRANCH2
|
|
|
|
``rebase``
|
|
keep the versions of the commits from the second branch rebased
|
|
onto the first branch. The result is similar to what you would
|
|
get from ::
|
|
|
|
git checkout BRANCH2
|
|
git rebase BRANCH1
|
|
|
|
``rebase-with-history``
|
|
like rebase, except that each of the rebased commits is recorded
|
|
as a merge from its original version to its rebased predecessor.
|
|
This is a style of rebasing that does not discard the old version
|
|
of the branch, and allows an already-published branch to be
|
|
rebased. See [2]_ for more information.
|
|
|
|
|
|
Simple operation
|
|
================
|
|
|
|
For basic operation, you only need to know three ``git-imerge``
|
|
commands. To merge ``BRANCH`` into ``MASTER`` or rebase ``BRANCH``
|
|
onto ``MASTER``, ::
|
|
|
|
git checkout MASTER
|
|
git-imerge start --name=NAME --goal=GOAL --first-parent BRANCH
|
|
while not done:
|
|
<fix conflict presented to you>
|
|
git commit
|
|
git-imerge continue
|
|
git-imerge finish
|
|
|
|
where
|
|
|
|
``NAME``
|
|
is the name for this merge (and also the default name of the
|
|
branch to which the results will be saved)
|
|
|
|
``GOAL``
|
|
describes how you want to simplify the results:
|
|
|
|
* ``merge`` for a simple merge
|
|
|
|
* ``rebase`` for a simple rebase
|
|
|
|
* ``rebase-with-history`` for a rebase that retains history. This
|
|
is equivalent to merging the commits from BRANCH into MASTER, one
|
|
commit at a time. In other words, it transforms this::
|
|
|
|
o---o---o---o MASTER
|
|
\
|
|
A---B---C---D BRANCH
|
|
|
|
into this::
|
|
|
|
o---o---o---o---A'--B'--C'--D' MASTER
|
|
\ / / / /
|
|
--------A---B---C---D BRANCH
|
|
|
|
This is like a rebase, except that it retains the history of
|
|
individual merges. See [2]_ for more information.
|
|
|
|
|
|
License
|
|
=======
|
|
|
|
git-imerge is released as open-source software under the GNU General
|
|
Public License (GPL), version 2 or later.
|
|
|
|
|
|
.. _`git-imerge: A Practical Introduction`:
|
|
http://softwareswirl.blogspot.com/2013/05/git-imerge-practical-introduction.html
|
|
|
|
.. [1]
|
|
* http://softwareswirl.blogspot.com/2012/12/the-conflict-frontier-of-nightmare-merge.html
|
|
* http://softwareswirl.blogspot.com/2012/12/mapping-merge-conflict-frontier.html
|
|
* http://softwareswirl.blogspot.com/2012/12/real-world-conflict-diagrams.html
|
|
* http://softwareswirl.blogspot.com/2013/05/git-incremental-merge.html
|
|
* http://softwareswirl.blogspot.com/2013/05/one-merge-to-rule-them-all.html
|
|
* http://softwareswirl.blogspot.com/2013/05/incremental-merge-vs-direct-merge-vs.html
|
|
|
|
.. [2]
|
|
* http://softwareswirl.blogspot.com/2009/04/truce-in-merge-vs-rebase-war.html
|
|
* http://softwareswirl.blogspot.com/2009/08/upstream-rebase-just-works-if-history.html
|
|
* http://softwareswirl.blogspot.com/2009/08/rebase-with-history-implementation.html
|
|
|
|
|