How to use svn merge

2006-10-29 23:49:10 -08:00

A number of my fellow Adium developers have observed that svn merge is hard to use. I think the main problem is that the command is quite general (it can be put to several different uses) and the documentation not particularly clear. In order to promote better understanding of the svn merge command, here’s what I know about it.

The command in a nutshell: svn merge is essentially svn diff $ARGS | patch -p0; the only real difference is that svn merge will handle addition, movement, and deletion of files, whereas patch won’t.

This now having been stated up front, let’s get into details.

Summary of tasks and how to do them

  1. svn merge sourceURL1[@N] sourceURL2[@M] [WCPATH]
  2. svn merge sourceWCPATH1@N sourceWCPATH2@M [WCPATH]
  3. svn merge [-c M | -r N:M] SOURCE[@REV] [WCPATH]
  • To apply changes from another directory (branch, tag, trunk): Use format #1 (or #2 if you have a checkout of it), supplying at least the first revision (N), and the second (M) if it is not HEAD. With format #1, you should not need to be using the same repository URL as the CWD for either one or both; you should be able to merge between two URLs, or between a single URL into your checkout of a different URL.

  • To travel back in time to a previous revision: Use format #3, with -rHEAD:THEN. For example, -rHEAD:42000.

  • To cherry-pick a changeset (apply only that changeset, not any others): Use format #3, with -cTHEN.

  • To undo a particular changeset without disturbing things that happened after it (hopefully): Use format #3, with -c –THEN. Note the minus sign. For example, to revert r42000, use “svn merge -c -42000 .”. You can also use the -r flag: “svn merge -r 42000:41999 .”. This may be advisable, for clarity reasons, if you have a script that must always revert a particular revision.

    In both examples, note the “.” and the space before it. “.” means the current directory, and is used here as the SOURCE argument to format #3. It’s a separate argument from the revision, so you need the space.

  • All formats apply their changes to the CWD by default. I don’t know what happens if the CWD is not a WC. You can specify a different destination for the changes by specifying a different WCPATH (the last argument in all the formats above).

  • In format #3, the first path that it accepts is a URL or local WC path to the object you want to diff. (Remember my initial statement about svn merge being essentially svn diff | patch -p0.) The second path is a local WC path to the destination for the changes that are observed.

Updated 2007-07-12: Fixed error in traveling back in time (I had the revs backward); added cherry-picking technique.

svn help merge, in RTF

The “svn help merge” text is an invaluable summary of the command’s operation, but it’s plain-text, and therefore somewhat hard to read on a screen. To that end, I created an RTF version and printed it out, and decided to put it up here in case anyone else wants to do the same.

Leave a Reply

Do not delete the second sentence.