Here ends the automated magic. Sooner or later, once you get the hang of branching and merging, you're going to have to ask Subversion to merge specific changes from one place to another. And in order to do this, you're going to have to start passing more complicated arguments to svn merge. This next section describes the fully-expanded syntax of the merge command, and discusses a number of common scenarios that require it.
Just as the term “changeset” is often used in version control systems, so is the term of cherrypicking. This word refers to the act of choosing one specific changeset from a branch and replicating it to another. Cherrypicking may also refer to the act of duplicating a particular set of (not necessarily contiguous!) changesets from one branch to another. This is in contrast to more typical merging scenarios, where the “next” contiguous range of revisions is duplicated automatically.
Why would people want to replicate just a single change?
It comes up more often than you'd think. For example, let's
go back in time and imagine that you haven't yet merged your
private feature-branch back to the trunk. At the
water-cooler, you get word that Sally made an interesting
change to integer.c on the trunk.
Looking over the history of commits to the trunk, you see that
in revision 355 she fixed a critical bug that directly
impacts the feature you're working on. You might not be ready
to merge all the trunk changes to your branch just yet, but
you certainly need that particular bugfix in order to continue
your work.
$ svn diff -c 355 http://svn.example.com/repos/calc/trunk
Index: integer.c
===================================================================
--- integer.c (revision 354)
+++ integer.c (revision 355)
@@ -147,7 +147,7 @@
case 6: sprintf(info->operating_system, "HPFS (OS/2 or NT)"); break;
case 7: sprintf(info->operating_system, "Macintosh"); break;
case 8: sprintf(info->operating_system, "Z-System"); break;
- case 9: sprintf(info->operating_system, "CP/MM");
+ case 9: sprintf(info->operating_system, "CP/M"); break;
case 10: sprintf(info->operating_system, "TOPS-20"); break;
case 11: sprintf(info->operating_system, "NTFS (Windows NT)"); break;
case 12: sprintf(info->operating_system, "QDOS"); break;
Just as you used svn diff in the prior example to examine revision 355, you can pass the same option to svn merge:
$ svn merge -c 355 http://svn.example.com/repos/calc/trunk U integer.c $ svn status M integer.c
You can now go through the usual testing procedures before committing this change to your branch. After the commit, Subversion marks r355 as having been merged to the branch, so that future “magic” merges that synchronize your branch with the trunk know to skip over r355. (Merging the same change to the same branch almost always results in a conflict!)
$ cd my-calc-branch
$ svn propget svn:mergeinfo .
/trunk:341-349,355
$ svn mergeinfo .
Path: .
Source path: /trunk
Merged ranges: r341:349,r355
Eligible ranges: r350:354,r356:360
$ svn merge http://svn.example.com/repos/calc/trunk
--- Merging r350 through r354 into '.':
U integer.c
U Makefile
--- Merging r356 through r360 into '.':
U integer.c
U button.c
This use-case of replicating (or backporting) bugfixes from one branch to another is perhaps the most popular reason for cherrypicking changes; it comes up all the time, for example, when a team is maintaining a “release branch” of software. (We discuss this pattern in “发布分支”一节.)
Did you notice how, in the last example, the merge invocation caused two distinct ranges of merges to be applied? The svn merge command applied two independent patches to your working copy in order to skip over changeset 355, which your branch already contained. There's nothing inherently wrong with this, except that it has the potential to make conflict-resolution more tricky. If the first range of changes creates conflicts, you must resolve them interactively in order for the merge process to continue and apply the second range of changes. If you postpone a conflict from the first wave of changes, the whole merge command will bail out with an error message.[21]
A word of warning: while svn diff and svn merge are very similar in concept, they do have different syntax in many cases. Be sure to read about them in 第 9 章 Subversion 完全参考 for details, or ask svn help. For example, svn merge requires a working-copy path as a target, i.e. a place where it should apply the generated patch. If the target isn't specified, it assumes you are trying to perform one of the following common operations:
你希望合并目录修改到工作拷贝的当前目录。
你希望合并修改到你的当前工作目录的相同文件名的文件。
如果你合并一个目录而没有指定特定的目标，svn merge假定第一种情况，在你的当前目录应用修改。如果你合并一个文件，而这个文件（或是一个有相同的名字文件）在你的当前工作目录存在，svn merge假定第二种情况，你想对这个同名文件使用合并。
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.
迷惑的主要原因是这个命令的名称，术语“合并”不知什么原因被用来表明分支的组合，或者是其他什么神奇的数据混合，这不是事实，一个更好的名称应该是svn diff-and-apply，这是发生的所有事件：首先两个版本库树比较，然后将区别应用到本地拷贝。
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 like
$ 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 only duplicate changes that your working copy
doesn't yet have. If you repeat this command once a week, it
will only duplicate 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, then the command takes three main arguments:
初始的版本树（通常叫做比较的左边），
最终的版本树（通常叫做比较的右边），
一个接收区别的工作拷贝（通常叫做合并的目标）。
一旦这三个参数指定以后，两个目录树将要做比较，比较结果将会作为本地修改应用到目标工作拷贝，当命令结束后，结果同你手工修改或者是使用svn add或svn delete没有什么区别，如果你喜欢这结果，你可以提交，如果不喜欢，你可以使用svn revert恢复修改。
svn merge的语法允许非常灵活的指定三个必要的参数，如下是一些例子：
$ 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
第一种语法使用URL@REV的形式直接列出了所有参数，第二种语法可以用来作为比较同一个URL的不同版本的简略写法，最后一种语法表示工作拷贝是可选的，如果省略，默认是当前目录。
svn merge另一个常用的做法是取消已经做得提交，假设你愉快的在/calc/trunk工作，你发现303版本对integer.c的修改完全错了，它不应该被提交，你可以使用svn merge来“取消”这个工作拷贝上所作的操作，然后提交本地修改到版本库，你要做得只是指定一个相反的区别。（你可以通过指定--revision 303:302--change -303
$ svn merge -c -303 http://svn.example.com/repos/calc/trunk --- Reverse-merging r303 into 'integer.c': U integer.c $ svn status M integer.c $ svn diff … # verify that the change is removed … $ svn commit -m "Undoing change committed in r303." Sending integer.c Transmitting file data . Committed revision 350.
As we mentioned earlier, one way to think about a
repository revision is as a specific changeset. By using the
-r option, you can ask svn
merge to apply a changeset, or whole range of
changesets, to your working copy. In our case of undoing a
change, we're asking svn merge to apply
changeset #303 to our working copy
backwards.
记住回滚修改和任何一个svn merge命令都一样，所以你应该使用svn status或是svn diff来确定你的工作处于期望的状态中，然后使用svn commit来提交，提交之后，这个特定修改集不会反映到HEAD版本了。
继续，你也许会想：好吧，这不是真的取消提交吧！是吧？版本303还依然存在着修改，如果任何人取出calc的303-349版本，他还会得到错误的修改，对吧？
Yes, that's true. When we talk about
“removing” a change, we're really talking about
removing it from the HEAD revision. The
original change still exists in the repository's history. For
most situations, this is good enough. Most people are only
interested in tracking the HEAD of a
project anyway. There are special cases, however, where you
really might want to destroy all evidence of the commit.
(Perhaps somebody accidentally committed a confidential
document.) This isn't so easy, it turns out, because
Subversion was deliberately designed to never lose
information. Revisions are immutable trees which build upon
one another. Removing a revision from history would cause a
domino effect, creating chaos in all subsequent revisions and
possibly invalidating all working copies.
[22]
版本控制系统非常重要的一个特性就是它的信息从不丢失，即使当你删除了文件或目录，它也许从HEAD版本消失了 ，但这个对象依然存在于历史的早期版本 ，一个新手经常问到的问题是“怎样找回我的文件和目录？”。
第一步首先要知道需要拯救的项目是什么，这里有个很有用的比喻：你可以认为任何存在于版本库的对象生活在一个二维的坐标系统里，第一维是一个特定的版本树，第二维是在树中的路径，所以你的文件或目录的任何版本可以通过这样一对坐标定义。（记住常见的“peg修订版本”语法— foo.c@224 — 在前面的“Peg 算法和版本”一节提到过。 ）
首先，你需要svn log来察看你需要找回的坐标对，一个好的策略是使用svn log --verbose来察看包含删除项目的目录，--verbose选项显示所有改变的项目的每一个版本 ，你只需要找出你删除文件或目录的那一个版本。你可以通过目测找出这个版本，也可以使用另一种工具来检查日志的输出 （通过grep或是在编辑器里增量查找）。
$ cd parent-dir $ svn log -v … ------------------------------------------------------------------------ r808 | joe | 2003-12-26 14:29:40 -0600 (Fri, 26 Dec 2003) | 3 lines Changed paths: D /calc/trunk/real.c M /calc/trunk/integer.c Added fast fourier transform functions to integer.c. Removed real.c because code now in double.c. …
在这个例子里，你可以假定你正在找已经删除了的文件real.c，通过查找父目录的历史 ，你知道这个文件在808版本被删除，所以存在这个对象的版本在此之前 。结论：你想从版本807找回/calc/trunk/real.c。
以上是最重要的部分—重新找到你需要恢复的对象。现在你已经知道该恢复的文件，而你有两种选择。
One option is to use svn merge to apply
revision 808 “in reverse”. (We've already
discussed how to undo changes, see
“取消修改”一节.) This
would have the effect of re-adding real.c
as a local modification. The file would be scheduled for
addition, and after a commit, the file would again exist
in HEAD.
在这个例子里，这不是一个好的策略，这样做不仅把real.c加入添加到计划，也取消了对integer.c的修改，而这不是你期望的。确实，你可以恢复到版本808，然后对integer.c执行取消svn revert操作，但这样的操作无法扩大使用，因为如果从版本808修改了90个文件怎么办？
所以第二个方法不是使用svn merge，而是使用svn copy命令，精确的拷贝版本和路径“坐标对”到你的工作拷贝：
$ svn copy http://svn.example.com/repos/calc/trunk/real.c@807 ./real.c $ svn status A + real.c $ svn commit -m "Resurrected real.c from revision 807, /calc/trunk/real.c." Adding real.c Transmitting file data . Committed revision 1390.
The plus sign in the status output indicates that the item
isn't merely scheduled for addition, but scheduled for
addition “with history”. Subversion remembers
where it was copied from. In the future, running svn
log on this file will traverse back through the
file's resurrection and through all the history it had prior
to revision 807. In other words, this new
real.c isn't really new; it's a direct
descendant of the original, deleted file. This is usually
considered a good and useful thing. If, however, you wanted
to resurrect the file without
maintaining a historical link to the old file, this technique
works just as well:
$ svn cat http://svn.example.com/repos/calc/trunk/real.c@807 > ./real.c $ svn add real.c A real.c $ svn commit -m "Recreated real.c from revision 807." Adding real.c Transmitting file data . Committed revision 1390.
Although our example shows us resurrecting a file, note that these same techniques work just as well for resurrecting deleted directories. Also note that a resurrection doesn't have to happen in your working copy—it can happen entirely in the repository:
$ svn copy http://svn.example.com/repos/calc/trunk/real.c@807 \
http://svn.example.com/repos/calc/trunk/
Committed revision 1390.
$ svn update
A real.c
Updated to revision 1390.
就像svn update命令，svn merge会把修改应用到工作拷贝，因此它也会造成冲突，因为svn merge造成的冲突有时候会有些不同，本小节会解释这些区别。
作为开始，我们假定本地没有修改，当你svn update到一个特定修订版本时，修改会“干净的”应用到工作拷贝，服务器产生比较两树的增量数据：一个工作拷贝和你关注的版本树的虚拟快照，因为比较的左边同你拥有的完全相同，增量数据确保你把工作拷贝转化到右边的树。
But svn merge has no such guarantees and can be much more chaotic: the advanced user can ask the server to compare any two trees at all, even ones that are unrelated to the working copy! This means there's large potential for human error. Users will sometimes compare the wrong two trees, creating a delta that doesn't apply cleanly. svn merge will do its best to apply as much of the delta as possible, but some parts may be impossible. Just as the Unix patch command sometimes complains about “failed hunks”, svn merge will complain about “skipped targets”:
$ svn merge -r 1288:1351 http://svn.example.com/repos/branch U foo.c U bar.c Skipped missing target: 'baz.c' U glub.c U sputter.h Conflict discovered in 'glorb.h'. Select: (p)ostpone, (d)iff, (e)dit, (h)elp for more options :
在前一个例子中，baz.c也许会存在于比较的两个分支快照里，但工作拷贝里不存在，比较的增量数据要应用到这个文件，这种情况下会发生什么？“skipped”信息意味着用户可能是在比较错误的两棵树，这是经典的用户错误，当发生这种情况，可以使用迭代恢复（svn revert --recursive）合并所作的修改，删除恢复后留下的所有未版本化的文件和目录，并且使用另外的参数运行svn merge。
也应当注意前一个例子显示glorb.h发生了冲突，我们已经规定本地拷贝没有修改：冲突怎么会发生呢？因为用户可以使用svn merge将过去的任何变化应用到当前工作拷贝，变化包含的文本修改也许并不能干净的应用到工作拷贝文件，即使这些文件没有本地修改。
另一个svn update和svn merge的小区别是冲突产生的文件的名字不同，在“解决冲突（合并别人的修改）”一节，我们看到过更新产生的文件名字为filename.mine、filename.rOLDREV和filename.rNEWREV，当svn merge产生冲突时，它产生的三个文件分别为 filename.working、filename.left和filename.right。在这种情况下，术语“left”和“right”表示了两棵树比较时的两边，在两种情况下，不同的名字会帮助你区分冲突是因为更新造成的还是合并造成的。
Sometimes there's a particular changeset which you don't
want to be automatically merged. For example, perhaps your
team's policy is to do new development work on
/trunk, but to be more conservative about
backporting changes to a “stable” branch you use
for releasing to the public. On one extreme, you can manually
cherrypick single changesets from trunk to the
branch—only the changes that are stable enough to pass
muster. Maybe things aren't quite that strict, though;
perhaps most of the time you'd like to just let svn
merge automatically merge most changes from trunk to
branch. In this case, you'd like a way to mask a few specific
changes out, i.e. prevent them from ever being automatically
merged.
In Subversion 1.5, the only way to block a changeset is to
make the system believe that the change has
already been merged. You'll need to
manually edit the svn:mergeinfo property on
the branch, and add the blocked revision(s) to the
list:
$ cd my-calc-branch $ svn propget svn:mergeinfo . /trunk:1680-3305 $ svn propset svn:mergeinfo "/trunk:1680-3305,3328" . property 'svn:mergeinfo' set on '.'
This technique works, but it's also a little bit dangerous. The main problem is that we're not differentiating between the ideas of “I don't want this change” and “I don't have this change”. We're effectively lying to the system, making it think that the change was previously merged. This puts the responsibility on you—the user—to remember that the change wasn't actually merged, it just wasn't wanted. There's no way to ask Subversion for a list of “blocked changelists”. If you want to track them (so that you can unblock them someday) you'll need to record it in a text file somewhere, or perhaps in an invented property. In Subversion 1.5, unfortunately, this is the only way to manage blocked revisions; the plans are to make a better interface for this in future versions.
One of the main features of any version control system is to keep track of who changed what, and when they did it. The svn log and svn blame commands are just the tools for this: when invoked on individual files, they show not only the history of changesets that affected the file, but exactly which user wrote which line of code, and when they did it.
When changes start getting replicated between branches, however, things start to get complicated. For example, if you were to ask svn log about the history of your feature branch, it shows exactly every revision that ever affected the branch:
$ cd my-calc-branch $ svn log -q ------------------------------------------------------------------------ r390 | user | 2002-11-22 11:01:57 -0600 (Fri, 22 Nov 2002) | 1 line ------------------------------------------------------------------------ r388 | user | 2002-11-21 05:20:00 -0600 (Thu, 21 Nov 2002) | 2 lines ------------------------------------------------------------------------ r381 | user | 2002-11-20 15:07:06 -0600 (Wed, 20 Nov 2002) | 2 lines ------------------------------------------------------------------------ r359 | user | 2002-11-19 19:19:20 -0600 (Tue, 19 Nov 2002) | 2 lines ------------------------------------------------------------------------ r357 | user | 2002-11-15 14:29:52 -0600 (Fri, 15 Nov 2002) | 2 lines ------------------------------------------------------------------------ r343 | user | 2002-11-07 13:50:10 -0600 (Thu, 07 Nov 2002) | 2 lines ------------------------------------------------------------------------ r341 | user | 2002-11-03 07:17:16 -0600 (Sun, 03 Nov 2002) | 2 lines ------------------------------------------------------------------------ r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines ------------------------------------------------------------------------ r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines ------------------------------------------------------------------------
But is this really an accurate picture of all the changes that happened on the branch? What's being left out here is the fact that revisions 390, 381, and 357 were actually the results of merging changes from trunk. If you look at a one of these logs in detail, the multiple trunk changesets that comprised the branch change are nowhere to be seen.
$ svn log -v -r 390 ------------------------------------------------------------------------ r390 | user | 2002-11-22 11:01:57 -0600 (Fri, 22 Nov 2002) | 1 line Changed paths: M /branches/my-calc-branch/button.c M /branches/my-calc-branch/README Final merge of trunk changes to my-calc-branch.
We happen to know that this merge to the branch was
nothing but a merge of trunk changes. How can we see those
trunk changes as well? The answer is to use
the --use-merge-history (-g) option. This
option expands those “child” changes that were
part of the merge.
$ svn log -v -r 390 -g ------------------------------------------------------------------------ r390 | user | 2002-11-22 11:01:57 -0600 (Fri, 22 Nov 2002) | 1 line Changed paths: M /branches/my-calc-branch/button.c M /branches/my-calc-branch/README Final merge of trunk changes to my-calc-branch. ------------------------------------------------------------------------ r383 | sally | 2002-11-21 03:19:00 -0600 (Thu, 21 Nov 2002) | 2 lines Changed paths: M /branches/my-calc-branch/button.c Result of a merge from: r390 Fix inverse graphic error on button. ------------------------------------------------------------------------ r382 | sally | 2002-11-20 16:57:06 -0600 (Wed, 20 Nov 2002) | 2 lines Changed paths: M /branches/my-calc-branch/README Result of a merge from: r390 Document my last fix in README.
By making the log operation use merge history, we see not just the revision we queried (r390), but the two revisions that came along on the ride with it—a couple of changes made by Sally to the trunk. This is a much more complete picture of history!
The svn blame command also takes
the --use-merge-history (-g) option. If this
option is neglected, then somebody looking at a line-by-line
annotation of button.c may get the
mistaken impression that you were responsible for the lines
that fixed a certain error:
$ svn blame button.c ... 390 user retval = inverse_func(button, path); 390 user return retval; 390 user } ...
And while it's true that you did actually commit those three lines in revision 390, two of them were actually writen by Sally back in revision 383:
$ svn blame button.c -g
...
G 383 sally retval = inverse_func(button, path);
G 383 sally return retval;
390 user }
...
Now we know who to really blame for those two lines of code!
当与Subversion开发者交谈时你一定会听到提及术语祖先，这个词是用来描述两个对象的关系：如果他们互相关联，一个对象就是另一个的祖先，或者相反。
举个例子，假设你提交版本100，包括对foo.c的修改，则foo.c@99是foo.c@100的一个“祖先”，另一方面，假设你在版本101删除这个文件，而在102版本提交一个同名的文件，在这个情况下，foo.c@99与foo.c@102看起来是关联的（有同样的路径），但是事实上他们是完全不同的对象，它们并不共享同一个历史或者说“祖先”。
指出svn diff和svn merge区别的重要性在于，前一个命令忽略祖先，如果你询问svn diff来比较文件foo.c的版本99和102，你会看到行为基础的区别，diff命令只是盲目的比较两条路径，但是如果你使用svn merge是比较同样的两个对象，它会注意到他们是不关联的，而且首先尝试删除旧文件，然后添加新文件，输出会是一个删除紧接着一个增加：
D foo.c
A foo.c
大多数合并包括比较包括祖先关联的两条树，因此svn merge这样运作，然而，你也许会希望merge命令能够比较两个不相关的目录树，举个例子，你有两个目录树分别代表了卖主软件项目的不同版本（见“卖主分支”一节），如果你使用svn merge进行比较，你会看到第一个目录树被删除，而第二个树添加上！在这个情况下，你仅仅是希望svn merge以路径为基础比较两棵树，而忽略文件和目录的不相关性，当为合并命令添加--ignore-ancestry选项时，就会像svn diff一样工作。（相反，--notice-ancestry会导致svn diff像merge命令一样工作。）
一个普遍的愿望是重构源程序，特别是Java软件项目。在改名中文件和目录变乱，通常导致每个项目成员的极大破坏。听起来好像应该使用分支，不是吗？只是创建分支，变乱事情，然后合并回主干，不对吗？
唉，这个场景下这样并不正确，可以看作Subversion当前的弱点，这个问题是因为Subversion的update还不是足够的强壮，特别是针对拷贝和移动操作。
当你使用svn copy复制文件时，版本库会记住新文件的出处，但是它不能将这个信息传递给使用svn update或svn merge的客户端，不是告诉客户端“ 将文件拷贝到新的位置”，而是传递一整个新文件。这样会导致问题，特别是因为这件事也发生在改名的文件。 一个鲜为人知的事实是Subversion缺乏真正的重命名—svn move命令只是一个svn copy和svn delete的组合。
例如，假定我们在一个私有分支工作，你将integer.c改名为whole.c，你这是在分支上创建了原来文件的一个拷贝，并且删除了原来的文件。同时，回到trunk，Sally提交了一些integer.c的修改，所以你需要将分支合并到主干：
$ cd calc/trunk
$ svn merge --reintegrate http://svn.example.com/repos/calc/branches/my-calc-branch
D integer.c
A whole.c
第一眼看起来不是很差，但是很可能这不是你和Sally希望的，合并操作已经删除了最新版本的integer.c（包含了Sally最新的修改），而且盲目的添加了你的whole.c文件—是旧版本的integer.c复制品。最终的结果是将你的“rename”合并到分支，并且从最新修订版本删除了Sally最近的修改。
这不是真的数据丢失；Sally的修改还在版本库的历史中，但是。在Subversion改进之前，最好小心对分支进行合并和改名。
If you've just upgraded your server to Subversion 1.5 or
later, then there's a significant risk that pre-1.5 Subversion
clients can mess up your merge-tracking. Why is this? When a
pre-1.5 Subversion client performs svn
merge, it doesn't modify the value of
the svn:mergeinfo property at all. So the
subsequent commit, despite being the result of a merge,
doesn't tell the repository about the duplicated
changes—that information is lost. Later on,
when “merge-aware” clients attempt automatic
merging, they're likely to run into all sorts of conflicts
resulting from repeated merges.
If you and your team are relying on the merge-tracking
features of Subversion, then you may want to configure your
repository to prevent older clients from committing changes.
The easy way to do this is by inspecting
the “capabilities” parameter in
the start-commit hook script. If the
client reports itself as having mergeinfo
capabilities, the hook script can allow the commit to start.
If the client doesn't report that capability, have the hook
deny the commit. We'll learn more about hook scripts in the
next chapter; see
“实现版本库钩子”一节 and
start-commit for
details.
[21] At least, this is true in Subversion 1.5 at the time of writing. This behavior may improve in future versions of Subversion.
[22] Subversion项目有计划，不管用什么方式，会有一天要实现svnadmin obliterate命令来进行永久删除操作，而此时可以看“svndumpfilter”一节找到可行的方案。