The xMerge ('cross-merge') add-on helps to automate merging of moved and renamed files for single-source merges.
The default merge implementation provided by Subversion lacks 'true rename' support. The most recent stable version (SVN 1.6.x) currently is able only to raise a tree conflict for a file which was copied or moved at some certain moment in history, if that copy breaks somehow normal merge process on that file. The user then has to manually fix that kind of conflict by running sub-merges or reverting modified files.
xMerge inherits the default merge implementation. This means, that xMerge behaves the way default merge implementation does in case a file can be processed properly. In addition, xMerge also overrides the default merge behavior to process those files which are skipped by the default merge implementation.
Diagram A sample use-case illustrates a basic use-case of xMerge when working with a 'release branch'. The release branch branch has been forked off the trunk. The branch should only receive the minimal amount of changes which are required to fix a bug. In terms of revisions this means that only those revisions should be merged from trunk which are actually bug-fixes. Now, a common problem is that restructuring/refactoring in trunk may result in file moves/renames and hence fixes to those files can't be merged back to the trunk using default SVN merge implementation anymore. The older a branch is the more pressing this problem can get.
With default SVN merge, the solution is either to manually merge the bug-fix revision by selecting the file in the branch and merging from the corresponding trunk file. This can be cumbersome for a larger amount of files and is error-prone. Or one could merge the necessary restructurings/refactorings to the branch, too, but this contradicts the requirement of 'minimal amount of changes required'.
This is where xMerge comes into play. xMerge will be able to identify the corresponding file(s) in the branch. It will display an overview of the planned merge showing which files from the merge source will be merged to which files in the local working copy and on confirmation, properly perform that merge.
To enable xMerge, select Enable xMerge for merging renamed/moved files in the Merge dialog. Optionally, select For xMerge, ignore simple copies on the Advanced page.
When performing Merge, SmartSVN will now start a dry-merge run to collect information on what will happen during the merge. xMerge requires the working copy to be at a clean revision. It will ask you to update to the maximum revision found in your working copy, in case you have mixed revisions. This usually is a safe operation, however note that by the update missing files might be re-fetched, so it's recommended to schedule such files for removal before performing the merge.
If during this dry-run phase, files which will be skipped by SVN's default merge will be encountered or -- if option For xMerge, ignore simple copies had been de-selected -- will be encountered, the Merge Preview will come up, containing the xMerge Resolutions control in the upper area.
The xMerge Resolutions control shows all files which are processible by xMerge. For every file, the table displays the merge Source path, the selected Resolution, the Target path in the local working copy and the adjusted Copy From information. The resolution can be adjusted by the radio controls below the table which will also affect Target and Copy From. Resolutions can also be adjusted for multiple files at once by selecting those files and using the radio controls.
Depending on the selected resolutions, the Directories/Files preview will show the overall planned merge result. Use Merge|Perform Merge to finally perform the merge as previewed.
Use this option to let SVN's default merge implementation process the file. This option will only be available, if the file is actually processible, i.e. if it wouldn't be skipped. This is typically the case for copied files, if option For xMerge, ignore simple copies had been selected in the Merge dialog.
Use this option to not process the file by the merge. This option is available, if the file is not processible by SVN's default merge implementation, i.e. if the file would be skipped.
Use this option to apply the changes of the selected file (in the selected revisions) onto an existing working copy file. This option will be available, if xMerge could associate the source file with an existing file in the working copy.
Use this option to copy the source file as it is to a new file in the local working copy. Optionally you may select and set 'copy-from' to to adjust the history-information of the newly added file in the working copy:
By default, SVN will link the added file's history to that of the source file. For example, if branch/dir/oldfile will be merged to trunk/dir/newfile, trunk/dir/newfile will be linked with branch/dir/oldfile. In most cases, it will be more appropriate to link trunk/dir/newfile to trunk/dir/oldfile, if that file exists. The history link is adjusted this way when and set 'copy-from' to has been selected.
Copy source file to will be available for added, copied or moved/renamed source files. and set 'copy-from' to will only be available for copied or moved/renamed source files for which the copy-source in the merge source could be associated with a corresponding file in the working copy.
Use this option to apply the changes of the selected file (in the selected revisions) onto the content of an existing working copy file, but store the merge result as a new file in the working copy. The history of the new file ('copy-from') will be linked to the existing working copy file.
This option is a kind of combination of Apply source changes to and Copy source file to and will be available if the source file has been moved/renamed in the selected source revisions and xMerge could associate this file with an existing file in the working copy.