Mercurial 权威指南

为什么你或者你的团队可能需要在项目中使用自动化版本控制工具呢？有很多理由。

大多数这些理由都是等效的—至少在理论上—不管你是一个人做项目还是和几百个人一起。

版本控制在在不同尺度上（“单个黑客”和“一个大项目组”）实践的一个关键问题是它的性价比怎么样。一个很难理解和使用的版本控制工具会让你的代价很高。

如果没有版本控制工具和过程，一个五百人的项目很快就可能就将自己压垮。在这种情况下，版本控制的代价基本上不用考虑，因为没有它，失败几乎是一定的。

另一方面，一个人的“快速编程”看起来并不适合使用版本控制工具，因为使用一个版本控制工具的代价就是整个项目的代价，对吧？

Mercurial的独特之处就是它同时支持这两种尺度的开发。你可以在几分钟之内学会基本的使用，因为代价很小，你可以很方便的在最小的项目上应用版本管理。它的简洁性意味着不会有很多艰深的概念和命令干扰你真正的工作。同时，Mercurial高性能和点对点的特性可以让你轻易的应对大的项目。

没有一个版本控制工具能拯救一个糟糕的项目，但是在项目中选择好的工具会大大的提高效率，正是工欲善其事，必先利其器。

版本控制是一个各自为政的领域，以至于有很多名称和缩略语，下面是你可能遇到的一些常用的术语：

有些人声称这些术语有不同的含义，但实际上它们的含义太重叠了，根本没有一致的，甚至有用的方式来区别它们。

如果你喜欢一个开源项目并且决定准备开始改进它，同时这个项目使用分布式版本控制工具的话，你立刻可以和其他人一样认为自己成为项目的“核心”。如果他们发布了他们的版本库，你可以立即拷贝他们的项目。开始修改，记录你自己的工作，和内部人员一样使用同样的工具。相比之下，如果使用集中式工具，除非有人给你向中央服务器提交修改的权限，你只能用只读的方式使用软件。这样，你就不能记录你的修改，而且当你从版本库更新的时候，本地的修改随时有崩溃的可能。

遍布全球的团队正在进行许多商业项目。远离中央服务器的贡献者会发现执行命令速度很慢同时不怎么可靠。商业的版本控制系统改善这个问题的办法就是让你购买远程复制插件，这通常很昂贵，并且很难管理。分布式系统首先不会有这样的问题。其次，你可以很容易的建立多个授权服务器，假设每个站点一个，这样可以避免在昂贵的长途线路上的冗余的通讯。

集中式的版本控制系统的扩展性相对较低。只要不多的并行用户的组合负载就可以将一个昂贵的中央服务器压垮。同样，典型的反应就是昂贵笨重的复制设备。因为中央服务器的最大负载—如果你有的话—比分布式工具低很多（因为所有的数据要北复制到其它地方），一个廉价的服务器就可以满足一个相当大的团队的要求，为平衡负载而进行的复制只需要简单的脚本就够了。

如果你有员工需要在客户方解决问题，那么他们会受益于分布式版本控制。工具允许他们创建定制的环境，互相独立的尝试不同的解决方案。并且可以高效的从历史代码中查找bug的根源，在客户环境中进行回归，所有的这些都不需要连接公司的网络。

Subversion是一个流行的版本控制工具，是用来替代CVS的，它采用的是集中式的客户/服务器结构。

Subversion和Mercurial相同操作的命令的命名上非常相似，所以如果你熟悉一个，很容易学会另外一个，两个工具都可以在大多数平台上运行。

在1.5版之前，Subversion对合并的支持并不好。在我写本书的时候，它刚新增了并跟踪的功能，出名的复杂和容易出错。

在我测量过的每个版本控制操作上Mercurial都比Subversion有很大的性能优势。差距从两个数量级到六个数量级不等，我用的是Subversion 1.4.3的ra_local文件存储方式，这是已知的最快的存取方式了。在实际的部署中包括网络存储，那么Subversion的劣势更大。因为很多Subversion命令必须和主机交互，并且因为Subversion没有好的复制机制，使得对于中的等大小的项目而言，服务器容量和网络带宽成为主要瓶颈。

另外，Subversion以在客户端使用了更多存储空间的方法，换取降低几个常用操作的网络负载，例如查找修改过的文件（status）和显示对于当前版本的更改（diff）。结果Subversion的工作副本经常和Mercurial的版本库和工作目录一样大，或者更大，虽然Mercurial的版本库包括了项目的完整历史。

Subversion有很多的第三方工具支持。Mercurial现在在这方面稍微欠缺。然而差距正在逐渐缩小，实际上一些有Mercurial的GUI工具比Subversion类似工具还略胜一筹。和Mercurial一样，Subversion也有完善的用户手册。

Subversion并不在客户端存储版本历史，所以它很适合管理那些有很多大的二进制文件的项目。如果你对一个未压缩的10MB文件检入了五十次，Subversion客户端的占用的磁盘空间基本上保持不变。而对于分布式SCM软件，磁盘空间会随着版本数量的增加成而迅速增长，因为每个版本之间的差异非常大。

另外，合并不同版本的二进制文件非常困难，换句话说，基本上不可能。Subversion提供了锁定功能，用户可以锁定一个文件，这样他就取得了对这个文件临时的独占的提交权，这对于广泛使用二进制文件的项目而言是个明显优势。

Mercurial可以从Subversion的版本库中导入历史版本。它也可以向Subversion的版本库输出历史版本。这样在决定转换之前很容易先“试一下水”，同时并行的使用Mercurial和Subversion。版本史的转换是递增的，你可以先构造一个初始版本，每次有了新的更改后加入一个小的转换。

Git是为了管理Linux内核代码而开发的一个分布式版本控制工具。它和Mercurial一样在设计上受了Monotone的影响。

Git有非常大的命令集，1.5.0版本提供了139个单独的命令。它以难学而闻名于世。与Git相比，Mercurial力求简洁。

就性能而言，Git非常快。在很多情况下它都比Mercurial快，至少是在Linux上，但Mercurial在其它操作上有优势。而在Windows上，Git不管是性能还是提供的支持，都比Mercurial差很多，至少在本书写作的时候是这样。

Mercurial的版本库不需要维护，但Git的版本库需要频繁的手工维护，将其元数据“repacks”，如果不这样做，性能就会下降，磁盘空间也会迅速增加。有多个Git版本库的服务器需要严格和频繁的重新打包，否则在备份的时候就会成为严重的瓶颈，曾经有过运行每日备份超过24小时的例子。一个新打包的Git版本库比Mercurial稍小一些，但是未打包的版本库则会大几个数量级。

Git的核心由C语言编写，许多Git命令是用shell或者perl脚本实现的，这些脚本的质量差别很大。我碰到过好几次这样的情况，明明已经出现了致命错误了，脚本还在盲目的执行。

Mercurial可以从Git的版本库中导入版本历史。

CVS可能是世界上使用最广泛的版本控制工具。因为它是太古老和内部实现很混乱，许多年来都处于维护状态。

CVS采用的是集中式客户/服务器结构。它不会将相关的文件变更一起作为原子提交，这使得它很容易“破坏构建”：一个人成功的提交了一部分更改，然后要停下来处理合并，这使得其他人只能看见他们的部分工作。这样也会影响你和项目历史的工作方式。如果你想看到其他人针对他的那部分任务做的全部修改，你必须手动检查每个受影响的文件的变更描述和时间戳（假如你知道是哪些文件）。

CVS的分支和标签的概念实在是太混乱了，我都不想给你介绍。它也不支持文件和目录的重命名。这使得版本库非常容易崩溃。它几乎没任何的内部一致性检查功能，所以通常你不可能知道版本库是不是崩溃了。不管是新项目还是老项目，我都不推荐使用CVS。

