Quick SVN merging guide

Calling SVN merge

The basic usage for svn merge is:

svn merge <what> <from> <to>

Where <from> and <to> are the paths of the source and destination files or directories. <to> has to be a file system path, <from> can be either a file system path or a URL, and <what> indicates which revision(s) to merge (more about that below). If <to> is not specified, it defaults to either . (current directory) if <from> is a directory, or to the base name of <from> if its a file.

There are more usage modes than the ones covered here; run svn help merge to learn everything you ever wanted to know about svn merge .

When run, svn merge will apply the specified revisions as a local modification to the destination path. This means you still have to commit the merge.

Merging individual revisions

To merge an individual revision, use svn merge -c revid from to. Example:

$ cd ~/mediawiki/branches/wmf/1.16wmf4
$ svn merge -c 76077 ../../../trunk/phase3/includes/api/ includes/api/
--- Merging r76077 into 'includes/api/ApiLogin.php':
U    includes/api/ApiLogin.php
$

Merging ranges of revisions

To merge a range of revisions, use svn merge -r start:end from to where start and end are revision IDs. This will merge all revisions starting at start+1 up to and INCLUDING end.

Note: it will NOT include the first revision (ex: -r3:45 will merge 4 through 45). This means that, for instance, 76077:76077 is a useless empty range, 76077:76078 is a range containing one revision (r76078) and -c 12345 is equivalent to -r 12344:12345.

Reverting (ranges of) revisions

To revert (SVN lingo: reverse-merge) a range, simply swap the start and end revisions, e.g. -r 76100:76077 to revert -r 76077:76100 . To revert a single revision, use a negative revision ID, e.g. -c -76077 to revert r76077 (this is equivalent to -r 76077:76076).

Conflicts

In its interaction with the user, svn merge is very similar to svn up in that it outputs file names with status markers (Updated, Added, Deleted, Conflicted, ...) and asks the user what to do when it encounters a conflict. Merge conflicts are presented and resolved just like normal conflicts thrown by svn up .

Tips and tricks

Although the basics are fairly simple, merging is a true art (or the seventh circle of hell, depending on who you ask) in complex cases. I can provide some tips to help you along, but experience and a good understanding of SVN merging is required for complex merges.

• Have a clean working copy when you start. A failed merge can make it very hard to get your original changes back
• When something goes wrong, consider using svn revert to undo your changes and start over
• When doing multi-step merges, it may be wise to back up your tree (or the diff) between steps so you can go back to the previous state easily
• When you get a conflict, don't panic right away, but try to at least look at the conflict; many conflicts are trivial
• SVN allows you to postpone a conflict, leaving the conflict markers for you to resolve later, and in some cases does this automatically. Files marked as conflicted show up with a C in svn status, and SVN will refuse to commit such files. Use svn resolved filename to mark a conflicted file as resolved
  • There are multiple ways in which you can accidentally mark a file that still contains conflict markers as resolved. Before committing a merge, check your diff (as you should for every commit anyway) and keep an eye out for conflict markers. Conflict markers are <<<<<, ===== and >>>>>