You’ve now seen some examples of the svn merge command, and you’re about to see several more. If you’re feeling confused about exactly how merging works, you’re not alone. Many users (especially those new to version control) are initially perplexed about the proper syntax of the command and about how and when the feature should be used. But fear not, this command is actually much simpler than you think! There’s a very easy technique for understanding exactly how svn merge behaves.

The main source of confusion is the name of the command. The term “merge” somehow denotes that branches are combined together, or that some sort of mysterious blending of data is going on. That’s not the case. A better name for the command might have been svn diff-and-apply, because that’s all that happens: two repository trees are compared, and the differences are applied to a working copy.

If you’re using svn merge to do basic copying of changes between branches, it will generally do the right thing automatically. For example, a command such as the following:

$ svn merge http://svn.example.com/repos/calc/some-branch

will attempt to duplicate any changes made on some-branch into your current working directory, which is presumably a working copy that shares some historical connection to the branch. The command is smart enough to duplicate only changes that your working copy doesn’t yet have. If you repeat this command once a week, it will duplicate only the “newest” branch changes that happened since you last merged.

If you choose to use the svn merge command in all its full glory by giving it specific revision ranges to duplicate, the command takes three main arguments:

Once these three arguments are specified, the two trees are compared, and the differences are applied to the target working copy as local modifications. When the command is done, the results are no different than if you had hand-edited the files or run various svn add or svn delete commands yourself. If you like the results, you can commit them. If you don’t like the results, you can simply svn revert all of the changes.

The syntax of svn merge allows you to specify the three necessary arguments rather flexibly. Here are some examples:

$ svn merge http://svn.example.com/repos/branch1@150 
            http://svn.example.com/repos/branch2@212 
            my-working-copy

$ svn merge -r 100:200 http://svn.example.com/repos/trunk my-working-copy

$ svn merge -r 100:200 http://svn.example.com/repos/trunk

The first syntax lays out all three arguments explicitly, naming each tree in the form URL@REV and naming the working copy target. The second syntax can be used as a shorthand for situations when you’re comparing two different revisions of the same URL. The last syntax shows how the working copy argument is optional; if omitted, it defaults to the current directory.

While the first example shows the “full” syntax of svn merge, it needs to be used very carefully; it can result in merges that do not record any svn:mergeinfo metadata at all. The next section talks a little more about this.