Svnmerge.py
svnmerge.py is a tool for automatic branch management. It allows branch maintainers to merge changes from and to their branch very easily, and automatically records which changes were already merged. This allows displaying an always updated list of changes yet to be merged, and totally prevents merge mistakes (such as merging the same change twice). See our feature list for a more detailed description.
Features
- Merge tracking support: the tool remembers which revisions have been already merged, and always do the right thing by default (only merges new revisions).
- Specific support for development branches with a very simple "merge everything" command (does everything automatically).
- Specific support for release branches through cherry-picking: name and merge single revisions or revision ranges.
- List revisions available for merging (revision numbers, logs, or diffs).
- Bidirectional merges: merges changes forth and back between a branch and its head.
- Multiple heads support: merge changes from multiple sources. This is useful, for instance, for the trunk, which usually needs to merge changes from multiple branches.
- Revision blocking: mark some revisions as unwanted in the branch, so that they will never get merged and you can forget about them.
- Merge rollbacks: freely revert merges in case you changed your mind.
- Absolutely commit-free: the user will always have to do the commit himself, and thus will always have a chance to review svnmerge.py's modifications.
- Commit message suggestions: an informative commit message listing all the logs of the merged revisions is generated in a text file, as a suggestion for a good commit message.
- Manual merges support: if you merged some changes manually, you can inform svnmerge.py to update its merge tracking info.
System requirements
System requirements are down to a bare minimum, to lower as much as possible the bar for using the tool. Currently, you need:
- SVN command line client, version 1.1 or later.
It might actually work with an older version but it has never been tested. Notice that the command line client is required: so, noticeably, if you use TortoiseSVN, you need to go install the official SVN distribution to use svnmerge.py (and no, this causes no conflicts whatsoever!) - Python 2.0 or later.
This is used to run svnmerge.py directly from its source; another option is to download the binary Windows distribution (svnmerge.exe) which does not require an existing Python installation.
Downloads
| Link | Description |
|---|---|
| svnmerge.py trunk version | This is the default development version, which is usually very stable. Get it without worrying too much! |
| svnmerge.py 1.4-branch version | This is the version shipped with SVN 1.4. It's less updated than the trunk version so it will usually have less features but maybe be a little more stable. Get this if the current trunk version is temporarily broken. |
| svnmerge.exe Windows executable | Self-contained Windows executable, does not require a Python installation (but still requires SVN command line client). This is updated every once in a while, use --version to compare it with the trunk version. |
svnmerge.py is maintained within the Subversion repository. There is not a proper release plan or development map, so there are no official releases. svnmerge.py gets shipped with Subversion mostly 'the way it is' when Subversion itself is shipped. Thus, the trunk version is recommended: we believe it to be mostly stable (there is a quite extensive testsuite).
Quick tutorials
What follows are two quick tutorials for two common usage cases. These tutorials are meant to "feel" how svnmerge.py works: you are still encourage to read the full manual to get a better understanding of how the tool works.
Development branches
This tutorial assumes that you are working on a recently-created development branch, made off the trunk, that was never merged (that is, no changes have yet been imported from the trunk).
- Go to the top-level directory of a pristine working copy of the branch. svnmerge.py is meant to always operate in this condition (so let me repeat: top-level directory, no local modifications).
- Initialize merge tracking support:
$ svnmerge.py init
This command will scan the branch history to find out when the branch was created, so to initialize merge tracking support. This needs to be done only once for each branch you want to use svnmerge.py on.
- svnmerge.py never does a commit, so it's your turn. You can use the handy automatically generated file:
$ svn ci -F svnmerge-commit-message.txt $ rm svnmerge-commit-message.txt
Or use your favourite commit message.
- It's time to do a merge. To merge everything from the trunk into the branch, it's sufficient to do:
$ svnmerge.py merge
and that's it! Then, review the merge, fix any eventual conflict, and commit. There is a handy commit message listing the logs of all the merged revisions (can be quite long), which many people find useful.
- Repeat the last step at please, whenever you want to merge new changes from the trunk.
- If you want to have a look at what new changes are available to be merged from the trunk, do this:
$ svnmerge.py avail # show only the revision numbers $ svnmerge.py avail --logs # show logs of the revisions $ svnmerge.py avail --diffs # show diffs of the revisions
Release branches
This tutorial assumes that you are working on a recently-created release branch, made off the trunk, in which no changes were previously merged. With release branch, we mean a branch commonly used to stabilize a release: only a few selected changes must be merged from the trunk, the others must be ignored.
- Go to the top-level directory of a pristine working copy of the branch. svnmerge.py is meant to always operate in this condition (so let me repeat: top-level directory, no local modifications).
- Initialize merge tracking support:
$ svnmerge.py init
This command will scan the branch history to find out when the branch was created, so to initialize merge tracking support. This needs to be done only once for each branch you want to use svnmerge.py on.
- svnmerge.py never does a commit, so it's your turn. You can use the handy automatically generated file:
$ svn ci -F svnmerge-commit-message.txt $ rm svnmerge-commit-message.txt
Or use your favourite commit message.
- Review changes available on the trunk to be integrated into the branch:
$ svnmerge.py avail # show only the revision numbers $ svnmerge.py avail --logs # show logs of the revisions $ svnmerge.py avail --diffs # show diffs of the revisions
- When you identify specific revision(s) that you want to merge into the release branch, use the following command to do the merge:
$ svnmerge.py merge -r4500,4671,4812
Then review the changes and commit them. The automatically generated commit message (svnmerge-commit-message.txt) quotes the logs of the revisions that you have merged. These revisions will of course disappear from the list shown by svnmerge.py avail.
- When you identify specific revision(s) which are obviously not going to be integrated into the branch, mark them as blocked:
$ svnmerge.py block -r6456-6460,6881
and commit. These revisions will disappear from the list shown by svnmerge.py avail, so that you don't have to re-review them every time.
- Repeat the last two steps ad libitum, until you reduce the avail list to the bare minimum. A well-maintained release branch always has a small avail list of revisions which are still to be reviewed and/or discussed for backport into the branch: all the other revisions are either already merged or blocked.