Mercurial可以导入CVS的版本历史。然而，这里面有很多限制；对其版本控制工具的CVS导入程序也是一样。因为CVS缺少原子更改并且不支持文件系统层次的版本控制，所以不可能完全精确的重建CVS的历史。有些需要猜测，重命名通常发现不了。因为CVS的很多的高级管理功能必须手动完成，因此非常容易出错。碰到崩溃的版本库，CVS导入程序通常会出现很多问题(完全伪造的版本时间戳，若干文件被锁定十多年，这是我个人经历的两个不太有趣的问题）。

Mercurial可以从CVS版本库导入版本历史。

Perforce采用的是集中式客户/服务器结构，客户端不缓存任何数据。和现代的版本控制工具不同，每次想要编辑的一个文件，用户必须运行一个命令通知Perforce服务器。

对于小的团队而言，Perforce相当好，但是当用户数目超过数十个以后，性能急剧下降。中等大小Perforce安装需要部署代理来处理用户产生的负载。

除了CVS之外，以上列出的所有工具都各有所长，没有一个版本控制工具适合所有情况。

比如说，因为采用集中式的结构并且支持文件锁定，Subversion非常适合频繁编辑二进制文件的场合。

我已经使用Mercurial很多年了，个人认为它有简洁，高性能，良好的合并支持诸多特点。

Windows 中最好的 Mercurial 版本是TortoiseHg，它的主页地址是 http://bitbucket.org/tortoisehg/stable/wiki/Home。这个软件没有外部依赖，它可以“独立工作”，同时提供了命令行和图形用户界面。

Lee Cantey 为 Mac OS X 在 http://mercurial.berkwood.com 发布了 Mercurial 安装程序。

由于每种 Linux 发行版都有自己的包管理工具，开发策略和进度，从而很难给出安装 Mercurial 二进制包的全面说明。你安装的 Mercurial 版本，在很大程度上依赖于你所使用的发行版的 Mercurial 维护者的活跃程度。

为了让事情简单，我会致力于说明在最流行的 Linux 发行版中，从命令行安装 Mercurial 的方法。这些发行版都提供了图形界面的包管理器，让你通过点击鼠标安装 Mercurial；寻找的包名称是 mercurial。

位于 http://www.sunfreeware.com 的 SunFreeWare 提供了 Mercurial 的二进制安装包。

Mercurial 内置了帮助系统。当你不记得如何执行一个命令时，它会给你重要的帮助。如果你完全没有头绪，那就直接运行 hg help；它会给出命令的简短列表，还描述了每个命令的作用。如果你需要具体命令的帮助(下述)，它会给出更详细的信息。

$ hg help init
hg init [-e CMD] [--remotecmd CMD] [DEST]

create a new repository in the given directory

    Initialize a new repository in the given directory. If the given
    directory does not exist, it will be created.

    If no directory is given, the current directory is used.

    It is possible to specify an ssh:// URL as the destination.
    See 'hg help urls' for more information.

options:

 -e --ssh        specify ssh command to use
    --remotecmd  specify hg command to run on the remote side

use "hg -v help init" to show global options

要获得更多的详细信息(通常不需要)，可以执行 hg help -v。选项 -v 是 --verbose 的短格式，告诉 Mercurial 要打印通常不需要的更多信息。

拷贝版本库有点特殊。虽然你可以使用文件拷贝命令来复制一般版本库，最好还是用Mercurial内置的命令。这个命令叫做 hg clone，因为它创建了一个原来版本库的拷贝。

$ hg clone http://hg.serpentine.com/tutorial/hello
destination directory: hello
requesting all changes
adding changesets
adding manifests
adding file changes
added 5 changesets with 5 changes to 2 files
updating working directory
2 files updated, 0 files merged, 0 files removed, 0 files unresolved

如上所示，使用hg clone的好处在于它能够让你通过网络克隆版本库。另外一个好处你它会记得这个版本库是从哪里克隆的，稍后会看到，当我们想从其他的版本库获取新的变更的时候这点这会非常有用。

如果我们克隆成功，我们会得到一个本地目录，叫做 hello。这个目录会包括一些文件。

$ ls -l
total 0
drwxr-xr-x 3 dongsheng g11n 45 Oct 23 01:38 hello
$ ls hello
Makefile  hello.c

这个版本库中的文件和我们刚才克隆的版本库中的文件相同的内容和版本历史

每个Mercurial版本库都是完整的，自包含的，独立的。它包含了项目文件的一份私有拷贝和全部历史。我们刚才已经提到，克隆的版本库会记住它克隆的那个版本库的地址，但是Mercurial不会和那个或者其他任何一个版本库通信，除非你给它命令。

这意味着，我们可以随意的在我们的版本库中做实验，非常安全，因为它是一个私有的“沙盒”，不会影响任何人。

当我们仔细观察版本库内部时，我们会发现它有一个叫.hg的目录。这就是Mercurial为版本库保存所有元数据的地方。

$ cd hello
$ ls -a
.  ..  .hg  Makefile  hello.c

目录.hg中的内容和其子目录是Mercurial私有的。版本库中的其他任何文件和目录你都可以随意操作。

介绍一点术语， .hg目录是“真正的”版本库，所有其他的文件和目录称为工作目录一个简单的区分的方法就是版本库中包含了项目的历史，而 工作目录则是项目组一个特定历史点上的快照。

英语是一种非常随便的语言，计算机史上也向来以混乱的术语为荣（如能用四个词为什么要用一个呢？），就版本控制而言，有很多词和短语有相同的意思。如果你和别人讨论Mercurial版本库的历史，你会发现“变更集”这个词常常被简化成“变更”或者（写的时候）“cset”,有时候变更集也指一个“版本”或者“rev”。

实际上，用哪个词来描述“变更集”的概念并不重要，重要的是如何用标识符来标识“一个特定的变更集”。回忆一下hg log命令的输出，changeset字段里用一个数字和一个十六进制字符串来标识一个变更集。

这个区别很重要。如果你通过邮件和别人讨论“版本33”，很有可能他们的版本33和你的不一样。原因在于版本号依赖于相应变更进入版本库的顺序。，不能保证同一个变更在不同的版本库中会有相同的次序。有可能三个变更a,b,c在一个版本库中的次序是0,1,2，而在另外一个版本库中则变成0,2,1

Mercurial使用版本号纯粹是为了有些命令的方便，如果你要和别人讨论变更集，或者由于某些原因为一个变更集做记录（如在bug报告中），请使用十六进制标识符。

如果只想用hg log查看一个版本的日志使用-r（或者--rev）选项。版本号和十六进制标识符都可以来指定版本，可以一次指定任意多个版本。

$ hg log -r 3
changeset:   3:0272e0d5a517
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Sat Aug 16 22:08:02 2008 +0200
summary:     Get make to generate the final binary from a .o file.

$ hg log -r 0272e0d5a517
changeset:   3:0272e0d5a517
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Sat Aug 16 22:08:02 2008 +0200
summary:     Get make to generate the final binary from a .o file.

$ hg log -r 1 -r 4
changeset:   1:82e55d328c8c
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile

changeset:   4:2278160e78d4
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Sat Aug 16 22:16:53 2008 +0200
summary:     Trim comments.

如果你想显示几个版本历史，但是不想一个一个的列出来，可以使用 范围标记；它会显示包括abc和def，以及它们之间的所有版本的版本历史。

$ hg log -r 2:4
changeset:   2:fef857204a0c
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Sat Aug 16 22:05:04 2008 +0200
summary:     Introduce a typo into hello.c.

changeset:   3:0272e0d5a517
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Sat Aug 16 22:08:02 2008 +0200
summary:     Get make to generate the final binary from a .o file.

changeset:   4:2278160e78d4
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Sat Aug 16 22:16:53 2008 +0200
summary:     Trim comments.

Mercurial还可以指定版本的输出顺序，如hg log -r 2:4输出2，3，4。而hg log -r 4:2则输出4，3，2。

当你知道你在找那个版本的时候，hg log输出的摘要是非常有用的，但有时候你不知道要找哪个版本，你想看到变更的完整描述，或者修改过的文件的列表，hg log命令的-v（--verbose）选项会给出更详细的信息。

$ hg log -v -r 3
changeset:   3:0272e0d5a517
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Sat Aug 16 22:08:02 2008 +0200
files:       Makefile
description:
Get make to generate the final binary from a .o file.

如果你想同时看到变更的描述和内容，增加-p（--patch）选项。这会将变更的内容以unified diff的格式显示（如果你不知道unified diff，请参考第 12.4 节 “理解补丁”。

$ hg log -v -p -r 2
changeset:   2:fef857204a0c
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Sat Aug 16 22:05:04 2008 +0200
files:       hello.c
description:
Introduce a typo into hello.c.


diff -r 82e55d328c8c -r fef857204a0c hello.c
--- a/hello.c	Fri Aug 26 01:21:28 2005 -0700
+++ b/hello.c	Sat Aug 16 22:05:04 2008 +0200
@@ -11,6 +11,6 @@
 
 int main(int argc, char **argv)
 {
-	printf("hello, world!\n");
+	printf("hello, world!\");
 	return 0;
 }

-p选项非常有用，所以一定要记住。

当你准备第一次运行hg commit命令时，不一定会成功。对于你提交的每个变更，Mercurial都会记录你的名字和邮件地址，这样你和其他人以后就能分开是谁做的哪个变更。Mercurial会自动尝试找出一个有意义的用户名来提交。它会依次尝试以下方法：

如果所有的这些机制都失败了，Mercurial会执行失败退出，打印出一条错误信息这种情况下，只有你设定了用户名之后才能提交。

当你需要覆盖Mercurial缺省的用户时，可以考虑HGUSER环境变量和hg commit命令的-u选项。正常使用的情况下，最简单实用的方法就是创建.hgrc文件来设定用户名；步骤如下。

2.7.1.1. 创建 Mercurial 的配置文件

设定用户名的时候，使用你最喜欢的编辑器在你的主目录创建一个名为.hgrc的文件。Mercurial将会从这个文件中查找你的个人配置信息。你的.hgrc开始的时候应该是这样子。

	Windows上的“主目录”
	英文版的Windows的主目录通常是C:\Documents and Settings下你的用户名的那个文件夹。如果要找出你的主目录的确切位置，可以打开一个命令行窗口，运行以下命令。 C:\> echo %UserProfile%

# This is a Mercurial configuration file.
[ui]
username = Firstname Lastname <email.address@example.net>

配置文件中“[ui]”这行标识着一个字段的开始,“username = ...”这行的意思是在ui字段中设定项username的值。当出现一个新的字段或者到达文件结尾的时候，当前的字段才结束。

2.7.1.2. 选择用户名称

username配置项的值可以是你喜欢的任意文字，因为这项信息主要是给其他用户阅读的，所以Mercurial不会去解释它。大多数人的习惯是采用用户名加上邮件地址的格式，就像上面的例子一样。

	注意
	Mercurial内置的网络服务器会混淆邮件地址，让垃圾邮件发送者用的邮件地址抓取工具很难获取你的邮件地址。当你把Mercurial的版本库在网路上发布的时候，这可以减小你接收到垃圾邮件的风险。

我们提交一个变更的时候，Mercurial会打开一个编辑器，让我们输入一些信息来描述这个变更集做的更改。这就是提交日志。它会告诉读者我们改了什么以及修改的原因，我们提交之后，命令hg log会输出这些信息。

$ hg commit

hg commit命令打开的编辑器包括一两个空行，接着是以“HG:”开始的行。

This is where I type my commit comment.

HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: --
HG: user: Bryan O'Sullivan <bos@serpentine.com>
HG: branch 'default'
HG: changed hello.c

Mercurial会忽略以“HG:”为开始的行；它仅仅用来告诉我们这个变更集中包括哪些文件。修改或者删除这行没有任何影响。

因为hg log命令在缺省情况下仅会输出提交日志的第一行，所以日志第一行最好是单独的一行。下面是一个日志的实例，它没有遵守这个规则，因此摘要可读性很差。

changeset:   73:584af0e231be
user:        Censored Person <censored.person@example.org>
date:        Tue Sep 26 21:37:07 2006 -0700
summary:     include buildmeister/commondefs. Add exports.

至于日志的其他部分的内容，没有严格的规定。Mercurial并不解释或者关心日志的内容，虽然你的项目可能有某种格式的规定。

我个人喜欢简短，而又信息量大的日志，它能告诉我一些我不能通过快速浏览hg log --patch的输出而得到的信息。

如果我们运行hg commit命令的时候没有指定文件，它会提交我们做的所有修改，与hg status和hg diff这两个命令的输出一样。

	Subversion用户的困惑
	和所有的Mercurial命令一样，如果我们不明确指出hg commit命令要提交的文件名，它会在整个版本库的工作目录上执行操作。如果你以前使用过CVS或者Subversion，那一定要注意，你可能仅仅希望提交当前目录与其子目录的修改。

如果你在编辑日志的时候决定不再提交，只要退出编辑器同时不保存文件就可以了。这对版本库和当前目录都没有任何影响。

提交完成后，我们就可以用hg tip命令显示刚刚创建的变更集。这个命令和hg log的输出一样，但是只显示版本库中最新的版本。

$ hg tip -vp
changeset:   5:cfb10a77c108
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:05 2009 +0000
files:       hello.c
description:
Added an extra line of output


diff -r 2278160e78d4 -r cfb10a77c108 hello.c
--- a/hello.c	Sat Aug 16 22:16:53 2008 +0200
+++ b/hello.c	Fri Oct 23 01:38:05 2009 +0000
@@ -8,5 +8,6 @@
 int main(int argc, char **argv)
 {
 	printf("hello, world!\");
+	printf("hello again!\n");
 	return 0;
 }

我们通常把版本库中最新的版本称为tip版本或者简称为tip。

顺便提一下，hg tip命令可以接受很多和hg log命令一样的选项。如-v选项的意思是“详细的”。-p的意思是“输出补丁”。使用-p输出补丁也是我们前面提到的一致性的另外一个例子。

首先，我们克隆原始版本的hello版本库，它不包含我们刚刚提交的变更。我们将这个临时版本库称为hello。

$ cd ..
$ hg clone hello hello-pull
updating working directory
2 files updated, 0 files merged, 0 files removed, 0 files unresolved

我们用hg pull命令将变更从my-hello拖到hello-pull。然而，不管三七二十一将不了解的变更拖进版本库也实在是冒险。Mercurial提供了hg incoming命令，它会告诉我们hg pull将会把哪些变更拖进版本库，但不会真正的执行。

$ cd hello-pull
$ hg incoming ../my-hello
comparing with ../my-hello
searching for changes
changeset:   5:cfb10a77c108
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:05 2009 +0000
summary:     Added an extra line of output

运行hg pull命令将变更拖进版本库非常简单，你可以指定从那个版本库拖变更。

$ hg tip
changeset:   4:2278160e78d4
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Sat Aug 16 22:16:53 2008 +0200
summary:     Trim comments.

$ hg pull ../my-hello
pulling from ../my-hello
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
(run 'hg update' to get a working copy)
$ hg tip
changeset:   5:cfb10a77c108
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:05 2009 +0000
summary:     Added an extra line of output

从前后的hg tip的输出可以看出，我们成功将变更拖进了我们的版本库。然而，Mercurial将拖变更和更新当前工作目录分成两个操作。在看到在当前目录中我们刚拖进的变更之前，还有一步要完成。

	提取指定的修改
	因为在运行hg incoming和hg pull之间可能存在延时,你可能不能看到从其他版本库中的所有导入进来的变更集。假如你正在通过网络从其他地方的版本库拖变更。当你查看hg incoming的输出，还没有拖这些变更的时候，其他人向这个版本库提交了一些东西。这意味着你可能拖进来比你用hg incoming看见的多的变更。 如果你仅希望将hg incoming命令列出的变更拖进来，或者由于其他原因希望得到变更的一个子集，那么你可以明确的指定变更集的ID，比如hg pull -r7e95bb。

现在我们已经对版本库和它的工作目录之间的关系有了粗略的了解。我们在第 2.8.1 节 “从其它版本库取得变更”一节运行的hg pull命令会将变更拖进版本库，但是如果我们检查一下的话，就会发现工作目录并没有变化。这是因为hg pull命令并不会影响工作目录。实际上，我们需要hg update命令来完成这个工作。

$ grep printf hello.c
	printf("hello, world!\");
$ hg update tip
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ grep printf hello.c
	printf("hello, world!\");
	printf("hello again!\n");

hg pull命令并不会自动更新工作目录，这看起来有点奇怪。但实际上这样做是有原因的：你可以用hg update来更新工作目录，切换到版本库中的任意一个版本。假设你将工作目录切换到一个老的版本—假如说是为了追踪一个bug—然后运行了hg pull命令。它自动将工作目录更新到新版本，这可能并不是你想要的结果。

因为拖然后更新是个非常常用的操作顺序，Mercurial允许你将这两个操作组合在一起，只要给hg pull命令加上-u选项就可以了。

如果回顾第 2.8.1 节 “从其它版本库取得变更”一节，我们运行hg pull而又没有加上-u选项时，你可能会发现它输出了一条很有用的提示，我们还需要执行一个操作，才能更新工作目录。

如果想知道工作目录的版本，可以使用hg parents命令。

$ hg parents
changeset:   5:cfb10a77c108
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:05 2009 +0000
summary:     Added an extra line of output

如果回顾图 2.1 “版本库 hello 的历史图”一节，你会看到箭头连着每个变更集。箭头离开的节点是父版本，箭头指向的是子版本。工作目录的父版本也是一样的方式；它是工作目录包含的变更集。

如果需要将工作目录切换到一个特定版本，给hg update命令加上版本号或者变更集标识符就可以了。

$ hg update 2
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ hg parents
changeset:   2:fef857204a0c
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Sat Aug 16 22:05:04 2008 +0200
summary:     Introduce a typo into hello.c.

$ hg update
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ hg parents
changeset:   5:cfb10a77c108
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:05 2009 +0000
summary:     Added an extra line of output

如果没有明确指出版本，hg update会更新到tip版，就像上面例子hg update第二次执行的结果一样。

我们可以将变更从当前所在的版本库推到其他的版本库。与上面的hgpull例子一样，我们可以创建一个临时的版本库存放我们的变更。

$ cd ..
$ hg clone hello hello-push
updating working directory
2 files updated, 0 files merged, 0 files removed, 0 files unresolved

hg outgoing命令可以告诉我们那些变更将会被推到另外一个版本库。

$ cd my-hello
$ hg outgoing ../hello-push
comparing with ../hello-push
searching for changes
changeset:   5:cfb10a77c108
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:05 2009 +0000
summary:     Added an extra line of output

而hg push命令则会执行真正的推操作。

$ hg push ../hello-push
pushing to ../hello-push
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files

与hg pull一样，在变更推送之后，hg push命令并不会更新版本库的工作目录，与hg pull命令不同，hg push并不提供-u选项来更新其他版本库的工作目录。这一不对称是有目的的：我们推送的版本库可能是一个远端的服务器，并且很多人共享使用它。如果在其他人正在工作的时候，我们更新了工作目录，那么他们的工作很可能被破坏。

如果我们向一个已经包含了这些变更的版本库推送或者拉这些变更会发生什么事情呢？，什么也不会发生。

$ hg push ../hello-push
pushing to ../hello-push
searching for changes
no changes found

在我们克隆版本库的时候，Mercurial会在新的版本库的.hg/hgrc文件中记录下版本库的位置，如果我们对hg pull没有指定来源，或者对于hg push 没有指定目标，那么这些命令就会使用缺省位置。hg incoming和hg outgoing命令也是如此。

如果你用文本编辑器打开版本库的.hg/hgrc文件，你会看到如下内容。

[paths]
default = http://www.selenic.com/repo/hg

有可能—并且常常很有用—hg push和hg outgoing的缺省位置与hg pull和hg incoming的位置不同。我们可以给.hg/hgrc文件的[paths]节加上default-push条目，如下所示。

[paths]
default = http://www.selenic.com/repo/hg
default-push = http://hg.example.com/hg

前面几节我们介绍的命令不仅可以用于本地版本库，还可以用于网络；只要传递的参数从本地路径变成URL就可以了。

$ hg outgoing http://hg.serpentine.com/tutorial/hello
comparing with http://hg.serpentine.com/tutorial/hello
searching for changes
changeset:   5:cfb10a77c108
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:05 2009 +0000
summary:     Added an extra line of output

在本例中，我们可以看到准备向远程版本库推送的变更，但是该版本库并不允许匿名用户推送。

$ hg push http://hg.serpentine.com/tutorial/hello
pushing to http://hg.serpentine.com/tutorial/hello
searching for changes
ssl required

Remember that Mercurial records what the parent of each change is. If a change has a parent, we call it a child or descendant of the parent. A head is a change that has no children. The tip revision is thus a head, because the newest revision in a repository doesn't have any children. There are times when a repository can contain more than one head.

图 3.2. 从 my-hello 拉到 my-new-hello 之后版本库的内容

In 图 3.2 “从 my-hello 拉到 my-new-hello 之后版本库的内容”, you can see the effect of the pull from my-hello into my-new-hello. The history that was already present in my-new-hello is untouched, but a new revision has been added. By referring to 图 3.1 “my-hello 与 my-new-hello 最新的历史分叉”, we can see that the changeset ID remains the same in the new repository, but the revision number has changed. (This, incidentally, is a fine example of why it's not safe to use revision numbers when discussing changesets.) We can view the heads in a repository using the hg heads command.

$ hg heads
changeset:   6:cfb10a77c108
tag:         tip
parent:      4:2278160e78d4
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:05 2009 +0000
summary:     Added an extra line of output

changeset:   5:acf466dc3272
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:09 2009 +0000
summary:     A new hello for a new day.

What happens if we try to use the normal hg update command to update to the new tip?

$ hg update
abort: crosses branches (use 'hg merge' or 'hg update -C')

Mercurial is telling us that the hg update command won't do a merge; it won't update the working directory when it thinks we might want to do a merge, unless we force it to do so. (Incidentally, forcing the update with hg update -C would revert any uncommitted changes in the working directory.)

我们使用 hg merge 命令来合并两个顶点。

$ hg merge
merging hello.c
0 files updated, 1 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)

We resolve the contents of hello.c This updates the working directory so that it contains changes from both heads, which is reflected in both the output of hg parents and the contents of hello.c.

$ hg parents
changeset:   5:acf466dc3272
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:09 2009 +0000
summary:     A new hello for a new day.

changeset:   6:cfb10a77c108
tag:         tip
parent:      4:2278160e78d4
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:05 2009 +0000
summary:     Added an extra line of output

$ cat hello.c
/*
 * Placed in the public domain by Bryan O'Sullivan.  This program is
 * not covered by patents in the United States or other countries.
 */

#include <stdio.h>

int main(int argc, char **argv)
{
	printf("once more, hello.\n");
	printf("hello, world!\");
	printf("hello again!\n");
	return 0;
}

Whenever we've done a merge, hg parents will display two parents until we hg commit the results of the merge.

$ hg commit -m 'Merged changes'

We now have a new tip revision; notice that it has both of our former heads as its parents. These are the same revisions that were previously displayed by hg parents.

$ hg tip
changeset:   7:a8fcbc2b9caf
tag:         tip
parent:      5:acf466dc3272
parent:      6:cfb10a77c108
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:10 2009 +0000
summary:     Merged changes

In 图 3.3 “在合并期间，以及提交之后的工作目录与版本库”, you can see a representation of what happens to the working directory during the merge, and how this affects the repository when the commit happens. During the merge, the working directory has two parent changesets, and these become the parents of the new changeset.

图 3.3. 在合并期间，以及提交之后的工作目录与版本库

We sometimes talk about a merge having sides: the left side is the first parent in the output of hg parents, and the right side is the second. If the working directory was at e.g. revision 5 before we began a merge, that revision will become the left side of the merge.

My preferred graphical merge tool is kdiff3, which I'll use to describe the features that are common to graphical file merging tools. You can see a screenshot of kdiff3 in action in 图 3.5 “使用 kdiff3 合并文件的不同版本”. The kind of merge it is performing is called a three-way merge, because there are three different versions of the file of interest to us. The tool thus splits the upper portion of the window into three panes:

In the pane below these is the current result of the merge. Our task is to replace all of the red text, which indicates unresolved conflicts, with some sensible merger of the “ours” and “theirs” versions of the file.

All four of these panes are locked together; if we scroll vertically or horizontally in any of them, the others are updated to display the corresponding sections of their respective files.

图 3.5. 使用 kdiff3 合并文件的不同版本

For each conflicting portion of the file, we can choose to resolve the conflict using some combination of text from the base version, ours, or theirs. We can also manually edit the merged file at any time, in case we need to make further modifications.

There are many file merging tools available, too many to cover here. They vary in which platforms they are available for, and in their particular strengths and weaknesses. Most are tuned for merging files containing plain text, while a few are aimed at specialised file formats (generally XML).

In this example, we will reproduce the file modification history of 图 3.4 “冲突的修改” above. Let's begin by creating a repository with a base version of our document.

$ cat > letter.txt <<EOF
> Greetings!
> I am Mariam Abacha, the wife of former
> Nigerian dictator Sani Abacha.
> EOF
$ hg add letter.txt
$ hg commit -m '419 scam, first draft'

We'll clone the repository and make a change to the file.

$ cd ..
$ hg clone scam scam-cousin
updating working directory
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ cd scam-cousin
$ cat > letter.txt <<EOF
> Greetings!
> I am Shehu Musa Abacha, cousin to the former
> Nigerian dictator Sani Abacha.
> EOF
$ hg commit -m '419 scam, with cousin'

And another clone, to simulate someone else making a change to the file. (This hints at the idea that it's not all that unusual to merge with yourself when you isolate tasks in separate repositories, and indeed to find and resolve conflicts while doing so.)

$ cd ..
$ hg clone scam scam-son
updating working directory
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ cd scam-son
$ cat > letter.txt <<EOF
> Greetings!
> I am Alhaji Abba Abacha, son of the former
> Nigerian dictator Sani Abacha.
> EOF
$ hg commit -m '419 scam, with son'

Having created two different versions of the file, we'll set up an environment suitable for running our merge.

$ cd ..
$ hg clone scam-cousin scam-merge
updating working directory
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ cd scam-merge
$ hg pull -u ../scam-son
pulling from ../scam-son
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
not updating, since new heads added
(run 'hg heads' to see heads, 'hg merge' to merge)

In this example, I'll set HGMERGE to tell Mercurial to use the non-interactive merge command. This is bundled with many Unix-like systems. (If you're following this example on your computer, don't bother setting HGMERGE. You'll get dropped into a GUI file merge tool instead, which is much preferable.)

$ export HGMERGE=merge
$ hg merge
merging letter.txt
sh: merge: command not found
merging letter.txt failed!
0 files updated, 0 files merged, 0 files removed, 1 files unresolved
use 'hg resolve' to retry unresolved file merges or 'hg up --clean' to abandon
$ cat letter.txt
Greetings!
I am Shehu Musa Abacha, cousin to the former
Nigerian dictator Sani Abacha.

Because merge can't resolve the conflicting changes, it leaves merge markers inside the file that has conflicts, indicating which lines have conflicts, and whether they came from our version of the file or theirs.

Mercurial can tell from the way merge exits that it wasn't able to merge successfully, so it tells us what commands we'll need to run if we want to redo the merging operation. This could be useful if, for example, we were running a graphical merge tool and quit because we were confused or realised we had made a mistake.

If automatic or manual merges fail, there's nothing to prevent us from “fixing up” the affected files ourselves, and committing the results of our merge:

$ cat > letter.txt <<EOF
> Greetings!
> I am Bryan O'Sullivan, no relation of the former
> Nigerian dictator Sani Abacha.
> EOF
$ hg resolve -m letter.txt
$ hg commit -m 'Send me your money'
$ hg tip
changeset:   3:e16d77b1e039
tag:         tip
parent:      1:06a49da8146c
parent:      2:472b72d30abb
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:38:11 2009 +0000
summary:     Send me your money

	在哪里能找到 hg resolve 命令?
	The hg resolve command was introduced in Mercurial 1.1, which was released in December 2008. If you are using an older version of Mercurial (run hg version to see), this command will not be present. If your version of Mercurial is older than 1.1, you should strongly consider upgrading to a newer version before trying to tackle complicated merges.

When Mercurial tracks modifications to a file, it stores the history of that file in a metadata object called a filelog. Each entry in the filelog contains enough information to reconstruct one revision of the file that is being tracked. Filelogs are stored as files in the .hg/store/data directory. A filelog contains two kinds of information: revision data, and an index to help Mercurial to find a revision efficiently.

A file that is large, or has a lot of history, has its filelog stored in separate data (“.d” suffix) and index (“.i” suffix) files. For small files without much history, the revision data and index are combined in a single “.i” file. The correspondence between a file in the working directory and the filelog that tracks its history in the repository is illustrated in 图 4.1 “工作目录中的文件与版本库中的文件日志之间的关系”.

图 4.1. 工作目录中的文件与版本库中的文件日志之间的关系

Mercurial uses a structure called a manifest to collect together information about the files that it tracks. Each entry in the manifest contains information about the files present in a single changeset. An entry records which files are present in the changeset, the revision of each file, and a few other pieces of file metadata.

The changelog contains information about each changeset. Each revision records who committed a change, the changeset comment, other pieces of changeset-related information, and the revision of the manifest to use.

Within a changelog, a manifest, or a filelog, each revision stores a pointer to its immediate parent (or to its two parents, if it's a merge revision). As I mentioned above, there are also relationships between revisions across these structures, and they are hierarchical in nature.

For every changeset in a repository, there is exactly one revision stored in the changelog. Each revision of the changelog contains a pointer to a single revision of the manifest. A revision of the manifest stores a pointer to a single revision of each filelog tracked when that changeset was created. These relationships are illustrated in 图 4.2 “元数据之间的关系”.

图 4.2. 元数据之间的关系

As the illustration shows, there is not a “one to one” relationship between revisions in the changelog, manifest, or filelog. If a file that Mercurial tracks hasn't changed between two changesets, the entry for that file in the two revisions of the manifest will point to the same revision of its filelog^[3].

The revlog provides efficient storage of revisions using a delta mechanism. Instead of storing a complete copy of a file for each revision, it stores the changes needed to transform an older revision into the new revision. For many kinds of file data, these deltas are typically a fraction of a percent of the size of a full copy of a file.

Some obsolete revision control systems can only work with deltas of text files. They must either store binary files as complete snapshots or encoded into a text representation, both of which are wasteful approaches. Mercurial can efficiently handle deltas of files with arbitrary binary contents; it doesn't need to treat text as special.

Mercurial only ever appends data to the end of a revlog file. It never modifies a section of a file after it has written it. This is both more robust and efficient than schemes that need to modify or rewrite data.

In addition, Mercurial treats every write as part of a transaction that can span a number of files. A transaction is atomic: either the entire transaction succeeds and its effects are all visible to readers in one go, or the whole thing is undone. This guarantee of atomicity means that if you're running two copies of Mercurial, where one is reading data and one is writing it, the reader will never see a partially written result that might confuse it.

The fact that Mercurial only appends to files makes it easier to provide this transactional guarantee. The easier it is to do stuff like this, the more confident you should be that it's done correctly.

Mercurial cleverly avoids a pitfall common to all earlier revision control systems: the problem of inefficient retrieval. Most revision control systems store the contents of a revision as an incremental series of modifications against a “snapshot”. (Some base the snapshot on the oldest revision, others on the newest.) To reconstruct a specific revision, you must first read the snapshot, and then every one of the revisions between the snapshot and your target revision. The more history that a file accumulates, the more revisions you must read, hence the longer it takes to reconstruct a particular revision.

图 4.3. 版本日志的快照，以及增量差异

The innovation that Mercurial applies to this problem is simple but effective. Once the cumulative amount of delta information stored since the last snapshot exceeds a fixed threshold, it stores a new snapshot (compressed, of course), instead of another delta. This makes it possible to reconstruct any revision of a file quickly. This approach works so well that it has since been copied by several other revision control systems.

图 4.3 “版本日志的快照，以及增量差异” illustrates the idea. In an entry in a revlog's index file, Mercurial stores the range of entries from the data file that it must read to reconstruct a particular revision.

Along with delta or snapshot information, a revlog entry contains a cryptographic hash of the data that it represents. This makes it difficult to forge the contents of a revision, and easy to detect accidental corruption.

Hashes provide more than a mere check against corruption; they are used as the identifiers for revisions. The changeset identification hashes that you see as an end user are from revisions of the changelog. Although filelogs and the manifest also use hashes, Mercurial only uses these behind the scenes.

Mercurial verifies that hashes are correct when it retrieves file revisions and when it pulls changes from another repository. If it encounters an integrity problem, it will complain and stop whatever it's doing.

In addition to the effect it has on retrieval efficiency, Mercurial's use of periodic snapshots makes it more robust against partial data corruption. If a revlog becomes partly corrupted due to a hardware error or system bug, it's often possible to reconstruct some or most revisions from the uncorrupted sections of the revlog, both before and after the corrupted section. This would not be possible with a delta-only storage model.

The dirstate stores parent information for more than just book-keeping purposes. Mercurial uses the parents of the dirstate as the parents of a new changeset when you perform a commit.

图 4.5. 工作目录可以有两个父亲

图 4.5 “工作目录可以有两个父亲” shows the normal state of the working directory, where it has a single changeset as parent. That changeset is the tip, the newest changeset in the repository that has no children.

图 4.6. 提交之后，工作目录的父亲就改变了

It's useful to think of the working directory as “the changeset I'm about to commit”. Any files that you tell Mercurial that you've added, removed, renamed, or copied will be reflected in that changeset, as will modifications to any files that Mercurial is already tracking; the new changeset will have the parents of the working directory as its parents.

After a commit, Mercurial will update the parents of the working directory, so that the first parent is the ID of the new changeset, and the second is the null ID. This is shown in 图 4.6 “提交之后，工作目录的父亲就改变了”. Mercurial doesn't touch any of the files in the working directory when you commit; it just modifies the dirstate to note its new parents.

It's perfectly normal to update the working directory to a changeset other than the current tip. For example, you might want to know what your project looked like last Tuesday, or you could be looking through changesets to see which one introduced a bug. In cases like this, the natural thing to do is update the working directory to the changeset you're interested in, and then examine the files in the working directory directly to see their contents as they were when you committed that changeset. The effect of this is shown in 图 4.7 “同步到旧修改集的工作目录”.

图 4.7. 同步到旧修改集的工作目录

Having updated the working directory to an older changeset, what happens if you make some changes, and then commit? Mercurial behaves in the same way as I outlined above. The parents of the working directory become the parents of the new changeset. This new changeset has no children, so it becomes the new tip. And the repository now contains two changesets that have no children; we call these heads. You can see the structure that this creates in 图 4.8 “对同步到旧修改集的工作目录提交之后”.

图 4.8. 对同步到旧修改集的工作目录提交之后

注意

If you're new to Mercurial, you should keep in mind a common “error”, which is to use the hg pull command without any options. By default, the hg pull command does not update the working directory, so you'll bring new changesets into your repository, but the working directory will stay synced at the same changeset as before the pull. If you make some changes and commit afterwards, you'll thus create a new head, because your working directory isn't synced to whatever the current tip is. To combine the operation of a pull, followed by an update, run hg pull -u. I put the word “error” in quotes because all that you need to do to rectify the situation where you created a new head by accident is hg merge, then hg commit. In other words, this almost never has negative consequences; it's just something of a surprise for newcomers. I'll discuss other ways to avoid this behavior, and why Mercurial behaves in this initially surprising way, later on.

When you run the hg merge command, Mercurial leaves the first parent of the working directory unchanged, and sets the second parent to the changeset you're merging with, as shown in 图 4.9 “合并两个顶点”.

图 4.9. 合并两个顶点

Mercurial also has to modify the working directory, to merge the files managed in the two changesets. Simplified a little, the merging process goes like this, for every file in the manifests of both changesets.

There are more details—merging has plenty of corner cases—but these are the most common choices that are involved in a merge. As you can see, most cases are completely automatic, and indeed most merges finish automatically, without requiring your input to resolve any conflicts.

When you're thinking about what happens when you commit after a merge, once again the working directory is “the changeset I'm about to commit”. After the hg merge command completes, the working directory has two parents; these will become the parents of the new changeset.

Mercurial lets you perform multiple merges, but you must commit the results of each individual merge as you go. This is necessary because Mercurial only tracks two parents for both revisions and the working directory. While it would be technically feasible to merge multiple changesets at once, Mercurial avoids this for simplicity. With multi-way merges, the risks of user confusion, nasty conflict resolution, and making a terrible mess of a merge would grow intolerable.

A surprising number of revision control systems pay little or no attention to a file's name over time. For instance, it used to be common that if a file got renamed on one side of a merge, the changes from the other side would be silently dropped.

Mercurial records metadata when you tell it to perform a rename or copy. It uses this metadata during a merge to do the right thing in the case of a merge. For instance, if I rename a file, and you edit it without renaming it, when we merge our work the file will be renamed and have your edits applied.

When appropriate, Mercurial will store both snapshots and deltas in compressed form. It does this by always trying to compress a snapshot or delta, but only storing the compressed version if it's smaller than the uncompressed version.

This means that Mercurial does “the right thing” when storing a file whose native form is compressed, such as a zip archive or a JPEG image. When these types of files are compressed a second time, the resulting file is usually bigger than the once-compressed form, and so Mercurial will store the plain zip or JPEG.

Deltas between revisions of a compressed file are usually larger than snapshots of the file, and Mercurial again does “the right thing” in these cases. It finds that such a delta exceeds the threshold at which it should store a complete snapshot of the file, so it stores the snapshot, again saving space compared to a naive delta-only approach.

[ui]
ssh = ssh -C

Appending to files isn't the whole story when it comes to guaranteeing that a reader won't see a partial write. If you recall 图 4.2 “元数据之间的关系”, revisions in the changelog point to revisions in the manifest, and revisions in the manifest point to revisions in filelogs. This hierarchy is deliberate.

A writer starts a transaction by writing filelog and manifest data, and doesn't write any changelog data until those are finished. A reader starts by reading changelog data, then manifest data, followed by filelog data.

Since the writer has always finished writing filelog and manifest data before it writes to the changelog, a reader will never read a pointer to a partially written manifest revision from the changelog, and it will never read a pointer to a partially written filelog revision from the manifest.

The read/write ordering and atomicity guarantees mean that Mercurial never needs to lock a repository when it's reading data, even if the repository is being written to while the read is occurring. This has a big effect on scalability; you can have an arbitrary number of Mercurial processes safely reading data from a repository all at once, no matter whether it's being written to or not.

The lockless nature of reading means that if you're sharing a repository on a multi-user system, you don't need to grant other local users permission to write to your repository in order for them to be able to clone it or pull changes from it; they only need read permission. (This is not a common feature among revision control systems, so don't take it for granted! Most require readers to be able to lock a repository to access it safely, and this requires write permission on at least one directory, which of course makes for all kinds of nasty and annoying security and administrative problems.)

Mercurial uses locks to ensure that only one process can write to a repository at a time (the locking mechanism is safe even over filesystems that are notoriously hostile to locking, such as NFS). If a repository is locked, a writer will wait for a while to retry if the repository becomes unlocked, but if the repository remains locked for too long, the process attempting to write will time out after a while. This means that your daily automated scripts won't get stuck forever and pile up if a system crashes unnoticed, for example. (Yes, the timeout is configurable, from zero to infinity.)

Critical to Mercurial's performance is the avoidance of seeks of the disk head, since any seek is far more expensive than even a comparatively large read operation.

This is why, for example, the dirstate is stored in a single file. If there were a dirstate file per directory that Mercurial tracked, the disk would seek once per directory. Instead, Mercurial reads the entire single dirstate file in one step.

Mercurial also uses a “copy on write” scheme when cloning a repository on local storage. Instead of copying every revlog file from the old repository into the new repository, it makes a “hard link”, which is a shorthand way to say “these two names point to the same file”. When Mercurial is about to write to one of a revlog's files, it checks to see if the number of names pointing at the file is greater than one. If it is, more than one repository is using the file, so Mercurial makes a new copy of the file that is private to this repository.

A few revision control developers have pointed out that this idea of making a complete private copy of a file is not very efficient in its use of storage. While this is true, storage is cheap, and this method gives the highest performance while deferring most book-keeping to the operating system. An alternative scheme would most likely reduce performance and increase the complexity of the software, but speed and simplicity are key to the “feel” of day-to-day use.

Because Mercurial doesn't force you to tell it when you're modifying a file, it uses the dirstate to store some extra information so it can determine efficiently whether you have modified a file. For each file in the working directory, it stores the time that it last modified the file itself, and the size of the file at that time.

When you explicitly hg add, hg remove, hg rename or hg copy files, Mercurial updates the dirstate so that it knows what to do with those files when you commit.

The dirstate helps Mercurial to efficiently check the status of files in a repository.

Storing the modification time and size dramatically reduces the number of read operations that Mercurial needs to perform when we run commands like hg status. This results in large performance improvements.

A useful behavior that Mercurial has is that if you pass the name of a directory to a command, every Mercurial command will treat this as “I want to operate on every file in this directory and its subdirectories”.

$ mkdir b
$ echo b > b/somefile.txt
$ echo c > b/source.cpp
$ mkdir b/d
$ echo d > b/d/test.h
$ hg add b
adding b/d/test.h
adding b/somefile.txt
adding b/source.cpp
$ hg commit -m 'Added all files in subdirectory'

Notice in this example that Mercurial printed the names of the files it added, whereas it didn't do so when we added the file named myfile.txt in the earlier example.

What's going on is that in the former case, we explicitly named the file to add on the command line. The assumption that Mercurial makes in such cases is that we know what we are doing, and it doesn't print any output.

However, when we imply the names of files by giving the name of a directory, Mercurial takes the extra step of printing the name of each file that it does something with. This makes it more clear what is happening, and reduces the likelihood of a silent and nasty surprise. This behavior is common to most Mercurial commands.

Mercurial does not track directory information. Instead, it tracks the path to a file. Before creating a file, it first creates any missing directory components of the path. After it deletes a file, it then deletes any empty directories that were in the deleted file's path. This sounds like a trivial distinction, but it has one minor practical consequence: it is not possible to represent a completely empty directory in Mercurial.

Empty directories are rarely useful, and there are unintrusive workarounds that you can use to achieve an appropriate effect. The developers of Mercurial thus felt that the complexity that would be required to manage empty directories was not worth the limited benefit this feature would bring.

If you need an empty directory in your repository, there are a few ways to achieve this. One is to create a directory, then hg add a “hidden” file to that directory. On Unix-like systems, any file name that begins with a period (“.”) is treated as hidden by most commands and GUI tools. This approach is illustrated below.

$ hg init hidden-example
$ cd hidden-example
$ mkdir empty
$ touch empty/.hidden
$ hg add empty/.hidden
$ hg commit -m 'Manage an empty-looking directory'
$ ls empty
$ cd ..
$ hg clone hidden-example tmp
updating working directory
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ ls tmp
empty
$ ls tmp/empty

Another way to tackle a need for an empty directory is to simply create one in your automated build scripts before they will need it.

It is important to understand that removing a file has only two effects.

Removing a file does not in any way alter the history of the file.

If you update the working directory to a changeset that was committed when it was still tracking a file that you later removed, the file will reappear in the working directory, with the contents it had when you committed that changeset. If you then update the working directory to a later changeset, in which the file had been removed, Mercurial will once again remove the file from the working directory.

Mercurial considers a file that you have deleted, but not used hg remove to delete, to be missing. A missing file is represented with “!” in the output of hg status. Mercurial commands will not generally do anything with missing files.

$ hg init missing-example
$ cd missing-example
$ echo a > a
$ hg add a
$ hg commit -m 'File about to be missing'
$ rm a
$ hg status
! a

If your repository contains a file that hg status reports as missing, and you want the file to stay gone, you can run hg remove --after at any time later on, to tell Mercurial that you really did mean to remove the file.

$ hg remove --after a
$ hg status
R a

On the other hand, if you deleted the missing file by accident, give hg revert the name of the file to recover. It will reappear, in unmodified form.

$ hg revert a
$ cat a
a
$ hg status

You might wonder why Mercurial requires you to explicitly tell it that you are deleting a file. Early during the development of Mercurial, it let you delete a file however you pleased; Mercurial would notice the absence of the file automatically when you next ran a hg commit, and stop tracking the file. In practice, this made it too easy to accidentally remove a file without noticing.

Mercurial offers a combination command, hg addremove, that adds untracked files and marks missing files as removed.

$ hg init addremove-example
$ cd addremove-example
$ echo a > a
$ echo b > b
$ hg addremove
adding a
adding b

The hg commit command also provides a -A option that performs this same add-and-remove, immediately followed by a commit.

$ echo c > c
$ hg commit -A -m 'Commit with addremove'
adding c

What happens during a merge is that changes “follow” a copy. To best illustrate what this means, let's create an example. We'll start with the usual tiny repository that contains a single file.

$ hg init my-copy
$ cd my-copy
$ echo line > file
$ hg add file
$ hg commit -m 'Added a file'

We need to do some work in parallel, so that we'll have something to merge. So let's clone our repository.

$ cd ..
$ hg clone my-copy your-copy
updating working directory
1 files updated, 0 files merged, 0 files removed, 0 files unresolved

Back in our initial repository, let's use the hg copy command to make a copy of the first file we created.

$ cd my-copy
$ hg copy file new-file

If we look at the output of the hg status command afterwards, the copied file looks just like a normal added file.

$ hg status
A new-file

But if we pass the -C option to hg status, it prints another line of output: this is the file that our newly-added file was copied from.

$ hg status -C
A new-file
  file
$ hg commit -m 'Copied file'

Now, back in the repository we cloned, let's make a change in parallel. We'll add a line of content to the original file that we created.

$ cd ../your-copy
$ echo 'new contents' >> file
$ hg commit -m 'Changed file'

Now we have a modified file in this repository. When we pull the changes from the first repository, and merge the two heads, Mercurial will propagate the changes that we made locally to file into its copy, new-file.

$ hg pull ../my-copy
pulling from ../my-copy
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
(run 'hg heads' to see heads, 'hg merge' to merge)
$ hg merge
merging file and new-file to new-file
0 files updated, 1 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
$ cat new-file
line
new contents

This behavior—of changes to a file propagating out to copies of the file—might seem esoteric, but in most cases it's highly desirable.

First of all, remember that this propagation only happens when you merge. So if you hg copy a file, and subsequently modify the original file during the normal course of your work, nothing will happen.

The second thing to know is that modifications will only propagate across a copy as long as the changeset that you're merging changes from hasn't yet seen the copy.

The reason that Mercurial does this is as follows. Let's say I make an important bug fix in a source file, and commit my changes. Meanwhile, you've decided to hg copy the file in your repository, without knowing about the bug or having seen the fix, and you have started hacking on your copy of the file.

If you pulled and merged my changes, and Mercurial didn't propagate changes across copies, your new source file would now contain the bug, and unless you knew to propagate the bug fix by hand, the bug would remain in your copy of the file.

By automatically propagating the change that fixed the bug from the original file to the copy, Mercurial prevents this class of problem. To my knowledge, Mercurial is the only revision control system that propagates changes across copies like this.

Once your change history has a record that the copy and subsequent merge occurred, there's usually no further need to propagate changes from the original file to the copied file, and that's why Mercurial only propagates changes across copies at the first merge, and not afterwards.

If, for some reason, you decide that this business of automatically propagating changes across copies is not for you, simply use your system's normal file copy command (on Unix-like systems, that's cp) to make a copy of a file, then hg add the new copy by hand. Before you do so, though, please do reread 第 5.3.2 节 “为什么复制后需要后续修改?”, and make an informed decision that this behavior is not appropriate to your specific case.

When you use the hg copy command, Mercurial makes a copy of each source file as it currently stands in the working directory. This means that if you make some modifications to a file, then hg copy it without first having committed those changes, the new copy will also contain the modifications you have made up until that point. (I find this behavior a little counterintuitive, which is why I mention it here.)

The hg copy command acts similarly to the Unix cp command (you can use the hg cp alias if you prefer). We must supply two or more arguments, of which the last is treated as the destination, and all others are sources.

If you pass hg copy a single file as the source, and the destination does not exist, it creates a new file with that name.

$ mkdir k
$ hg copy a k
$ ls k
a

If the destination is a directory, Mercurial copies its sources into that directory.

$ mkdir d
$ hg copy a b d
$ ls d
a  b

Copying a directory is recursive, and preserves the directory structure of the source.

$ hg copy z e
copying z/a/c to e/a/c

If the source and destination are both directories, the source tree is recreated in the destination directory.

$ hg copy z d
copying z/a/c to d/z/a/c

As with the hg remove command, if you copy a file manually and then want Mercurial to know that you've copied the file, simply use the --after option to hg copy.

$ cp a n
$ hg copy --after a n

Since Mercurial's rename is implemented as copy-and-remove, the same propagation of changes happens when you merge after a rename as after a copy.

If I modify a file, and you rename it to a new name, and then we merge our respective changes, my modifications to the file under its original name will be propagated into the file under its new name. (This is something you might expect to “simply work,” but not all revision control systems actually do this.)

Whereas having changes follow a copy is a feature where you can perhaps nod and say “yes, that might be useful,” it should be clear that having them follow a rename is definitely important. Without this facility, it would simply be too easy for changes to become orphaned when files are renamed.

The case of diverging names occurs when two developers start with a file—let's call it foo—in their respective repositories.

$ hg clone orig anne
updating working directory
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ hg clone orig bob
updating working directory
1 files updated, 0 files merged, 0 files removed, 0 files unresolved

Anne renames the file to bar.

$ cd anne
$ hg rename foo bar
$ hg ci -m 'Rename foo to bar'

Meanwhile, Bob renames it to quux. (Remember that hg mv is an alias for hg rename.)

$ cd ../bob
$ hg mv foo quux
$ hg ci -m 'Rename foo to quux'

I like to think of this as a conflict because each developer has expressed different intentions about what the file ought to be named.

What do you think should happen when they merge their work? Mercurial's actual behavior is that it always preserves both names when it merges changesets that contain divergent renames.

# See http://www.selenic.com/mercurial/bts/issue455
$ cd ../orig
$ hg pull -u ../anne
pulling from ../anne
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
1 files updated, 0 files merged, 1 files removed, 0 files unresolved
$ hg pull ../bob
pulling from ../bob
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
(run 'hg heads' to see heads, 'hg merge' to merge)
$ hg merge
warning: detected divergent renames of foo to:
 bar
 quux
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
$ ls
bar  quux

Notice that while Mercurial warns about the divergent renames, it leaves it up to you to do something about the divergence after the merge.

Another kind of rename conflict occurs when two people choose to rename different source files to the same destination. In this case, Mercurial runs its normal merge machinery, and lets you guide it to a suitable resolution.

Mercurial has a longstanding bug in which it fails to handle a merge where one side has a file with a given name, while another has a directory with the same name. This is documented as issue 29.

$ hg init issue29
$ cd issue29
$ echo a > a
$ hg ci -Ama
adding a
$ echo b > b
$ hg ci -Amb
adding b
$ hg up 0
0 files updated, 0 files merged, 1 files removed, 0 files unresolved
$ mkdir b
$ echo b > b/b
$ hg ci -Amc
adding b/b
created new head
$ hg merge
abort: Is a directory: /tmp/issue29C-mmLm/issue29/b

When a merge occurs, most files will usually remain unmodified. For each file where Mercurial has to do something, it tracks the state of the file.

If Mercurial sees any file in the unresolved state after a merge, it considers the merge to have failed. Fortunately, we do not need to restart the entire merge from scratch.

The --list or -l option to hg resolve prints out the state of each merged file.

$ hg resolve -l
U myfile.txt

In the output from hg resolve, a resolved file is marked with R, while an unresolved file is marked with U. If any files are listed with U, we know that an attempt to commit the results of the merge will fail.

We have several options to move a file from the unresolved into the resolved state. By far the most common is to rerun hg resolve. If we pass the names of individual files or directories, it will retry the merges of any unresolved files present in those locations. We can also pass the --all or -a option, which will retry the merges of all unresolved files.

Mercurial also lets us modify the resolution state of a file directly. We can manually mark a file as resolved using the --mark option, or as unresolved using the --unmark option. This allows us to clean up a particularly messy merge by hand, and to keep track of our progress with each file as we go.

The most important aspect of any model that you must keep in mind is how well it matches the needs and capabilities of the people who will be using it. This might seem self-evident; even so, you still can't afford to forget it for a moment.

I once put together a workflow model that seemed to make perfect sense to me, but that caused a considerable amount of consternation and strife within my development team. In spite of my attempts to explain why we needed a complex set of branches, and how changes ought to flow between them, a few team members revolted. Even though they were smart people, they didn't want to pay attention to the constraints we were operating under, or face the consequences of those constraints in the details of the model that I was advocating.

Don't sweep foreseeable social or technical problems under the rug. Whatever scheme you put into effect, you should plan for mistakes and problem scenarios. Consider adding automated machinery to prevent, or quickly recover from, trouble that you can anticipate. As an example, if you intend to have a branch with not-for-release changes in it, you'd do well to think early about the possibility that someone might accidentally merge those changes into a release branch. You could avoid this particular problem by writing a hook that prevents changes from being merged from an inappropriate branch.

I wouldn't suggest an “anything goes” approach as something sustainable, but it's a model that's easy to grasp, and it works perfectly well in a few unusual situations.

As one example, many projects have a loose-knit group of collaborators who rarely physically meet each other. Some groups like to overcome the isolation of working at a distance by organizing occasional “sprints”. In a sprint, a number of people get together in a single location (a company's conference room, a hotel meeting room, that kind of place) and spend several days more or less locked in there, hacking intensely on a handful of projects.

A sprint or a hacking session in a coffee shop are the perfect places to use the hg serve command, since hg serve does not require any fancy server infrastructure. You can get started with hg serve in moments, by reading 第 6.4 节 “使用 hg serve 进行非正式共享” below. Then simply tell the person next to you that you're running a server, send the URL to them in an instant message, and you immediately have a quick-turnaround way to work together. They can type your URL into their web browser and quickly review your changes; or they can pull a bugfix from you and verify it; or they can clone a branch containing a new feature and try it out.

The charm, and the problem, with doing things in an ad hoc fashion like this is that only people who know about your changes, and where they are, can see them. Such an informal approach simply doesn't scale beyond a handful people, because each individual needs to know about n different repositories to pull from.

For smaller projects migrating from a centralised revision control tool, perhaps the easiest way to get started is to have changes flow through a single shared central repository. This is also the most common “building block” for more ambitious workflow schemes.

Contributors start by cloning a copy of this repository. They can pull changes from it whenever they need to, and some (perhaps all) developers have permission to push a change back when they're ready for other people to see it.

Under this model, it can still often make sense for people to pull changes directly from each other, without going through the central repository. Consider a case in which I have a tentative bug fix, but I am worried that if I were to publish it to the central repository, it might subsequently break everyone else's trees as they pull it. To reduce the potential for damage, I can ask you to clone my repository into a temporary repository of your own and test it. This lets us put off publishing the potentially unsafe change until it has had a little testing.

If a team is hosting its own repository in this kind of scenario, people will usually use the ssh protocol to securely push changes to the central repository, as documented in 第 6.5 节 “使用 ssh 协议”. It's also usual to publish a read-only copy of the repository over HTTP, as in 第 6.6 节 “使用 CGI 通过 HTTP 提供服务”. Publishing over HTTP satisfies the needs of people who don't have push access, and those who want to use web browsers to browse the repository's history.

A wonderful thing about public hosting services like Bitbucket is that not only do they handle the fiddly server configuration details, such as user accounts, authentication, and secure wire protocols, they provide additional infrastructure to make this model work well.

For instance, a well-engineered hosting service will let people clone their own copies of a repository with a single click. This lets people work in separate spaces and share their changes when they're ready.

In addition, a good hosting service will let people communicate with each other, for instance to say “there are changes ready for you to review in this tree”.

Projects of any significant size naturally tend to make progress on several fronts simultaneously. In the case of software, it's common for a project to go through periodic official releases. A release might then go into “maintenance mode” for a while after its first publication; maintenance releases tend to contain only bug fixes, not new features. In parallel with these maintenance releases, one or more future releases may be under development. People normally use the word “branch” to refer to one of these many slightly different directions in which development is proceeding.

Mercurial is particularly well suited to managing a number of simultaneous, but not identical, branches. Each “development direction” can live in its own central repository, and you can merge changes from one to another as the need arises. Because repositories are independent of each other, unstable changes in a development branch will never affect a stable branch unless someone explicitly merges those changes into the stable branch.

Here's an example of how this can work in practice. Let's say you have one “main branch” on a central server.

$ hg init main
$ cd main
$ echo 'This is a boring feature.' > myfile
$ hg commit -A -m 'We have reached an important milestone!'
adding myfile

People clone it, make changes locally, test them, and push them back.

Once the main branch reaches a release milestone, you can use the hg tag command to give a permanent name to the milestone revision.

$ hg tag v1.0
$ hg tip
changeset:   1:13566bd528e9
tag:         tip
user:        Bryan O'Sullivan <bos@serpentine.com>
date:        Fri Oct 23 01:37:42 2009 +0000
summary:     Added tag v1.0 for changeset 7645a955f751

$ hg tags
tip                                1:13566bd528e9
v1.0                               0:7645a955f751

Let's say some ongoing development occurs on the main branch.

$ cd ../main
$ echo 'This is exciting and new!' >> myfile
$ hg commit -m 'Add a new feature'
$ cat myfile
This is a boring feature.
This is exciting and new!

Using the tag that was recorded at the milestone, people who clone that repository at any time in the future can use hg update to get a copy of the working directory exactly as it was when that tagged revision was committed.

$ cd ..
$ hg clone -U main main-old
$ cd main-old
$ hg update v1.0
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ cat myfile
This is a boring feature.

In addition, immediately after the main branch is tagged, we can then clone the main branch on the server to a new “stable” branch, also on the server.

$ cd ..
$ hg clone -rv1.0 main stable
requesting all changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
updating working directory
1 files updated, 0 files merged, 0 files removed, 0 files unresolved

If we need to make a change to the stable branch, we can then clone that repository, make our changes, commit, and push our changes back there.

$ hg clone stable stable-fix
updating working directory
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ cd stable-fix
$ echo 'This is a fix to a boring feature.' > myfile
$ hg commit -m 'Fix a bug'
$ hg push
pushing to /tmp/branching6Z6CMu/stable
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files

Because Mercurial repositories are independent, and Mercurial doesn't move changes around automatically, the stable and main branches are isolated from each other. The changes that we made on the main branch don't “leak” to the stable branch, and vice versa.

We'll often want all of our bugfixes on the stable branch to show up on the main branch, too. Rather than rewrite a bugfix on the main branch, we can simply pull and merge changes from the stable to the main branch, and Mercurial will bring those bugfixes in for us.

$ cd ../main
$ hg pull ../stable
pulling from ../stable
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
(run 'hg heads' to see heads, 'hg merge' to merge)
$ hg merge
merging myfile
0 files updated, 1 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
$ hg commit -m 'Bring in bugfix from stable branch'
$ cat myfile
This is a fix to a boring feature.
This is exciting and new!

The main branch will still contain changes that are not on the stable branch, but it will also contain all of the bugfixes from the stable branch. The stable branch remains unaffected by these changes, since changes are only flowing from the stable to the main branch, and not the other way.

For larger projects, an effective way to manage change is to break up a team into smaller groups. Each group has a shared branch of its own, cloned from a single “master” branch used by the entire project. People working on an individual branch are typically quite isolated from developments on other branches.

图 6.1. 特性分支

When a particular feature is deemed to be in suitable shape, someone on that feature team pulls and merges from the master branch into the feature branch, then pushes back up to the master branch.

Some projects are organized on a “train” basis: a release is scheduled to happen every few months, and whatever features are ready when the “train” is ready to leave are allowed in.

This model resembles working with feature branches. The difference is that when a feature branch misses a train, someone on the feature team pulls and merges the changes that went out on that train release into the feature branch, and the team continues its work on top of that release so that their feature can make the next release.

The development of the Linux kernel has a shallow hierarchical structure, surrounded by a cloud of apparent chaos. Because most Linux developers use git, a distributed revision control tool with capabilities similar to Mercurial, it's useful to describe the way work flows in that environment; if you like the ideas, the approach translates well across tools.

At the center of the community sits Linus Torvalds, the creator of Linux. He publishes a single source repository that is considered the “authoritative” current tree by the entire developer community. Anyone can clone Linus's tree, but he is very choosy about whose trees he pulls from.

Linus has a number of “trusted lieutenants”. As a general rule, he pulls whatever changes they publish, in most cases without even reviewing those changes. Some of those lieutenants are generally agreed to be “maintainers”, responsible for specific subsystems within the kernel. If a random kernel hacker wants to make a change to a subsystem that they want to end up in Linus's tree, they must find out who the subsystem's maintainer is, and ask that maintainer to take their change. If the maintainer reviews their changes and agrees to take them, they'll pass them along to Linus in due course.

Individual lieutenants have their own approaches to reviewing, accepting, and publishing changes; and for deciding when to feed them to Linus. In addition, there are several well known branches that people use for different purposes. For example, a few people maintain “stable” repositories of older versions of the kernel, to which they apply critical fixes as needed. Some maintainers publish multiple trees: one for experimental changes; one for changes that they are about to feed upstream; and so on. Others just publish a single tree.

This model has two notable features. The first is that it's “pull only”. You have to ask, convince, or beg another developer to take a change from you, because there are almost no trees to which more than one person can push, and there's no way to push changes into a tree that someone else controls.

The second is that it's based on reputation and acclaim. If you're an unknown, Linus will probably ignore changes from you without even responding. But a subsystem maintainer will probably review them, and will likely take them if they pass their criteria for suitability. The more “good” changes you contribute to a maintainer, the more likely they are to trust your judgment and accept your changes. If you're well-known and maintain a long-lived branch for something Linus hasn't yet accepted, people with similar interests may pull your changes regularly to keep up with your work.

Reputation and acclaim don't necessarily cross subsystem or “people” boundaries. If you're a respected but specialised storage hacker, and you try to fix a networking bug, that change will receive a level of scrutiny from a network maintainer comparable to a change from a complete stranger.

To people who come from more orderly project backgrounds, the comparatively chaotic Linux kernel development process often seems completely insane. It's subject to the whims of individuals; people make sweeping changes whenever they deem it appropriate; and the pace of development is astounding. And yet Linux is a highly successful, well-regarded piece of software.

A perpetual source of heat in the open source community is whether a development model in which people only ever pull changes from others is “better than” one in which multiple people can push changes to a shared repository.

Typically, the backers of the shared-push model use tools that actively enforce this approach. If you're using a centralised revision control tool such as Subversion, there's no way to make a choice over which model you'll use: the tool gives you shared-push, and if you want to do anything else, you'll have to roll your own approach on top (such as applying a patch by hand).

A good distributed revision control tool will support both models. You and your collaborators can then structure how you work together based on your own needs and preferences, not on what contortions your tools force you into.

Once you and your team set up some shared repositories and start propagating changes back and forth between local and shared repos, you begin to face a related, but slightly different challenge: that of managing the multiple directions in which your team may be moving at once. Even though this subject is intimately related to how your team collaborates, it's dense enough to merit treatment of its own, in 第 8 章 发布管理与分支开发.

Because it provides unauthenticated read access to all clients, you should only use hg serve in an environment where you either don't care, or have complete control over, who can access your network and pull data from your repository.

The hg serve command knows nothing about any firewall software you might have installed on your system or network. It cannot detect or control your firewall software. If other people are unable to talk to a running hg serve instance, the second thing you should do (after you make sure that they're using the correct URL) is check your firewall configuration.

By default, hg serve listens for incoming connections on port 8000. If another process is already listening on the port you want to use, you can specify a different port to listen on using the -p option.

Normally, when hg serve starts, it prints no output, which can be a bit unnerving. If you'd like to confirm that it is indeed running correctly, and find out what URL you should send to your collaborators, start it with the -v option.

An ssh URL tends to look like this:

ssh://bos@hg.serpentine.com:22/hg/hgbook

There's plenty of scope for confusion with the path component of ssh URLs, as there is no standard way for tools to interpret it. Some programs behave differently than others when dealing with these paths. This isn't an ideal situation, but it's unlikely to change. Please read the following paragraphs carefully.

Mercurial treats the path to a repository on the server as relative to the remote user's home directory. For example, if user foo on the server has a home directory of /home/foo, then an ssh URL that contains a path component of bar really refers to the directory /home/foo/bar.

If you want to specify a path relative to another user's home directory, you can use a path that starts with a tilde character followed by the user's name (let's call them otheruser), like this.

ssh://server/~otheruser/hg/repo

And if you really want to specify an absolute path on the server, begin the path component with two slashes, as in this example.

ssh://server//absolute/path

Almost every Unix-like system comes with OpenSSH preinstalled. If you're using such a system, run which ssh to find out if the ssh command is installed (it's usually in /usr/bin). In the unlikely event that it isn't present, take a look at your system documentation to figure out how to install it.

On Windows, the TortoiseHg package is bundled with a version of Simon Tatham's excellent plink command, and you should not need to do any further configuration.

To avoid the need to repetitively type a password every time you need to use your ssh client, I recommend generating a key pair.

	Key pairs are not mandatory
	Mercurial knows nothing about ssh authentication or key pairs. You can, if you like, safely ignore this section and the one that follows until you grow tired of repeatedly typing ssh passwords.

When you generate a key pair, it's usually highly advisable to protect it with a passphrase. (The only time that you might not want to do this is when you're using the ssh protocol for automated tasks on a secure network.)

Simply generating a key pair isn't enough, however. You'll need to add the public key to the set of authorised keys for whatever user you're logging in remotely as. For servers using OpenSSH (the vast majority), this will mean adding the public key to a list in a file called authorized_keys in their .ssh directory.

On a Unix-like system, your public key will have a .pub extension. If you're using puttygen on Windows, you can save the public key to a file of your choosing, or paste it from the window it's displayed in straight into the authorized_keys file.

An authentication agent is a daemon that stores passphrases in memory (so it will forget passphrases if you log out and log back in again). An ssh client will notice if it's running, and query it for a passphrase. If there's no authentication agent running, or the agent doesn't store the necessary passphrase, you'll have to type your passphrase every time Mercurial tries to communicate with a server on your behalf (e.g. whenever you pull or push changes).

The downside of storing passphrases in an agent is that it's possible for a well-prepared attacker to recover the plain text of your passphrases, in some cases even if your system has been power-cycled. You should make your own judgment as to whether this is an acceptable risk. It certainly saves a lot of repeated typing.

Because ssh can be fiddly to set up if you're new to it, a variety of things can go wrong. Add Mercurial on top, and there's plenty more scope for head-scratching. Most of these potential problems occur on the server side, not the client side. The good news is that once you've gotten a configuration working, it will usually continue to work indefinitely.

Before you try using Mercurial to talk to an ssh server, it's best to make sure that you can use the normal ssh or putty command to talk to the server first. If you run into problems with using these commands directly, Mercurial surely won't work. Worse, it will obscure the underlying problem. Any time you want to debug ssh-related Mercurial problems, you should drop back to making sure that plain ssh client commands work first, before you worry about whether there's a problem with Mercurial.

The first thing to be sure of on the server side is that you can actually log in from another machine at all. If you can't use ssh or putty to log in, the error message you get may give you a few hints as to what's wrong. The most common problems are as follows.

In summary, if you're having trouble talking to the server's ssh daemon, first make sure that one is running at all. On many systems it will be installed, but disabled, by default. Once you're done with this step, you should then check that the server's firewall is configured to allow incoming connections on the port the ssh daemon is listening on (usually 22). Don't worry about more exotic possibilities for misconfiguration until you've checked these two first.

If you're using an authentication agent on the client side to store passphrases for your keys, you ought to be able to log into the server without being prompted for a passphrase or a password. If you're prompted for a passphrase, there are a few possible culprits.

If you're being prompted for the remote user's password, there are another few possible problems to check.

In the ideal world, you should be able to run the following command successfully, and it should print exactly one line of output, the current date and time.

ssh myserver date

If, on your server, you have login scripts that print banners or other junk even when running non-interactive commands like this, you should fix them before you continue, so that they only print output if they're run interactively. Otherwise these banners will at least clutter up Mercurial's output. Worse, they could potentially cause problems with running Mercurial commands remotely. Mercurial tries to detect and ignore banners in non-interactive ssh sessions, but it is not foolproof. (If you're editing your login scripts on your server, the usual way to see if a login script is running in an interactive shell is to check the return code from the command tty -s.)

Once you've verified that plain old ssh is working with your server, the next step is to ensure that Mercurial runs on the server. The following command should run successfully:

ssh myserver hg version

If you see an error message instead of normal hg version output, this is usually because you haven't installed Mercurial to /usr/bin. Don't worry if this is the case; you don't need to do that. But you should check for a few possible problems.

If you can run hg version over an ssh connection, well done! You've got the server and client sorted out. You should now be able to use Mercurial to access repositories hosted by that username on that server. If you run into problems with Mercurial and ssh at this point, try using the --debug option to get a clearer picture of what's going on.

Mercurial does not compress data when it uses the ssh protocol, because the ssh protocol can transparently compress data. However, the default behavior of ssh clients is not to request compression.

Over any network other than a fast LAN (even a wireless network), using compression is likely to significantly speed up Mercurial's network operations. For example, over a WAN, someone measured compression as reducing the amount of time required to clone a particularly large repository from 51 minutes to 17 minutes.

Both ssh and plink accept a -C option which turns on compression. You can easily edit your ~/.hgrc to enable compression for all of Mercurial's uses of the ssh protocol. Here is how to do so for regular ssh on Unix-like systems, for example.

[ui]
ssh = ssh -C

If you use ssh on a Unix-like system, you can configure it to always use compression when talking to your server. To do this, edit your .ssh/config file (which may not yet exist), as follows.

Host hg
  Compression yes
  HostName hg.example.com

This defines a hostname alias, hg. When you use that hostname on the ssh command line or in a Mercurial ssh-protocol URL, it will cause ssh to connect to hg.example.com and use compression. This gives you both a shorter name to type and compression, each of which is a good thing in its own right.

Before you continue, do take a few moments to check a few aspects of your system's setup.

If you don't have a web server installed, and don't have substantial experience configuring Apache, you should consider using the lighttpd web server instead of Apache. Apache has a well-deserved reputation for baroque and confusing configuration. While lighttpd is less capable in some ways than Apache, most of these capabilities are not relevant to serving Mercurial repositories. And lighttpd is undeniably much easier to get started with than Apache.

On Unix-like systems, it's common for users to have a subdirectory named something like public_html in their home directory, from which they can serve up web pages. A file named foo in this directory will be accessible at a URL of the form http://www.example.com/username/foo.

To get started, find the hgweb.cgi script that should be present in your Mercurial installation. If you can't quickly find a local copy on your system, simply download one from the master Mercurial repository at http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi.

You'll need to copy this script into your public_html directory, and ensure that it's executable.

cp .../hgweb.cgi ~/public_html
chmod 755 ~/public_html/hgweb.cgi

The 755 argument to chmod is a little more general than just making the script executable: it ensures that the script is executable by anyone, and that “group” and “other” write permissions are not set. If you were to leave those write permissions enabled, Apache's suexec subsystem would likely refuse to execute the script. In fact, suexec also insists that the directory in which the script resides must not be writable by others.

chmod 755 ~/public_html

chmod 755 ~
find ~/public_html -type d -print0 | xargs -0r chmod 755
find ~/public_html -type f -print0 | xargs -0r chmod 644

<Directory /home/*/public_html>
  AllowOverride FileInfo AuthConfig Limit
  Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
  <Limit GET POST OPTIONS>
    Order allow,deny
    Allow from all
  </Limit>
  <LimitExcept GET POST OPTIONS>
    Order deny,allow Deny from all
  </LimitExcept>
</Directory>

AddHandler cgi-script .cgi

userdir.path = "public_html"
cgi.assign = (".cgi" => "" )

The hgweb.cgi script only lets you publish a single repository, which is an annoying restriction. If you want to publish more than one without wracking yourself with multiple copies of the same script, each with different names, a better choice is to use the hgwebdir.cgi script.

The procedure to configure hgwebdir.cgi is only a little more involved than for hgweb.cgi. First, you must obtain a copy of the script. If you don't have one handy, you can download a copy from the master Mercurial repository at http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi.

You'll need to copy this script into your public_html directory, and ensure that it's executable.

cp .../hgwebdir.cgi ~/public_html
chmod 755 ~/public_html ~/public_html/hgwebdir.cgi

With basic configuration out of the way, try to visit http://myhostname/~myuser/hgwebdir.cgi in your browser. It should display an empty list of repositories. If you get a blank window or error message, try walking through the list of potential problems in 第 6.6.2.1 节 “什么可能会出错?”.

The hgwebdir.cgi script relies on an external configuration file. By default, it searches for a file named hgweb.config in the same directory as itself. You'll need to create this file, and make it world-readable. The format of the file is similar to a Windows “ini” file, as understood by Python's ConfigParser [web:configparser] module.

The easiest way to configure hgwebdir.cgi is with a section named collections. This will automatically publish every repository under the directories you name. The section should look like this:

[collections]
/my/root = /my/root

Mercurial interprets this by looking at the directory name on the right hand side of the “=” sign; finding repositories in that directory hierarchy; and using the text on the left to strip off matching text from the names it will actually list in the web interface. The remaining component of a path after this stripping has occurred is called a “virtual path”.

Given the example above, if we have a repository whose local path is /my/root/this/repo, the CGI script will strip the leading /my/root from the name, and publish the repository with a virtual path of this/repo. If the base URL for our CGI script is http://myhostname/~myuser/hgwebdir.cgi, the complete URL for that repository will be http://myhostname/~myuser/hgwebdir.cgi/this/repo.

If we replace /my/root on the left hand side of this example with /my, then hgwebdir.cgi will only strip off /my from the repository name, and will give us a virtual path of root/this/repo instead of this/repo.

The hgwebdir.cgi script will recursively search each directory listed in the collections section of its configuration file, but it will not recurse into the repositories it finds.

The collections mechanism makes it easy to publish many repositories in a “fire and forget” manner. You only need to set up the CGI script and configuration file one time. Afterwards, you can publish or unpublish a repository at any time by simply moving it into, or out of, the directory hierarchy in which you've configured hgwebdir.cgi to look.

6.6.3.1. 明确指出要发布的版本库

In addition to the collections mechanism, the hgwebdir.cgi script allows you to publish a specific list of repositories. To do so, create a paths section, with contents of the following form.

[paths]
repo1 = /my/path/to/some/repo
repo2 = /some/path/to/another

In this case, the virtual path (the component that will appear in a URL) is on the left hand side of each definition, while the path to the repository is on the right. Notice that there does not need to be any relationship between the virtual path you choose and the location of a repository in your filesystem.

If you wish, you can use both the collections and paths mechanisms simultaneously in a single configuration file.

	Beware duplicate virtual paths
	If several repositories have the same virtual path, hgwebdir.cgi will not report an error. Instead, it will behave unpredictably.

Mercurial's web interface lets users download an archive of any revision. This archive will contain a snapshot of the working directory as of that revision, but it will not contain a copy of the repository data.

By default, this feature is not enabled. To enable it, you'll need to add an allow_archive item to the web section of your ~/.hgrc; see below for details.

Mercurial's web interfaces (the hg serve command, and the hgweb.cgi and hgwebdir.cgi scripts) have a number of configuration options that you can set. These belong in a section named web.

If you are using hgwebdir.cgi, you can place a few configuration items in a web section of the hgweb.config file instead of a ~/.hgrc file, for convenience. These items are motd and style.

One situation in which a global hgrc can be useful is if users are pulling changes owned by other users. By default, Mercurial will not trust most of the configuration items in a .hg/hgrc file inside a repository that is owned by a different user. If we clone or pull changes from such a repository, Mercurial will print a warning stating that it does not trust their .hg/hgrc.

If everyone in a particular Unix group is on the same team and should trust each other's configuration settings, or we want to trust particular users, we can override Mercurial's skeptical defaults by creating a system-wide hgrc file such as the following:

# Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
[trusted]
# Trust all entries in any hgrc file owned by the "editors" or
# "www-data" groups.
groups = editors, www-data

# Trust entries in hgrc files owned by the following users.
users = apache, bobo

This is an overview of the kinds of patterns you can use when you're matching on glob patterns.

The “*” character matches any string, within a single directory.

$ hg add 'glob:*.py'
adding main.py

The “**” pattern matches any string, and crosses directory boundaries. It's not a standard Unix glob token, but it's accepted by several popular Unix shells, and is very useful.

$ cd ..
$ hg status 'glob:**.py'
A examples/simple.py
A src/main.py
? examples/performant.py
? setup.py
? src/watcher/watcher.py

The “?” pattern matches any single character.

$ hg status 'glob:**.?'
? src/watcher/_watcher.c

The “[” character begins a character class. This matches any single character within the class. The class ends with a “]” character. A class may contain multiple ranges of the form “a-f”, which is shorthand for “abcdef”.

$ hg status 'glob:**[nr-t]'
? MANIFEST.in
? src/xyzzy.txt

If the first character after the “[” in a character class is a “!”, it negates the class, making it match any single character not in the class.

A “{” begins a group of subpatterns, where the whole group matches if any subpattern in the group matches. The “,” character separates subpatterns, and “}” ends the group.

$ hg status 'glob:*.{in,py}'
? MANIFEST.in
? setup.py

$ hg status 'glob:*.py'
? setup.py
$ hg status 'glob:**.py'
A examples/simple.py
A src/main.py
? examples/performant.py
? setup.py
? src/watcher/watcher.py

Mercurial accepts the same regular expression syntax as the Python programming language (it uses Python's regexp engine internally). This is based on the Perl language's regexp syntax, which is the most popular dialect in use (it's also used in Java, for example).

I won't discuss Mercurial's regexp dialect in any detail here, as regexps are not often used. Perl-style regexps are in any case already exhaustively documented on a multitude of web sites, and in many books. Instead, I will focus here on a few things you should know if you find yourself needing to use regexps with Mercurial.

A regexp is matched against an entire file name, relative to the root of the repository. In other words, even if you're already in subbdirectory foo, if you want to match files under this directory, your pattern must start with “foo/”.

One thing to note, if you're familiar with Perl-style regexps, is that Mercurial's are rooted. That is, a regexp starts matching against the beginning of a string; it doesn't look for a match anywhere within the string. To match anywhere in a string, start your pattern with “.*”.

Mercurial's repository storage mechanism is case safe. It translates file names so that they can be safely stored on both case sensitive and case insensitive filesystems. This means that you can use normal file copying tools to transfer a Mercurial repository onto, for example, a USB thumb drive, and safely move that drive and repository back and forth between a Mac, a PC running Windows, and a Linux box.

When operating in the working directory, Mercurial honours the naming policy of the filesystem where the working directory is located. If the filesystem is case preserving, but insensitive, Mercurial will treat names that differ only in case as the same.

An important aspect of this approach is that it is possible to commit a changeset on a case sensitive (typically Linux or Unix) filesystem that will cause trouble for users on case insensitive (usually Windows and MacOS) users. If a Linux user commits changes to two files, one named myfile.c and the other named MyFile.C, they will be stored correctly in the repository. And in the working directories of other Linux users, they will be correctly represented as separate files.

If a Windows or Mac user pulls this change, they will not initially have a problem, because Mercurial's repository storage mechanism is case safe. However, once they try to hg update the working directory to that changeset, or hg merge with that changeset, Mercurial will spot the conflict between the two file names that the filesystem would treat as the same, and forbid the update or merge from occurring.

If you are using Windows or a Mac in a mixed environment where some of your collaborators are using Linux or Unix, and Mercurial reports a case folding conflict when you try to hg update or hg merge, the procedure to fix the problem is simple.

Just find a nearby Linux or Unix box, clone the problem repository onto it, and use Mercurial's hg rename command to change the names of any offending files or directories so that they will no longer cause case folding conflicts. Commit this change, hg pull or hg push it across to your Windows or MacOS system, and hg update to the revision with the non-conflicting names.

The changeset with case-conflicting names will remain in your project's history, and you still won't be able to hg update your working directory to that changeset on a Windows or MacOS system, but you can continue development unimpeded.

You won't often need to care about the .hgtags file, but it sometimes makes its presence known during a merge. The format of the file is simple: it consists of a series of lines. Each line starts with a changeset hash, followed by a space, followed by the name of a tag.

If you're resolving a conflict in the .hgtags file during a merge, there's one twist to modifying the .hgtags file: when Mercurial is parsing the tags in a repository, it never reads the working copy of the .hgtags file. Instead, it reads the most recently committed revision of the file.

An unfortunate consequence of this design is that you can't actually verify that your merged .hgtags file is correct until after you've committed a change. So if you find yourself resolving a conflict on .hgtags during a merge, be sure to run hg tags after you commit. If it finds an error in the .hgtags file, it will report the location of the error, which you can then fix and commit. You should then run hg tags again, just to be sure that your fix is correct.

You may have noticed that the hg clone command has a -r option that lets you clone an exact copy of the repository as of a particular changeset. The new clone will not contain any project history that comes after the revision you specified. This has an interaction with tags that can surprise the unwary.

Recall that a tag is stored as a revision to the .hgtags file. When you create a tag, the changeset in which its recorded refers to an older changeset. When you run hg clone -r foo to clone a repository as of tag foo, the new clone will not contain any revision newer than the one the tag refers to, including the revision where the tag was created. The result is that you'll get exactly the right subset of the project's history in the new repository, but not the tag you might have expected.

Since Mercurial's tags are revision controlled and carried around with a project's history, everyone you work with will see the tags you create. But giving names to revisions has uses beyond simply noting that revision 4237e45506ee is really v2.0.2. If you're trying to track down a subtle bug, you might want a tag to remind you of something like “Anne saw the symptoms with this revision”.

For cases like this, what you might want to use are local tags. You can create a local tag with the -l option to the hg tag command. This will store the tag in a file called .hg/localtags. Unlike .hgtags, .hg/localtags is not revision controlled. Any tags you create using -l remain strictly local to the repository you're currently working in.