1.1 --- a/.hgignore	Thu Mar 26 08:57:10 2009 +0100
     1.2 +++ b/.hgignore	Sun Aug 16 03:41:39 2009 +0200
     1.3 @@ -1,37 +1,33 @@
     1.4 -[^/]+/auto/
     1.5 -[^/]+/dist/
     1.6 -[^/]+/html/
     1.7 +[^/]+/htdocs/
     1.8  
     1.9  syntax: glob
    1.10  
    1.11 -beta/*.tex
    1.12 -build_id.tex
    1.13 -hg_id.tex
    1.14 -*.4[ct][ct]
    1.15 -*.aux
    1.16 -*.bbl
    1.17 -*.bib
    1.18 -*.blg
    1.19 -*.dvi
    1.20 -*.eps
    1.21 +*-tmp.*
    1.22  *.err
    1.23 -*.idx
    1.24 -*.ilg
    1.25 -*.ind
    1.26 -*.lg
    1.27 -*.lo[fgt]
    1.28  *.lxo
    1.29 +*.mo
    1.30  *.orig
    1.31  *.out
    1.32 -*.pdf
    1.33 +*.bb
    1.34  *.png
    1.35 -*.ps
    1.36 +*.pyc
    1.37  *.rej
    1.38  *.run
    1.39 -*.tmp
    1.40 -*.toc
    1.41 -*.xref
    1.42  *~
    1.43 -.*.swp
    1.44 +.*.sw[op]
    1.45  .\#*
    1.46  .run
    1.47 +.validated-00book.xml
    1.48 +Makefile.vars
    1.49 +build
    1.50 +en/all-ids.dat
    1.51 +en/complete.xml
    1.52 +en/examples/results
    1.53 +en/html
    1.54 +en/svn
    1.55 +stylesheets/system-xsl
    1.56 +tools
    1.57 +web/hgbook/.database.sqlite3
    1.58 +web/hgbook/secrets.py
    1.59 +web/index-read.html.in
    1.60 +xsl/system-xsl

     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/.hgtags	Sun Aug 16 03:41:39 2009 +0200
     2.3 @@ -0,0 +1,1 @@
     2.4 +18131160f7ee3b81bf39ce2c58f762b8d671cef3 submitted

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/Makefile	Sun Aug 16 03:41:39 2009 +0200
     3.3 @@ -0,0 +1,254 @@
     3.4 +#
     3.5 +# Makefile for the hgbook, top-level
     3.6 +#
     3.7 +include Makefile.vars
     3.8 +
     3.9 +FORMATS=html html-single pdf epub
    3.10 +
    3.11 +PO_LANGUAGES := zh
    3.12 +DBK_LANGUAGES := en
    3.13 +LANGUAGES := $(DBK_LANGUAGES) $(PO_LANGUAGES)
    3.14 +
    3.15 +UPDATEPO = PERLLIB=$(PO4A_LIB) $(PO4A_HOME)/po4a-updatepo -M UTF-8 \
    3.16 +	   -f docbook -o doctype=docbook -o includeexternal \
    3.17 +	   -o nodefault="<programlisting> <screen>" \
    3.18 +	   -o untranslated="<programlisting> <screen>"
    3.19 +TRANSLATE = PERLLIB=$(PO4A_LIB) $(PO4A_HOME)/po4a-translate -M UTF-8 \
    3.20 +	   -f docbook -o doctype=docbook -o includeexternal \
    3.21 +	   -o nodefault="<programlisting> <screen>" \
    3.22 +	   -o untranslated="<programlisting> <screen>" \
    3.23 +	   -k 0
    3.24 +
    3.25 +#rev_id = $(shell hg parents --template '{node|short} ({date|isodate})')
    3.26 +rev_id = $(shell hg parents --template '{node|short} ({date|shortdate})')
    3.27 +
    3.28 +images := \
    3.29 +	en/figs/bad-merge-1.png \
    3.30 +	en/figs/bad-merge-2.png \
    3.31 +	en/figs/bad-merge-3.png \
    3.32 +	en/figs/bad-merge-4.png \
    3.33 +	en/figs/bad-merge-5.png \
    3.34 +	en/figs/feature-branches.png \
    3.35 +	en/figs/filelog.png \
    3.36 +	en/figs/metadata.png \
    3.37 +	en/figs/mq-stack.png \
    3.38 +	en/figs/revlog.png \
    3.39 +	en/figs/snapshot.png \
    3.40 +	en/figs/tour-history.png \
    3.41 +	en/figs/tour-merge-conflict.png \
    3.42 +	en/figs/tour-merge-merge.png \
    3.43 +	en/figs/tour-merge-pull.png \
    3.44 +	en/figs/tour-merge-sep-repos.png \
    3.45 +	en/figs/undo-manual-merge.png \
    3.46 +	en/figs/undo-manual.png \
    3.47 +	en/figs/undo-non-tip.png \
    3.48 +	en/figs/undo-simple.png \
    3.49 +	en/figs/wdir-after-commit.png \
    3.50 +	en/figs/wdir-branch.png \
    3.51 +	en/figs/wdir-merge.png \
    3.52 +	en/figs/wdir.png \
    3.53 +	en/figs/wdir-pre-branch.png
    3.54 +
    3.55 +help:
    3.56 +	@echo "  make epub         [LINGUA=en|zh|...]"
    3.57 +	@echo "  make html         [LINGUA=en|zh|...]"
    3.58 +	@echo "  make html-single  [LINGUA=en|zh|...]"
    3.59 +	@echo "  make pdf          [LINGUA=en|zh|...]"
    3.60 +	@echo "  make validate     [LINGUA=en|zh|...] # always before commit!"
    3.61 +	@echo "  make tidypo       [LINGUA=zh|...]    # always before commit!"
    3.62 +	@echo "  make updatepo     [LINGUA=zh|...]    # update po files."
    3.63 +	@echo "  make all          [LINGUA=en|zh|...]"
    3.64 +	@echo "  make stat         # print statistics about po files."
    3.65 +	@echo "  make clean        # Remove the build files."
    3.66 +
    3.67 +clean:
    3.68 +	@rm -fr build po/*.mo hello en/hello en/html en/.validated-00book.xml en/examples/.run en/examples/results \
    3.69 +          stylesheets/system-xsl en/figs/*-tmp.svg \
    3.70 +          web/index-read.html.in \
    3.71 +          en/figs/bad-merge-1.png \
    3.72 +          en/figs/bad-merge-2.png \
    3.73 +          en/figs/bad-merge-3.png \
    3.74 +          en/figs/bad-merge-4.png \
    3.75 +          en/figs/bad-merge-5.png \
    3.76 +          en/figs/feature-branches.png \
    3.77 +          en/figs/filelog.png \
    3.78 +          en/figs/feature-branches.png \
    3.79 +          en/figs/filelog.png \
    3.80 +          en/figs/metadata.png \
    3.81 +          en/figs/mq-stack.png \
    3.82 +          en/figs/revlog.png \
    3.83 +          en/figs/snapshot.png \
    3.84 +          en/figs/tour-history.png \
    3.85 +          en/figs/tour-merge-conflict.png \
    3.86 +          en/figs/tour-merge-merge.png \
    3.87 +          en/figs/tour-merge-pull.png \
    3.88 +          en/figs/tour-merge-sep-repos.png \
    3.89 +          en/figs/undo-manual-merge.png \
    3.90 +          en/figs/undo-manual.png \
    3.91 +          en/figs/undo-non-tip.png \
    3.92 +          en/figs/undo-simple.png \
    3.93 +          en/figs/wdir-after-commit.png \
    3.94 +          en/figs/wdir-branch.png \
    3.95 +          en/figs/wdir-merge.png \
    3.96 +          en/figs/wdir-pre-branch.png \
    3.97 +          en/figs/wdir.png
    3.98 +
    3.99 +all:
   3.100 +ifdef LINGUA
   3.101 +	for f in $(FORMATS); do \
   3.102 +	  $(MAKE) LINGUA=$(LINGUA) $$f; \
   3.103 +	done
   3.104 +else
   3.105 +	for l in $(LANGUAGES); do \
   3.106 +	    for f in $(FORMATS); do \
   3.107 +		$(MAKE) LINGUA=$$l $$f; \
   3.108 +	    done; \
   3.109 +	done
   3.110 +endif
   3.111 +
   3.112 +stat:
   3.113 +	@( \
   3.114 +	LANG=C; export LANG; cd po; \
   3.115 +	for f in *.po; do \
   3.116 +	    printf "%s\t" $$f; \
   3.117 +	    msgfmt --statistics -c $$f; \
   3.118 +	done; \
   3.119 +	)
   3.120 +
   3.121 +tidypo:
   3.122 +ifdef LINGUA
   3.123 +	msgcat --sort-by-file --width=80 po/$(LINGUA).po > po/$(LINGUA).tmp && \
   3.124 +	    mv po/$(LINGUA).tmp po/$(LINGUA).po;
   3.125 +else
   3.126 +	for po in $(wildcard po/*.po); do \
   3.127 +	    msgcat --sort-by-file --width=80 $$po > $$po.tmp && mv $$po.tmp $$po; \
   3.128 +	done
   3.129 +endif
   3.130 +
   3.131 +ifndef LINGUA
   3.132 +updatepo:
   3.133 +	for l in $(PO_LANGUAGES); do \
   3.134 +	    $(MAKE) $@ LINGUA=$$l; \
   3.135 +	done
   3.136 +else
   3.137 +updatepo:
   3.138 +ifneq "$(findstring $(LINGUA),$(PO_LANGUAGES))" ""
   3.139 +	(cd po; \
   3.140 +	$(UPDATEPO) -m ../en/00book.xml -p $(LINGUA).po; \
   3.141 +	)
   3.142 +	$(MAKE) tidypo LINGUA=$(LINGUA)
   3.143 +endif
   3.144 +endif
   3.145 +
   3.146 +ifndef LINGUA
   3.147 +validate:
   3.148 +	for l in $(LANGUAGES); do \
   3.149 +	    $(MAKE) $@ LINGUA=$$l; \
   3.150 +	done
   3.151 +else
   3.152 +validate: build/$(LINGUA)/source/hgbook.xml
   3.153 +	xmllint --nonet --noout --postvalid --xinclude $<
   3.154 +
   3.155 +ifneq "$(findstring $(LINGUA),$(DBK_LANGUAGES))" ""
   3.156 +$(LINGUA)/examples/.run:
   3.157 +	(cd $(LINGUA)/examples; ./run-example -v -a)
   3.158 +
   3.159 +build/$(LINGUA)/source/hgbook.xml: $(wildcard $(LINGUA)/*.xml) $(images) $(LINGUA)/examples/.run
   3.160 +	mkdir -p build/$(LINGUA)/source/figs
   3.161 +	cp $(LINGUA)/figs/*.png build/$(LINGUA)/source/figs
   3.162 +	cp stylesheets/hgbook.css build/$(LINGUA)/source
   3.163 +	(cd $(LINGUA); xmllint --nonet --noent --xinclude --postvalid --output ../$@.tmp 00book.xml)
   3.164 +	cat $@.tmp | sed 's/\$$rev_id\$$/${rev_id}/' > $@
   3.165 +else
   3.166 +en/examples/.run:
   3.167 +	(cd en/examples; ./run-example -v -a)
   3.168 +
   3.169 +build/en/source/hgbook.xml:
   3.170 +	${MAKE} LINGUA=en $@
   3.171 +
   3.172 +build/$(LINGUA)/source/hgbook.xml: $(wildcard en/*.xml) po/$(LINGUA).po $(images)
   3.173 +	mkdir -p build/$(LINGUA)/source/figs
   3.174 +	cp en/figs/*.png build/$(LINGUA)/source/figs
   3.175 +	cp stylesheets/hgbook.css build/$(LINGUA)/source
   3.176 +	$(TRANSLATE) -m en/00book.xml -p po/$(LINGUA).po -l en/hgbook.xml.$(LINGUA)
   3.177 +	xmllint --nonet --noent --xinclude --postvalid --output $@.tmp en/hgbook.xml.$(LINGUA)
   3.178 +	cat $@.tmp | sed 's/\$$rev_id\$$/${rev_id}/' > $@
   3.179 +	mv en/hgbook.xml.$(LINGUA) build/$(LINGUA)/source
   3.180 +endif
   3.181 +
   3.182 +endif
   3.183 +
   3.184 +ifndef LINGUA
   3.185 +epub:
   3.186 +	for l in $(LANGUAGES); do \
   3.187 +	    $(MAKE) $@ LINGUA=$$l; \
   3.188 +	done
   3.189 +else
   3.190 +epub: build/$(LINGUA)/epub/hgbook.epub
   3.191 +
   3.192 +build/$(LINGUA)/epub/hgbook.epub: build/$(LINGUA)/source/hgbook.xml
   3.193 +	mkdir -p build/$(LINGUA)/epub
   3.194 +	(cd build/$(LINGUA)/source; $(DB2EPUB) -c hgbook.css -v hgbook.xml; mv hgbook.epub ../epub)
   3.195 +endif
   3.196 +
   3.197 +ifndef LINGUA
   3.198 +html:
   3.199 +	for l in $(LANGUAGES); do \
   3.200 +	    $(MAKE) $@ LINGUA=$$l; \
   3.201 +	done
   3.202 +else
   3.203 +html: build/$(LINGUA)/html/index.html
   3.204 +
   3.205 +build/$(LINGUA)/html/index.html: build/$(LINGUA)/source/hgbook.xml stylesheets/html.xsl stylesheets/$(LINGUA)/html.xsl
   3.206 +	mkdir -p build/$(LINGUA)/html/figs
   3.207 +	cp en/figs/*.png build/$(LINGUA)/html/figs
   3.208 +	cp stylesheets/hgbook.css build/$(LINGUA)/html
   3.209 +	xsltproc --output build/$(LINGUA)/html/ \
   3.210 +	    stylesheets/$(LINGUA)/html.xsl build/$(LINGUA)/source/hgbook.xml
   3.211 +endif
   3.212 +
   3.213 +ifndef LINGUA
   3.214 +html-single:
   3.215 +	for l in $(LANGUAGES); do \
   3.216 +	    $(MAKE) $@ LINGUA=$$l; \
   3.217 +	done
   3.218 +else
   3.219 +html-single: build/$(LINGUA)/html-single/hgbook.html
   3.220 +
   3.221 +build/$(LINGUA)/html-single/hgbook.html: build/$(LINGUA)/source/hgbook.xml stylesheets/html-single.xsl stylesheets/$(LINGUA)/html-single.xsl
   3.222 +	mkdir -p build/$(LINGUA)/html-single/figs
   3.223 +	cp en/figs/*.png build/$(LINGUA)/html-single/figs
   3.224 +	cp stylesheets/hgbook.css build/$(LINGUA)/html-single
   3.225 +	xsltproc --output build/$(LINGUA)/html-single/hgbook.html \
   3.226 +	    stylesheets/$(LINGUA)/html-single.xsl build/$(LINGUA)/source/hgbook.xml
   3.227 +endif
   3.228 +
   3.229 +ifndef LINGUA
   3.230 +pdf:
   3.231 +	for l in $(LANGUAGES); do \
   3.232 +	    $(MAKE) $@ LINGUA=$$l; \
   3.233 +	done
   3.234 +else
   3.235 +pdf: build/$(LINGUA)/pdf/hgbook.pdf
   3.236 +
   3.237 +build/$(LINGUA)/pdf/hgbook.pdf: build/$(LINGUA)/source/hgbook.xml stylesheets/fo.xsl stylesheets/$(LINGUA)/fo.xsl
   3.238 +	mkdir -p build/$(LINGUA)/pdf
   3.239 +	java -classpath $(JAVA_LIB)/saxon65.jar:$(JAVA_LIB)/saxon65-dbxsl.jar:$(JAVA_LIB)/xml-commons-resolver-1.2.jar:$(JAVA_LIB) \
   3.240 +	    com.icl.saxon.StyleSheet \
   3.241 +	    -x org.apache.xml.resolver.tools.ResolvingXMLReader \
   3.242 +	    -y org.apache.xml.resolver.tools.ResolvingXMLReader \
   3.243 +	    -r org.apache.xml.resolver.tools.CatalogResolver \
   3.244 +	    -o build/$(LINGUA)/source/hgbook.fo \
   3.245 +	    build/$(LINGUA)/source/hgbook.xml \
   3.246 +	    stylesheets/$(LINGUA)/fo.xsl \
   3.247 +	    fop1.extensions=1
   3.248 +
   3.249 +	(cd build/$(LINGUA)/source && $(FOP_HOME)/fop.sh -c $(FOP_HOME)/conf/userconfig.xml hgbook.fo ../pdf/hgbook.pdf)
   3.250 +endif
   3.251 +
   3.252 +en/figs/%.png: en/figs/%.svg en/fixsvg
   3.253 +	en/fixsvg $<
   3.254 +	inkscape -D -d 120 -e $@ $<-tmp.svg
   3.255 +
   3.256 +en/figs/%.svg: en/figs/%.dot
   3.257 +	dot -Tsvg -o $@ $<

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/Makefile.vars.tmpl	Sun Aug 16 03:41:39 2009 +0200
     4.3 @@ -0,0 +1,20 @@
     4.4 +#
     4.5 +# Please create your Makefile.vars file from this template file.
     4.6 +#
     4.7 +# Please use absolute path, DO NOT use relative path !
     4.8 +#
     4.9 +
    4.10 +# po4a (>= 0.36.1): Only for PO based Makefile !
    4.11 +# po4A_HOME=/usr/bin
    4.12 +# PO4A_LIB=/usr/share/perl5
    4.13 +PO4A_HOME=/home/dongsheng/var/svn/i18n-zh/trunk/lib/po4a
    4.14 +PO4A_LIB=$(PO4A_HOME)/lib
    4.15 +
    4.16 +# saxon65.jar, saxon65-dbxsl.jar, xml-commons-resolver-1.2.jar: Only for pdf format !
    4.17 +JAVA_LIB=/home/dongsheng/var/svn/i18n-zh/trunk/lib/share/java
    4.18 +
    4.19 +# fop (>= 0.9.6): Only for pdf format !
    4.20 +FOP_HOME=/home/dongsheng/var/svn/i18n-zh/trunk/lib/fop
    4.21 +
    4.22 +# docbook-xsl (>= 1.74.3): Only for ePub format !
    4.23 +DB2EPUB=/home/dongsheng/var/svn/i18n-zh/trunk/lib/docbook/docbook-xsl/epub/bin/dbtoepub

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/README	Sun Aug 16 03:41:39 2009 +0200
     5.3 @@ -0,0 +1,16 @@
     5.4 +Mercurial: The Definitive Guide
     5.5 +-------------------------------
     5.6 +
     5.7 +Welcome to the source code for the book.  You can clone the definitive
     5.8 +copy of the source tree using Mercurial as follows:
     5.9 +
    5.10 +  hg clone http://hg.serpentine.com/mercurial/book
    5.11 +
    5.12 +Here's a top-level tour of interesting directories:
    5.13 +
    5.14 +en        English-language content
    5.15 +es        Spanish-language content
    5.16 +examples  Miscellaneous example scripts
    5.17 +tools     Old, largely unused conversion scripts
    5.18 +web       Content and comment system for http://hgbook.red-bean.com/
    5.19 +xsl       XSLT scripts for generating HTML

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/README.BUILD	Sun Aug 16 03:41:39 2009 +0200
     6.3 @@ -0,0 +1,99 @@
     6.4 +HOW-TO:  Compiling the Mercurial Book
     6.5 +======================================
     6.6 +
     6.7 +This Mercurial Book is written in DocBook 4.5.
     6.8 +
     6.9 +The goal of this document is to give simple instructions to anyone who
    6.10 +wants to compile this book into a useful format, like HTML or PDF.  It
    6.11 +should state *exactly* which tools to use, and how to invoke them, in
    6.12 +simplest terms.
    6.13 +
    6.14 +Table of Contents:
    6.15 +
    6.16 +  I. PRIMER
    6.17 + II. COMPILING THE DOCS
    6.18 +III. HACKING ON THE DOCS
    6.19 +
    6.20 +I. PRIMER
    6.21 +
    6.22 +  DocBook has a tortured, confusing history.  Before you do anything,
    6.23 +  take a look at Eric Raymond's excellent "DocBook Demystification HOWTO":
    6.24 +
    6.25 +      http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/
    6.26 +
    6.27 +  It's very short and clears up many things.
    6.28 +
    6.29 +
    6.30 +II. COMPILING THE DOCS
    6.31 +
    6.32 +
    6.33 +1. Install XML DTD and XSL stylesheets for DocBook
    6.34 +
    6.35 +      % sudo apt-get install docbook-xml docbook-xsl
    6.36 +
    6.37 +2. Install libxml2-utils
    6.38 +
    6.39 +      % sudo apt-get install libxml2-utils
    6.40 +
    6.41 +3. Install graph drawing tools
    6.42 +
    6.43 +      % sudo apt-get install graphviz inkscape
    6.44 +
    6.45 +4. Install pdf support
    6.46 +
    6.47 +      % sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop
    6.48 +
    6.49 +  The Makefile will actually invoke tools/fop/fop.sh, you should do
    6.50 +  some trick, let fop's CLASSPATH include saxon.jar and docbook-xsl-saxon.jar .
    6.51 +
    6.52 +5. Make
    6.53 +  Run 'make' for more details, for example:
    6.54 +
    6.55 +  * make all document(pdf, html and html-single for all languages)
    6.56 +      % make all
    6.57 +
    6.58 +  * make english document(pdf, html and html-single for all languages)
    6.59 +      % make LINGUA=en all
    6.60 +
    6.61 +  * make Chinese document(pdf, html and html-single for all languages)
    6.62 +      % make LINGUA=zh all
    6.63 +
    6.64 +  * make Chinese pdf document
    6.65 +      % make LINGUA=zh pdf
    6.66 +
    6.67 +III. HACKING ON THE DOCS
    6.68 +
    6.69 +In addition to everything in section II:
    6.70 +
    6.71 +
    6.72 +1. Get a nice editing environment for SGML/XML.
    6.73 +
    6.74 +  This isn't strictly required, but it's nice when your editor
    6.75 +  colorizes things, understands the DTD, tells you what tags you can
    6.76 +  insert, etc.
    6.77 +
    6.78 +  If you use emacs, we recommend the PSGML major-mode.  Most free
    6.79 +  operating systems package it, or its home page is here:
    6.80 +
    6.81 +      http://www.lysator.liu.se/projects/about_psgml.html
    6.82 +
    6.83 +  If you use vim, you might check out xmledit, at:
    6.84 +
    6.85 +      http://www.vim.org/scripts/script.php?script_id=301
    6.86 +
    6.87 +
    6.88 +2. Get a validating parser.
    6.89 +
    6.90 +  Actually, if you have what you need to compile the documentation,
    6.91 +  then you almost certainly have an XML validator installed already -
    6.92 +  it is called xmllint, and comes as part of libxml2.
    6.93 +
    6.94 +  The makefile is preconfigured with a suitable invocation of it,
    6.95 +  so simply run:
    6.96 +
    6.97 +      $ make validate
    6.98 +
    6.99 +3. Read about DocBook.
   6.100 +
   6.101 +  You'll want to get real intimate with a DocBook reference, such as
   6.102 +  can be found at:  http://www.docbook.org/tdg/en/html/

     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/contrib/hg-interdiff	Sun Aug 16 03:41:39 2009 +0200
     7.3 @@ -0,0 +1,45 @@
     7.4 +#!/usr/bin/env python
     7.5 +#
     7.6 +# Adapter for using interdiff with mercurial's extdiff extension.
     7.7 +#
     7.8 +# Copyright 2006 Bryan O'Sullivan <bos@serpentine.com>
     7.9 +#
    7.10 +# This software may be used and distributed according to the terms of
    7.11 +# the GNU General Public License, incorporated herein by reference.
    7.12 +
    7.13 +import os, sys
    7.14 +
    7.15 +def walk(base):
    7.16 +    # yield all non-directories below the base path.
    7.17 +    for root, dirs, files in os.walk(base):
    7.18 +        for f in files:
    7.19 +            path = os.path.join(root, f)
    7.20 +            yield path[len(base)+1:], path
    7.21 +    else:
    7.22 +        if os.path.isfile(base):
    7.23 +            yield '', base
    7.24 +
    7.25 +# create list of unique file names under both directories.
    7.26 +files = dict(walk(sys.argv[1]))
    7.27 +files.update(walk(sys.argv[2]))
    7.28 +files = files.keys()
    7.29 +files.sort()
    7.30 +
    7.31 +def name(base, f):
    7.32 +    if f:
    7.33 +        path = os.path.join(base, f)
    7.34 +    else:
    7.35 +        path = base
    7.36 +    # interdiff requires two files; use /dev/null if one is missing.
    7.37 +    if os.path.exists(path):
    7.38 +        return path
    7.39 +    return '/dev/null'
    7.40 +
    7.41 +ret = 0
    7.42 +
    7.43 +for f in files:
    7.44 +    if os.system('interdiff "%s" "%s"' % (name(sys.argv[1], f),
    7.45 +                                          name(sys.argv[2], f))):
    7.46 +        ret = 1
    7.47 +
    7.48 +sys.exit(ret)

     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/contrib/hg-package	Sun Aug 16 03:41:39 2009 +0200
     8.3 @@ -0,0 +1,80 @@
     8.4 +#!/bin/sh
     8.5 +
     8.6 +build_dir=`dirname "$0"`/../build
     8.7 +rev_id=`hg parents --template '{date|shortdate}' | sed 's/-//g'`
     8.8 +
     8.9 +for l in en zh; do
    8.10 +  (
    8.11 +  if [ ! -d "${build_dir}/${l}" ] ; then
    8.12 +    continue
    8.13 +  fi
    8.14 +
    8.15 +  cd ${build_dir}/${l};
    8.16 +
    8.17 +  f='html'
    8.18 +  if [ -f "${f}/index.html" ] ; then
    8.19 +     d=hgbook-${l}-${f}
    8.20 +     rm -fr ${d} && cp -r ${f} ${d} && tar czf ../${d}-${rev_id}.tar.gz ${d}
    8.21 +  fi
    8.22 +
    8.23 +  f='html-single'
    8.24 +  if [ -f "${f}/hgbook.html" ] ; then
    8.25 +     d=hgbook-${l}-${f}
    8.26 +     rm -fr ${d} && cp -r ${f} ${d} && tar czf ../${d}-${rev_id}.tar.gz ${d}
    8.27 +  fi
    8.28 +
    8.29 +  if [ -f "pdf/hgbook.pdf" ] ; then
    8.30 +     cp pdf/hgbook.pdf ../hgbook-${l}-${rev_id}.pdf
    8.31 +     gzip -f9 ../hgbook-${l}-${rev_id}.pdf
    8.32 +  fi
    8.33 +
    8.34 +  if [ -f "epub/hgbook.epub" ] ; then
    8.35 +     cp epub/hgbook.epub ../hgbook-${l}-${rev_id}.epub
    8.36 +  fi
    8.37 +  )
    8.38 +done
    8.39 +
    8.40 +upload_pass=$1
    8.41 +upload_user=$2
    8.42 +
    8.43 +# echo "upload_pass: ${upload_pass}"
    8.44 +# echo "upload_user: ${upload_user}"
    8.45 +
    8.46 +if [ "${upload_user}x" == "x" ]; then
    8.47 +  upload_user="dongsheng.song"
    8.48 +fi
    8.49 +
    8.50 +if [ "${upload_pass}x" != "x" ]; then
    8.51 +  (
    8.52 +  cd ${build_dir}
    8.53 +  curl -s -O http://support.googlecode.com/svn/trunk/scripts/googlecode_upload.py
    8.54 +  if [[ "0" != $? ]]; then
    8.55 +    exit 1
    8.56 +  fi
    8.57 +
    8.58 +  for l in en zh; do
    8.59 +    if [ -f "hgbook-${l}-${rev_id}.epub" ] ; then
    8.60 +      python googlecode_upload.py --user="${upload_user}" --password="${upload_pass}" \
    8.61 +          -p "i18n-zh" -l "Type-Docs,book,hgbook,hg,mercurial,ebook" \
    8.62 +          -s "Distributed revision control with Mercurial - ${l} - ePub" \
    8.63 +          hgbook-${l}-${rev_id}.epub
    8.64 +    fi
    8.65 +
    8.66 +    if [ -f "hgbook-${l}-${rev_id}.pdf.gz" ] ; then
    8.67 +      python googlecode_upload.py --user="${upload_user}" --password="${upload_pass}" \
    8.68 +          -p "i18n-zh" -l "Type-Docs,book,hgbook,hg,mercurial" \
    8.69 +          -s "Distributed revision control with Mercurial - ${l} - pdf" \
    8.70 +          hgbook-${l}-${rev_id}.pdf.gz
    8.71 +    fi
    8.72 +
    8.73 +    for f in html html-single; do
    8.74 +      if [ -f "hgbook-${l}-${f}-${rev_id}.tar.gz" ] ; then
    8.75 +        python googlecode_upload.py --user="${upload_user}" --password="${upload_pass}" \
    8.76 +            -p "i18n-zh" -l "Type-Docs,book,hgbook,hg,mercurial" \
    8.77 +            -s "Distributed revision control with Mercurial - ${l} - ${f}" \
    8.78 +            hgbook-${l}-${f}-${rev_id}.tar.gz
    8.79 +      fi
    8.80 +    done
    8.81 +  done
    8.82 +  )
    8.83 +fi

     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/contrib/hg-replay	Sun Aug 16 03:41:39 2009 +0200
     9.3 @@ -0,0 +1,107 @@
     9.4 +#!/usr/bin/env python
     9.5 +#
     9.6 +# Adapter for using interdiff with mercurial's extdiff extension.
     9.7 +#
     9.8 +# Copyright 2006 Bryan O'Sullivan <bos@serpentine.com>
     9.9 +#
    9.10 +# This software may be used and distributed according to the terms of
    9.11 +# the GNU General Public License, incorporated herein by reference.
    9.12 +
    9.13 +import os
    9.14 +import shutil
    9.15 +import sys
    9.16 +import tempfile
    9.17 +
    9.18 +if len(sys.argv) < 4:
    9.19 +    print >> sys.stderr, ('usage: %s srcrepo destrepo cset-to-omit [...]' %
    9.20 +                          os.path.basename(sys.argv[0]))
    9.21 +    sys.exit(1)
    9.22 +
    9.23 +srcrepo, destrepo = sys.argv[1], sys.argv[2]
    9.24 +omit = sys.argv[3:]
    9.25 +    
    9.26 +changemap = {}
    9.27 +revs = []
    9.28 +
    9.29 +parent = None
    9.30 +
    9.31 +sys.stdout.write('gathering history...')
    9.32 +sys.stdout.flush()
    9.33 +
    9.34 +for line in os.popen("hg --cwd %r log -r0:tip --template '{rev}:{node} {parents}\n'" % srcrepo):
    9.35 +    changes = line.split()
    9.36 +    cset = changes[0].split(':')[1]
    9.37 +    rev = len(revs)
    9.38 +    changemap[cset] = rev
    9.39 +    if len(changes) >= 2:
    9.40 +        p1 = int(changes[1].split(':', 1)[0])
    9.41 +    if len(changes) == 3:
    9.42 +        p2 = int(changes[2].split(':', 1)[0])
    9.43 +    else:
    9.44 +        p2 = None
    9.45 +    if len(changes) == 1:
    9.46 +        p1 = parent
    9.47 +    revs.append((cset, p1, p2))
    9.48 +    parent = rev
    9.49 +
    9.50 +sys.stdout.write(' %d revs\n' % len(revs))
    9.51 +
    9.52 +def findrev(r):
    9.53 +    try:
    9.54 +        i = int(r)
    9.55 +        if str(i) == r:
    9.56 +            rev = i
    9.57 +        if rev < 0:
    9.58 +            rev += len(revs)
    9.59 +        if rev < 0 or rev > len(revs):
    9.60 +            print >> sys.stderr, 'bad changeset: %r' % r
    9.61 +            sys.exit(1)
    9.62 +        cset = revs[rev][0]
    9.63 +    except ValueError:
    9.64 +        cset = r
    9.65 +        matches = [changemap[c] for c in changemap if c.startswith(cset)]
    9.66 +        if len(matches) != 1:
    9.67 +            print >> sys.stderr, 'bad changeset: %r' % r
    9.68 +            sys.exit(1)
    9.69 +        rev = matches[0]
    9.70 +    return rev
    9.71 +
    9.72 +def run(cmd):
    9.73 +    print cmd
    9.74 +    ret = os.system(cmd)
    9.75 +    if ret:
    9.76 +        print >> sys.stderr, 'failure:', cmd
    9.77 +        sys.exit(1)
    9.78 +
    9.79 +omit = map(findrev, omit)
    9.80 +omit.sort()
    9.81 +newrevs = revs[:omit[0]]
    9.82 +tip = len(newrevs) - 1
    9.83 +run('hg clone -q -r%s %r %r' % (tip, srcrepo, destrepo))
    9.84 +    
    9.85 +os.environ['HGMERGE'] = 'true'
    9.86 +
    9.87 +patchdir = tempfile.mkdtemp(prefix='replay.')
    9.88 +try:
    9.89 +    run('hg --cwd %r export --git -o %r%s%%R %d:tip' %
    9.90 +        (srcrepo, patchdir, os.sep, omit[0]+1))
    9.91 +    for rev in xrange(omit[0], len(revs)):
    9.92 +        if rev in omit:
    9.93 +            print 'omit', rev
    9.94 +            newrevs.append((None, revs[rev][1], None))
    9.95 +            continue
    9.96 +        _, p1, p2 = revs[rev]
    9.97 +        np1 = newrevs[p1][1]
    9.98 +        if tip != np1:
    9.99 +            run('hg --cwd %r update -q -C %s' % (destrepo, np1))
   9.100 +        np2 = None
   9.101 +        if p2:
   9.102 +            np2 = newrevs[p2][1]
   9.103 +            run('hg --cwd %r merge -q %s' % (destrepo, np2))
   9.104 +            print >> sys.stderr, 'XXX - cannot handle merges properly yet'
   9.105 +        run('hg --cwd %r import -q -f %r%s%d' % (destrepo, patchdir, os.sep, rev))
   9.106 +        tip = len(newrevs) - 1
   9.107 +        newrevs.append((None, tip, np2))
   9.108 +finally:
   9.109 +    print 'cleaning up ...'
   9.110 +    #shutil.rmtree(patchdir)

    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/contrib/latex-to-docbook	Sun Aug 16 03:41:39 2009 +0200
    10.3 @@ -0,0 +1,198 @@
    10.4 +#!/usr/bin/python
    10.5 +#
    10.6 +# This is the most horrible of hacks. Pretend you're not looking.</para>
    10.7 +
    10.8 +import cStringIO as StringIO
    10.9 +import re, sys
   10.10 +
   10.11 +sections = {
   10.12 +    'chapter': 'chapter',
   10.13 +    'section': 'sect1',
   10.14 +    'subsection': 'sect2',
   10.15 +    'subsubsection': 'sect3',
   10.16 +    }
   10.17 +
   10.18 +envs = {
   10.19 +    'codesample2': 'programlisting',
   10.20 +    'codesample4': 'programlisting',
   10.21 +    'enumerate': 'orderedlist',
   10.22 +    'figure': 'informalfigure',
   10.23 +    'itemize': 'itemizedlist',
   10.24 +    'note': 'note',
   10.25 +    'quote': 'blockquote',
   10.26 +    }
   10.27 +
   10.28 +def process(ifp, ofp):
   10.29 +    print >> ofp, '<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->\n'
   10.30 +    stack = []
   10.31 +    para = True
   10.32 +    inlist = 0
   10.33 +    for line in ifp:
   10.34 +        if line.startswith('%%% Local Variables:'):
   10.35 +            break
   10.36 +        line = (line.rstrip()
   10.37 +                .replace('~', ' ')
   10.38 +                .replace('&', '&amp;')
   10.39 +                .replace('---', '&emdash;')
   10.40 +                .replace('\_', '_')
   10.41 +                .replace('\{', '{')
   10.42 +                .replace('\}', '}')
   10.43 +                .replace('\$', '$')
   10.44 +                .replace('\%', '%')
   10.45 +                .replace('\#', '#')
   10.46 +                .replace('<', '&lt;')
   10.47 +                .replace('>', '&gt;')
   10.48 +                .replace('``', '<quote>')
   10.49 +                .replace("''", '</quote>')
   10.50 +                .replace('\\', '\\'))
   10.51 +        line = re.sub(r'\s*\\(?:centering|small)\b\s*', '', line)
   10.52 +        line = re.sub(r'\\(?:hgrc\\|hgrc)\b',
   10.53 +                      r'<filename role="special"> /.hgrc</filename>', line)
   10.54 +        line = re.sub(r'\\item\[(?P<key>[^]]+)\]', r'\item \g<key>:', line)
   10.55 +        line = re.sub(r'\\bug{(?P<id>\d+)}',
   10.56 +                      r'<ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue\g<id>">issue \g<id></ulink>', line)
   10.57 +        line = re.sub(r'\\cite{([^}]+)}', r'<citation>\1</citation>', line)
   10.58 +        line = re.sub(r'\\hggopt{(?P<opt>[^}]+)}',
   10.59 +                      r'<option role="hg-opt-global">\g<opt></option>', line)
   10.60 +        line = re.sub(r'\\hgxopt{(?P<ext>[^}]+)}{(?P<cmd>[^}]+)}{(?P<opt>[^}]+)}',
   10.61 +                      r'<option role="hg-ext-\g<ext>-cmd-\g<cmd>-opt">\g<opt></option>', line)
   10.62 +        line = re.sub(r'\\hgxcmd{(?P<ext>[^}]+)}{(?P<cmd>[^}]+)}',
   10.63 +                      r'<command role="hg-ext-\g<ext>">\g<cmd></command>', line)
   10.64 +        line = re.sub(r'\\hgext{(?P<ext>[^}]+)}',
   10.65 +                      r'<literal role="hg-ext">\g<ext></literal>', line)
   10.66 +        line = re.sub(r'\\hgopt{(?P<cmd>[^}]+)}{(?P<opt>[^}]+)}',
   10.67 +                      r'<option role="hg-opt-\g<cmd>">\g<opt></option>',
   10.68 +                      line)
   10.69 +        line = re.sub(r'\\cmdopt{(?P<cmd>[^}]+)}{(?P<opt>[^}]+)}',
   10.70 +                      r'<option role="cmd-opt-\g<cmd>">\g<opt></option>',
   10.71 +                      line)
   10.72 +        line = re.sub(r'\\hgcmd{(?P<cmd>[^}]+)}',
   10.73 +                      r'<command role="hg-cmd">hg \g<cmd></command>', line)
   10.74 +        line = re.sub(r'\\caption{(?P<text>[^}]+?)}',
   10.75 +                      r'<caption><para>\g<text></para></caption>', line)
   10.76 +        line = re.sub(r'\\grafix{(?P<name>[^}]+)}',
   10.77 +                      r'<mediaobject><imageobject><imagedata fileref="\g<name>"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject>', line)
   10.78 +        line = re.sub(r'\\envar{(?P<name>[^}]+)}',
   10.79 +                      r'<envar>\g<name></envar>', line)
   10.80 +        line = re.sub(r'\\rcsection{(?P<sect>[^}]+)}',
   10.81 +                      r'<literal role="rc-\g<sect>">\g<sect></literal>', line)
   10.82 +        line = re.sub(r'\\rcitem{(?P<sect>[^}]+)}{(?P<name>[^}]+)}',
   10.83 +                      r'<envar role="rc-item-\g<sect>">\g<name></envar>', line)
   10.84 +        line = re.sub(r'\\dirname{(?P<dir>[^}]+?)}',
   10.85 +                      r'<filename class="directory">\g<dir></filename>', line)
   10.86 +        line = re.sub(r'\\filename{(?P<file>[^}]+?)}',
   10.87 +                      r'<filename>\g<file></filename>', line)
   10.88 +        line = re.sub(r'\\tildefile{(?P<file>[^}]+)}',
   10.89 +                      r'<filename role="home">~/\g<file></filename>', line)
   10.90 +        line = re.sub(r'\\sfilename{(?P<file>[^}]+)}',
   10.91 +                      r'<filename role="special">\g<file></filename>', line)
   10.92 +        line = re.sub(r'\\sdirname{(?P<dir>[^}]+)}',
   10.93 +                      r'<filename role="special" class="directory">\g<dir></filename>', line)
   10.94 +        line = re.sub(r'\\interaction{(?P<id>[^}]+)}',
   10.95 +                      r'<!-- &interaction.\g<id>; -->', line)
   10.96 +        line = re.sub(r'\\excode{(?P<id>[^}]+)}',
   10.97 +                      r'<!-- &example.\g<id>; -->', line)
   10.98 +        line = re.sub(r'\\pymod{(?P<mod>[^}]+)}',
   10.99 +                      r'<literal role="py-mod">\g<mod></literal>', line)
  10.100 +        line = re.sub(r'\\pymodclass{(?P<mod>[^}]+)}{(?P<class>[^}]+)}',
  10.101 +                      r'<literal role="py-mod-\g<mod>">\g<class></literal>', line)
  10.102 +        line = re.sub(r'\\url{(?P<url>[^}]+)}',
  10.103 +                      r'<ulink url="\g<url>">\g<url></ulink>', line)
  10.104 +        line = re.sub(r'\\href{(?P<url>[^}]+)}{(?P<text>[^}]+)}',
  10.105 +                      r'<ulink url="\g<url>">\g<text></ulink>', line)
  10.106 +        line = re.sub(r'\\command{(?P<cmd>[^}]+)}',
  10.107 +                      r'<command>\g<cmd></command>', line)
  10.108 +        line = re.sub(r'\\option{(?P<opt>[^}]+)}',
  10.109 +                      r'<option>\g<opt></option>', line)
  10.110 +        line = re.sub(r'\\ref{(?P<id>[^}]+)}', r'<xref linkend="\g<id>"/>', line)
  10.111 +        line = re.sub(r'\\emph{(?P<txt>[^}]+)}',
  10.112 +                      r'<emphasis>\g<txt></emphasis>', line)
  10.113 +        line = re.sub(r'\\texttt{(?P<txt>[^}]+)}',
  10.114 +                      r'<literal>\g<txt></literal>', line)
  10.115 +        line = re.sub(r'\\textbf{(?P<txt>[^}]+)}',
  10.116 +                      r'<emphasis role="bold">\g<txt></emphasis>', line)
  10.117 +        line = re.sub(r'\\hook{(?P<name>[^}]+)}',
  10.118 +                      r'<literal role="hook">\g<name></literal>', line)
  10.119 +        line = re.sub(r'\\tplfilter{(?P<name>[^}]+)}',
  10.120 +                      r'<literal role="template-filter">\g<name></literal>', line)
  10.121 +        line = re.sub(r'\\tplkword{(?P<name>[^}]+)}',
  10.122 +                      r'<literal role="template-keyword">\g<name></literal>', line)
  10.123 +        line = re.sub(r'\\tplkwfilt{(?P<tpl>[^}]+)}{(?P<name>[^}]+)}',
  10.124 +                      r'<literal role="template-kw-filt-\g<tpl>">\g<name></literal>', line)
  10.125 +        line = re.sub(r'\\[vV]erb(.)(?P<txt>[^\1]+?)\1',
  10.126 +                      r'<literal>\g<txt></literal>', line)
  10.127 +        line = re.sub(r'\\package{(?P<name>[^}]+)}',
  10.128 +                      r'<literal role="package">\g<name></literal>', line)
  10.129 +        line = re.sub(r'\\hgcmdargs{(?P<cmd>[^}]+)}{(?P<args>[^}]+)}',
  10.130 +                      r'<command role="hg-cmd">hg \g<cmd> \g<args></command>',
  10.131 +                      line)
  10.132 +        line = re.sub(r'\\cmdargs{(?P<cmd>[^}]+)}{(?P<args>[^}]+)}',
  10.133 +                      r'<command>\g<cmd> \g<args></command>',
  10.134 +                      line)
  10.135 +        m = re.match(r'\\(chapter|section|subsection|subsubsection){(.*)}', line)
  10.136 +        if m:
  10.137 +            kind, content = m.groups()
  10.138 +            sec = sections[kind]
  10.139 +            while stack and stack[-1] >= sec:
  10.140 +                close = stack.pop()
  10.141 +                print >> ofp, '</%s>' % close
  10.142 +            stack.append(sec)
  10.143 +            print >> ofp, '<%s>\n<title>%s</title>' % (sec, content)
  10.144 +        else:
  10.145 +            m = re.match(r'\s*\\(begin|end){(?P<sect>[^}]+)}', line)
  10.146 +            if m:
  10.147 +                if not para:
  10.148 +                    print >> ofp, '</para>'
  10.149 +                    if inlist:
  10.150 +                        ofp.write('</listitem>')
  10.151 +                    para = True
  10.152 +                state, env = m.groups()
  10.153 +                env = envs[env]
  10.154 +                if state == 'begin':
  10.155 +                    ofp.write('<')
  10.156 +                    if env in ('itemizedlist', 'orderedlist'):
  10.157 +                        inlist = 1
  10.158 +                else:
  10.159 +                    ofp.write('</')
  10.160 +                    if env in ('itemizedlist', 'orderedlist'):
  10.161 +                        inlist = 0
  10.162 +                print >> ofp, env + '>'
  10.163 +            else:
  10.164 +                if line.startswith('\\item '):
  10.165 +                    if inlist > 1:
  10.166 +                        print >> ofp, '</para>'
  10.167 +                        print >> ofp, '</listitem>'
  10.168 +                    else:
  10.169 +                        inlist = 2
  10.170 +                    para = True
  10.171 +                    line = line[6:]
  10.172 +                if line and para:
  10.173 +                    if inlist:
  10.174 +                        ofp.write('<listitem>')
  10.175 +                    ofp.write('<para>')
  10.176 +                    para = False
  10.177 +                if not line and not para:
  10.178 +                    print >> ofp, '</para>'
  10.179 +                    if inlist:
  10.180 +                        ofp.write('</listitem>')
  10.181 +                    para = True
  10.182 +                print >> ofp, line
  10.183 +    while stack:
  10.184 +        print >> ofp, '</%s>' % stack.pop()
  10.185 +    ofp.write('\n'.join(['\n<!--',
  10.186 +                         'local variables: ',
  10.187 +                         'sgml-parent-document: ("00book.xml" "book" "chapter")',
  10.188 +                         'end:',
  10.189 +                         '-->']))
  10.190 +
  10.191 +
  10.192 +if __name__ == '__main__':
  10.193 +    for name in sys.argv[1:]:
  10.194 +        if not name.endswith('.tex'):
  10.195 +            continue
  10.196 +        newname = name[:-3] + 'xml'
  10.197 +        ofp = StringIO.StringIO()
  10.198 +        process(open(name), ofp)
  10.199 +        s = ofp.getvalue()
  10.200 +        s = re.sub('\n+</para>', '</para>', s, re.M)
  10.201 +        open(newname, 'w').write(s)

    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/contrib/sillybench.py	Sun Aug 16 03:41:39 2009 +0200
    11.3 @@ -0,0 +1,177 @@
    11.4 +#!/usr/bin/python
    11.5 +#
    11.6 +# Silly benchmarking program, to give a vague idea of how fast a few
    11.7 +# tools are on a handful of common operations.
    11.8 +#
    11.9 +# Use a fairly big and real source tarball to test with: Firefox
   11.10 +# 2.0.0.3 (37622 files, 5374 directories, 343MB unpacked onto
   11.11 +# 4KB-blocksize ext3).
   11.12 +
   11.13 +import csv
   11.14 +import os
   11.15 +import shutil
   11.16 +import sys
   11.17 +import tempfile
   11.18 +import time
   11.19 +import urllib2
   11.20 +
   11.21 +url = 'ftp://ftp.mozilla.org/pub/mozilla.org/firefox/releases/2.0.0.3/source/firefox-2.0.0.3-source.tar.bz2'
   11.22 +
   11.23 +class CommandFailure(Exception):
   11.24 +    pass
   11.25 +
   11.26 +class rcs(object):
   11.27 +    def __init__(self):
   11.28 +        self.logfp = open(self.__class__.__name__ + '.csv', 'w')
   11.29 +        self.csv = csv.writer(self.logfp)
   11.30 +
   11.31 +    def download(self):
   11.32 +        name = url[url.rfind('/')+1:]
   11.33 +        path = os.path.join(os.environ['HOME'], name)
   11.34 +        if not os.path.isfile(path):
   11.35 +            ofp = open(path + '.part', 'wb')
   11.36 +            try:
   11.37 +                ifp = urllib2.urlopen(url)
   11.38 +                nbytes = ifp.info()['content-length']
   11.39 +                sys.stdout.write('%s: %s bytes ' % (name, nbytes))
   11.40 +                sys.stdout.flush()
   11.41 +                while True:
   11.42 +                    data = ifp.read(131072)
   11.43 +                    if not data: break
   11.44 +                    sys.stdout.write('.')
   11.45 +                    sys.stdout.flush()
   11.46 +                    ofp.write(data)
   11.47 +                del ofp
   11.48 +                os.rename(path + '.part', path)
   11.49 +            except:
   11.50 +                if os.path.exists(path + '.part'):
   11.51 +                    os.unlink(path + '.part')
   11.52 +                if os.path.exists(path):
   11.53 +                    os.unlink(path)
   11.54 +                raise
   11.55 +        return path
   11.56 +
   11.57 +    def run(self, args, mustsucceed=True):
   11.58 +        ret = os.spawnvp(os.P_WAIT, args[0], args)
   11.59 +        if ret < 0:
   11.60 +            msg = 'killed by signal %d' % (-ret)
   11.61 +        if ret > 0:
   11.62 +            msg = 'exited with status %d' % (ret)
   11.63 +        if ret:
   11.64 +            if mustsucceed:
   11.65 +                raise CommandFailure('%s: %s' % (msg, ' '.join(args)))
   11.66 +            print >> sys.stderr, 'WARNING: %s: %s' % (msg, ' '.join(args))
   11.67 +
   11.68 +    def time(self, *args, **kwargs):
   11.69 +        start = time.time()
   11.70 +        self.run(*args, **kwargs)
   11.71 +        end = time.time()
   11.72 +        return end - start
   11.73 +        
   11.74 +    def logtime(self, name, elapsed, rest=[]):
   11.75 +        self.log('time:' + name, '%.3f' % elapsed, rest)
   11.76 +
   11.77 +    def log(self, name, value, rest=[]):
   11.78 +        item = (name, value, repr(rest))
   11.79 +        print ' '.join(item)
   11.80 +        self.csv.writerow(item)
   11.81 +        self.logfp.flush()
   11.82 +
   11.83 +    def unpack(self):
   11.84 +        tarball = self.download()
   11.85 +        t = self.time(['tar', '-C', self.wdir, '-jxf', tarball])
   11.86 +        self.logtime('internal:untar', t)
   11.87 +        for name in os.listdir(os.path.join(self.wdir, 'mozilla')):
   11.88 +            os.rename(os.path.join(self.wdir, 'mozilla', name),
   11.89 +                      os.path.join(self.wdir, name))
   11.90 +
   11.91 +    def cleanup(self):
   11.92 +        pass
   11.93 +
   11.94 +    def add(self, paths):
   11.95 +        pass
   11.96 +
   11.97 +    def commit(self, msg, paths):
   11.98 +        pass
   11.99 +
  11.100 +    def status(self, path):
  11.101 +        pass
  11.102 +
  11.103 +    def remove(self, path):
  11.104 +        pass
  11.105 +
  11.106 +
  11.107 +class subversion(rcs):
  11.108 +    def __init__(self, root):
  11.109 +        rcs.__init__(self)
  11.110 +        self.repo = os.path.join(root, 'repo')
  11.111 +        self.wdir = os.path.join(root, 'wc')
  11.112 +        create = self.time(['svnadmin', 'create', '--fs-type=fsfs', self.repo])
  11.113 +        self.logtime('svn:create', create)
  11.114 +        co = self.time(['svn', 'co', 'file://' + self.repo, self.wdir])
  11.115 +        self.logtime('svn:co', co)
  11.116 +        self.logtime('init', create + co)
  11.117 +        os.chdir(self.wdir)
  11.118 +
  11.119 +    def dropmeta(self, names):
  11.120 +        return [n for n in names if os.path.basename(n) != '.svn']
  11.121 +
  11.122 +    def add(self, paths):
  11.123 +        t = self.time(['svn', 'add', '-q'] + paths)
  11.124 +        self.logtime('add %r' % paths, t)
  11.125 +
  11.126 +    def commit(self, msg, paths=[]):
  11.127 +        if paths:
  11.128 +            t = self.time(['svn', 'ci', '-q', '-m', msg] + paths)
  11.129 +        else:
  11.130 +            t = self.time(['svn', 'ci', '-q', '-m', msg])
  11.131 +        self.logtime('commit %r' % paths, t)
  11.132 +
  11.133 +
  11.134 +class mercurial(rcs):
  11.135 +    def __init__(self, root):
  11.136 +        rcs.__init__(self)
  11.137 +        self.repo = os.path.join(root, 'repo')
  11.138 +        self.wdir = self.repo
  11.139 +        init = self.time(['hg', 'init', self.repo])
  11.140 +        self.logtime('init', init)
  11.141 +        os.chdir(self.wdir)
  11.142 +
  11.143 +    def dropmeta(self, names):
  11.144 +        return [n for n in names if os.path.basename(n) != '.hg']
  11.145 +
  11.146 +    def add(self, paths):
  11.147 +        t = self.time(['hg', 'add', '-q'] + paths)
  11.148 +        self.logtime('add %r' % paths, t)
  11.149 +
  11.150 +    def commit(self, msg, paths=[]):
  11.151 +        if paths:
  11.152 +            t = self.time(['hg', 'ci', '-q', '-m', msg] + paths)
  11.153 +        else:
  11.154 +            t = self.time(['hg', 'ci', '-q', '-m', msg])
  11.155 +        self.logtime('commit %r' % paths, t)
  11.156 +
  11.157 +def benchmark(cls):
  11.158 +    oldcwd = os.getcwd()
  11.159 +    root = tempfile.mkdtemp(prefix='sillybench.')
  11.160 +    try:
  11.161 +        print 'root', root
  11.162 +        inst = cls(root)
  11.163 +        inst.unpack()
  11.164 +        names = inst.dropmeta(os.listdir('.'))
  11.165 +        dirs = [n for n in names if os.path.isdir(n)]
  11.166 +        nondirs = [n for n in names if not os.path.isdir(n)]
  11.167 +        dirs.sort(key=hash)
  11.168 +        names.sort(key=hash)
  11.169 +        for d in dirs[:len(dirs)/2]:
  11.170 +            inst.add([d])
  11.171 +            inst.commit('Add %r' % d, [d])
  11.172 +        inst.add(dirs[len(dirs)/2:] + names)
  11.173 +        inst.commit('Add remaining dirs and files')
  11.174 +    finally:
  11.175 +        print >> sys.stderr, '[cleaning up...]'
  11.176 +        shutil.rmtree(root)
  11.177 +        os.chdir(oldcwd)
  11.178 +
  11.179 +benchmark(mercurial)
  11.180 +#benchmark(subversion)

    12.1 --- a/en/00book.tex	Thu Mar 26 08:57:10 2009 +0100
    12.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    12.3 @@ -1,76 +0,0 @@
    12.4 -% The use of oneside here is a temporary hack; \marginpar entries
    12.5 -% don't show up on odd pages of PDF output without it.  Sigh.
    12.6 -\documentclass[oneside]{book}
    12.7 -\usepackage{enumerate}
    12.8 -\usepackage{fullpage}
    12.9 -\usepackage{makeidx}
   12.10 -\usepackage{ifpdf}
   12.11 -\usepackage{graphicx}
   12.12 -\usepackage{pslatex}
   12.13 -\usepackage{fancyvrb}
   12.14 -% leave hyperref until last
   12.15 -\usepackage[colorlinks=true,bookmarks=true,pdftitle={Distributed
   12.16 -  revision control with Mercurial},pdfsubject={Revision
   12.17 -  control},pdfkeywords={Mercurial, Revision control, Distributed
   12.18 -  revision control},pdfauthor={Bryan O'Sullivan}]{hyperref}
   12.19 -
   12.20 -\include{99defs}
   12.21 -
   12.22 -\title{Distributed revision control with Mercurial} \author{Bryan
   12.23 -  O'Sullivan}
   12.24 -\date{Copyright \copyright\ 2006, 2007 Bryan O'Sullivan.\\
   12.25 -  This material may be distributed only subject to the terms and
   12.26 -  conditions set forth in version 1.0 of the Open Publication License.
   12.27 -  Please refer to Appendix~\ref{cha:opl} for the license text.\\
   12.28 -  This book was prepared from
   12.29 -  \href{http://hg.serpentine.com/mercurial/book/}{rev~\input{build_id}}
   12.30 -  using \href{http://www.selenic.com/hg/}{rev~\input{hg_id}} of Mercurial.}
   12.31 -
   12.32 -\makeindex
   12.33 -
   12.34 -\begin{document}
   12.35 -
   12.36 -\maketitle
   12.37 -
   12.38 -\addcontentsline{toc}{chapter}{Contents}
   12.39 -\pagenumbering{roman}
   12.40 -\tableofcontents
   12.41 -\listoffigures
   12.42 -%\listoftables
   12.43 -
   12.44 -\pagenumbering{arabic}
   12.45 -
   12.46 -\include{preface}
   12.47 -\include{intro}
   12.48 -\include{tour-basic}
   12.49 -\include{tour-merge}
   12.50 -\include{concepts}
   12.51 -\include{daily}
   12.52 -\include{collab}
   12.53 -\include{filenames}
   12.54 -\include{branch}
   12.55 -\include{undo}
   12.56 -\include{hook}
   12.57 -\include{template}
   12.58 -\include{mq}
   12.59 -\include{mq-collab}
   12.60 -\include{hgext}
   12.61 -
   12.62 -\appendix
   12.63 -\include{cmdref}
   12.64 -\include{mq-ref}
   12.65 -\include{srcinstall}
   12.66 -\include{license}
   12.67 -\addcontentsline{toc}{chapter}{Bibliography}
   12.68 -\bibliographystyle{alpha}
   12.69 -\bibliography{99book}
   12.70 -
   12.71 -\addcontentsline{toc}{chapter}{Index}
   12.72 -\printindex
   12.73 -
   12.74 -\end{document}
   12.75 -
   12.76 -%%% Local Variables: 
   12.77 -%%% mode: latex
   12.78 -%%% TeX-master: t
   12.79 -%%% End: 

    13.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    13.2 +++ b/en/00book.xml	Sun Aug 16 03:41:39 2009 +0200
    13.3 @@ -0,0 +1,110 @@
    13.4 +<?xml version="1.0" encoding="UTF-8"?>
    13.5 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    13.6 +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
    13.7 + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
    13.8 +[
    13.9 +<!-- Below are references to files in this directory. -->
   13.10 +
   13.11 +<!-- Chapters. -->
   13.12 +
   13.13 +<!ENTITY ch00     SYSTEM "ch00-preface.xml">
   13.14 +<!ENTITY ch01     SYSTEM "ch01-intro.xml">
   13.15 +<!ENTITY ch02     SYSTEM "ch02-tour-basic.xml">
   13.16 +<!ENTITY ch03     SYSTEM "ch03-tour-merge.xml">
   13.17 +<!ENTITY ch04     SYSTEM "ch04-concepts.xml">
   13.18 +<!ENTITY ch05     SYSTEM "ch05-daily.xml">
   13.19 +<!ENTITY ch06     SYSTEM "ch06-collab.xml">
   13.20 +<!ENTITY ch07     SYSTEM "ch07-filenames.xml">
   13.21 +<!ENTITY ch08     SYSTEM "ch08-branch.xml">
   13.22 +<!ENTITY ch09     SYSTEM "ch09-undo.xml">
   13.23 +<!ENTITY ch10     SYSTEM "ch10-hook.xml">
   13.24 +<!ENTITY ch11     SYSTEM "ch11-template.xml">
   13.25 +<!ENTITY ch12     SYSTEM "ch12-mq.xml">
   13.26 +<!ENTITY ch13     SYSTEM "ch13-mq-collab.xml">
   13.27 +<!ENTITY ch14     SYSTEM "ch14-hgext.xml">
   13.28 +<!ENTITY appA     SYSTEM "appA-svn.xml">
   13.29 +<!ENTITY appB     SYSTEM "appB-mq-ref.xml">
   13.30 +<!ENTITY appC     SYSTEM "appC-srcinstall.xml">
   13.31 +<!ENTITY appD     SYSTEM "appD-license.xml">
   13.32 +
   13.33 +<!-- Include our standard shortcuts. -->
   13.34 +
   13.35 +<!ENTITY % SHORTCUTS SYSTEM "book-shortcuts.xml">
   13.36 +%SHORTCUTS;
   13.37 +
   13.38 +<!-- Include automatically and manually generated code snippets. -->
   13.39 +
   13.40 +<!ENTITY % AUTOSNIPPETS SYSTEM "examples/auto-snippets.xml">
   13.41 +%AUTOSNIPPETS;
   13.42 +]>
   13.43 +
   13.44 +<book id="hg">
   13.45 +  <title>Mercurial: The Definitive Guide</title>
   13.46 +  
   13.47 +  <!-- hg parents &#x2d;&#x2d;template '{node|short} ({date|shortdate})' 
   13.48 +  <subtitle>Compiled from 8a1d3f1aff17 (2009-03-10)</subtitle>
   13.49 +  -->
   13.50 +  <subtitle>Compiled from $rev_id$</subtitle>
   13.51 +  <bookinfo>
   13.52 +    <edition>1</edition>
   13.53 +    <isbn>9780596800673</isbn>
   13.54 +    <authorgroup>
   13.55 +      <author>
   13.56 +        <firstname>Bryan</firstname>
   13.57 +        <surname>O'Sullivan</surname>
   13.58 +      </author>
   13.59 +    </authorgroup>
   13.60 +
   13.61 +    <editor>
   13.62 +      <firstname>Mike</firstname>
   13.63 +      <surname>Loukides</surname>
   13.64 +    </editor>
   13.65 +
   13.66 +    <copyright>
   13.67 +      <year>2006</year>
   13.68 +      <year>2007</year>
   13.69 +      <year>2008</year>
   13.70 +      <year>2009</year>
   13.71 +      <holder>Bryan O'Sullivan</holder>
   13.72 +    </copyright>
   13.73 +  </bookinfo>
   13.74 +
   13.75 +  <!-- BEGIN ch00 -->
   13.76 +  &ch00;
   13.77 +  <!-- BEGIN ch01 -->
   13.78 +  &ch01;
   13.79 +  <!-- BEGIN ch02 -->
   13.80 +  &ch02;
   13.81 +  <!-- BEGIN ch03 -->
   13.82 +  &ch03;
   13.83 +  <!-- BEGIN ch04 -->
   13.84 +  &ch04;
   13.85 +  <!-- BEGIN ch05 -->
   13.86 +  &ch05;
   13.87 +  <!-- BEGIN ch06 -->
   13.88 +  &ch06;
   13.89 +  <!-- BEGIN ch07 -->
   13.90 +  &ch07;
   13.91 +  <!-- BEGIN ch08 -->
   13.92 +  &ch08;
   13.93 +  <!-- BEGIN ch09 -->
   13.94 +  &ch09;
   13.95 +  <!-- BEGIN ch10 -->
   13.96 +  &ch10;
   13.97 +  <!-- BEGIN ch11 -->
   13.98 +  &ch11;
   13.99 +  <!-- BEGIN ch12 -->
  13.100 +  &ch12;
  13.101 +  <!-- BEGIN ch13 -->
  13.102 +  &ch13;
  13.103 +  <!-- BEGIN ch14 -->
  13.104 +  &ch14;
  13.105 +  <!-- BEGIN appA -->
  13.106 +  &appA;
  13.107 +  <!-- BEGIN appB -->
  13.108 +  &appB;
  13.109 +  <!-- BEGIN appC -->
  13.110 +  &appC;
  13.111 +  <!-- BEGIN appD -->
  13.112 +  &appD;
  13.113 +</book>

    14.1 --- a/en/99book.bib	Thu Mar 26 08:57:10 2009 +0100
    14.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    14.3 @@ -1,76 +0,0 @@
    14.4 -@Unpublished{gruenbacher:2005,
    14.5 -  author = 	 {Andreas Gruenbacher},
    14.6 -  title = 	 {How To Survive With Many Patches (Introduction to \texttt{quilt})},
    14.7 -  year = 	 {2005},
    14.8 -  month = 	 {June},
    14.9 -  note =         {\url{http://www.suse.de/~agruen/quilt.pdf}},
   14.10 -}
   14.11 -
   14.12 -@InProceedings{web:europython,
   14.13 -  author = 	 {Bryan O'Sullivan},
   14.14 -  title = 	 {Achieving High Performance in Mercurial},
   14.15 -  booktitle = 	 {EuroPython Conference},
   14.16 -  year = 	 {2006},
   14.17 -  month = 	 {July},
   14.18 -  note = 	 {\url{XXX}},
   14.19 -}
   14.20 -
   14.21 -@Misc{web:diffstat,
   14.22 -  author = 	 {Thomas Dickey},
   14.23 -  title = 	 {\texttt{diffstat}--make a histogram of \texttt{diff} output},
   14.24 -  note = 	 {\url{http://dickey.his.com/diffstat/diffstat.html}},
   14.25 -}
   14.26 -
   14.27 -@Misc{web:quilt,
   14.28 -  author = 	 {Andreas Gruenbacher, Martin Quinson, Jean Delvare},
   14.29 -  title = 	 {Patchwork Quilt},
   14.30 -  note = 	 {\url{http://savannah.nongnu.org/projects/quilt}},
   14.31 -}
   14.32 -
   14.33 -@Misc{web:patchutils,
   14.34 -  author = 	 {Tim Waugh},
   14.35 -  title = 	 {\texttt{patchutils}--programs that operate on patch files},
   14.36 -  note = 	 {\url{http://cyberelk.net/tim/patchutils/}},
   14.37 -}
   14.38 -
   14.39 -@Misc{web:mpatch,
   14.40 -  author = 	 {Chris Mason},
   14.41 -  title = 	 {\texttt{mpatch}--help solve patch rejects},
   14.42 -  note = 	 {\url{http://oss.oracle.com/~mason/mpatch/}},
   14.43 -}
   14.44 -
   14.45 -@Misc{web:wiggle,
   14.46 -  author = 	 {Neil Brown},
   14.47 -  title = 	 {\texttt{wiggle}--apply conflicting patches},
   14.48 -  note = 	 {\url{http://cgi.cse.unsw.edu.au/~neilb/source/wiggle/}},
   14.49 -}
   14.50 -
   14.51 -@Misc{web:mysql-python,
   14.52 -  author =	 {Andy Dustman},
   14.53 -  title =	 {MySQL for Python},
   14.54 -  note =	 {\url{http://sourceforge.net/projects/mysql-python}},
   14.55 -}
   14.56 -
   14.57 -@Misc{web:changelog,
   14.58 -  author =	 {Richard Stallman, GNU Project volunteers},
   14.59 -  title =	 {GNU Coding Standards---Change Logs},
   14.60 -  note =	 {\url{http://www.gnu.org/prep/standards/html_node/Change-Logs.html}},
   14.61 -}
   14.62 -
   14.63 -@Misc{web:macpython,
   14.64 -  author =	 {Bob Ippolito, Ronald Oussoren},
   14.65 -  title =	 {Universal MacPython},
   14.66 -  note =	 {\url{http://bob.pythonmac.org/archives/2006/04/10/python-and-universal-binaries-on-mac-os-x/}},
   14.67 -}
   14.68 -
   14.69 -@Misc{web:putty,
   14.70 -  author =	 {Simon Tatham},
   14.71 -  title =	 {PuTTY---open source ssh client for Windows},
   14.72 -  note =	 {\url{http://www.chiark.greenend.org.uk/~sgtatham/putty/}},
   14.73 -}
   14.74 -
   14.75 -@Misc{web:configparser,
   14.76 -  author =       {Python.org},
   14.77 -  title =	 {\texttt{ConfigParser}---Configuration file parser},
   14.78 -  note =	 {\url{http://docs.python.org/lib/module-ConfigParser.html}},
   14.79 -}

    15.1 --- a/en/99defs.tex	Thu Mar 26 08:57:10 2009 +0100
    15.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    15.3 @@ -1,146 +0,0 @@
    15.4 -% Bug ID.
    15.5 -\newcommand{\bug}[1]{\index{Mercurial bug
    15.6 -    database!\href{http://www.selenic.com/mercurial/bts/issue#1}{bug
    15.7 -      ~#1}}\href{http://www.selenic.com/mercurial/bts/issue#1}{Mercurial
    15.8 -    bug no.~#1}}
    15.9 -
   15.10 -% File name in the user's home directory.
   15.11 -\newcommand{\tildefile}[1]{\texttt{\~{}/#1}}
   15.12 -
   15.13 -% File name.
   15.14 -\newcommand{\filename}[1]{\texttt{#1}}
   15.15 -
   15.16 -% Directory name.
   15.17 -\newcommand{\dirname}[1]{\texttt{#1}}
   15.18 -
   15.19 -% File name, with index entry.
   15.20 -% The ``s'' prefix comes from ``special''.
   15.21 -\newcommand{\sfilename}[1]{\index{\texttt{#1} file}\texttt{#1}}
   15.22 -
   15.23 -% Directory name, with index entry.
   15.24 -\newcommand{\sdirname}[1]{\index{\texttt{#1} directory}\texttt{#1}}
   15.25 -
   15.26 -% Mercurial extension.
   15.27 -\newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}}
   15.28 -
   15.29 -% Command provided by a Mercurial extension.
   15.30 -\newcommand{\hgxcmd}[2]{\index{\texttt{#2} command (\texttt{#1}
   15.31 -      extension)}\index{\texttt{#1} extension!\texttt{#2} command}``\texttt{hg #2}''}
   15.32 -
   15.33 -% Mercurial command.
   15.34 -\newcommand{\hgcmd}[1]{\index{\texttt{#1} command}``\texttt{hg #1}''}
   15.35 -
   15.36 -% Mercurial command, with arguments.
   15.37 -\newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
   15.38 -
   15.39 -\newcommand{\tplkword}[1]{\index{\texttt{#1} template keyword}\index{template keywords!\texttt{#1}}\texttt{#1}}
   15.40 -
   15.41 -\newcommand{\tplkwfilt}[2]{\index{\texttt{#1} template keyword!\texttt{#2}
   15.42 -    filter}\index{template filters!\texttt{#2}}\index{\texttt{#2}
   15.43 -    template filter}\texttt{#2}}
   15.44 -
   15.45 -\newcommand{\tplfilter}[1]{\index{template
   15.46 -    filters!\texttt{#1}}\index{\texttt{#1} template
   15.47 -    filter}\texttt{#1}}
   15.48 -
   15.49 -% Shell/system command.
   15.50 -\newcommand{\command}[1]{\index{\texttt{#1} system command}\texttt{#1}}
   15.51 -
   15.52 -% Shell/system command, with arguments.
   15.53 -\newcommand{\cmdargs}[2]{\index{\texttt{#1} system command}``\texttt{#1 #2}''}
   15.54 -
   15.55 -% Mercurial command option.
   15.56 -\newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
   15.57 -
   15.58 -% Mercurial command option, provided by an extension command.
   15.59 -\newcommand{\hgxopt}[3]{\index{\texttt{#2} command (\texttt{#1} extension)!\texttt{#3} option}\index{\texttt{#1} extension!\texttt{#2} command!\texttt{#3} option}\texttt{#3}}
   15.60 -
   15.61 -% Mercurial global option.
   15.62 -\newcommand{\hggopt}[1]{\index{global options!\texttt{#1} option}\texttt{#1}}
   15.63 -
   15.64 -% Shell/system command option.
   15.65 -\newcommand{\cmdopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
   15.66 -
   15.67 -% Command option.
   15.68 -\newcommand{\option}[1]{\texttt{#1}}
   15.69 -
   15.70 -% Software package.
   15.71 -\newcommand{\package}[1]{\index{\texttt{#1} package}\texttt{#1}}
   15.72 -
   15.73 -% Section name from a hgrc file.
   15.74 -\newcommand{\rcsection}[1]{\index{\texttt{hgrc} file!\texttt{#1} section}\texttt{[#1]}}
   15.75 -
   15.76 -% Named item in a hgrc file section.
   15.77 -\newcommand{\rcitem}[2]{\index{\texttt{hgrc} file!\texttt{#1}
   15.78 -    section!\texttt{#2} entry}\texttt{#2}}
   15.79 -
   15.80 -% hgrc file.
   15.81 -\newcommand{\hgrc}{\index{configuration file!\texttt{hgrc}
   15.82 -    (Linux/Unix)}\index{\texttt{hgrc} configuration file}\texttt{hgrc}}
   15.83 -
   15.84 -% Mercurial.ini file.
   15.85 -\newcommand{\hgini}{\index{configuration file!\texttt{Mercurial.ini}
   15.86 -    (Windows)}\index{\texttt{Mercurial.ini} configuration file}\texttt{Mercurial.ini}}
   15.87 -
   15.88 -% Hook name.
   15.89 -\newcommand{\hook}[1]{\index{\texttt{#1} hook}\index{hooks!\texttt{#1}}\texttt{#1}}
   15.90 -
   15.91 -% Environment variable.
   15.92 -\newcommand{\envar}[1]{\index{\texttt{#1} environment
   15.93 -    variable}\index{environment variables!\texttt{#1}}\texttt{#1}}
   15.94 -
   15.95 -% Python module.
   15.96 -\newcommand{\pymod}[1]{\index{\texttt{#1} module}\texttt{#1}}
   15.97 -
   15.98 -% Python class in a module.
   15.99 -\newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2}
  15.100 -    class}\texttt{#1.#2}}
  15.101 -
  15.102 -% Python function in a module.
  15.103 -\newcommand{\pymodfunc}[2]{\index{\texttt{#1} module!\texttt{#2}
  15.104 -    function}\texttt{#1.#2}}
  15.105 -
  15.106 -% Note: blah blah.
  15.107 -\newsavebox{\notebox}
  15.108 -\newenvironment{note}%
  15.109 -  {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Note:}\space}%
  15.110 -  {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
  15.111 -\newenvironment{caution}%
  15.112 -  {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Caution:}\space}%
  15.113 -  {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
  15.114 -
  15.115 -% Code sample, eating 4 characters of leading space.
  15.116 -\DefineVerbatimEnvironment{codesample4}{Verbatim}{frame=single,gobble=4,numbers=left,commandchars=\\\{\}}
  15.117 -
  15.118 -% Code sample, eating 2 characters of leading space.
  15.119 -\DefineVerbatimEnvironment{codesample2}{Verbatim}{frame=single,gobble=2,numbers=left,commandchars=\\\{\}}
  15.120 -
  15.121 -% Interaction from the examples directory.
  15.122 -\newcommand{\interaction}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{examples/#1.lxo}}
  15.123 -% Example code from the examples directory.
  15.124 -\newcommand{\excode}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{../examples/#1}}
  15.125 -
  15.126 -% Graphics inclusion.
  15.127 -\ifpdf
  15.128 -  \newcommand{\grafix}[1]{\includegraphics{#1}}
  15.129 -\else
  15.130 -  \newcommand{\grafix}[1]{\includegraphics{#1.png}}
  15.131 -\fi
  15.132 -
  15.133 -% Reference entry for a command.
  15.134 -\newcommand{\cmdref}[2]{\section{\hgcmd{#1}---#2}\label{cmdref:#1}\index{\texttt{#1} command}}
  15.135 -
  15.136 -% Reference entry for a command option with long and short forms.
  15.137 -\newcommand{\optref}[3]{\subsubsection{\hgopt{#1}{--#3}, also \hgopt{#1}{-#2}}}
  15.138 -
  15.139 -% Reference entry for a command option with only long form.
  15.140 -\newcommand{\loptref}[2]{\subsubsection{\hgopt{#1}{--#2} option}}
  15.141 -
  15.142 -% command to generate a footnote to be used as a translator's note
  15.143 -\newcommand{\ndt}[1]{\footnote{\textbf{N. del T.} #1}}
  15.144 -
  15.145 -
  15.146 -%%% Local Variables: 
  15.147 -%%% mode: latex
  15.148 -%%% TeX-master: "00book"
  15.149 -%%% End: 

    16.1 --- a/en/Makefile	Thu Mar 26 08:57:10 2009 +0100
    16.2 +++ b/en/Makefile	Sun Aug 16 03:41:39 2009 +0200
    16.3 @@ -1,62 +1,26 @@
    16.4  # This makefile requires GNU make.
    16.5  
    16.6 -sources := \
    16.7 -	00book.tex \
    16.8 -	99book.bib \
    16.9 -	99defs.tex \
   16.10 -	build_id.tex \
   16.11 -	branch.tex \
   16.12 -	cmdref.tex \
   16.13 -	collab.tex \
   16.14 -	concepts.tex \
   16.15 -	daily.tex \
   16.16 -	filenames.tex \
   16.17 -	hg_id.tex \
   16.18 -	hgext.tex \
   16.19 -	hook.tex \
   16.20 -	intro.tex \
   16.21 -	mq.tex \
   16.22 -	mq-collab.tex \
   16.23 -	mq-ref.tex \
   16.24 -	preface.tex \
   16.25 -	srcinstall.tex \
   16.26 -	template.tex \
   16.27 -	tour-basic.tex \
   16.28 -	tour-merge.tex \
   16.29 -	undo.tex
   16.30 -
   16.31 -image-sources := \
   16.32 -	feature-branches.dot \
   16.33 -	filelog.svg \
   16.34 -	kdiff3.png \
   16.35 -	metadata.svg \
   16.36 -	mq-stack.svg \
   16.37 -	note.png \
   16.38 -	revlog.svg \
   16.39 -	snapshot.svg \
   16.40 -	tour-history.svg \
   16.41 -	tour-merge-conflict.svg \
   16.42 -	tour-merge-merge.svg \
   16.43 -	tour-merge-pull.svg \
   16.44 -	tour-merge-sep-repos.svg \
   16.45 -	undo-manual.dot \
   16.46 -	undo-manual-merge.dot \
   16.47 -	undo-non-tip.dot \
   16.48 -	undo-simple.dot \
   16.49 -	wdir.svg \
   16.50 -	wdir-after-commit.svg \
   16.51 -	wdir-branch.svg \
   16.52 -	wdir-merge.svg \
   16.53 -	wdir-pre-branch.svg
   16.54 +image-sources := $(wildcard figs/*.dot figs/*.gif figs/*.png figs/*.svg)
   16.55 +
   16.56 +xml-src-files := \
   16.57 +	00book.xml \
   16.58 +	app*.xml \
   16.59 +	ch*.xml
   16.60  
   16.61  image-dot := $(filter %.dot,$(image-sources))
   16.62  image-svg := $(filter %.svg,$(image-sources))
   16.63 -image-png := $(filter %.png,$(image-sources))
   16.64 -
   16.65 -image-pdf := $(image-dot:%.dot=%.pdf) $(image-svg:%.svg=%.pdf) $(image-png)
   16.66 -image-html := $(image-dot:%.dot=%.png) $(image-svg:%.svg=%.png) $(image-png)
   16.67 -
   16.68 -example-sources := \
   16.69 +image-oth := $(filter %.gif %.png,$(image-sources))
   16.70 +
   16.71 +obj-web := html
   16.72 +obj-websup := $(obj-web)/support
   16.73 +obj-web-read := $(obj-web)/read
   16.74 +
   16.75 +image-web := \
   16.76 +	$(image-dot:%.dot=$(obj-web-read)/%.png) \
   16.77 +	$(image-svg:%.svg=$(obj-web-read)/%.png) \
   16.78 +	$(image-oth:%=$(obj-web-read)/%)
   16.79 +
   16.80 +example-sources-by-name := \
   16.81  	backout \
   16.82  	bisect \
   16.83  	branching \
   16.84 @@ -71,7 +35,6 @@
   16.85  	filenames \
   16.86  	hook.msglen \
   16.87  	hook.simple \
   16.88 -	hook.ws \
   16.89  	issue29 \
   16.90  	mq.guards \
   16.91  	mq.qinit-help \
   16.92 @@ -88,6 +51,49 @@
   16.93  	tour \
   16.94  	tour-merge-conflict
   16.95  
   16.96 +example-sources := \
   16.97 +	$(example-sources-by-name:%=examples/%) \
   16.98 +	$(wildcard examples/ch*/*)
   16.99 +
  16.100 +extras-web-base := \
  16.101 +	$(obj-web)/index.html \
  16.102 +	$(obj-web)/robots.txt \
  16.103 +	$(obj-websup)/form-min.js \
  16.104 +	$(obj-websup)/form.js \
  16.105 +	$(obj-websup)/hsbook.js \
  16.106 +	$(obj-websup)/jquery-min.js \
  16.107 +	$(obj-websup)/jquery.js \
  16.108 +	$(obj-websup)/styles.css
  16.109 +
  16.110 +extras-web := $(extras-web-base) $(extras-web-base:%=%.gz)
  16.111 +
  16.112 +xsltproc := xsltproc
  16.113 +xsltproc-opts := --nonet --xinclude --path '$(xml-path)'
  16.114 +
  16.115 +xmllint := xmllint
  16.116 +xmllint-opts := --noout --nonet --valid
  16.117 +
  16.118 +system-xsl-dir := $(firstword $(wildcard \
  16.119 +	/usr/share/sgml/docbook/xsl-stylesheets \
  16.120 +	/usr/share/xml/docbook/stylesheet/nwalsh \
  16.121 +	))
  16.122 +
  16.123 +# Bletcherousness.
  16.124 +
  16.125 +ifneq ($(wildcard /usr/share/sgml/docbook/xml-dtd-4.4-*),)
  16.126 +dtd-dir := $(wildcard /usr/share/sgml/docbook/xml-dtd-4.4-*)
  16.127 +else
  16.128 +ifneq ($(wildcard /usr/share/xml/docbook/schema/dtd/4.4),)
  16.129 +dtd-dir := $(wildcard /usr/share/xml/docbook/schema/dtd/4.4)
  16.130 +else
  16.131 +$(error Do not know where to look for DocBook XML 4.4 DTD)
  16.132 +endif
  16.133 +endif
  16.134 +
  16.135 +ifeq ($(system-xsl-dir),)
  16.136 +$(error add a suitable directory to system-xsl-dir)
  16.137 +endif
  16.138 +
  16.139  example-prereqs := \
  16.140  	/usr/bin/merge
  16.141  
  16.142 @@ -96,11 +102,6 @@
  16.143  	../html/index.html.var \
  16.144  	../html/index.en.html
  16.145  
  16.146 -latex-options = \
  16.147 -	-interaction batchmode \
  16.148 -	-output-directory $(dir $(1)) \
  16.149 -	-jobname $(basename $(notdir $(1)))
  16.150 -
  16.151  hg = $(shell which hg)
  16.152  
  16.153  hg-id = $(shell hg parents --template '{node|short}, dated {date|isodate},\n')
  16.154 @@ -108,113 +109,111 @@
  16.155  hg-version = $(shell hg version -q | \
  16.156  		     sed 's,.*(version \(unknown\|[a-f0-9+]*\)),\1,')
  16.157  
  16.158 -all: pdf html
  16.159 -
  16.160 -pdf: pdf/hgbook.pdf
  16.161 -
  16.162 -define pdf
  16.163 +all: web complete.xml
  16.164 +
  16.165 +../stylesheets/system-xsl: $(system-xsl-dir)
  16.166 +	ln -s $< $@
  16.167 +
  16.168 +web: ../stylesheets/system-xsl websup html
  16.169 +
  16.170 +html: $(obj-web-read)/index.html
  16.171 +
  16.172 +../web/index-read.html.in: ../web/genindex.py $(xml-src-files)
  16.173 +	cd ../web && ./genindex.py
  16.174 +
  16.175 +$(obj-web-read)/index.html: ../stylesheets/system-xsl .validated-00book.xml ../web/index-read.html.in
  16.176 +	xsltproc $(xsltproc-opts) -o $(obj-web-read)/x ../stylesheets/chunk-stylesheet.xsl 00book.xml
  16.177 +	python ../web/texpand.py ../web/index-read.html.in html/read/index.html
  16.178 +	for i in $(obj-web-read)/*.html; do \
  16.179 +	  gzip -9 -c $$i > $$i.gz; \
  16.180 +	done
  16.181 +
  16.182 +websup: $(extras-web) $(image-web)
  16.183 +	mkdir -p $(obj-websup)/figs $(obj-web-read)/figs
  16.184 +	cp ../stylesheets/system-xsl/images/*.png $(obj-websup)/figs
  16.185 +	cp -f ../web/icons/*.png $(obj-websup)/figs
  16.186 +
  16.187 +complete.xml: .validated-00book.xml
  16.188 +	$(xsltproc) $(xsltproc-opts) -o $@ ../stylesheets/dtd-profile.xsl 00book.xml
  16.189 +
  16.190 +all-ids.dat: ../stylesheets/all-ids.xsl $(xml-src-files)
  16.191 +	$(xsltproc) $(xsltproc-opts) -o $@ ../stylesheets/all-ids.xsl 00book.xml
  16.192 +
  16.193 +web: websup
  16.194 +
  16.195 +valid: .validated-00book.xml
  16.196 +
  16.197 +.validated-00book.xml: $(xml-src-files) examples/.run
  16.198 +	$(xmllint) --path '$(dtd-dir):$(xml-path)' $(xmllint-opts) $<
  16.199 +	touch $@
  16.200 +
  16.201 +# Produce 90dpi PNGs for the web.
  16.202 +
  16.203 +$(obj-web-read)/figs/%.png: $(obj-web-read)/figs/%.svg fixsvg
  16.204  	mkdir -p $(dir $@)
  16.205 -	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
  16.206 -	cp 99book.bib $(dir $@)
  16.207 -	cd $(dir $@) && bibtex $(basename $(notdir $@))
  16.208 -	cd $(dir $@) && makeindex $(basename $(notdir $@))
  16.209 -	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
  16.210 -	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
  16.211 -	if grep 'Reference.*undefined' $(@:.pdf=.log); then exit 1; fi
  16.212 -endef
  16.213 -
  16.214 -pdf/hgbook.pdf: $(sources) examples $(image-pdf)
  16.215 -	$(call pdf)
  16.216 -
  16.217 -html: onepage split
  16.218 -
  16.219 -onepage: $(htlatex) html/onepage/hgbook.html html/onepage/hgbook.css $(image-html:%=html/onepage/%)
  16.220 -
  16.221 -html/onepage/%: %
  16.222 -	cp $< $@
  16.223 -
  16.224 -split: $(htlatex) html/split/hgbook.html html/split/hgbook.css $(image-html:%=html/split/%)
  16.225 -
  16.226 -html/split/%: %
  16.227 -	cp $< $@
  16.228 -
  16.229 -# This is a horrible hack to work around the fact that the htlatex
  16.230 -# command in tex4ht is itself a horrible hack.  I really don't want to
  16.231 -# include verbatim the big wad of TeX that is repeated in that script,
  16.232 -# but I've given up and run a hacked copy as htlatex.book here.
  16.233 -
  16.234 -define htlatex
  16.235 -	mkdir -p $(dir $(1))
  16.236 -	cp 99book.bib $(dir $(1))
  16.237 -	TEXINPUTS=$(dir $(2)): ./htlatex.book $(2) "bookhtml,html4-uni,$(3)" " -cunihtf -utf8" "$(dir $(1))" "$(call latex-options,$(1))" || (rm -f $(1); exit 1)
  16.238 -	cd $(dir $(1)) && tex4ht -f/$(basename $(notdir $(1))) -cvalidate -cunihtf
  16.239 -	cd $(dir $(1)) && t4ht -f/$(basename $(notdir $(1)))
  16.240 -	./fixhtml.py $(dir $(1))/*.html
  16.241 -	rm $(dir $(1))/hgbook.css
  16.242 -endef
  16.243 -
  16.244 -html/onepage/hgbook.html: $(sources) examples $(image-html) bookhtml.cfg
  16.245 -	$(call htlatex,$@,$<)
  16.246 -
  16.247 -html/split/hgbook.html: $(sources) examples bookhtml.cfg
  16.248 -	$(call htlatex,$@,$<,2)
  16.249 -
  16.250 -# Produce 90dpi PNGs for the web.
  16.251 -
  16.252 -%.png: %.svg fixsvg
  16.253  	./fixsvg $<
  16.254  	inkscape -D -e $@ $<-tmp.svg
  16.255  	rm $<-tmp.svg
  16.256  
  16.257 -%.svg: %.dot
  16.258 +$(obj-web-read)/figs/%.png: figs/%.svg fixsvg
  16.259 +	mkdir -p $(dir $@)
  16.260 +	./fixsvg $<
  16.261 +	inkscape -D -e $@ $<-tmp.svg
  16.262 +	rm $<-tmp.svg
  16.263 +
  16.264 +$(obj-web-read)/figs/%.gif: figs/%.gif
  16.265 +	cp $< $@
  16.266 +
  16.267 +$(obj-web-read)/figs/%.png: figs/%.png
  16.268 +	cp $< $@
  16.269 +
  16.270 +$(obj-web-read)/figs/%.svg: figs/%.dot
  16.271 +	mkdir -p $(dir $@)
  16.272  	dot -Tsvg -o $@ $<
  16.273  
  16.274 -# Produce eps & pdf for the pdf
  16.275 -
  16.276 -%.pdf: %.eps
  16.277 -	epstopdf $<
  16.278 -
  16.279 -%.eps: %.svg
  16.280 -	./fixsvg $<
  16.281 -	inkscape -E $@ $<-tmp.svg
  16.282 -	rm $<-tmp.svg
  16.283 -
  16.284 -%.eps: %.dot
  16.285 -	dot -Tps -o $@ $<
  16.286 -
  16.287  examples: $(example-prereqs) examples/.run
  16.288  
  16.289 -examples/.run: $(example-sources:%=examples/%.run)
  16.290 -	touch examples/.run
  16.291 +examples/.run: $(example-sources)
  16.292 +	cd examples && ./run-example -a
  16.293  
  16.294  examples/%.run: examples/% examples/run-example
  16.295 -	cd examples && ./run-example $(notdir $<)
  16.296 -
  16.297 -changelog := $(wildcard ../.hg/store/00changelog.[id])
  16.298 -ifeq ($(changelog),)
  16.299 -changelog := $(wildcard ../.hg/00changelog.[id])
  16.300 -endif
  16.301 -
  16.302 -build_id.tex: $(changelog)
  16.303 -	echo -n '$(hg-id)' > build_id.tex
  16.304 -
  16.305 -hg_id.tex: $(hg)
  16.306 -	echo -n '$(hg-version)' > hg_id.tex
  16.307  
  16.308  clean:
  16.309 -	rm -rf dist html pdf \
  16.310 -		$(image-dot:%.dot=%.pdf) \
  16.311 -		$(image-dot:%.dot=%.png) \
  16.312 -		$(image-svg:%.svg=%.pdf) \
  16.313 -		$(image-svg:%.svg=%.png) \
  16.314 -		examples/*.{lxo,run} examples/.run build_id.tex hg_id.tex
  16.315 -
  16.316 -install: pdf split $(dist-sources)
  16.317 +	-rm -rf dist html $(image-dot:%.dot=%.pdf) $(image-dot:%.dot=%.png) \
  16.318 +	  $(image-svg:%.svg=%.png) examples/*.{lxo,run} examples/.run
  16.319 +
  16.320 +install: html $(dist-sources)
  16.321  	rm -rf dist
  16.322  	mkdir -p dist
  16.323 -	cp pdf/hgbook.pdf dist
  16.324 -	cp html/split/*.{css,html,png} dist
  16.325 +	cp html/*.{css,html,png} dist
  16.326  	cp $(dist-sources) dist
  16.327  
  16.328  rsync: install
  16.329  	rsync -avz --delete dist sp.red-bean.com:public_html/hgbook
  16.330 +
  16.331 +vpath %.css ../web
  16.332 +vpath %.html.in ../web
  16.333 +vpath %.js ../web/javascript
  16.334 +
  16.335 +$(obj-websup)/%.css: %.css
  16.336 +	@mkdir -p $(dir $@)
  16.337 +	cp $< $@
  16.338 +
  16.339 +$(obj-websup)/%.jpg: %.jpg
  16.340 +	@mkdir -p $(dir $@)
  16.341 +	cp $< $@
  16.342 +
  16.343 +$(obj-websup)/%.js: %.js
  16.344 +	@mkdir -p $(dir $@)
  16.345 +	cp $< $@
  16.346 +
  16.347 +$(obj-web)/%: ../web/%
  16.348 +	@mkdir -p $(dir $@)
  16.349 +	cp $< $@
  16.350 +
  16.351 +$(obj-web)/%.html: %.html.in
  16.352 +	@mkdir -p $(dir $@)
  16.353 +	python ../web/texpand.py $< $@
  16.354 +
  16.355 +%.gz: %
  16.356 +	gzip -9 -c $< > $@

    17.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    17.2 +++ b/en/appA-svn.xml	Sun Aug 16 03:41:39 2009 +0200
    17.3 @@ -0,0 +1,540 @@
    17.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    17.5 +
    17.6 +<appendix id="svn">
    17.7 +  <?dbhtml filename="migrating-to-mercurial.html"?>
    17.8 +<title>Migrating to Mercurial</title>
    17.9 +
   17.10 +  <para id="x_6e1">A common way to test the waters with a new revision control
   17.11 +    tool is to experiment with switching an existing project, rather
   17.12 +    than starting a new project from scratch.</para>
   17.13 +
   17.14 +  <para id="x_6e2">In this appendix, we discuss how to import a project's history
   17.15 +    into Mercurial, and what to look out for if you are used to a
   17.16 +    different revision control system.</para>
   17.17 +
   17.18 +  <sect1>
   17.19 +    <title>Importing history from another system</title>
   17.20 +
   17.21 +    <para id="x_6e3">Mercurial ships with an extension named
   17.22 +      <literal>convert</literal>, which can import project history
   17.23 +      from most popular revision control systems.  At the time this
   17.24 +      book was written, it could import history from the following
   17.25 +      systems:</para>
   17.26 +    <itemizedlist>
   17.27 +      <listitem>
   17.28 +	<para id="x_6e4">Subversion</para>
   17.29 +      </listitem>
   17.30 +      <listitem>
   17.31 +	<para id="x_6e5">CVS</para>
   17.32 +      </listitem>
   17.33 +      <listitem>
   17.34 +	<para id="x_6e6">git</para>
   17.35 +      </listitem>
   17.36 +      <listitem>
   17.37 +	<para id="x_6e7">Darcs</para>
   17.38 +      </listitem>
   17.39 +      <listitem>
   17.40 +	<para id="x_6e8">Bazaar</para>
   17.41 +      </listitem>
   17.42 +      <listitem>
   17.43 +	<para id="x_6e9">Monotone</para>
   17.44 +      </listitem>
   17.45 +      <listitem>
   17.46 +	<para id="x_6ea">GNU Arch</para>
   17.47 +      </listitem>
   17.48 +      <listitem>
   17.49 +	<para id="x_6eb">Mercurial</para>
   17.50 +      </listitem>
   17.51 +    </itemizedlist>
   17.52 +
   17.53 +    <para id="x_6ec">(To see why Mercurial itself is supported as a source, see
   17.54 +      <xref linkend="svn.filemap"/>.)</para>
   17.55 +
   17.56 +    <para id="x_6ed">You can enable the extension in the usual way, by editing
   17.57 +      your <filename>~/.hgrc</filename> file.</para>
   17.58 +
   17.59 +    <programlisting>[extensions]
   17.60 +convert =</programlisting>
   17.61 +
   17.62 +    <para id="x_6ee">This will make a <command>hg convert</command> command
   17.63 +      available.  The command is easy to use.  For instance, this
   17.64 +      command will import the Subversion history for the Nose unit
   17.65 +      testing framework into Mercurial.</para>
   17.66 +
   17.67 +    <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
   17.68 +
   17.69 +    <para id="x_6ef">The <literal>convert</literal> extension operates
   17.70 +      incrementally.  In other words, after you have run <command>hg
   17.71 +	convert</command> once, running it again will import any new
   17.72 +      revisions committed after the first run began.  Incremental
   17.73 +      conversion will only work if you run <command>hg
   17.74 +	convert</command> in the same Mercurial repository that you
   17.75 +      originally used, because the <literal>convert</literal>
   17.76 +      extension saves some private metadata in a
   17.77 +      non-revision-controlled file named
   17.78 +      <filename>.hg/shamap</filename> inside the target
   17.79 +      repository.</para>
   17.80 +
   17.81 +    <para id="x_707">When you want to start making changes using Mercurial, it's
   17.82 +      best to clone the tree in which you are doing your conversions,
   17.83 +      and leave the original tree for future incremental conversions.
   17.84 +      This is the safest way to let you pull and merge future commits
   17.85 +      from the source revision control system into your newly active
   17.86 +      Mercurial project.</para>
   17.87 +
   17.88 +    <sect2>
   17.89 +      <title>Converting multiple branches</title>
   17.90 +
   17.91 +      <para id="x_708">The <command>hg convert</command> command given above
   17.92 +	converts only the history of the <literal>trunk</literal>
   17.93 +	branch of the Subversion repository.  If we instead use the
   17.94 +	URL <literal>http://python-nose.googlecode.com/svn</literal>,
   17.95 +	Mercurial will automatically detect the
   17.96 +	<literal>trunk</literal>, <literal>tags</literal> and
   17.97 +	<literal>branches</literal> layout that Subversion projects
   17.98 +	usually use, and it will import each as a separate Mercurial
   17.99 +	branch.</para>
  17.100 +
  17.101 +      <para id="x_709">By default, each Subversion branch imported into Mercurial
  17.102 +	is given a branch name.  After the conversion completes, you
  17.103 +	can get a list of the active branch names in the Mercurial
  17.104 +	repository using <command>hg branches -a</command>. If you
  17.105 +	would prefer to import the Subversion branches without names,
  17.106 +	pass the <option>--config
  17.107 +	  convert.hg.usebranchnames=false</option> option to
  17.108 +	<command>hg convert</command>.</para>
  17.109 +
  17.110 +      <para id="x_70a">Once you have converted your tree, if you want to follow
  17.111 +	the usual Mercurial practice of working in a tree that
  17.112 +	contains a single branch, you can clone that single branch
  17.113 +	using <command>hg clone -r mybranchname</command>.</para>
  17.114 +    </sect2>
  17.115 +
  17.116 +    <sect2>
  17.117 +      <title>Mapping user names</title>
  17.118 +
  17.119 +      <para id="x_6f0">Some revision control tools save only short usernames with
  17.120 +	commits, and these can be difficult to interpret.  The norm
  17.121 +	with Mercurial is to save a committer's name and email
  17.122 +	address, which is much more useful for talking to them after
  17.123 +	the fact.</para>
  17.124 +
  17.125 +      <para id="x_6f1">If you are converting a tree from a revision control
  17.126 +	system that uses short names, you can map those names to
  17.127 +	longer equivalents by passing a <option>--authors</option>
  17.128 +	option to <command>hg convert</command>.  This option accepts
  17.129 +	a file name that should contain entries of the following
  17.130 +	form.</para>
  17.131 +
  17.132 +      <programlisting>arist = Aristotle &lt;aristotle@phil.example.gr&gt;
  17.133 +soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
  17.134 +
  17.135 +      <para id="x_6f2">Whenever <literal>convert</literal> encounters a commit
  17.136 +	with the username <literal>arist</literal> in the source
  17.137 +	repository, it will use the name <literal>Aristotle
  17.138 +	  &lt;aristotle@phil.example.gr&gt;</literal> in the converted
  17.139 +	Mercurial revision.  If no match is found for a name, it is
  17.140 +	used verbatim.</para>
  17.141 +    </sect2>
  17.142 +
  17.143 +    <sect2 id="svn.filemap">
  17.144 +      <title>Tidying up the tree</title>
  17.145 +
  17.146 +      <para id="x_6f3">Not all projects have pristine history.  There may be a
  17.147 +	directory that should never have been checked in, a file that
  17.148 +	is too big, or a whole hierarchy that needs to be
  17.149 +	refactored.</para>
  17.150 +
  17.151 +      <para id="x_6f4">The <literal>convert</literal> extension supports the idea
  17.152 +	of a <quote>file map</quote> that can reorganize the files and
  17.153 +	directories in a project as it imports the project's history.
  17.154 +	This is useful not only when importing history from other
  17.155 +	revision control systems, but also to prune or refactor a
  17.156 +	Mercurial tree.</para>
  17.157 +
  17.158 +      <para id="x_6f5">To specify a file map, use the <option>--filemap</option>
  17.159 +	option and supply a file name.  A file map contains lines of the
  17.160 +	following forms.</para>
  17.161 +
  17.162 +      <programlisting># This is a comment.
  17.163 +# Empty lines are ignored.	
  17.164 +
  17.165 +include path/to/file
  17.166 +
  17.167 +exclude path/to/file
  17.168 +
  17.169 +rename from/some/path to/some/other/place
  17.170 +</programlisting>
  17.171 +
  17.172 +      <para id="x_6f6">The <literal>include</literal> directive causes a file, or
  17.173 +	all files under a directory, to be included in the destination
  17.174 +	repository.  This also excludes all other files and dirs not
  17.175 +	explicitely included.  The <literal>exclude</literal>
  17.176 +	directive causes files or directories to be omitted, and
  17.177 +	others not explicitly mentioned to be included.</para>
  17.178 +
  17.179 +      <para id="x_6f7">To move a file or directory from one location to another,
  17.180 +	use the <literal>rename</literal> directive.  If you need to
  17.181 +	move a file or directory from a subdirectory into the root of
  17.182 +	the repository, use <literal>.</literal> as the second
  17.183 +	argument to the <literal>rename</literal> directive.</para>
  17.184 +    </sect2>
  17.185 +
  17.186 +    <sect2>
  17.187 +      <title>Improving Subversion conversion performance</title>
  17.188 +
  17.189 +      <para id="x_70b">You will often need several attempts before you hit the
  17.190 +	perfect combination of user map, file map, and other
  17.191 +	conversion parameters.  Converting a Subversion repository
  17.192 +	over an access protocol like <literal>ssh</literal> or
  17.193 +	<literal>http</literal> can proceed thousands of times more
  17.194 +	slowly than Mercurial is capable of actually operating, due to
  17.195 +	network delays.  This can make tuning that perfect conversion
  17.196 +	recipe very painful.</para>
  17.197 +
  17.198 +      <para id="x_70c">The <ulink
  17.199 +	  url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command>svnsync</command></ulink> 
  17.200 +	command can greatly speed up the conversion of a Subversion
  17.201 +	repository.  It is a read-only mirroring program for
  17.202 +	Subversion repositories.  The idea is that you create a local
  17.203 +	mirror of your Subversion tree, then convert the mirror into a
  17.204 +	Mercurial repository.</para>
  17.205 +
  17.206 +      <para id="x_70d">Suppose we want to convert the Subversion repository for
  17.207 +	the popular Memcached project into a Mercurial tree.  First,
  17.208 +	we create a local Subversion repository.</para>
  17.209 +
  17.210 +      <screen><prompt>$</prompt> <userinput>svnadmin create memcached-mirror</userinput></screen>
  17.211 +
  17.212 +      <para id="x_70e">Next, we set up a Subversion hook that
  17.213 +	<command>svnsync</command> needs.</para>
  17.214 +
  17.215 +      <screen><prompt>$</prompt> <userinput>echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change</userinput>
  17.216 +<prompt>$</prompt> <userinput>chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
  17.217 +
  17.218 +      <para id="x_70f">We then initialize <command>svnsync</command> in this
  17.219 +	repository.</para>
  17.220 +
  17.221 +      <screen><prompt>$</prompt> <userinput>svnsync --init file://`pwd`/memcached-mirror \
  17.222 +  http://code.sixapart.com/svn/memcached</userinput></screen>
  17.223 +
  17.224 +      <para id="x_710">Our next step is to begin the <command>svnsync</command>
  17.225 +	mirroring process.</para>
  17.226 +
  17.227 +      <screen><prompt>$</prompt> <userinput>svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
  17.228 +
  17.229 +      <para id="x_711">Finally, we import the history of our local Subversion
  17.230 +	mirror into Mercurial.</para>
  17.231 +
  17.232 +      <screen><prompt>$</prompt> <userinput>hg convert memcached-mirror</userinput></screen>
  17.233 +      
  17.234 +      <para id="x_712">We can use this process incrementally if the Subversion
  17.235 +	repository is still in use.  We run <command>svnsync</command>
  17.236 +	to pull new changes into our mirror, then <command>hg
  17.237 +	  convert</command> to import them into our Mercurial
  17.238 +	tree.</para>
  17.239 +
  17.240 +      <para id="x_713">There are two advantages to doing a two-stage import with
  17.241 +	<command>svnsync</command>.  The first is that it uses more
  17.242 +	efficient Subversion network syncing code than <command>hg
  17.243 +	  convert</command>, so it transfers less data over the
  17.244 +	network.  The second is that the import from a local
  17.245 +	Subversion tree is so fast that you can tweak your conversion
  17.246 +	setup repeatedly without having to sit through a painfully
  17.247 +	slow network-based conversion process each time.</para>
  17.248 +    </sect2>
  17.249 +  </sect1>
  17.250 +
  17.251 +  <sect1>
  17.252 +    <title>Migrating from Subversion</title>
  17.253 +
  17.254 +    <para id="x_6f8">Subversion is currently the most popular open source
  17.255 +      revision control system. Although there are many differences
  17.256 +      between Mercurial and Subversion, making the transition from
  17.257 +      Subversion to Mercurial is not particularly difficult.  The two
  17.258 +      have similar command sets and generally uniform
  17.259 +      interfaces.</para>
  17.260 +
  17.261 +    <sect2>
  17.262 +      <title>Philosophical differences</title>
  17.263 +
  17.264 +      <para id="x_6f9">The fundamental difference between Subversion and
  17.265 +	Mercurial is of course that Subversion is centralized, while
  17.266 +	Mercurial is distributed.  Since Mercurial stores all of a
  17.267 +	project's history on your local drive, it only needs to
  17.268 +	perform a network access when you want to explicitly
  17.269 +	communicate with another repository. In contrast, Subversion
  17.270 +	stores very little information locally, and the client must
  17.271 +	thus contact its server for many common operations.</para>
  17.272 +
  17.273 +      <para id="x_6fa">Subversion more or less gets away without a well-defined
  17.274 +	notion of a branch: which portion of a server's namespace
  17.275 +	qualifies as a branch is a matter of convention, with the
  17.276 +	software providing no enforcement.  Mercurial treats a
  17.277 +	repository as the unit of branch management.</para>
  17.278 +
  17.279 +      <sect3>
  17.280 +	<title>Scope of commands</title>
  17.281 +
  17.282 +	<para id="x_6fb">Since Subversion doesn't know what parts of its
  17.283 +	  namespace are really branches, it treats most commands as
  17.284 +	  requests to operate at and below whatever directory you are
  17.285 +	  currently visiting.  For instance, if you run <command>svn
  17.286 +	    log</command>, you'll get the history of whatever part of
  17.287 +	  the tree you're looking at, not the tree as a whole.</para>
  17.288 +
  17.289 +	<para id="x_6fc">Mercurial's commands behave differently, by defaulting
  17.290 +	  to operating over an entire repository.  Run <command>hg
  17.291 +	    log</command> and it will tell you the history of the
  17.292 +	  entire tree, no matter what part of the working directory
  17.293 +	  you're visiting at the time.  If you want the history of
  17.294 +	  just a particular file or directory, simply supply it by
  17.295 +	  name, e.g. <command>hg log src</command>.</para>
  17.296 +
  17.297 +	<para id="x_6fd">From my own experience, this difference in default
  17.298 +	  behaviors is probably the most likely to trip you up if you
  17.299 +	  have to switch back and forth frequently between the two
  17.300 +	  tools.</para>
  17.301 +      </sect3>
  17.302 +
  17.303 +      <sect3>
  17.304 +	<title>Multi-user operation and safety</title>
  17.305 +
  17.306 +	<para id="x_6fe">With Subversion, it is normal (though slightly frowned
  17.307 +	  upon) for multiple people to collaborate in a single branch.
  17.308 +	  If Alice and Bob are working together, and Alice commits
  17.309 +	  some changes to their shared branch, Bob must update his
  17.310 +	  client's view of the branch before he can commit.  Since at
  17.311 +	  this time he has no permanent record of the changes he has
  17.312 +	  made, he can corrupt or lose his modifications during and
  17.313 +	  after his update.</para>
  17.314 +
  17.315 +	<para id="x_6ff">Mercurial encourages a commit-then-merge model instead.
  17.316 +	  Bob commits his changes locally before pulling changes from,
  17.317 +	  or pushing them to, the server that he shares with Alice.
  17.318 +	  If Alice pushed her changes before Bob tries to push his, he
  17.319 +	  will not be able to push his changes until he pulls hers,
  17.320 +	  merges with them, and commits the result of the merge.  If
  17.321 +	  he makes a mistake during the merge, he still has the option
  17.322 +	  of reverting to the commit that recorded his changes.</para>
  17.323 +
  17.324 +	<para id="x_700">It is worth emphasizing that these are the common ways
  17.325 +	  of working with these tools. Subversion supports a safer
  17.326 +	  work-in-your-own-branch model, but it is cumbersome enough
  17.327 +	  in practice to not be widely used.  Mercurial can support
  17.328 +	  the less safe mode of allowing changes to be pulled in and
  17.329 +	  merged on top of uncommitted edits, but this is considered
  17.330 +	  highly unusual.</para>
  17.331 +      </sect3>
  17.332 +
  17.333 +      <sect3>
  17.334 +	<title>Published vs local changes</title>
  17.335 +
  17.336 +	<para id="x_701">A Subversion <command>svn commit</command> command
  17.337 +	  immediately publishes changes to a server, where they can be
  17.338 +	  seen by everyone who has read access.</para>
  17.339 +
  17.340 +	<para id="x_702">With Mercurial, commits are always local, and must be
  17.341 +	  published via a <command>hg push</command> command
  17.342 +	  afterwards.</para>
  17.343 +
  17.344 +	<para id="x_703">Each approach has its advantages and disadvantages.  The
  17.345 +	  Subversion model means that changes are published, and hence
  17.346 +	  reviewable and usable, immediately.  On the other hand, this
  17.347 +	  means that a user must have commit access to a repository in
  17.348 +	  order to use the software in a normal way, and commit access
  17.349 +	  is not lightly given out by most open source
  17.350 +	  projects.</para>
  17.351 +
  17.352 +	<para id="x_704">The Mercurial approach allows anyone who can clone a
  17.353 +	  repository to commit changes without the need for someone
  17.354 +	  else's permission, and they can then publish their changes
  17.355 +	  and continue to participate however they see fit.  The
  17.356 +	  distinction between committing and pushing does open up the
  17.357 +	  possibility of someone committing changes to their laptop
  17.358 +	  and walking away for a few days having forgotten to push
  17.359 +	  them, which in rare cases might leave collaborators
  17.360 +	  temporarily stuck.</para>
  17.361 +      </sect3>
  17.362 +    </sect2>
  17.363 +
  17.364 +    <sect2>
  17.365 +      <title>Quick reference</title>
  17.366 +
  17.367 +      <table>
  17.368 +	<title>Subversion commands and Mercurial equivalents</title>
  17.369 +	<tgroup cols="3">
  17.370 +	  <thead>
  17.371 +	    <row>
  17.372 +	      <entry>Subversion</entry>
  17.373 +	      <entry>Mercurial</entry>
  17.374 +	      <entry>Notes</entry>
  17.375 +	    </row>
  17.376 +	  </thead>
  17.377 +	  <tbody>
  17.378 +	    <row>
  17.379 +	      <entry><command>svn add</command></entry>
  17.380 +	      <entry><command>hg add</command></entry>
  17.381 +	      <entry></entry>
  17.382 +	    </row>
  17.383 +	    <row>
  17.384 +	      <entry><command>svn blame</command></entry>
  17.385 +	      <entry><command>hg annotate</command></entry>
  17.386 +	      <entry></entry>
  17.387 +	    </row>
  17.388 +	    <row>
  17.389 +	      <entry><command>svn cat</command></entry>
  17.390 +	      <entry><command>hg cat</command></entry>
  17.391 +	      <entry></entry>
  17.392 +	    </row>
  17.393 +	    <row>
  17.394 +	      <entry><command>svn checkout</command></entry>
  17.395 +	      <entry><command>hg clone</command></entry>
  17.396 +	      <entry></entry>
  17.397 +	    </row>
  17.398 +	    <row>
  17.399 +	      <entry><command>svn cleanup</command></entry>
  17.400 +	      <entry>n/a</entry>
  17.401 +	      <entry>No cleanup needed</entry>
  17.402 +	    </row>
  17.403 +	    <row>
  17.404 +	      <entry><command>svn commit</command></entry>
  17.405 +	      <entry><command>hg commit</command>; <command>hg
  17.406 +		  push</command></entry>
  17.407 +	      <entry><command>hg push</command> publishes after
  17.408 +		commit</entry>
  17.409 +	    </row>
  17.410 +	    <row>
  17.411 +	      <entry><command>svn copy</command></entry>
  17.412 +	      <entry><command>hg clone</command></entry>
  17.413 +	      <entry>To create a new branch</entry>
  17.414 +	    </row>
  17.415 +	    <row>
  17.416 +	      <entry><command>svn copy</command></entry>
  17.417 +	      <entry><command>hg copy</command></entry>
  17.418 +	      <entry>To copy files or directories</entry>
  17.419 +	    </row>
  17.420 +	    <row>
  17.421 +	      <entry><command>svn delete</command> (<command>svn
  17.422 +		  remove</command>)</entry>
  17.423 +	      <entry><command>hg remove</command></entry>
  17.424 +	      <entry></entry>
  17.425 +	    </row>
  17.426 +	    <row>
  17.427 +	      <entry><command>svn diff</command></entry>
  17.428 +	      <entry><command>hg diff</command></entry>
  17.429 +	      <entry></entry>
  17.430 +	    </row>
  17.431 +	    <row>
  17.432 +	      <entry><command>svn export</command></entry>
  17.433 +	      <entry><command>hg archive</command></entry>
  17.434 +	      <entry></entry>
  17.435 +	    </row>
  17.436 +	    <row>
  17.437 +	      <entry><command>svn help</command></entry>
  17.438 +	      <entry><command>hg help</command></entry>
  17.439 +	      <entry></entry>
  17.440 +	    </row>
  17.441 +	    <row>
  17.442 +	      <entry><command>svn import</command></entry>
  17.443 +	      <entry><command>hg addremove</command>; <command>hg
  17.444 +		  commit</command></entry>
  17.445 +	      <entry></entry>
  17.446 +	    </row>
  17.447 +	    <row>
  17.448 +	      <entry><command>svn info</command></entry>
  17.449 +	      <entry><command>hg parents</command></entry>
  17.450 +	      <entry>Shows what revision is checked out</entry>
  17.451 +	    </row>
  17.452 +	    <row>
  17.453 +	      <entry><command>svn info</command></entry>
  17.454 +	      <entry><command>hg showconfig
  17.455 +		  paths.parent</command></entry>
  17.456 +	      <entry>Shows what URL is checked out</entry>
  17.457 +	    </row>
  17.458 +	    <row>
  17.459 +	      <entry><command>svn list</command></entry>
  17.460 +	      <entry><command>hg manifest</command></entry>
  17.461 +	      <entry></entry>
  17.462 +	    </row>
  17.463 +	    <row>
  17.464 +	      <entry><command>svn log</command></entry>
  17.465 +	      <entry><command>hg log</command></entry>
  17.466 +	      <entry></entry>
  17.467 +	    </row>
  17.468 +	    <row>
  17.469 +	      <entry><command>svn merge</command></entry>
  17.470 +	      <entry><command>hg merge</command></entry>
  17.471 +	      <entry></entry>
  17.472 +	    </row>
  17.473 +	    <row>
  17.474 +	      <entry><command>svn mkdir</command></entry>
  17.475 +	      <entry>n/a</entry>
  17.476 +	      <entry>Mercurial does not track directories</entry>
  17.477 +	    </row>
  17.478 +	    <row>
  17.479 +	      <entry><command>svn move</command> (<command>svn
  17.480 +		  rename</command>)</entry>
  17.481 +	      <entry><command>hg rename</command></entry>
  17.482 +	      <entry></entry>
  17.483 +	    </row>
  17.484 +	    <row>
  17.485 +	      <entry><command>svn resolved</command></entry>
  17.486 +	      <entry><command>hg resolve -m</command></entry>
  17.487 +	      <entry></entry>
  17.488 +	    </row>
  17.489 +	    <row>
  17.490 +	      <entry><command>svn revert</command></entry>
  17.491 +	      <entry><command>hg revert</command></entry>
  17.492 +	      <entry></entry>
  17.493 +	    </row>
  17.494 +	    <row>
  17.495 +	      <entry><command>svn status</command></entry>
  17.496 +	      <entry><command>hg status</command></entry>
  17.497 +	      <entry></entry>
  17.498 +	    </row>
  17.499 +	    <row>
  17.500 +	      <entry><command>svn update</command></entry>
  17.501 +	      <entry><command>hg pull -u</command></entry>
  17.502 +	      <entry></entry>
  17.503 +	    </row>
  17.504 +	  </tbody>
  17.505 +	</tgroup>
  17.506 +      </table>
  17.507 +    </sect2>
  17.508 +  </sect1>
  17.509 +
  17.510 +  <sect1>
  17.511 +    <title>Useful tips for newcomers</title>
  17.512 +
  17.513 +    <para id="x_705">Under some revision control systems, printing a diff for a
  17.514 +      single committed revision can be painful. For instance, with
  17.515 +      Subversion, to see what changed in revision 104654, you must
  17.516 +      type <command>svn diff -r104653:104654</command>. Mercurial
  17.517 +      eliminates the need to type the revision ID twice in this common
  17.518 +      case. For a plain diff, <command>hg export 104654</command>. For
  17.519 +      a log message followed by a diff, <command>hg log -r104654
  17.520 +	-p</command>.</para>
  17.521 +
  17.522 +    <para id="x_706">When you run <command>hg status</command> without any
  17.523 +      arguments, it prints the status of the entire tree, with paths
  17.524 +      relative to the root of the repository.  This makes it tricky to
  17.525 +      copy a file name from the output of <command>hg status</command>
  17.526 +      into the command line.  If you supply a file or directory name
  17.527 +      to <command>hg status</command>, it will print paths relative to
  17.528 +      your current location instead.  So to get tree-wide status from
  17.529 +      <command>hg status</command>, with paths that are relative to
  17.530 +      your current directory and not the root of the repository, feed
  17.531 +      the output of <command>hg root</command> into <command>hg
  17.532 +	status</command>.  You can easily do this as follows on a
  17.533 +      Unix-like system:</para>
  17.534 +
  17.535 +    <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
  17.536 +  </sect1>
  17.537 +</appendix>
  17.538 +
  17.539 +<!--
  17.540 +local variables: 
  17.541 +sgml-parent-document: ("00book.xml" "book" "appendix")
  17.542 +end:
  17.543 +-->

    18.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    18.2 +++ b/en/appB-mq-ref.xml	Sun Aug 16 03:41:39 2009 +0200
    18.3 @@ -0,0 +1,563 @@
    18.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    18.5 +
    18.6 +<appendix id="chap:mqref">
    18.7 +  <?dbhtml filename="mercurial-queues-reference.html"?>
    18.8 +  <title>Mercurial Queues reference</title>
    18.9 +
   18.10 +  <sect1 id="sec:mqref:cmdref">
   18.11 +    <title>MQ command reference</title>
   18.12 +
   18.13 +    <para id="x_5e8">For an overview of the commands provided by MQ, use the
   18.14 +      command <command role="hg-cmd">hg help mq</command>.</para>
   18.15 +
   18.16 +    <sect2>
   18.17 +      <title><command role="hg-ext-mq">qapplied</command>&emdash;print
   18.18 +	applied patches</title>
   18.19 +
   18.20 +      <para id="x_5e9">The <command role="hg-ext-mq">qapplied</command> command
   18.21 +	prints the current stack of applied patches.  Patches are
   18.22 +	printed in oldest-to-newest order, so the last patch in the
   18.23 +	list is the <quote>top</quote> patch.</para>
   18.24 +
   18.25 +    </sect2>
   18.26 +    <sect2>
   18.27 +      <title><command role="hg-ext-mq">qcommit</command>&emdash;commit
   18.28 +	changes in the queue repository</title>
   18.29 +
   18.30 +      <para id="x_5ea">The <command role="hg-ext-mq">qcommit</command> command
   18.31 +	commits any outstanding changes in the <filename
   18.32 +	  role="special" class="directory">.hg/patches</filename>
   18.33 +	repository.  This command only works if the <filename
   18.34 +	  role="special" class="directory">.hg/patches</filename>
   18.35 +	directory is a repository, i.e. you created the directory
   18.36 +	using <command role="hg-cmd">hg qinit <option
   18.37 +	    role="hg-ext-mq-cmd-qinit-opt">-c</option></command> or
   18.38 +	ran <command role="hg-cmd">hg init</command> in the directory
   18.39 +	after running <command
   18.40 +	  role="hg-ext-mq">qinit</command>.</para>
   18.41 +
   18.42 +      <para id="x_5eb">This command is shorthand for <command role="hg-cmd">hg
   18.43 +	  commit --cwd .hg/patches</command>.</para>
   18.44 +    </sect2>
   18.45 +    <sect2>
   18.46 +	<title><command
   18.47 +	  role="hg-ext-mq">qdelete</command>&emdash;delete a patch
   18.48 +	from the <filename role="special">series</filename>
   18.49 +	file</title>
   18.50 +
   18.51 +      <para id="x_5ec">The <command role="hg-ext-mq">qdelete</command> command
   18.52 +	removes the entry for a patch from the <filename
   18.53 +	  role="special">series</filename> file in the <filename
   18.54 +	  role="special" class="directory">.hg/patches</filename>
   18.55 +	directory.  It does not pop the patch if the patch is already
   18.56 +	applied.  By default, it does not delete the patch file; use
   18.57 +	the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
   18.58 +	to do that.</para>
   18.59 +
   18.60 +      <para id="x_5ed">Options:</para>
   18.61 +      <itemizedlist>
   18.62 +	<listitem><para id="x_5ee"><option
   18.63 +	      role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
   18.64 +	    patch file.</para>
   18.65 +	</listitem></itemizedlist>
   18.66 +
   18.67 +    </sect2>
   18.68 +    <sect2>
   18.69 +      <title><command role="hg-ext-mq">qdiff</command>&emdash;print a
   18.70 +	diff of the topmost applied patch</title>
   18.71 +
   18.72 +      <para id="x_5ef">The <command role="hg-ext-mq">qdiff</command> command
   18.73 +	prints a diff of the topmost applied patch. It is equivalent
   18.74 +	to <command role="hg-cmd">hg diff -r-2:-1</command>.</para>
   18.75 +
   18.76 +    </sect2>
   18.77 +    <sect2>
   18.78 +      <title><command role="hg-ext-mq">qfold</command>&emdash;move
   18.79 +	applied patches into repository history</title>
   18.80 +
   18.81 +      <para id="x_72d">The <command>hg qfinish</command> command converts the
   18.82 +	specified applied patches into permanent changes by moving
   18.83 +	them out of MQ's control so that they will be treated as
   18.84 +	normal repository history.</para>
   18.85 +    </sect2>
   18.86 +
   18.87 +    <sect2>
   18.88 +      <title><command role="hg-ext-mq">qfold</command>&emdash;merge
   18.89 +	(<quote>fold</quote>) several patches into one</title>
   18.90 +
   18.91 +      <para id="x_5f0">The <command role="hg-ext-mq">qfold</command> command
   18.92 +	merges multiple patches into the topmost applied patch, so
   18.93 +	that the topmost applied patch makes the union of all of the
   18.94 +	changes in the patches in question.</para>
   18.95 +
   18.96 +      <para id="x_5f1">The patches to fold must not be applied; <command
   18.97 +	  role="hg-ext-mq">qfold</command> will exit with an error if
   18.98 +	any is.  The order in which patches are folded is significant;
   18.99 +	<command role="hg-cmd">hg qfold a b</command> means
  18.100 +	<quote>apply the current topmost patch, followed by
  18.101 +	  <literal>a</literal>, followed by
  18.102 +	  <literal>b</literal></quote>.</para>
  18.103 +
  18.104 +      <para id="x_5f2">The comments from the folded patches are appended to the
  18.105 +	comments of the destination patch, with each block of comments
  18.106 +	separated by three asterisk
  18.107 +	(<quote><literal>*</literal></quote>) characters.  Use the
  18.108 +	<option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
  18.109 +	edit the commit message for the combined patch/changeset after
  18.110 +	the folding has completed.</para>
  18.111 +
  18.112 +      <para id="x_5f3">Options:</para>
  18.113 +      <itemizedlist>
  18.114 +	<listitem><para id="x_5f4"><option
  18.115 +	      role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
  18.116 +	    commit message and patch description for the newly folded
  18.117 +	    patch.</para>
  18.118 +	</listitem>
  18.119 +	<listitem><para id="x_5f5"><option
  18.120 +	      role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
  18.121 +	    contents of the given file as the new commit message and
  18.122 +	    patch description for the folded patch.</para>
  18.123 +	</listitem>
  18.124 +	<listitem><para id="x_5f6"><option
  18.125 +	      role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
  18.126 +	    given text as the new commit message and patch description
  18.127 +	    for the folded patch.</para>
  18.128 +	</listitem></itemizedlist>
  18.129 +
  18.130 +    </sect2>
  18.131 +    <sect2>
  18.132 +      <title><command
  18.133 +	  role="hg-ext-mq">qheader</command>&emdash;display the
  18.134 +	header/description of a patch</title>
  18.135 +
  18.136 +      <para id="x_5f7">The <command role="hg-ext-mq">qheader</command> command
  18.137 +	prints the header, or description, of a patch.  By default, it
  18.138 +	prints the header of the topmost applied patch. Given an
  18.139 +	argument, it prints the header of the named patch.</para>
  18.140 +
  18.141 +    </sect2>
  18.142 +    <sect2>
  18.143 +      <title><command role="hg-ext-mq">qimport</command>&emdash;import
  18.144 +	a third-party patch into the queue</title>
  18.145 +
  18.146 +      <para id="x_5f8">The <command role="hg-ext-mq">qimport</command> command
  18.147 +	adds an entry for an external patch to the <filename
  18.148 +	  role="special">series</filename> file, and copies the patch
  18.149 +	into the <filename role="special"
  18.150 +	  class="directory">.hg/patches</filename> directory.  It adds
  18.151 +	the entry immediately after the topmost applied patch, but
  18.152 +	does not push the patch.</para>
  18.153 +
  18.154 +      <para id="x_5f9">If the <filename role="special"
  18.155 +	  class="directory">.hg/patches</filename> directory is a
  18.156 +	repository, <command role="hg-ext-mq">qimport</command>
  18.157 +	automatically does an <command role="hg-cmd">hg add</command>
  18.158 +	of the imported patch.</para>
  18.159 +
  18.160 +    </sect2>
  18.161 +    <sect2>
  18.162 +      <title><command role="hg-ext-mq">qinit</command>&emdash;prepare
  18.163 +	a repository to work with MQ</title>
  18.164 +
  18.165 +      <para id="x_5fa">The <command role="hg-ext-mq">qinit</command> command
  18.166 +	prepares a repository to work with MQ.  It creates a directory
  18.167 +	called <filename role="special"
  18.168 +	  class="directory">.hg/patches</filename>.</para>
  18.169 +
  18.170 +      <para id="x_5fb">Options:</para>
  18.171 +      <itemizedlist>
  18.172 +	<listitem><para id="x_5fc"><option
  18.173 +	      role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
  18.174 +	    <filename role="special"
  18.175 +	      class="directory">.hg/patches</filename> as a repository
  18.176 +	    in its own right.  Also creates a <filename
  18.177 +	      role="special">.hgignore</filename> file that will
  18.178 +	    ignore the <filename role="special">status</filename>
  18.179 +	    file.</para>
  18.180 +	</listitem></itemizedlist>
  18.181 +
  18.182 +      <para id="x_5fd">When the <filename role="special"
  18.183 +	  class="directory">.hg/patches</filename> directory is a
  18.184 +	repository, the <command role="hg-ext-mq">qimport</command>
  18.185 +	and <command role="hg-ext-mq">qnew</command> commands
  18.186 +	automatically <command role="hg-cmd">hg add</command> new
  18.187 +	patches.</para>
  18.188 +
  18.189 +    </sect2>
  18.190 +    <sect2>
  18.191 +      <title><command role="hg-ext-mq">qnew</command>&emdash;create a
  18.192 +	new patch</title>
  18.193 +
  18.194 +      <para id="x_5fe">The <command role="hg-ext-mq">qnew</command> command
  18.195 +	creates a new patch.  It takes one mandatory argument, the
  18.196 +	name to use for the patch file.  The newly created patch is
  18.197 +	created empty by default.  It is added to the <filename
  18.198 +	  role="special">series</filename> file after the current
  18.199 +	topmost applied patch, and is immediately pushed on top of
  18.200 +	that patch.</para>
  18.201 +
  18.202 +      <para id="x_5ff">If <command role="hg-ext-mq">qnew</command> finds modified
  18.203 +	files in the working directory, it will refuse to create a new
  18.204 +	patch unless the <option
  18.205 +	  role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
  18.206 +	(see below).  This behavior allows you to <command
  18.207 +	  role="hg-ext-mq">qrefresh</command> your topmost applied
  18.208 +	patch before you apply a new patch on top of it.</para>
  18.209 +
  18.210 +      <para id="x_600">Options:</para>
  18.211 +      <itemizedlist>
  18.212 +	<listitem><para id="x_601"><option
  18.213 +	      role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
  18.214 +	    patch if the contents of the working directory are
  18.215 +	    modified.  Any outstanding modifications are added to the
  18.216 +	    newly created patch, so after this command completes, the
  18.217 +	    working directory will no longer be modified.</para>
  18.218 +	</listitem>
  18.219 +	<listitem><para id="x_602"><option
  18.220 +	      role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
  18.221 +	    text as the commit message. This text will be stored at
  18.222 +	    the beginning of the patch file, before the patch
  18.223 +	    data.</para>
  18.224 +	</listitem></itemizedlist>
  18.225 +
  18.226 +    </sect2>
  18.227 +    <sect2>
  18.228 +      <title><command role="hg-ext-mq">qnext</command>&emdash;print
  18.229 +	the name of the next patch</title>
  18.230 +
  18.231 +      <para id="x_603">The <command role="hg-ext-mq">qnext</command> command
  18.232 +	prints the name name of the next patch in the <filename
  18.233 +	  role="special">series</filename> file after the topmost
  18.234 +	applied patch.  This patch will become the topmost applied
  18.235 +	patch if you run <command
  18.236 +	  role="hg-ext-mq">qpush</command>.</para>
  18.237 +
  18.238 +    </sect2>
  18.239 +    <sect2>
  18.240 +      <title><command role="hg-ext-mq">qpop</command>&emdash;pop
  18.241 +	patches off the stack</title>
  18.242 +
  18.243 +      <para id="x_604">The <command role="hg-ext-mq">qpop</command> command
  18.244 +	removes applied patches from the top of the stack of applied
  18.245 +	patches.  By default, it removes only one patch.</para>
  18.246 +
  18.247 +      <para id="x_605">This command removes the changesets that represent the
  18.248 +	popped patches from the repository, and updates the working
  18.249 +	directory to undo the effects of the patches.</para>
  18.250 +
  18.251 +      <para id="x_606">This command takes an optional argument, which it uses as
  18.252 +	the name or index of the patch to pop to.  If given a name, it
  18.253 +	will pop patches until the named patch is the topmost applied
  18.254 +	patch.  If given a number, <command
  18.255 +	  role="hg-ext-mq">qpop</command> treats the number as an
  18.256 +	index into the entries in the series file, counting from zero
  18.257 +	(empty lines and lines containing only comments do not count).
  18.258 +	It pops patches until the patch identified by the given index
  18.259 +	is the topmost applied patch.</para>
  18.260 +
  18.261 +      <para id="x_607">The <command role="hg-ext-mq">qpop</command> command does
  18.262 +	not read or write patches or the <filename
  18.263 +	  role="special">series</filename> file.  It is thus safe to
  18.264 +	<command role="hg-ext-mq">qpop</command> a patch that you have
  18.265 +	removed from the <filename role="special">series</filename>
  18.266 +	file, or a patch that you have renamed or deleted entirely.
  18.267 +	In the latter two cases, use the name of the patch as it was
  18.268 +	when you applied it.</para>
  18.269 +
  18.270 +      <para id="x_608">By default, the <command role="hg-ext-mq">qpop</command>
  18.271 +	command will not pop any patches if the working directory has
  18.272 +	been modified.  You can override this behavior using the
  18.273 +	<option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
  18.274 +	which reverts all modifications in the working
  18.275 +	directory.</para>
  18.276 +
  18.277 +      <para id="x_609">Options:</para>
  18.278 +      <itemizedlist>
  18.279 +	<listitem><para id="x_60a"><option
  18.280 +	      role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
  18.281 +	    applied patches.  This returns the repository to its state
  18.282 +	    before you applied any patches.</para>
  18.283 +	</listitem>
  18.284 +	<listitem><para id="x_60b"><option
  18.285 +	      role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
  18.286 +	    revert any modifications to the working directory when
  18.287 +	    popping.</para>
  18.288 +	</listitem>
  18.289 +	<listitem><para id="x_60c"><option
  18.290 +	      role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
  18.291 +	    from the named queue.</para>
  18.292 +	</listitem></itemizedlist>
  18.293 +
  18.294 +      <para id="x_60d">The <command role="hg-ext-mq">qpop</command> command
  18.295 +	removes one line from the end of the <filename
  18.296 +	  role="special">status</filename> file for each patch that it
  18.297 +	pops.</para>
  18.298 +
  18.299 +    </sect2>
  18.300 +    <sect2>
  18.301 +      <title><command role="hg-ext-mq">qprev</command>&emdash;print
  18.302 +	the name of the previous patch</title>
  18.303 +
  18.304 +      <para id="x_60e">The <command role="hg-ext-mq">qprev</command> command
  18.305 +	prints the name of the patch in the <filename
  18.306 +	  role="special">series</filename> file that comes before the
  18.307 +	topmost applied patch. This will become the topmost applied
  18.308 +	patch if you run <command
  18.309 +	  role="hg-ext-mq">qpop</command>.</para>
  18.310 +
  18.311 +    </sect2>
  18.312 +    <sect2 id="sec:mqref:cmd:qpush">
  18.313 +      <title><command role="hg-ext-mq">qpush</command>&emdash;push
  18.314 +	patches onto the stack</title>
  18.315 +
  18.316 +      <para id="x_60f">The <command role="hg-ext-mq">qpush</command> command adds
  18.317 +	patches onto the applied stack.  By default, it adds only one
  18.318 +	patch.</para>
  18.319 +
  18.320 +      <para id="x_610">This command creates a new changeset to represent each
  18.321 +	applied patch, and updates the working directory to apply the
  18.322 +	effects of the patches.</para>
  18.323 +
  18.324 +      <para id="x_611">The default data used when creating a changeset are as
  18.325 +	follows:</para>
  18.326 +      <itemizedlist>
  18.327 +	<listitem><para id="x_612">The commit date and time zone are the current
  18.328 +	    date and time zone.  Because these data are used to
  18.329 +	    compute the identity of a changeset, this means that if
  18.330 +	    you <command role="hg-ext-mq">qpop</command> a patch and
  18.331 +	    <command role="hg-ext-mq">qpush</command> it again, the
  18.332 +	    changeset that you push will have a different identity
  18.333 +	    than the changeset you popped.</para>
  18.334 +	</listitem>
  18.335 +	<listitem><para id="x_613">The author is the same as the default used by
  18.336 +	    the <command role="hg-cmd">hg commit</command>
  18.337 +	    command.</para>
  18.338 +	</listitem>
  18.339 +	<listitem><para id="x_614">The commit message is any text from the patch
  18.340 +	    file that comes before the first diff header.  If there is
  18.341 +	    no such text, a default commit message is used that
  18.342 +	    identifies the name of the patch.</para>
  18.343 +	</listitem></itemizedlist>
  18.344 +      <para id="x_615">If a patch contains a Mercurial patch header,
  18.345 +	the information in the patch header overrides these
  18.346 +	defaults.</para>
  18.347 +
  18.348 +      <para id="x_616">Options:</para>
  18.349 +      <itemizedlist>
  18.350 +	<listitem><para id="x_617"><option
  18.351 +	      role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
  18.352 +	    unapplied patches from the <filename
  18.353 +	      role="special">series</filename> file until there are
  18.354 +	    none left to push.</para>
  18.355 +	</listitem>
  18.356 +	<listitem><para id="x_618"><option
  18.357 +	      role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
  18.358 +	    of the patch to the end of the commit message.</para>
  18.359 +	</listitem>
  18.360 +	<listitem><para id="x_619"><option
  18.361 +	      role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
  18.362 +	    fails to apply cleanly, use the entry for the patch in
  18.363 +	    another saved queue to compute the parameters for a
  18.364 +	    three-way merge, and perform a three-way merge using the
  18.365 +	    normal Mercurial merge machinery.  Use the resolution of
  18.366 +	    the merge as the new patch content.</para>
  18.367 +	</listitem>
  18.368 +	<listitem><para id="x_61a"><option
  18.369 +	      role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
  18.370 +	    named queue if merging while pushing.</para>
  18.371 +	</listitem></itemizedlist>
  18.372 +
  18.373 +      <para id="x_61b">The <command role="hg-ext-mq">qpush</command> command
  18.374 +	reads, but does not modify, the <filename
  18.375 +	  role="special">series</filename> file.  It appends one line
  18.376 +	to the <command role="hg-cmd">hg status</command> file for
  18.377 +	each patch that it pushes.</para>
  18.378 +
  18.379 +    </sect2>
  18.380 +    <sect2>
  18.381 +      <title><command
  18.382 +	  role="hg-ext-mq">qrefresh</command>&emdash;update the
  18.383 +	topmost applied patch</title>
  18.384 +
  18.385 +      <para id="x_61c">The <command role="hg-ext-mq">qrefresh</command> command
  18.386 +	updates the topmost applied patch.  It modifies the patch,
  18.387 +	removes the old changeset that represented the patch, and
  18.388 +	creates a new changeset to represent the modified
  18.389 +	patch.</para>
  18.390 +
  18.391 +      <para id="x_61d">The <command role="hg-ext-mq">qrefresh</command> command
  18.392 +	looks for the following modifications:</para>
  18.393 +      <itemizedlist>
  18.394 +	<listitem><para id="x_61e">Changes to the commit message, i.e. the text
  18.395 +	    before the first diff header in the patch file, are
  18.396 +	    reflected in the new changeset that represents the
  18.397 +	    patch.</para>
  18.398 +	</listitem>
  18.399 +	<listitem><para id="x_61f">Modifications to tracked files in the working
  18.400 +	    directory are added to the patch.</para>
  18.401 +	</listitem>
  18.402 +	<listitem><para id="x_620">Changes to the files tracked using <command
  18.403 +	      role="hg-cmd">hg add</command>, <command
  18.404 +	      role="hg-cmd">hg copy</command>, <command
  18.405 +	      role="hg-cmd">hg remove</command>, or <command
  18.406 +	      role="hg-cmd">hg rename</command>.  Added files and copy
  18.407 +	    and rename destinations are added to the patch, while
  18.408 +	    removed files and rename sources are removed.</para>
  18.409 +	</listitem></itemizedlist>
  18.410 +
  18.411 +      <para id="x_621">Even if <command role="hg-ext-mq">qrefresh</command>
  18.412 +	detects no changes, it still recreates the changeset that
  18.413 +	represents the patch.  This causes the identity of the
  18.414 +	changeset to differ from the previous changeset that
  18.415 +	identified the patch.</para>
  18.416 +
  18.417 +      <para id="x_622">Options:</para>
  18.418 +      <itemizedlist>
  18.419 +	<listitem><para id="x_623"><option
  18.420 +	      role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
  18.421 +	    the commit and patch description, using the preferred text
  18.422 +	    editor.</para>
  18.423 +	</listitem>
  18.424 +	<listitem><para id="x_624"><option
  18.425 +	      role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
  18.426 +	    the commit message and patch description, using the given
  18.427 +	    text.</para>
  18.428 +	</listitem>
  18.429 +	<listitem><para id="x_625"><option
  18.430 +	      role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
  18.431 +	    the commit message and patch description, using text from
  18.432 +	    the given file.</para>
  18.433 +	</listitem></itemizedlist>
  18.434 +
  18.435 +    </sect2>
  18.436 +    <sect2>
  18.437 +      <title><command role="hg-ext-mq">qrename</command>&emdash;rename
  18.438 +	a patch</title>
  18.439 +
  18.440 +      <para id="x_626">The <command role="hg-ext-mq">qrename</command> command
  18.441 +	renames a patch, and changes the entry for the patch in the
  18.442 +	<filename role="special">series</filename> file.</para>
  18.443 +
  18.444 +      <para id="x_627">With a single argument, <command
  18.445 +	  role="hg-ext-mq">qrename</command> renames the topmost
  18.446 +	applied patch.  With two arguments, it renames its first
  18.447 +	argument to its second.</para>
  18.448 +
  18.449 +    </sect2>
  18.450 +    <sect2>
  18.451 +      <title><command role="hg-ext-mq">qseries</command>&emdash;print
  18.452 +	the entire patch series</title>
  18.453 +
  18.454 +      <para id="x_62a">The <command role="hg-ext-mq">qseries</command> command
  18.455 +	prints the entire patch series from the <filename
  18.456 +	  role="special">series</filename> file.  It prints only patch
  18.457 +	names, not empty lines or comments.  It prints in order from
  18.458 +	first to be applied to last.</para>
  18.459 +
  18.460 +    </sect2>
  18.461 +    <sect2>
  18.462 +      <title><command role="hg-ext-mq">qtop</command>&emdash;print the
  18.463 +	name of the current patch</title>
  18.464 +
  18.465 +      <para id="x_62b">The <command role="hg-ext-mq">qtop</command> prints the
  18.466 +	name of the topmost currently applied patch.</para>
  18.467 +
  18.468 +    </sect2>
  18.469 +    <sect2>
  18.470 +      <title><command
  18.471 +	  role="hg-ext-mq">qunapplied</command>&emdash;print patches
  18.472 +	not yet applied</title>
  18.473 +
  18.474 +      <para id="x_62c">The <command role="hg-ext-mq">qunapplied</command> command
  18.475 +	prints the names of patches from the <filename
  18.476 +	  role="special">series</filename> file that are not yet
  18.477 +	applied.  It prints them in order from the next patch that
  18.478 +	will be pushed to the last.</para>
  18.479 +
  18.480 +    </sect2>
  18.481 +    <sect2>
  18.482 +      <title><command role="hg-cmd">hg strip</command>&emdash;remove a
  18.483 +	revision and descendants</title>
  18.484 +
  18.485 +      <para id="x_62d">The <command role="hg-cmd">hg strip</command> command
  18.486 +	removes a revision, and all of its descendants, from the
  18.487 +	repository.  It undoes the effects of the removed revisions
  18.488 +	from the repository, and updates the working directory to the
  18.489 +	first parent of the removed revision.</para>
  18.490 +
  18.491 +      <para id="x_62e">The <command role="hg-cmd">hg strip</command> command
  18.492 +	saves a backup of the removed changesets in a bundle, so that
  18.493 +	they can be reapplied if removed in error.</para>
  18.494 +
  18.495 +      <para id="x_62f">Options:</para>
  18.496 +      <itemizedlist>
  18.497 +	<listitem><para id="x_630"><option role="hg-opt-strip">-b</option>: Save
  18.498 +	    unrelated changesets that are intermixed with the stripped
  18.499 +	    changesets in the backup bundle.</para>
  18.500 +	</listitem>
  18.501 +	<listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
  18.502 +	    branch has multiple heads, remove all heads.</para>
  18.503 +	</listitem>
  18.504 +	<listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
  18.505 +	    not save a backup bundle.</para>
  18.506 +	</listitem></itemizedlist>
  18.507 +
  18.508 +    </sect2>
  18.509 +  </sect1>
  18.510 +  <sect1>
  18.511 +    <title>MQ file reference</title>
  18.512 +
  18.513 +    <sect2>
  18.514 +      <title>The <filename role="special">series</filename>
  18.515 +	file</title>
  18.516 +
  18.517 +      <para id="x_633">The <filename role="special">series</filename> file
  18.518 +	contains a list of the names of all patches that MQ can apply.
  18.519 +	It is represented as a list of names, with one name saved per
  18.520 +	line.  Leading and trailing white space in each line are
  18.521 +	ignored.</para>
  18.522 +
  18.523 +      <para id="x_634">Lines may contain comments.  A comment begins with the
  18.524 +	<quote><literal>#</literal></quote> character, and extends to
  18.525 +	the end of the line.  Empty lines, and lines that contain only
  18.526 +	comments, are ignored.</para>
  18.527 +
  18.528 +      <para id="x_635">You will often need to edit the <filename
  18.529 +	  role="special">series</filename> file by hand, hence the
  18.530 +	support for comments and empty lines noted above.  For
  18.531 +	example, you can comment out a patch temporarily, and <command
  18.532 +	  role="hg-ext-mq">qpush</command> will skip over that patch
  18.533 +	when applying patches.  You can also change the order in which
  18.534 +	patches are applied by reordering their entries in the
  18.535 +	<filename role="special">series</filename> file.</para>
  18.536 +
  18.537 +      <para id="x_636">Placing the <filename role="special">series</filename>
  18.538 +	file under revision control is also supported; it is a good
  18.539 +	idea to place all of the patches that it refers to under
  18.540 +	revision control, as well.  If you create a patch directory
  18.541 +	using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
  18.542 +	option to <command role="hg-ext-mq">qinit</command>, this will
  18.543 +	be done for you automatically.</para>
  18.544 +
  18.545 +    </sect2>
  18.546 +    <sect2>
  18.547 +      <title>The <filename role="special">status</filename>
  18.548 +	file</title>
  18.549 +
  18.550 +      <para id="x_637">The <filename role="special">status</filename> file
  18.551 +	contains the names and changeset hashes of all patches that MQ
  18.552 +	currently has applied.  Unlike the <filename
  18.553 +	  role="special">series</filename> file, this file is not
  18.554 +	intended for editing.  You should not place this file under
  18.555 +	revision control, or modify it in any way.  It is used by MQ
  18.556 +	strictly for internal book-keeping.</para>
  18.557 +
  18.558 +    </sect2>
  18.559 +  </sect1>
  18.560 +</appendix>
  18.561 +
  18.562 +<!--
  18.563 +local variables: 
  18.564 +sgml-parent-document: ("00book.xml" "book" "appendix")
  18.565 +end:
  18.566 +-->

    19.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    19.2 +++ b/en/appC-srcinstall.xml	Sun Aug 16 03:41:39 2009 +0200
    19.3 @@ -0,0 +1,66 @@
    19.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    19.5 +
    19.6 +<appendix id="chap:srcinstall">
    19.7 +  <?dbhtml filename="installing-mercurial-from-source.html"?>
    19.8 +  <title>Installing Mercurial from source</title>
    19.9 +
   19.10 +  <sect1 id="sec:srcinstall:unixlike">
   19.11 +    <title>On a Unix-like system</title>
   19.12 +
   19.13 +    <para id="x_5e0">If you are using a Unix-like system that has a sufficiently
   19.14 +      recent version of Python (2.3 or newer) available, it is easy to
   19.15 +      install Mercurial from source.</para>
   19.16 +    <orderedlist>
   19.17 +      <listitem><para id="x_5e1">Download a recent source tarball from <ulink
   19.18 +	    url="http://www.selenic.com/mercurial/download">http://www.selenic.com/mercurial/download</ulink>.</para>
   19.19 +      </listitem>
   19.20 +      <listitem><para id="x_5e2">Unpack the tarball:</para>
   19.21 +	<programlisting>gzip -dc mercurial-MYVERSION.tar.gz | tar xf -</programlisting>
   19.22 +      </listitem>
   19.23 +      <listitem><para id="x_5e3">Go into the source directory and run the
   19.24 +	  installer script.  This will build Mercurial and install it
   19.25 +	  in your home directory.</para>
   19.26 +	<programlisting>cd mercurial-MYVERSION
   19.27 +python setup.py install --force --home=$HOME</programlisting>
   19.28 +      </listitem>
   19.29 +    </orderedlist>
   19.30 +    <para id="x_5e4">Once the install finishes, Mercurial will be in the
   19.31 +      <literal>bin</literal> subdirectory of your home directory.
   19.32 +      Don't forget to make sure that this directory is present in your
   19.33 +      shell's search path.</para>
   19.34 +
   19.35 +    <para id="x_5e5">You will probably need to set the <envar>PYTHONPATH</envar>
   19.36 +      environment variable so that the Mercurial executable can find
   19.37 +      the rest of the Mercurial packages.  For example, on my laptop,
   19.38 +      I have set it to <literal>/home/bos/lib/python</literal>.  The
   19.39 +      exact path that you will need to use depends on how Python was
   19.40 +      built for your system, but should be easy to figure out.  If
   19.41 +      you're uncertain, look through the output of the installer
   19.42 +      script above, and see where the contents of the
   19.43 +      <literal>mercurial</literal> directory were installed to.</para>
   19.44 +
   19.45 +  </sect1>
   19.46 +  <sect1>
   19.47 +    <title>On Windows</title>
   19.48 +
   19.49 +    <para id="x_5e6">Building and installing Mercurial on Windows requires a
   19.50 +      variety of tools, a fair amount of technical knowledge, and
   19.51 +      considerable patience.  I very much <emphasis>do not
   19.52 +	recommend</emphasis> this route if you are a <quote>casual
   19.53 +	user</quote>.  Unless you intend to hack on Mercurial, I
   19.54 +      strongly suggest that you use a binary package instead.</para>
   19.55 +
   19.56 +    <para id="x_5e7">If you are intent on building Mercurial from source on
   19.57 +      Windows, follow the <quote>hard way</quote> directions on the
   19.58 +      Mercurial wiki at <ulink
   19.59 +	url="http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall">http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall</ulink>, 
   19.60 +      and expect the process to involve a lot of fiddly work.</para>
   19.61 +
   19.62 +  </sect1>
   19.63 +</appendix>
   19.64 +
   19.65 +<!--
   19.66 +local variables: 
   19.67 +sgml-parent-document: ("00book.xml" "book" "appendix")
   19.68 +end:
   19.69 +-->

    20.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    20.2 +++ b/en/appD-license.xml	Sun Aug 16 03:41:39 2009 +0200
    20.3 @@ -0,0 +1,179 @@
    20.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    20.5 +
    20.6 +<appendix id="cha:opl">
    20.7 +  <?dbhtml filename="open-publication-license.html"?>
    20.8 +  <title>Open Publication License</title>
    20.9 +
   20.10 +  <para id="x_638">Version 1.0, 8 June 1999</para>
   20.11 +
   20.12 +  <sect1>
   20.13 +    <title>Requirements on both unmodified and modified
   20.14 +      versions</title>
   20.15 +
   20.16 +    <para id="x_639">The Open Publication works may be reproduced and distributed
   20.17 +      in whole or in part, in any medium physical or electronic,
   20.18 +      provided that the terms of this license are adhered to, and that
   20.19 +      this license or an incorporation of it by reference (with any
   20.20 +      options elected by the author(s) and/or publisher) is displayed
   20.21 +      in the reproduction.</para>
   20.22 +
   20.23 +    <para id="x_63a">Proper form for an incorporation by reference is as
   20.24 +      follows:</para>
   20.25 +
   20.26 +    <blockquote>
   20.27 +      <para id="x_63b">  Copyright (c) <emphasis>year</emphasis> by
   20.28 +	<emphasis>author's name or designee</emphasis>. This material
   20.29 +	may be distributed only subject to the terms and conditions
   20.30 +	set forth in the Open Publication License,
   20.31 +	v<emphasis>x.y</emphasis> or later (the latest version is
   20.32 +	presently available at <ulink
   20.33 +	  url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
   20.34 +    </blockquote>
   20.35 +
   20.36 +    <para id="x_63c">The reference must be immediately followed with any options
   20.37 +      elected by the author(s) and/or publisher of the document (see
   20.38 +      <xref linkend="sec:opl:options"/>).</para>
   20.39 +
   20.40 +    <para id="x_63d">Commercial redistribution of Open Publication-licensed
   20.41 +      material is permitted.</para>
   20.42 +
   20.43 +    <para id="x_63e">Any publication in standard (paper) book form shall require
   20.44 +      the citation of the original publisher and author. The publisher
   20.45 +      and author's names shall appear on all outer surfaces of the
   20.46 +      book. On all outer surfaces of the book the original publisher's
   20.47 +      name shall be as large as the title of the work and cited as
   20.48 +      possessive with respect to the title.</para>
   20.49 +
   20.50 +  </sect1>
   20.51 +  <sect1>
   20.52 +    <title>Copyright</title>
   20.53 +
   20.54 +    <para id="x_63f">The copyright to each Open Publication is owned by its
   20.55 +      author(s) or designee.</para>
   20.56 +
   20.57 +  </sect1>
   20.58 +  <sect1>
   20.59 +    <title>Scope of license</title>
   20.60 +
   20.61 +    <para id="x_640">The following license terms apply to all Open Publication
   20.62 +      works, unless otherwise explicitly stated in the
   20.63 +      document.</para>
   20.64 +
   20.65 +    <para id="x_641">Mere aggregation of Open Publication works or a portion of
   20.66 +      an Open Publication work with other works or programs on the
   20.67 +      same media shall not cause this license to apply to those other
   20.68 +      works. The aggregate work shall contain a notice specifying the
   20.69 +      inclusion of the Open Publication material and appropriate
   20.70 +      copyright notice.</para>
   20.71 +
   20.72 +    <para id="x_642"><emphasis role="bold">Severability</emphasis>. If any part
   20.73 +      of this license is found to be unenforceable in any
   20.74 +      jurisdiction, the remaining portions of the license remain in
   20.75 +      force.</para>
   20.76 +
   20.77 +    <para id="x_643"><emphasis role="bold">No warranty</emphasis>. Open
   20.78 +      Publication works are licensed and provided <quote>as is</quote>
   20.79 +      without warranty of any kind, express or implied, including, but
   20.80 +      not limited to, the implied warranties of merchantability and
   20.81 +      fitness for a particular purpose or a warranty of
   20.82 +      non-infringement.</para>
   20.83 +
   20.84 +  </sect1>
   20.85 +  <sect1>
   20.86 +    <title>Requirements on modified works</title>
   20.87 +
   20.88 +    <para id="x_644">All modified versions of documents covered by this license,
   20.89 +      including translations, anthologies, compilations and partial
   20.90 +      documents, must meet the following requirements:</para>
   20.91 +
   20.92 +    <orderedlist>
   20.93 +      <listitem><para id="x_645">The modified version must be labeled as
   20.94 +	  such.</para>
   20.95 +      </listitem>
   20.96 +      <listitem><para id="x_646">The person making the modifications must be
   20.97 +	  identified and the modifications dated.</para>
   20.98 +      </listitem>
   20.99 +      <listitem><para id="x_647">Acknowledgement of the original author and
  20.100 +	  publisher if applicable must be retained according to normal
  20.101 +	  academic citation practices.</para>
  20.102 +      </listitem>
  20.103 +      <listitem><para id="x_648">The location of the original unmodified document
  20.104 +	  must be identified.</para>
  20.105 +      </listitem>
  20.106 +      <listitem><para id="x_649">The original author's (or authors') name(s) may
  20.107 +	  not be used to assert or imply endorsement of the resulting
  20.108 +	  document without the original author's (or authors')
  20.109 +	  permission.</para>
  20.110 +      </listitem></orderedlist>
  20.111 +
  20.112 +  </sect1>
  20.113 +  <sect1>
  20.114 +    <title>Good-practice recommendations</title>
  20.115 +
  20.116 +    <para id="x_64a">In addition to the requirements of this license, it is
  20.117 +      requested from and strongly recommended of redistributors
  20.118 +      that:</para>
  20.119 +
  20.120 +    <orderedlist>
  20.121 +      <listitem><para id="x_64b">If you are distributing Open Publication works
  20.122 +	  on hardcopy or CD-ROM, you provide email notification to the
  20.123 +	  authors of your intent to redistribute at least thirty days
  20.124 +	  before your manuscript or media freeze, to give the authors
  20.125 +	  time to provide updated documents. This notification should
  20.126 +	  describe modifications, if any, made to the document.</para>
  20.127 +      </listitem>
  20.128 +      <listitem><para id="x_64c">All substantive modifications (including
  20.129 +	  deletions) be either clearly marked up in the document or
  20.130 +	  else described in an attachment to the document.</para>
  20.131 +      </listitem>
  20.132 +      <listitem><para id="x_64d">Finally, while it is not mandatory under this
  20.133 +	  license, it is considered good form to offer a free copy of
  20.134 +	  any hardcopy and CD-ROM expression of an Open
  20.135 +	  Publication-licensed work to its author(s).</para>
  20.136 +      </listitem></orderedlist>
  20.137 +
  20.138 +  </sect1>
  20.139 +  <sect1 id="sec:opl:options">
  20.140 +    <title>License options</title>
  20.141 +
  20.142 +    <para id="x_64e">The author(s) and/or publisher of an Open
  20.143 +      Publication-licensed document may elect certain options by
  20.144 +      appending language to the reference to or copy of the license.
  20.145 +      These options are considered part of the license instance and
  20.146 +      must be included with the license (or its incorporation by
  20.147 +      reference) in derived works.</para>
  20.148 +
  20.149 +    <orderedlist>
  20.150 +      <listitem><para id="x_64f">To prohibit distribution of substantively
  20.151 +	  modified versions without the explicit permission of the
  20.152 +	  author(s). <quote>Substantive modification</quote> is
  20.153 +	  defined as a change to the semantic content of the document,
  20.154 +	  and excludes mere changes in format or typographical
  20.155 +	  corrections.</para>
  20.156 +      </listitem>
  20.157 +      <listitem><para id="x_650">  To accomplish this, add the phrase
  20.158 +	  <quote>Distribution of substantively modified versions of
  20.159 +	    this document is prohibited without the explicit
  20.160 +	    permission of the copyright holder.</quote> to the license
  20.161 +	  reference or copy.</para>
  20.162 +      </listitem>
  20.163 +      <listitem><para id="x_651">To prohibit any publication of this work or
  20.164 +	  derivative works in whole or in part in standard (paper)
  20.165 +	  book form for commercial purposes is prohibited unless prior
  20.166 +	  permission is obtained from the copyright holder.</para>
  20.167 +      </listitem>
  20.168 +      <listitem><para id="x_652">To accomplish this, add the phrase
  20.169 +	  <quote>Distribution of the work or derivative of the work in
  20.170 +	    any standard (paper) book form is prohibited unless prior
  20.171 +	    permission is obtained from the copyright holder.</quote>
  20.172 +	  to the license reference or copy.</para>
  20.173 +      </listitem></orderedlist>
  20.174 +
  20.175 +  </sect1>
  20.176 +</appendix>
  20.177 +
  20.178 +<!--
  20.179 +local variables: 
  20.180 +sgml-parent-document: ("00book.xml" "book" "appendix")
  20.181 +end:
  20.182 +-->

    21.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    21.2 +++ b/en/autoid.py	Sun Aug 16 03:41:39 2009 +0200
    21.3 @@ -0,0 +1,47 @@
    21.4 +#!/usr/bin/env python
    21.5 +#
    21.6 +# Add unique ID attributes to para tags.  This script should only be
    21.7 +# run by one person, since otherwise it introduces the possibility of
    21.8 +# chaotic conflicts among tags.
    21.9 +
   21.10 +import glob, os, re, sys
   21.11 +
   21.12 +tagged = re.compile('<para[^>]* id="x_([0-9a-f]+)"[^>]*>', re.M)
   21.13 +untagged = re.compile('<para>')
   21.14 +
   21.15 +names = glob.glob('ch*.xml') + glob.glob('app*.xml')
   21.16 +
   21.17 +# First pass: find the highest-numbered paragraph ID.
   21.18 +
   21.19 +biggest_id = 0
   21.20 +seen = set()
   21.21 +errs = 0
   21.22 +
   21.23 +for name in names:
   21.24 +    for m in tagged.finditer(open(name).read()):
   21.25 +        i = int(m.group(1),16)
   21.26 +        if i in seen:
   21.27 +            print >> sys.stderr, '%s: duplication of ID %s' % (name, i)
   21.28 +            errs += 1
   21.29 +        seen.add(i)
   21.30 +        if i > biggest_id:
   21.31 +            biggest_id = i
   21.32 +
   21.33 +def retag(s):
   21.34 +    global biggest_id
   21.35 +    biggest_id += 1
   21.36 +    return '<para id="x_%x">' % biggest_id
   21.37 +
   21.38 +# Second pass: add IDs to paragraphs that currently lack them.
   21.39 +
   21.40 +for name in names:
   21.41 +    f = open(name).read()
   21.42 +    f1 = untagged.sub(retag, f)
   21.43 +    if f1 != f:
   21.44 +        tmpname = name + '.tmp'
   21.45 +        fp = open(tmpname, 'w')
   21.46 +        fp.write(f1)
   21.47 +        fp.close()
   21.48 +        os.rename(tmpname, name)
   21.49 +
   21.50 +sys.exit(errs)

    22.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    22.2 +++ b/en/book-shortcuts.xml	Sun Aug 16 03:41:39 2009 +0200
    22.3 @@ -0,0 +1,3 @@
    22.4 +<!-- Please keep the contents of this file sorted. -->
    22.5 +
    22.6 +<!ENTITY emdash "&#8212;">

    23.1 --- a/en/bookhtml.cfg	Thu Mar 26 08:57:10 2009 +0100
    23.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    23.3 @@ -1,18 +0,0 @@
    23.4 -% -*- latex -*-
    23.5 -
    23.6 -\Preamble{xhtml}
    23.7 -
    23.8 -% Tex4ht's default definition of lists is complete crap.
    23.9 -% Unfortunately, it can't distinguish between "ul" and "dl" lists.
   23.10 -
   23.11 -\ConfigureList{itemize}%
   23.12 -   {\EndP\HCode{<ul>}\let\endItem=\empty}
   23.13 -   {\ifvmode \IgnorePar\fi
   23.14 -    \EndP\HCode{</li></ul>}\ShowPar}
   23.15 -   {\endItem \def\endItem{\EndP\Tg</span>}\HCode{<li><span class="dt">}}
   23.16 -   {\HCode{</span><span class="dd">}}
   23.17 -\def\textbullet{}
   23.18 -
   23.19 -\begin{document}
   23.20 -
   23.21 -\EndPreamble

    24.1 --- a/en/branch.tex	Thu Mar 26 08:57:10 2009 +0100
    24.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    24.3 @@ -1,392 +0,0 @@
    24.4 -\chapter{Managing releases and branchy development}
    24.5 -\label{chap:branch}
    24.6 -
    24.7 -Mercurial provides several mechanisms for you to manage a project that
    24.8 -is making progress on multiple fronts at once.  To understand these
    24.9 -mechanisms, let's first take a brief look at a fairly normal software
   24.10 -project structure.
   24.11 -
   24.12 -Many software projects issue periodic ``major'' releases that contain
   24.13 -substantial new features.  In parallel, they may issue ``minor''
   24.14 -releases.  These are usually identical to the major releases off which
   24.15 -they're based, but with a few bugs fixed.
   24.16 -
   24.17 -In this chapter, we'll start by talking about how to keep records of
   24.18 -project milestones such as releases.  We'll then continue on to talk
   24.19 -about the flow of work between different phases of a project, and how
   24.20 -Mercurial can help you to isolate and manage this work.
   24.21 -
   24.22 -\section{Giving a persistent name to a revision}
   24.23 -
   24.24 -Once you decide that you'd like to call a particular revision a
   24.25 -``release'', it's a good idea to record the identity of that revision.
   24.26 -This will let you reproduce that release at a later date, for whatever
   24.27 -purpose you might need at the time (reproducing a bug, porting to a
   24.28 -new platform, etc).
   24.29 -\interaction{tag.init}
   24.30 -
   24.31 -Mercurial lets you give a permanent name to any revision using the
   24.32 -\hgcmd{tag} command.  Not surprisingly, these names are called
   24.33 -``tags''.
   24.34 -\interaction{tag.tag}
   24.35 -
   24.36 -A tag is nothing more than a ``symbolic name'' for a revision.  Tags
   24.37 -exist purely for your convenience, so that you have a handy permanent
   24.38 -way to refer to a revision; Mercurial doesn't interpret the tag names
   24.39 -you use in any way.  Neither does Mercurial place any restrictions on
   24.40 -the name of a tag, beyond a few that are necessary to ensure that a
   24.41 -tag can be parsed unambiguously.  A tag name cannot contain any of the
   24.42 -following characters:
   24.43 -\begin{itemize}
   24.44 -\item Colon (ASCII 58, ``\texttt{:}'')
   24.45 -\item Carriage return (ASCII 13, ``\Verb+\r+'')
   24.46 -\item Newline (ASCII 10, ``\Verb+\n+'')
   24.47 -\end{itemize}
   24.48 -
   24.49 -You can use the \hgcmd{tags} command to display the tags present in
   24.50 -your repository.  In the output, each tagged revision is identified
   24.51 -first by its name, then by revision number, and finally by the unique
   24.52 -hash of the revision.  
   24.53 -\interaction{tag.tags}
   24.54 -Notice that \texttt{tip} is listed in the output of \hgcmd{tags}.  The
   24.55 -\texttt{tip} tag is a special ``floating'' tag, which always
   24.56 -identifies the newest revision in the repository.
   24.57 -
   24.58 -In the output of the \hgcmd{tags} command, tags are listed in reverse
   24.59 -order, by revision number.  This usually means that recent tags are
   24.60 -listed before older tags.  It also means that \texttt{tip} is always
   24.61 -going to be the first tag listed in the output of \hgcmd{tags}.
   24.62 -
   24.63 -When you run \hgcmd{log}, if it displays a revision that has tags
   24.64 -associated with it, it will print those tags.
   24.65 -\interaction{tag.log}
   24.66 -
   24.67 -Any time you need to provide a revision~ID to a Mercurial command, the
   24.68 -command will accept a tag name in its place.  Internally, Mercurial
   24.69 -will translate your tag name into the corresponding revision~ID, then
   24.70 -use that.
   24.71 -\interaction{tag.log.v1.0}
   24.72 -
   24.73 -There's no limit on the number of tags you can have in a repository,
   24.74 -or on the number of tags that a single revision can have.  As a
   24.75 -practical matter, it's not a great idea to have ``too many'' (a number
   24.76 -which will vary from project to project), simply because tags are
   24.77 -supposed to help you to find revisions.  If you have lots of tags, the
   24.78 -ease of using them to identify revisions diminishes rapidly.
   24.79 -
   24.80 -For example, if your project has milestones as frequent as every few
   24.81 -days, it's perfectly reasonable to tag each one of those.  But if you
   24.82 -have a continuous build system that makes sure every revision can be
   24.83 -built cleanly, you'd be introducing a lot of noise if you were to tag
   24.84 -every clean build.  Instead, you could tag failed builds (on the
   24.85 -assumption that they're rare!), or simply not use tags to track
   24.86 -buildability.
   24.87 -
   24.88 -If you want to remove a tag that you no longer want, use
   24.89 -\hgcmdargs{tag}{--remove}.  
   24.90 -\interaction{tag.remove}
   24.91 -You can also modify a tag at any time, so that it identifies a
   24.92 -different revision, by simply issuing a new \hgcmd{tag} command.
   24.93 -You'll have to use the \hgopt{tag}{-f} option to tell Mercurial that
   24.94 -you \emph{really} want to update the tag.
   24.95 -\interaction{tag.replace}
   24.96 -There will still be a permanent record of the previous identity of the
   24.97 -tag, but Mercurial will no longer use it.  There's thus no penalty to
   24.98 -tagging the wrong revision; all you have to do is turn around and tag
   24.99 -the correct revision once you discover your error.
  24.100 -
  24.101 -Mercurial stores tags in a normal revision-controlled file in your
  24.102 -repository.  If you've created any tags, you'll find them in a file
  24.103 -named \sfilename{.hgtags}.  When you run the \hgcmd{tag} command,
  24.104 -Mercurial modifies this file, then automatically commits the change to
  24.105 -it.  This means that every time you run \hgcmd{tag}, you'll see a
  24.106 -corresponding changeset in the output of \hgcmd{log}.
  24.107 -\interaction{tag.tip}
  24.108 -
  24.109 -\subsection{Handling tag conflicts during a merge}
  24.110 -
  24.111 -You won't often need to care about the \sfilename{.hgtags} file, but
  24.112 -it sometimes makes its presence known during a merge.  The format of
  24.113 -the file is simple: it consists of a series of lines.  Each line
  24.114 -starts with a changeset hash, followed by a space, followed by the
  24.115 -name of a tag.
  24.116 -
  24.117 -If you're resolving a conflict in the \sfilename{.hgtags} file during
  24.118 -a merge, there's one twist to modifying the \sfilename{.hgtags} file:
  24.119 -when Mercurial is parsing the tags in a repository, it \emph{never}
  24.120 -reads the working copy of the \sfilename{.hgtags} file.  Instead, it
  24.121 -reads the \emph{most recently committed} revision of the file.
  24.122 -
  24.123 -An unfortunate consequence of this design is that you can't actually
  24.124 -verify that your merged \sfilename{.hgtags} file is correct until
  24.125 -\emph{after} you've committed a change.  So if you find yourself
  24.126 -resolving a conflict on \sfilename{.hgtags} during a merge, be sure to
  24.127 -run \hgcmd{tags} after you commit.  If it finds an error in the
  24.128 -\sfilename{.hgtags} file, it will report the location of the error,
  24.129 -which you can then fix and commit.  You should then run \hgcmd{tags}
  24.130 -again, just to be sure that your fix is correct.
  24.131 -
  24.132 -\subsection{Tags and cloning}
  24.133 -
  24.134 -You may have noticed that the \hgcmd{clone} command has a
  24.135 -\hgopt{clone}{-r} option that lets you clone an exact copy of the
  24.136 -repository as of a particular changeset.  The new clone will not
  24.137 -contain any project history that comes after the revision you
  24.138 -specified.  This has an interaction with tags that can surprise the
  24.139 -unwary.
  24.140 -
  24.141 -Recall that a tag is stored as a revision to the \sfilename{.hgtags}
  24.142 -file, so that when you create a tag, the changeset in which it's
  24.143 -recorded necessarily refers to an older changeset.  When you run
  24.144 -\hgcmdargs{clone}{-r foo} to clone a repository as of tag
  24.145 -\texttt{foo}, the new clone \emph{will not contain the history that
  24.146 -  created the tag} that you used to clone the repository.  The result
  24.147 -is that you'll get exactly the right subset of the project's history
  24.148 -in the new repository, but \emph{not} the tag you might have expected.
  24.149 -
  24.150 -\subsection{When permanent tags are too much}
  24.151 -
  24.152 -Since Mercurial's tags are revision controlled and carried around with
  24.153 -a project's history, everyone you work with will see the tags you
  24.154 -create.  But giving names to revisions has uses beyond simply noting
  24.155 -that revision \texttt{4237e45506ee} is really \texttt{v2.0.2}.  If
  24.156 -you're trying to track down a subtle bug, you might want a tag to
  24.157 -remind you of something like ``Anne saw the symptoms with this
  24.158 -revision''.
  24.159 -
  24.160 -For cases like this, what you might want to use are \emph{local} tags.
  24.161 -You can create a local tag with the \hgopt{tag}{-l} option to the
  24.162 -\hgcmd{tag} command.  This will store the tag in a file called
  24.163 -\sfilename{.hg/localtags}.  Unlike \sfilename{.hgtags},
  24.164 -\sfilename{.hg/localtags} is not revision controlled.  Any tags you
  24.165 -create using \hgopt{tag}{-l} remain strictly local to the repository
  24.166 -you're currently working in.
  24.167 -
  24.168 -\section{The flow of changes---big picture vs. little}
  24.169 -
  24.170 -To return to the outline I sketched at the beginning of a chapter,
  24.171 -let's think about a project that has multiple concurrent pieces of
  24.172 -work under development at once.
  24.173 -
  24.174 -There might be a push for a new ``main'' release; a new minor bugfix
  24.175 -release to the last main release; and an unexpected ``hot fix'' to an
  24.176 -old release that is now in maintenance mode.
  24.177 -
  24.178 -The usual way people refer to these different concurrent directions of
  24.179 -development is as ``branches''.  However, we've already seen numerous
  24.180 -times that Mercurial treats \emph{all of history} as a series of
  24.181 -branches and merges.  Really, what we have here is two ideas that are
  24.182 -peripherally related, but which happen to share a name.
  24.183 -\begin{itemize}
  24.184 -\item ``Big picture'' branches represent the sweep of a project's
  24.185 -  evolution; people give them names, and talk about them in
  24.186 -  conversation.
  24.187 -\item ``Little picture'' branches are artefacts of the day-to-day
  24.188 -  activity of developing and merging changes.  They expose the
  24.189 -  narrative of how the code was developed.
  24.190 -\end{itemize}
  24.191 -
  24.192 -\section{Managing big-picture branches in repositories}
  24.193 -
  24.194 -The easiest way to isolate a ``big picture'' branch in Mercurial is in
  24.195 -a dedicated repository.  If you have an existing shared
  24.196 -repository---let's call it \texttt{myproject}---that reaches a ``1.0''
  24.197 -milestone, you can start to prepare for future maintenance releases on
  24.198 -top of version~1.0 by tagging the revision from which you prepared
  24.199 -the~1.0 release.
  24.200 -\interaction{branch-repo.tag}
  24.201 -You can then clone a new shared \texttt{myproject-1.0.1} repository as
  24.202 -of that tag.
  24.203 -\interaction{branch-repo.clone}
  24.204 -
  24.205 -Afterwards, if someone needs to work on a bug fix that ought to go
  24.206 -into an upcoming~1.0.1 minor release, they clone the
  24.207 -\texttt{myproject-1.0.1} repository, make their changes, and push them
  24.208 -back.
  24.209 -\interaction{branch-repo.bugfix}
  24.210 -Meanwhile, development for the next major release can continue,
  24.211 -isolated and unabated, in the \texttt{myproject} repository.
  24.212 -\interaction{branch-repo.new}
  24.213 -
  24.214 -\section{Don't repeat yourself: merging across branches}
  24.215 -
  24.216 -In many cases, if you have a bug to fix on a maintenance branch, the
  24.217 -chances are good that the bug exists on your project's main branch
  24.218 -(and possibly other maintenance branches, too).  It's a rare developer
  24.219 -who wants to fix the same bug multiple times, so let's look at a few
  24.220 -ways that Mercurial can help you to manage these bugfixes without
  24.221 -duplicating your work.
  24.222 -
  24.223 -In the simplest instance, all you need to do is pull changes from your
  24.224 -maintenance branch into your local clone of the target branch.
  24.225 -\interaction{branch-repo.pull}
  24.226 -You'll then need to merge the heads of the two branches, and push back
  24.227 -to the main branch.
  24.228 -\interaction{branch-repo.merge}
  24.229 -
  24.230 -\section{Naming branches within one repository}
  24.231 -
  24.232 -In most instances, isolating branches in repositories is the right
  24.233 -approach.  Its simplicity makes it easy to understand; and so it's
  24.234 -hard to make mistakes.  There's a one-to-one relationship between
  24.235 -branches you're working in and directories on your system.  This lets
  24.236 -you use normal (non-Mercurial-aware) tools to work on files within a
  24.237 -branch/repository.
  24.238 -
  24.239 -If you're more in the ``power user'' category (\emph{and} your
  24.240 -collaborators are too), there is an alternative way of handling
  24.241 -branches that you can consider.  I've already mentioned the
  24.242 -human-level distinction between ``small picture'' and ``big picture''
  24.243 -branches.  While Mercurial works with multiple ``small picture''
  24.244 -branches in a repository all the time (for example after you pull
  24.245 -changes in, but before you merge them), it can \emph{also} work with
  24.246 -multiple ``big picture'' branches.
  24.247 -
  24.248 -The key to working this way is that Mercurial lets you assign a
  24.249 -persistent \emph{name} to a branch.  There always exists a branch
  24.250 -named \texttt{default}.  Even before you start naming branches
  24.251 -yourself, you can find traces of the \texttt{default} branch if you
  24.252 -look for them.
  24.253 -
  24.254 -As an example, when you run the \hgcmd{commit} command, and it pops up
  24.255 -your editor so that you can enter a commit message, look for a line
  24.256 -that contains the text ``\texttt{HG: branch default}'' at the bottom.
  24.257 -This is telling you that your commit will occur on the branch named
  24.258 -\texttt{default}.
  24.259 -
  24.260 -To start working with named branches, use the \hgcmd{branches}
  24.261 -command.  This command lists the named branches already present in
  24.262 -your repository, telling you which changeset is the tip of each.
  24.263 -\interaction{branch-named.branches}
  24.264 -Since you haven't created any named branches yet, the only one that
  24.265 -exists is \texttt{default}.
  24.266 -
  24.267 -To find out what the ``current'' branch is, run the \hgcmd{branch}
  24.268 -command, giving it no arguments.  This tells you what branch the
  24.269 -parent of the current changeset is on.
  24.270 -\interaction{branch-named.branch}
  24.271 -
  24.272 -To create a new branch, run the \hgcmd{branch} command again.  This
  24.273 -time, give it one argument: the name of the branch you want to create.
  24.274 -\interaction{branch-named.create}
  24.275 -
  24.276 -After you've created a branch, you might wonder what effect the
  24.277 -\hgcmd{branch} command has had.  What do the \hgcmd{status} and
  24.278 -\hgcmd{tip} commands report?
  24.279 -\interaction{branch-named.status}
  24.280 -Nothing has changed in the working directory, and there's been no new
  24.281 -history created.  As this suggests, running the \hgcmd{branch} command
  24.282 -has no permanent effect; it only tells Mercurial what branch name to
  24.283 -use the \emph{next} time you commit a changeset.
  24.284 -
  24.285 -When you commit a change, Mercurial records the name of the branch on
  24.286 -which you committed.  Once you've switched from the \texttt{default}
  24.287 -branch to another and committed, you'll see the name of the new branch
  24.288 -show up in the output of \hgcmd{log}, \hgcmd{tip}, and other commands
  24.289 -that display the same kind of output.
  24.290 -\interaction{branch-named.commit}
  24.291 -The \hgcmd{log}-like commands will print the branch name of every
  24.292 -changeset that's not on the \texttt{default} branch.  As a result, if
  24.293 -you never use named branches, you'll never see this information.
  24.294 -
  24.295 -Once you've named a branch and committed a change with that name,
  24.296 -every subsequent commit that descends from that change will inherit
  24.297 -the same branch name.  You can change the name of a branch at any
  24.298 -time, using the \hgcmd{branch} command.  
  24.299 -\interaction{branch-named.rebranch}
  24.300 -In practice, this is something you won't do very often, as branch
  24.301 -names tend to have fairly long lifetimes.  (This isn't a rule, just an
  24.302 -observation.)
  24.303 -
  24.304 -\section{Dealing with multiple named branches in a repository}
  24.305 -
  24.306 -If you have more than one named branch in a repository, Mercurial will
  24.307 -remember the branch that your working directory on when you start a
  24.308 -command like \hgcmd{update} or \hgcmdargs{pull}{-u}.  It will update
  24.309 -the working directory to the tip of this branch, no matter what the
  24.310 -``repo-wide'' tip is.  To update to a revision that's on a different
  24.311 -named branch, you may need to use the \hgopt{update}{-C} option to
  24.312 -\hgcmd{update}.
  24.313 -
  24.314 -This behaviour is a little subtle, so let's see it in action.  First,
  24.315 -let's remind ourselves what branch we're currently on, and what
  24.316 -branches are in our repository.
  24.317 -\interaction{branch-named.parents}
  24.318 -We're on the \texttt{bar} branch, but there also exists an older
  24.319 -\hgcmd{foo} branch.
  24.320 -
  24.321 -We can \hgcmd{update} back and forth between the tips of the
  24.322 -\texttt{foo} and \texttt{bar} branches without needing to use the
  24.323 -\hgopt{update}{-C} option, because this only involves going backwards
  24.324 -and forwards linearly through our change history.
  24.325 -\interaction{branch-named.update-switchy}
  24.326 -
  24.327 -If we go back to the \texttt{foo} branch and then run \hgcmd{update},
  24.328 -it will keep us on \texttt{foo}, not move us to the tip of
  24.329 -\texttt{bar}.
  24.330 -\interaction{branch-named.update-nothing}
  24.331 -
  24.332 -Committing a new change on the \texttt{foo} branch introduces a new
  24.333 -head.
  24.334 -\interaction{branch-named.foo-commit}
  24.335 -
  24.336 -\section{Branch names and merging}
  24.337 -
  24.338 -As you've probably noticed, merges in Mercurial are not symmetrical.
  24.339 -Let's say our repository has two heads, 17 and 23.  If I
  24.340 -\hgcmd{update} to 17 and then \hgcmd{merge} with 23, Mercurial records
  24.341 -17 as the first parent of the merge, and 23 as the second.  Whereas if
  24.342 -I \hgcmd{update} to 23 and then \hgcmd{merge} with 17, it records 23
  24.343 -as the first parent, and 17 as the second.
  24.344 -
  24.345 -This affects Mercurial's choice of branch name when you merge.  After
  24.346 -a merge, Mercurial will retain the branch name of the first parent
  24.347 -when you commit the result of the merge.  If your first parent's
  24.348 -branch name is \texttt{foo}, and you merge with \texttt{bar}, the
  24.349 -branch name will still be \texttt{foo} after you merge.
  24.350 -
  24.351 -It's not unusual for a repository to contain multiple heads, each with
  24.352 -the same branch name.  Let's say I'm working on the \texttt{foo}
  24.353 -branch, and so are you.  We commit different changes; I pull your
  24.354 -changes; I now have two heads, each claiming to be on the \texttt{foo}
  24.355 -branch.  The result of a merge will be a single head on the
  24.356 -\texttt{foo} branch, as you might hope.
  24.357 -
  24.358 -But if I'm working on the \texttt{bar} branch, and I merge work from
  24.359 -the \texttt{foo} branch, the result will remain on the \texttt{bar}
  24.360 -branch.
  24.361 -\interaction{branch-named.merge}
  24.362 -
  24.363 -To give a more concrete example, if I'm working on the
  24.364 -\texttt{bleeding-edge} branch, and I want to bring in the latest fixes
  24.365 -from the \texttt{stable} branch, Mercurial will choose the ``right''
  24.366 -(\texttt{bleeding-edge}) branch name when I pull and merge from
  24.367 -\texttt{stable}.
  24.368 -
  24.369 -\section{Branch naming is generally useful}
  24.370 -
  24.371 -You shouldn't think of named branches as applicable only to situations
  24.372 -where you have multiple long-lived branches cohabiting in a single
  24.373 -repository.  They're very useful even in the one-branch-per-repository
  24.374 -case.  
  24.375 -
  24.376 -In the simplest case, giving a name to each branch gives you a
  24.377 -permanent record of which branch a changeset originated on.  This
  24.378 -gives you more context when you're trying to follow the history of a
  24.379 -long-lived branchy project.
  24.380 -
  24.381 -If you're working with shared repositories, you can set up a
  24.382 -\hook{pretxnchangegroup} hook on each that will block incoming changes
  24.383 -that have the ``wrong'' branch name.  This provides a simple, but
  24.384 -effective, defence against people accidentally pushing changes from a
  24.385 -``bleeding edge'' branch to a ``stable'' branch.  Such a hook might
  24.386 -look like this inside the shared repo's \hgrc.
  24.387 -\begin{codesample2}
  24.388 -  [hooks]
  24.389 -  pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch
  24.390 -\end{codesample2}
  24.391 -
  24.392 -%%% Local Variables: 
  24.393 -%%% mode: latex
  24.394 -%%% TeX-master: "00book"
  24.395 -%%% End: 

    25.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    25.2 +++ b/en/ch00-preface.xml	Sun Aug 16 03:41:39 2009 +0200
    25.3 @@ -0,0 +1,262 @@
    25.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    25.5 +
    25.6 +<preface id="chap:preface">
    25.7 +  <?dbhtml filename="preface.html"?>
    25.8 +  <title>Preface</title>
    25.9 +
   25.10 +  <sect1>
   25.11 +    <title>Technical storytelling</title>
   25.12 +
   25.13 +    <para id="x_72e">A few years ago, when I wanted to explain why I believed
   25.14 +      that distributed revision control is important, the field was
   25.15 +      then so new that there was almost no published literature to
   25.16 +      refer people to.</para>
   25.17 +
   25.18 +    <para id="x_72f">Although at that time I spent some time working on the
   25.19 +      internals of Mercurial itself, I switched to writing this book
   25.20 +      because that seemed like the most effective way to help the
   25.21 +      software to reach a wide audience, along with the idea that
   25.22 +      revision control ought to be distributed in nature.  I publish
   25.23 +      the book online under a liberal license for the same
   25.24 +      reason: to get the word out.</para>
   25.25 +
   25.26 +    <para id="x_730">There's a familiar rhythm to a good software book that
   25.27 +      closely resembles telling a story: What is this thing?  Why does
   25.28 +      it matter?  How will it help me?  How do I use it?  In this
   25.29 +      book, I try to answer those questions for distributed revision
   25.30 +      control in general, and for Mercurial in particular.</para>
   25.31 +  </sect1>
   25.32 +    
   25.33 +  <sect1>
   25.34 +    <title>Thank you for supporting Mercurial</title>
   25.35 +
   25.36 +    <para id="x_731">By purchasing a copy of this book, you are supporting the
   25.37 +      continued development and freedom of Mercurial in particular,
   25.38 +      and of open source and free software in general. O'Reilly Media
   25.39 +      and I are donating my royalties on the sales of this book to the
   25.40 +      Software Freedom Conservancy (<ulink
   25.41 +	url="http://www.softwarefreedom.org/">http://www.softwarefreedom.org/</ulink>) 
   25.42 +      which provides clerical and legal support to Mercurial and a
   25.43 +      number of other prominent and worthy open source software
   25.44 +      projects.</para>
   25.45 +  </sect1>
   25.46 +
   25.47 +  <sect1>
   25.48 +    <title>Acknowledgments</title>
   25.49 +
   25.50 +    <para id="x_732">This book would not exist were it not for the efforts of
   25.51 +      Matt Mackall, the author and project lead of Mercurial.  He is
   25.52 +      ably assisted by hundreds of volunteer contributors across the
   25.53 +      world.</para>
   25.54 +
   25.55 +    <para id="x_733">My children, Cian and Ruairi, always stood ready to help me
   25.56 +      to unwind with wonderful, madcap little-boy games.  I'd also
   25.57 +      like to thank my ex-wife, Shannon, for her support.</para>
   25.58 +
   25.59 +    <para id="x_734">My colleagues and friends provided help and support in
   25.60 +      innumerable ways.  This list of people is necessarily very
   25.61 +      incomplete: Stephen Hahn, Karyn Ritter, Bonnie Corwin, James
   25.62 +      Vasile, Matt Norwood, Eben Moglen, Bradley Kuhn, Robert Walsh,
   25.63 +      Jeremy Fitzhardinge, Rachel Chalmers.</para>
   25.64 +
   25.65 +    <para id="x_735">I developed this book in the open, posting drafts of
   25.66 +      chapters to the book web site as I completed them.  Readers then
   25.67 +      submitted feedback using a web application that I developed.  By
   25.68 +      the time I finished writing the book, more than 100 people had
   25.69 +      submitted comments, an amazing number considering that the
   25.70 +      comment system was live for only about two months towards the
   25.71 +      end of the writing process.</para>
   25.72 +
   25.73 +    <para id="x_736">I would particularly like to recognize the following people,
   25.74 +      who between them contributed over a third of the total number of
   25.75 +      comments.  I would like to thank them for their care and effort
   25.76 +      in providing so much detailed feedback.</para>
   25.77 +
   25.78 +    <para id="x_737">Martin Geisler, Damien Cassou, Alexey Bakhirkin, Till Plewe,
   25.79 +      Dan Himes, Paul Sargent, Gokberk Hamurcu, Matthijs van der
   25.80 +      Vleuten, Michael Chermside, John Mulligan, Jordi Fita, Jon
   25.81 +      Parise.</para>
   25.82 +
   25.83 +    <para id="x_738">I also want to acknowledge the help of the many people who
   25.84 +      caught errors and provided helpful suggestions throughout the
   25.85 +      book.</para>
   25.86 +
   25.87 +    <para id="x_739">Jeremy W. Sherman, Brian Mearns, Vincent Furia, Iwan
   25.88 +      Luijks, Billy Edwards, Andreas Sliwka, Paweł Sołyga, Eric
   25.89 +      Hanchrow, Steve Nicolai, Michał Masłowski, Kevin Fitch, Johan
   25.90 +      Holmberg, Hal Wine, Volker Simonis, Thomas P Jakobsen, Ted
   25.91 +      Stresen-Reuter, Stephen Rasku, Raphael Das Gupta, Ned
   25.92 +      Batchelder, Lou Keeble, Li Linxiao, Kao Cardoso Félix, Joseph
   25.93 +      Wecker, Jon Prescot, Jon Maken, John Yeary, Jason Harris,
   25.94 +      Geoffrey Zheng, Fredrik Jonson, Ed Davies, David Zumbrunnen,
   25.95 +      David Mercer, David Cabana, Ben Karel, Alan Franzoni, Yousry
   25.96 +      Abdallah, Whitney Young, Vinay Sajip, Tom Towle, Tim Ottinger,
   25.97 +      Thomas Schraitle, Tero Saarni, Ted Mielczarek, Svetoslav
   25.98 +      Agafonkin, Shaun Rowland, Rocco Rutte, Polo-Francois Poli,
   25.99 +      Philip Jenvey, Petr Tesałék, Peter R. Annema, Paul Bonser,
  25.100 +      Olivier Scherler, Olivier Fournier, Nick Parker, Nick Fabry,
  25.101 +      Nicholas Guarracino, Mike Driscoll, Mike Coleman, Mietek Bák,
  25.102 +      Michael Maloney, László Nagy, Kent Johnson, Julio Nobrega, Jord
  25.103 +      Fita, Jonathan March, Jonas Nockert, Jim Tittsler, Jeduan
  25.104 +      Cornejo Legorreta, Jan Larres, James Murphy, Henri Wiechers,
  25.105 +      Hagen Möbius, Gábor Farkas, Fabien Engels, Evert Rol, Evan
  25.106 +      Willms, Eduardo Felipe Castegnaro, Dennis Decker Jensen, Deniz
  25.107 +      Dogan, David Smith, Daed Lee, Christine Slotty, Charles Merriam,
  25.108 +      Guillaume Catto, Brian Dorsey, Bob Nystrom, Benoit Boissinot,
  25.109 +      Avi Rosenschein, Andrew Watts, Andrew Donkin, Alexey Rodriguez,
  25.110 +      Ahmed Chaudhary.</para>
  25.111 +  </sect1>
  25.112 +
  25.113 +  <sect1>
  25.114 +    <title>Conventions Used in This Book</title>
  25.115 +
  25.116 +    <para id="x_73a">The following typographical conventions are used in this
  25.117 +      book:</para>
  25.118 +
  25.119 +    <variablelist>
  25.120 +      <varlistentry>
  25.121 +        <term>Italic</term>
  25.122 +
  25.123 +        <listitem>
  25.124 +          <para id="x_73b">Indicates new terms, URLs, email addresses, filenames,
  25.125 +	    and file extensions.</para>
  25.126 +        </listitem>
  25.127 +      </varlistentry>
  25.128 +
  25.129 +      <varlistentry>
  25.130 +        <term><literal>Constant width</literal></term>
  25.131 +
  25.132 +        <listitem>
  25.133 +          <para id="x_73c">Used for program listings, as well as within
  25.134 +	    paragraphs to refer to program elements such as variable
  25.135 +	    or function names, databases, data types, environment
  25.136 +	    variables, statements, and keywords.</para>
  25.137 +        </listitem>
  25.138 +      </varlistentry>
  25.139 +
  25.140 +      <varlistentry>
  25.141 +        <term><userinput>Constant width bold</userinput></term>
  25.142 +
  25.143 +        <listitem>
  25.144 +          <para id="x_73d">Shows commands or other text that should be typed
  25.145 +	    literally by the user.</para>
  25.146 +        </listitem>
  25.147 +      </varlistentry>
  25.148 +
  25.149 +      <varlistentry>
  25.150 +        <term><replaceable>Constant width italic</replaceable></term>
  25.151 +
  25.152 +        <listitem>
  25.153 +          <para id="x_73e">Shows text that should be replaced with user-supplied
  25.154 +	    values or by values determined by context.</para>
  25.155 +        </listitem>
  25.156 +      </varlistentry>
  25.157 +    </variablelist>
  25.158 +
  25.159 +    <tip>
  25.160 +      <para id="x_73f">This icon signifies a tip, suggestion, or general
  25.161 +	note.</para>
  25.162 +    </tip>
  25.163 +
  25.164 +    <caution>
  25.165 +      <para id="x_740">This icon indicates a warning or caution.</para>
  25.166 +    </caution>
  25.167 +  </sect1>
  25.168 +
  25.169 +  <sect1>
  25.170 +    <title>Using Code Examples</title>
  25.171 +
  25.172 +    <para id="x_741">This book is here to help you get your job done. In general,
  25.173 +      you may use the code in this book in your programs and
  25.174 +      documentation. You do not need to contact us for permission
  25.175 +      unless you’re reproducing a significant portion of the code. For
  25.176 +      example, writing a program that uses several chunks of code from
  25.177 +      this book does not require permission. Selling or distributing a
  25.178 +      CD-ROM of examples from O’Reilly books does require permission.
  25.179 +      Answering a question by citing this book and quoting example
  25.180 +      code does not require permission. Incorporating a significant
  25.181 +      amount of example code from this book into your product’s
  25.182 +      documentation does require permission.</para>
  25.183 +
  25.184 +    <para id="x_742">We appreciate, but do not require, attribution. An
  25.185 +      attribution usually includes the title, author, publisher, and
  25.186 +      ISBN. For example: “<emphasis>Book Title</emphasis> by Some
  25.187 +      Author. Copyright 2008 O’Reilly Media, Inc.,
  25.188 +      978-0-596-xxxx-x.”</para>
  25.189 +
  25.190 +    <para id="x_743">If you feel your use of code examples falls outside fair use
  25.191 +      or the permission given above, feel free to contact us at
  25.192 +      <email>permissions@oreilly.com</email>.</para>
  25.193 +  </sect1>
  25.194 +
  25.195 +  <sect1>
  25.196 +    <title>Safari® Books Online</title>
  25.197 +
  25.198 +    <note role="safarienabled">
  25.199 +      <para id="x_744">When you see a Safari® Books Online icon on the cover of
  25.200 +	your favorite technology book, that means the book is
  25.201 +	available online through the O’Reilly Network Safari
  25.202 +	Bookshelf.</para>
  25.203 +    </note>
  25.204 +
  25.205 +    <para id="x_745">Safari offers a solution that’s better than e-books. It’s a
  25.206 +      virtual library that lets you easily search thousands of top
  25.207 +      tech books, cut and paste code samples, download chapters, and
  25.208 +      find quick answers when you need the most accurate, current
  25.209 +      information. Try it for free at <ulink role="orm:hideurl:ital"
  25.210 +	url="http://my.safaribooksonline.com/?portal=oreilly">http://my.safaribooksonline.com</ulink>.</para>
  25.211 +  </sect1>
  25.212 +
  25.213 +  <sect1>
  25.214 +    <title>How to Contact Us</title>
  25.215 +
  25.216 +    <para id="x_746">Please address comments and questions concerning this book
  25.217 +      to the publisher:</para>
  25.218 +
  25.219 +    <simplelist type="vert">
  25.220 +      <member>O’Reilly Media, Inc.</member>
  25.221 +
  25.222 +      <member>1005 Gravenstein Highway North</member>
  25.223 +
  25.224 +      <member>Sebastopol, CA 95472</member>
  25.225 +
  25.226 +      <member>800-998-9938 (in the United States or Canada)</member>
  25.227 +
  25.228 +      <member>707-829-0515 (international or local)</member>
  25.229 +
  25.230 +      <member>707 829-0104 (fax)</member>
  25.231 +    </simplelist>
  25.232 +
  25.233 +    <para id="x_747">We have a web page for this book, where we list errata,
  25.234 +      examples, and any additional information. You can access this
  25.235 +      page at:</para>
  25.236 +
  25.237 +    <simplelist type="vert">
  25.238 +      <member><ulink url="http://www.oreilly.com/catalog/&lt;catalog
  25.239 +	  page&gt;"></ulink></member>
  25.240 +    </simplelist>
  25.241 +
  25.242 +    <remark>Don’t forget to update the &lt;url&gt; attribute,
  25.243 +      too.</remark>
  25.244 +
  25.245 +    <para id="x_748">To comment or ask technical questions about this book, send
  25.246 +      email to:</para>
  25.247 +
  25.248 +    <simplelist type="vert">
  25.249 +      <member><email>bookquestions@oreilly.com</email></member>
  25.250 +    </simplelist>
  25.251 +
  25.252 +    <para id="x_749">For more information about our books, conferences, Resource
  25.253 +      Centers, and the O’Reilly Network, see our web site at:</para>
  25.254 +
  25.255 +    <simplelist type="vert">
  25.256 +      <member><ulink url="http://www.oreilly.com"></ulink></member>
  25.257 +    </simplelist>
  25.258 +  </sect1>
  25.259 +</preface>
  25.260 +
  25.261 +<!--
  25.262 +local variables: 
  25.263 +sgml-parent-document: ("00book.xml" "book" "preface")
  25.264 +end:
  25.265 +-->

    26.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    26.2 +++ b/en/ch01-intro.xml	Sun Aug 16 03:41:39 2009 +0200
    26.3 @@ -0,0 +1,734 @@
    26.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    26.5 +
    26.6 +<chapter id="chap:intro">
    26.7 +  <?dbhtml filename="how-did-we-get-here.html"?>
    26.8 +  <title>How did we get here?</title>
    26.9 +
   26.10 +  <sect1>
   26.11 +    <title>Why revision control? Why Mercurial?</title>
   26.12 +
   26.13 +    <para id="x_6d">Revision control is the process of managing multiple
   26.14 +      versions of a piece of information.  In its simplest form, this
   26.15 +      is something that many people do by hand: every time you modify
   26.16 +      a file, save it under a new name that contains a number, each
   26.17 +      one higher than the number of the preceding version.</para>
   26.18 +
   26.19 +    <para id="x_6e">Manually managing multiple versions of even a single file is
   26.20 +      an error-prone task, though, so software tools to help automate
   26.21 +      this process have long been available.  The earliest automated
   26.22 +      revision control tools were intended to help a single user to
   26.23 +      manage revisions of a single file.  Over the past few decades,
   26.24 +      the scope of revision control tools has expanded greatly; they
   26.25 +      now manage multiple files, and help multiple people to work
   26.26 +      together.  The best modern revision control tools have no
   26.27 +      problem coping with thousands of people working together on
   26.28 +      projects that consist of hundreds of thousands of files.</para>
   26.29 +
   26.30 +    <para id="x_6f">The arrival of distributed revision control is relatively
   26.31 +      recent, and so far this new field has grown due to people's
   26.32 +      willingness to explore ill-charted territory.</para>
   26.33 +
   26.34 +    <para id="x_70">I am writing a book about distributed revision control
   26.35 +      because I believe that it is an important subject that deserves
   26.36 +      a field guide. I chose to write about Mercurial because it is
   26.37 +      the easiest tool to learn the terrain with, and yet it scales to
   26.38 +      the demands of real, challenging environments where many other
   26.39 +      revision control tools buckle.</para>
   26.40 +
   26.41 +    <sect2>
   26.42 +      <title>Why use revision control?</title>
   26.43 +
   26.44 +      <para id="x_71">There are a number of reasons why you or your team might
   26.45 +	want to use an automated revision control tool for a
   26.46 +	project.</para>
   26.47 +
   26.48 +      <itemizedlist>
   26.49 +	<listitem><para id="x_72">It will track the history and evolution of
   26.50 +	    your project, so you don't have to.  For every change,
   26.51 +	    you'll have a log of <emphasis>who</emphasis> made it;
   26.52 +	    <emphasis>why</emphasis> they made it;
   26.53 +	    <emphasis>when</emphasis> they made it; and
   26.54 +	    <emphasis>what</emphasis> the change
   26.55 +	    was.</para></listitem>
   26.56 +	<listitem><para id="x_73">When you're working with other people,
   26.57 +	    revision control software makes it easier for you to
   26.58 +	    collaborate.  For example, when people more or less
   26.59 +	    simultaneously make potentially incompatible changes, the
   26.60 +	    software will help you to identify and resolve those
   26.61 +	    conflicts.</para></listitem>
   26.62 +	<listitem><para id="x_74">It can help you to recover from mistakes.  If
   26.63 +	    you make a change that later turns out to be in error, you
   26.64 +	    can revert to an earlier version of one or more files.  In
   26.65 +	    fact, a <emphasis>really</emphasis> good revision control
   26.66 +	    tool will even help you to efficiently figure out exactly
   26.67 +	    when a problem was introduced (see <xref
   26.68 +	      linkend="sec:undo:bisect"/> for details).</para></listitem>
   26.69 +	<listitem><para id="x_75">It will help you to work simultaneously on,
   26.70 +	    and manage the drift between, multiple versions of your
   26.71 +	    project.</para></listitem>
   26.72 +      </itemizedlist>
   26.73 +
   26.74 +      <para id="x_76">Most of these reasons are equally
   26.75 +	valid&emdash;at least in theory&emdash;whether you're working
   26.76 +	on a project by yourself, or with a hundred other
   26.77 +	people.</para>
   26.78 +
   26.79 +      <para id="x_77">A key question about the practicality of revision control
   26.80 +	at these two different scales (<quote>lone hacker</quote> and
   26.81 +	<quote>huge team</quote>) is how its
   26.82 +	<emphasis>benefits</emphasis> compare to its
   26.83 +	<emphasis>costs</emphasis>.  A revision control tool that's
   26.84 +	difficult to understand or use is going to impose a high
   26.85 +	cost.</para>
   26.86 +
   26.87 +      <para id="x_78">A five-hundred-person project is likely to collapse under
   26.88 +	its own weight almost immediately without a revision control
   26.89 +	tool and process. In this case, the cost of using revision
   26.90 +	control might hardly seem worth considering, since
   26.91 +	<emphasis>without</emphasis> it, failure is almost
   26.92 +	guaranteed.</para>
   26.93 +
   26.94 +      <para id="x_79">On the other hand, a one-person <quote>quick hack</quote>
   26.95 +	might seem like a poor place to use a revision control tool,
   26.96 +	because surely the cost of using one must be close to the
   26.97 +	overall cost of the project.  Right?</para>
   26.98 +
   26.99 +      <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of
  26.100 +	these scales of development.  You can learn the basics in just
  26.101 +	a few minutes, and due to its low overhead, you can apply
  26.102 +	revision control to the smallest of projects with ease.  Its
  26.103 +	simplicity means you won't have a lot of abstruse concepts or
  26.104 +	command sequences competing for mental space with whatever
  26.105 +	you're <emphasis>really</emphasis> trying to do.  At the same
  26.106 +	time, Mercurial's high performance and peer-to-peer nature let
  26.107 +	you scale painlessly to handle large projects.</para>
  26.108 +
  26.109 +      <para id="x_7b">No revision control tool can rescue a poorly run project,
  26.110 +	but a good choice of tools can make a huge difference to the
  26.111 +	fluidity with which you can work on a project.</para>
  26.112 +
  26.113 +    </sect2>
  26.114 +
  26.115 +    <sect2>
  26.116 +      <title>The many names of revision control</title>
  26.117 +
  26.118 +      <para id="x_7c">Revision control is a diverse field, so much so that it is
  26.119 +	referred to by many names and acronyms.  Here are a few of the
  26.120 +	more common variations you'll encounter:</para>
  26.121 +      <itemizedlist>
  26.122 +	<listitem><para id="x_7d">Revision control (RCS)</para></listitem>
  26.123 +	<listitem><para id="x_7e">Software configuration management (SCM), or
  26.124 +	    configuration management</para></listitem>
  26.125 +	<listitem><para id="x_7f">Source code management</para></listitem>
  26.126 +	<listitem><para id="x_80">Source code control, or source
  26.127 +	    control</para></listitem>
  26.128 +	<listitem><para id="x_81">Version control
  26.129 +	    (VCS)</para></listitem></itemizedlist>
  26.130 +      <para id="x_82">Some people claim that these terms actually have different
  26.131 +	meanings, but in practice they overlap so much that there's no
  26.132 +	agreed or even useful way to tease them apart.</para>
  26.133 +
  26.134 +    </sect2>
  26.135 +  </sect1>
  26.136 +
  26.137 +  <sect1>
  26.138 +    <title>About the examples in this book</title>
  26.139 +
  26.140 +    <para id="x_84">This book takes an unusual approach to code samples.  Every
  26.141 +      example is <quote>live</quote>&emdash;each one is actually the result
  26.142 +      of a shell script that executes the Mercurial commands you see.
  26.143 +      Every time an image of the book is built from its sources, all
  26.144 +      the example scripts are automatically run, and their current
  26.145 +      results compared against their expected results.</para>
  26.146 +
  26.147 +    <para id="x_85">The advantage of this approach is that the examples are
  26.148 +      always accurate; they describe <emphasis>exactly</emphasis> the
  26.149 +      behavior of the version of Mercurial that's mentioned at the
  26.150 +      front of the book.  If I update the version of Mercurial that
  26.151 +      I'm documenting, and the output of some command changes, the
  26.152 +      build fails.</para>
  26.153 +
  26.154 +    <para id="x_86">There is a small disadvantage to this approach, which is
  26.155 +      that the dates and times you'll see in examples tend to be
  26.156 +      <quote>squashed</quote> together in a way that they wouldn't be
  26.157 +      if the same commands were being typed by a human.  Where a human
  26.158 +      can issue no more than one command every few seconds, with any
  26.159 +      resulting timestamps correspondingly spread out, my automated
  26.160 +      example scripts run many commands in one second.</para>
  26.161 +
  26.162 +    <para id="x_87">As an instance of this, several consecutive commits in an
  26.163 +      example can show up as having occurred during the same second.
  26.164 +      You can see this occur in the <literal
  26.165 +	role="hg-ext">bisect</literal> example in <xref
  26.166 +	linkend="sec:undo:bisect"/>, for instance.</para>
  26.167 +
  26.168 +    <para id="x_88">So when you're reading examples, don't place too much weight
  26.169 +      on the dates or times you see in the output of commands.  But
  26.170 +      <emphasis>do</emphasis> be confident that the behavior you're
  26.171 +      seeing is consistent and reproducible.</para>
  26.172 +
  26.173 +  </sect1>
  26.174 +
  26.175 +  <sect1>
  26.176 +    <title>Trends in the field</title>
  26.177 +
  26.178 +    <para id="x_89">There has been an unmistakable trend in the development and
  26.179 +      use of revision control tools over the past four decades, as
  26.180 +      people have become familiar with the capabilities of their tools
  26.181 +      and constrained by their limitations.</para>
  26.182 +
  26.183 +    <para id="x_8a">The first generation began by managing single files on
  26.184 +      individual computers.  Although these tools represented a huge
  26.185 +      advance over ad-hoc manual revision control, their locking model
  26.186 +      and reliance on a single computer limited them to small,
  26.187 +      tightly-knit teams.</para>
  26.188 +
  26.189 +    <para id="x_8b">The second generation loosened these constraints by moving
  26.190 +      to network-centered architectures, and managing entire projects
  26.191 +      at a time.  As projects grew larger, they ran into new problems.
  26.192 +      With clients needing to talk to servers very frequently, server
  26.193 +      scaling became an issue for large projects.  An unreliable
  26.194 +      network connection could prevent remote users from being able to
  26.195 +      talk to the server at all.  As open source projects started
  26.196 +      making read-only access available anonymously to anyone, people
  26.197 +      without commit privileges found that they could not use the
  26.198 +      tools to interact with a project in a natural way, as they could
  26.199 +      not record their changes.</para>
  26.200 +
  26.201 +    <para id="x_8c">The current generation of revision control tools is
  26.202 +      peer-to-peer in nature.  All of these systems have dropped the
  26.203 +      dependency on a single central server, and allow people to
  26.204 +      distribute their revision control data to where it's actually
  26.205 +      needed.  Collaboration over the Internet has moved from
  26.206 +      constrained by technology to a matter of choice and consensus.
  26.207 +      Modern tools can operate offline indefinitely and autonomously,
  26.208 +      with a network connection only needed when syncing changes with
  26.209 +      another repository.</para>
  26.210 +
  26.211 +  </sect1>
  26.212 +  <sect1>
  26.213 +    <title>A few of the advantages of distributed revision
  26.214 +      control</title>
  26.215 +
  26.216 +    <para id="x_8d">Even though distributed revision control tools have for
  26.217 +      several years been as robust and usable as their
  26.218 +      previous-generation counterparts, people using older tools have
  26.219 +      not yet necessarily woken up to their advantages.  There are a
  26.220 +      number of ways in which distributed tools shine relative to
  26.221 +      centralised ones.</para>
  26.222 +
  26.223 +    <para id="x_8e">For an individual developer, distributed tools are almost
  26.224 +      always much faster than centralised tools.  This is for a simple
  26.225 +      reason: a centralised tool needs to talk over the network for
  26.226 +      many common operations, because most metadata is stored in a
  26.227 +      single copy on the central server.  A distributed tool stores
  26.228 +      all of its metadata locally.  All else being equal, talking over
  26.229 +      the network adds overhead to a centralised tool.  Don't
  26.230 +      underestimate the value of a snappy, responsive tool: you're
  26.231 +      going to spend a lot of time interacting with your revision
  26.232 +      control software.</para>
  26.233 +
  26.234 +    <para id="x_8f">Distributed tools are indifferent to the vagaries of your
  26.235 +      server infrastructure, again because they replicate metadata to
  26.236 +      so many locations.  If you use a centralised system and your
  26.237 +      server catches fire, you'd better hope that your backup media
  26.238 +      are reliable, and that your last backup was recent and actually
  26.239 +      worked.  With a distributed tool, you have many backups
  26.240 +      available on every contributor's computer.</para>
  26.241 +
  26.242 +    <para id="x_90">The reliability of your network will affect distributed
  26.243 +      tools far less than it will centralised tools.  You can't even
  26.244 +      use a centralised tool without a network connection, except for
  26.245 +      a few highly constrained commands.  With a distributed tool, if
  26.246 +      your network connection goes down while you're working, you may
  26.247 +      not even notice.  The only thing you won't be able to do is talk
  26.248 +      to repositories on other computers, something that is relatively
  26.249 +      rare compared with local operations.  If you have a far-flung
  26.250 +      team of collaborators, this may be significant.</para>
  26.251 +
  26.252 +    <sect2>
  26.253 +      <title>Advantages for open source projects</title>
  26.254 +
  26.255 +      <para id="x_91">If you take a shine to an open source project and decide
  26.256 +	that you would like to start hacking on it, and that project
  26.257 +	uses a distributed revision control tool, you are at once a
  26.258 +	peer with the people who consider themselves the
  26.259 +	<quote>core</quote> of that project.  If they publish their
  26.260 +	repositories, you can immediately copy their project history,
  26.261 +	start making changes, and record your work, using the same
  26.262 +	tools in the same ways as insiders.  By contrast, with a
  26.263 +	centralised tool, you must use the software in a <quote>read
  26.264 +	  only</quote> mode unless someone grants you permission to
  26.265 +	commit changes to their central server.  Until then, you won't
  26.266 +	be able to record changes, and your local modifications will
  26.267 +	be at risk of corruption any time you try to update your
  26.268 +	client's view of the repository.</para>
  26.269 +
  26.270 +      <sect3>
  26.271 +	<title>The forking non-problem</title>
  26.272 +
  26.273 +	<para id="x_92">It has been suggested that distributed revision control
  26.274 +	  tools pose some sort of risk to open source projects because
  26.275 +	  they make it easy to <quote>fork</quote> the development of
  26.276 +	  a project.  A fork happens when there are differences in
  26.277 +	  opinion or attitude between groups of developers that cause
  26.278 +	  them to decide that they can't work together any longer.
  26.279 +	  Each side takes a more or less complete copy of the
  26.280 +	  project's source code, and goes off in its own
  26.281 +	  direction.</para>
  26.282 +
  26.283 +	<para id="x_93">Sometimes the camps in a fork decide to reconcile their
  26.284 +	  differences. With a centralised revision control system, the
  26.285 +	  <emphasis>technical</emphasis> process of reconciliation is
  26.286 +	  painful, and has to be performed largely by hand.  You have
  26.287 +	  to decide whose revision history is going to
  26.288 +	  <quote>win</quote>, and graft the other team's changes into
  26.289 +	  the tree somehow. This usually loses some or all of one
  26.290 +	  side's revision history.</para>
  26.291 +
  26.292 +	<para id="x_94">What distributed tools do with respect to forking is
  26.293 +	  they make forking the <emphasis>only</emphasis> way to
  26.294 +	  develop a project.  Every single change that you make is
  26.295 +	  potentially a fork point.  The great strength of this
  26.296 +	  approach is that a distributed revision control tool has to
  26.297 +	  be really good at <emphasis>merging</emphasis> forks,
  26.298 +	  because forks are absolutely fundamental: they happen all
  26.299 +	  the time.</para>
  26.300 +
  26.301 +	<para id="x_95">If every piece of work that everybody does, all the
  26.302 +	  time, is framed in terms of forking and merging, then what
  26.303 +	  the open source world refers to as a <quote>fork</quote>
  26.304 +	  becomes <emphasis>purely</emphasis> a social issue.  If
  26.305 +	  anything, distributed tools <emphasis>lower</emphasis> the
  26.306 +	  likelihood of a fork:</para>
  26.307 +	<itemizedlist>
  26.308 +	  <listitem><para id="x_96">They eliminate the social distinction that
  26.309 +	      centralised tools impose: that between insiders (people
  26.310 +	      with commit access) and outsiders (people
  26.311 +	      without).</para></listitem>
  26.312 +	  <listitem><para id="x_97">They make it easier to reconcile after a
  26.313 +	      social fork, because all that's involved from the
  26.314 +	      perspective of the revision control software is just
  26.315 +	      another merge.</para></listitem></itemizedlist>
  26.316 +
  26.317 +	<para id="x_98">Some people resist distributed tools because they want
  26.318 +	  to retain tight control over their projects, and they
  26.319 +	  believe that centralised tools give them this control.
  26.320 +	  However, if you're of this belief, and you publish your CVS
  26.321 +	  or Subversion repositories publicly, there are plenty of
  26.322 +	  tools available that can pull out your entire project's
  26.323 +	  history (albeit slowly) and recreate it somewhere that you
  26.324 +	  don't control.  So while your control in this case is
  26.325 +	  illusory, you are forgoing the ability to fluidly
  26.326 +	  collaborate with whatever people feel compelled to mirror
  26.327 +	  and fork your history.</para>
  26.328 +
  26.329 +      </sect3>
  26.330 +    </sect2>
  26.331 +    <sect2>
  26.332 +      <title>Advantages for commercial projects</title>
  26.333 +
  26.334 +      <para id="x_99">Many commercial projects are undertaken by teams that are
  26.335 +	scattered across the globe.  Contributors who are far from a
  26.336 +	central server will see slower command execution and perhaps
  26.337 +	less reliability.  Commercial revision control systems attempt
  26.338 +	to ameliorate these problems with remote-site replication
  26.339 +	add-ons that are typically expensive to buy and cantankerous
  26.340 +	to administer.  A distributed system doesn't suffer from these
  26.341 +	problems in the first place.  Better yet, you can easily set
  26.342 +	up multiple authoritative servers, say one per site, so that
  26.343 +	there's no redundant communication between repositories over
  26.344 +	expensive long-haul network links.</para>
  26.345 +
  26.346 +      <para id="x_9a">Centralised revision control systems tend to have
  26.347 +	relatively low scalability.  It's not unusual for an expensive
  26.348 +	centralised system to fall over under the combined load of
  26.349 +	just a few dozen concurrent users.  Once again, the typical
  26.350 +	response tends to be an expensive and clunky replication
  26.351 +	facility.  Since the load on a central server&emdash;if you have
  26.352 +	one at all&emdash;is many times lower with a distributed tool
  26.353 +	(because all of the data is replicated everywhere), a single
  26.354 +	cheap server can handle the needs of a much larger team, and
  26.355 +	replication to balance load becomes a simple matter of
  26.356 +	scripting.</para>
  26.357 +
  26.358 +      <para id="x_9b">If you have an employee in the field, troubleshooting a
  26.359 +	problem at a customer's site, they'll benefit from distributed
  26.360 +	revision control. The tool will let them generate custom
  26.361 +	builds, try different fixes in isolation from each other, and
  26.362 +	search efficiently through history for the sources of bugs and
  26.363 +	regressions in the customer's environment, all without needing
  26.364 +	to connect to your company's network.</para>
  26.365 +
  26.366 +    </sect2>
  26.367 +  </sect1>
  26.368 +  <sect1>
  26.369 +    <title>Why choose Mercurial?</title>
  26.370 +
  26.371 +    <para id="x_9c">Mercurial has a unique set of properties that make it a
  26.372 +      particularly good choice as a revision control system.</para>
  26.373 +    <itemizedlist>
  26.374 +      <listitem><para id="x_9d">It is easy to learn and use.</para></listitem>
  26.375 +      <listitem><para id="x_9e">It is lightweight.</para></listitem>
  26.376 +      <listitem><para id="x_9f">It scales excellently.</para></listitem>
  26.377 +      <listitem><para id="x_a0">It is easy to
  26.378 +	  customise.</para></listitem></itemizedlist>
  26.379 +
  26.380 +    <para id="x_a1">If you are at all familiar with revision control systems,
  26.381 +      you should be able to get up and running with Mercurial in less
  26.382 +      than five minutes.  Even if not, it will take no more than a few
  26.383 +      minutes longer.  Mercurial's command and feature sets are
  26.384 +      generally uniform and consistent, so you can keep track of a few
  26.385 +      general rules instead of a host of exceptions.</para>
  26.386 +
  26.387 +    <para id="x_a2">On a small project, you can start working with Mercurial in
  26.388 +      moments. Creating new changes and branches; transferring changes
  26.389 +      around (whether locally or over a network); and history and
  26.390 +      status operations are all fast.  Mercurial attempts to stay
  26.391 +      nimble and largely out of your way by combining low cognitive
  26.392 +      overhead with blazingly fast operations.</para>
  26.393 +
  26.394 +    <para id="x_a3">The usefulness of Mercurial is not limited to small
  26.395 +      projects: it is used by projects with hundreds to thousands of
  26.396 +      contributors, each containing tens of thousands of files and
  26.397 +      hundreds of megabytes of source code.</para>
  26.398 +
  26.399 +    <para id="x_a4">If the core functionality of Mercurial is not enough for
  26.400 +      you, it's easy to build on.  Mercurial is well suited to
  26.401 +      scripting tasks, and its clean internals and implementation in
  26.402 +      Python make it easy to add features in the form of extensions.
  26.403 +      There are a number of popular and useful extensions already
  26.404 +      available, ranging from helping to identify bugs to improving
  26.405 +      performance.</para>
  26.406 +
  26.407 +  </sect1>
  26.408 +  <sect1>
  26.409 +    <title>Mercurial compared with other tools</title>
  26.410 +
  26.411 +    <para id="x_a5">Before you read on, please understand that this section
  26.412 +      necessarily reflects my own experiences, interests, and (dare I
  26.413 +      say it) biases.  I have used every one of the revision control
  26.414 +      tools listed below, in most cases for several years at a
  26.415 +      time.</para>
  26.416 +
  26.417 +
  26.418 +    <sect2>
  26.419 +      <title>Subversion</title>
  26.420 +
  26.421 +      <para id="x_a6">Subversion is a popular revision control tool, developed
  26.422 +	to replace CVS.  It has a centralised client/server
  26.423 +	architecture.</para>
  26.424 +
  26.425 +      <para id="x_a7">Subversion and Mercurial have similarly named commands for
  26.426 +	performing the same operations, so if you're familiar with
  26.427 +	one, it is easy to learn to use the other.  Both tools are
  26.428 +	portable to all popular operating systems.</para>
  26.429 +
  26.430 +      <para id="x_a8">Prior to version 1.5, Subversion had no useful support for
  26.431 +	merges. At the time of writing, its merge tracking capability
  26.432 +	is new, and known to be <ulink
  26.433 +	  url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 
  26.434 +	  and buggy</ulink>.</para>
  26.435 +
  26.436 +      <para id="x_a9">Mercurial has a substantial performance advantage over
  26.437 +	Subversion on every revision control operation I have
  26.438 +	benchmarked.  I have measured its advantage as ranging from a
  26.439 +	factor of two to a factor of six when compared with Subversion
  26.440 +	1.4.3's <emphasis>ra_local</emphasis> file store, which is the
  26.441 +	fastest access method available.  In more realistic
  26.442 +	deployments involving a network-based store, Subversion will
  26.443 +	be at a substantially larger disadvantage.  Because many
  26.444 +	Subversion commands must talk to the server and Subversion
  26.445 +	does not have useful replication facilities, server capacity
  26.446 +	and network bandwidth become bottlenecks for modestly large
  26.447 +	projects.</para>
  26.448 +
  26.449 +      <para id="x_aa">Additionally, Subversion incurs substantial storage
  26.450 +	overhead to avoid network transactions for a few common
  26.451 +	operations, such as finding modified files
  26.452 +	(<literal>status</literal>) and displaying modifications
  26.453 +	against the current revision (<literal>diff</literal>).  As a
  26.454 +	result, a Subversion working copy is often the same size as,
  26.455 +	or larger than, a Mercurial repository and working directory,
  26.456 +	even though the Mercurial repository contains a complete
  26.457 +	history of the project.</para>
  26.458 +
  26.459 +      <para id="x_ab">Subversion is widely supported by third party tools.
  26.460 +	Mercurial currently lags considerably in this area.  This gap
  26.461 +	is closing, however, and indeed some of Mercurial's GUI tools
  26.462 +	now outshine their Subversion equivalents.  Like Mercurial,
  26.463 +	Subversion has an excellent user manual.</para>
  26.464 +
  26.465 +      <para id="x_ac">Because Subversion doesn't store revision history on the
  26.466 +	client, it is well suited to managing projects that deal with
  26.467 +	lots of large, opaque binary files.  If you check in fifty
  26.468 +	revisions to an incompressible 10MB file, Subversion's
  26.469 +	client-side space usage stays constant The space used by any
  26.470 +	distributed SCM will grow rapidly in proportion to the number
  26.471 +	of revisions, because the differences between each revision
  26.472 +	are large.</para>
  26.473 +
  26.474 +      <para id="x_ad">In addition, it's often difficult or, more usually,
  26.475 +	impossible to merge different versions of a binary file.
  26.476 +	Subversion's ability to let a user lock a file, so that they
  26.477 +	temporarily have the exclusive right to commit changes to it,
  26.478 +	can be a significant advantage to a project where binary files
  26.479 +	are widely used.</para>
  26.480 +
  26.481 +      <para id="x_ae">Mercurial can import revision history from a Subversion
  26.482 +	repository. It can also export revision history to a
  26.483 +	Subversion repository.  This makes it easy to <quote>test the
  26.484 +	  waters</quote> and use Mercurial and Subversion in parallel
  26.485 +	before deciding to switch.  History conversion is incremental,
  26.486 +	so you can perform an initial conversion, then small
  26.487 +	additional conversions afterwards to bring in new
  26.488 +	changes.</para>
  26.489 +
  26.490 +
  26.491 +    </sect2>
  26.492 +    <sect2>
  26.493 +      <title>Git</title>
  26.494 +
  26.495 +      <para id="x_af">Git is a distributed revision control tool that was
  26.496 +	developed for managing the Linux kernel source tree.  Like
  26.497 +	Mercurial, its early design was somewhat influenced by
  26.498 +	Monotone.</para>
  26.499 +
  26.500 +      <para id="x_b0">Git has a very large command set, with version 1.5.0
  26.501 +	providing 139 individual commands.  It has something of a
  26.502 +	reputation for being difficult to learn.  Compared to Git,
  26.503 +	Mercurial has a strong focus on simplicity.</para>
  26.504 +
  26.505 +      <para id="x_b1">In terms of performance, Git is extremely fast.  In
  26.506 +	several cases, it is faster than Mercurial, at least on Linux,
  26.507 +	while Mercurial performs better on other operations.  However,
  26.508 +	on Windows, the performance and general level of support that
  26.509 +	Git provides is, at the time of writing, far behind that of
  26.510 +	Mercurial.</para>
  26.511 +
  26.512 +      <para id="x_b2">While a Mercurial repository needs no maintenance, a Git
  26.513 +	repository requires frequent manual <quote>repacks</quote> of
  26.514 +	its metadata.  Without these, performance degrades, while
  26.515 +	space usage grows rapidly.  A server that contains many Git
  26.516 +	repositories that are not rigorously and frequently repacked
  26.517 +	will become heavily disk-bound during backups, and there have
  26.518 +	been instances of daily backups taking far longer than 24
  26.519 +	hours as a result.  A freshly packed Git repository is
  26.520 +	slightly smaller than a Mercurial repository, but an unpacked
  26.521 +	repository is several orders of magnitude larger.</para>
  26.522 +
  26.523 +      <para id="x_b3">The core of Git is written in C.  Many Git commands are
  26.524 +	implemented as shell or Perl scripts, and the quality of these
  26.525 +	scripts varies widely. I have encountered several instances
  26.526 +	where scripts charged along blindly in the presence of errors
  26.527 +	that should have been fatal.</para>
  26.528 +
  26.529 +      <para id="x_b4">Mercurial can import revision history from a Git
  26.530 +	repository.</para>
  26.531 +
  26.532 +
  26.533 +    </sect2>
  26.534 +    <sect2>
  26.535 +      <title>CVS</title>
  26.536 +
  26.537 +      <para id="x_b5">CVS is probably the most widely used revision control tool
  26.538 +	in the world.  Due to its age and internal untidiness, it has
  26.539 +	been only lightly maintained for many years.</para>
  26.540 +
  26.541 +      <para id="x_b6">It has a centralised client/server architecture.  It does
  26.542 +	not group related file changes into atomic commits, making it
  26.543 +	easy for people to <quote>break the build</quote>: one person
  26.544 +	can successfully commit part of a change and then be blocked
  26.545 +	by the need for a merge, causing other people to see only a
  26.546 +	portion of the work they intended to do.  This also affects
  26.547 +	how you work with project history.  If you want to see all of
  26.548 +	the modifications someone made as part of a task, you will
  26.549 +	need to manually inspect the descriptions and timestamps of
  26.550 +	the changes made to each file involved (if you even know what
  26.551 +	those files were).</para>
  26.552 +
  26.553 +      <para id="x_b7">CVS has a muddled notion of tags and branches that I will
  26.554 +	not attempt to even describe.  It does not support renaming of
  26.555 +	files or directories well, making it easy to corrupt a
  26.556 +	repository.  It has almost no internal consistency checking
  26.557 +	capabilities, so it is usually not even possible to tell
  26.558 +	whether or how a repository is corrupt.  I would not recommend
  26.559 +	CVS for any project, existing or new.</para>
  26.560 +
  26.561 +      <para id="x_b8">Mercurial can import CVS revision history.  However, there
  26.562 +	are a few caveats that apply; these are true of every other
  26.563 +	revision control tool's CVS importer, too.  Due to CVS's lack
  26.564 +	of atomic changes and unversioned filesystem hierarchy, it is
  26.565 +	not possible to reconstruct CVS history completely accurately;
  26.566 +	some guesswork is involved, and renames will usually not show
  26.567 +	up.  Because a lot of advanced CVS administration has to be
  26.568 +	done by hand and is hence error-prone, it's common for CVS
  26.569 +	importers to run into multiple problems with corrupted
  26.570 +	repositories (completely bogus revision timestamps and files
  26.571 +	that have remained locked for over a decade are just two of
  26.572 +	the less interesting problems I can recall from personal
  26.573 +	experience).</para>
  26.574 +
  26.575 +      <para id="x_b9">Mercurial can import revision history from a CVS
  26.576 +	repository.</para>
  26.577 +
  26.578 +
  26.579 +    </sect2>
  26.580 +    <sect2>
  26.581 +      <title>Commercial tools</title>
  26.582 +
  26.583 +      <para id="x_ba">Perforce has a centralised client/server architecture,
  26.584 +	with no client-side caching of any data.  Unlike modern
  26.585 +	revision control tools, Perforce requires that a user run a
  26.586 +	command to inform the server about every file they intend to
  26.587 +	edit.</para>
  26.588 +
  26.589 +      <para id="x_bb">The performance of Perforce is quite good for small teams,
  26.590 +	but it falls off rapidly as the number of users grows beyond a
  26.591 +	few dozen. Modestly large Perforce installations require the
  26.592 +	deployment of proxies to cope with the load their users
  26.593 +	generate.</para>
  26.594 +
  26.595 +
  26.596 +    </sect2>
  26.597 +    <sect2>
  26.598 +      <title>Choosing a revision control tool</title>
  26.599 +
  26.600 +      <para id="x_bc">With the exception of CVS, all of the tools listed above
  26.601 +	have unique strengths that suit them to particular styles of
  26.602 +	work.  There is no single revision control tool that is best
  26.603 +	in all situations.</para>
  26.604 +
  26.605 +      <para id="x_bd">As an example, Subversion is a good choice for working
  26.606 +	with frequently edited binary files, due to its centralised
  26.607 +	nature and support for file locking.</para>
  26.608 +
  26.609 +      <para id="x_be">I personally find Mercurial's properties of simplicity,
  26.610 +	performance, and good merge support to be a compelling
  26.611 +	combination that has served me well for several years.</para>
  26.612 +
  26.613 +
  26.614 +    </sect2>
  26.615 +  </sect1>
  26.616 +  <sect1>
  26.617 +    <title>Switching from another tool to Mercurial</title>
  26.618 +
  26.619 +    <para id="x_bf">Mercurial is bundled with an extension named <literal
  26.620 +	role="hg-ext">convert</literal>, which can incrementally
  26.621 +      import revision history from several other revision control
  26.622 +      tools.  By <quote>incremental</quote>, I mean that you can
  26.623 +      convert all of a project's history to date in one go, then rerun
  26.624 +      the conversion later to obtain new changes that happened after
  26.625 +      the initial conversion.</para>
  26.626 +
  26.627 +    <para id="x_c0">The revision control tools supported by <literal
  26.628 +	role="hg-ext">convert</literal> are as follows:</para>
  26.629 +    <itemizedlist>
  26.630 +      <listitem><para id="x_c1">Subversion</para></listitem>
  26.631 +      <listitem><para id="x_c2">CVS</para></listitem>
  26.632 +      <listitem><para id="x_c3">Git</para></listitem>
  26.633 +      <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist>
  26.634 +
  26.635 +    <para id="x_c5">In addition, <literal role="hg-ext">convert</literal> can
  26.636 +      export changes from Mercurial to Subversion.  This makes it
  26.637 +      possible to try Subversion and Mercurial in parallel before
  26.638 +      committing to a switchover, without risking the loss of any
  26.639 +      work.</para>
  26.640 +
  26.641 +    <para id="x_c6">The <command role="hg-ext-convert">convert</command> command
  26.642 +      is easy to use.  Simply point it at the path or URL of the
  26.643 +      source repository, optionally give it the name of the
  26.644 +      destination repository, and it will start working.  After the
  26.645 +      initial conversion, just run the same command again to import
  26.646 +      new changes.</para>
  26.647 +  </sect1>
  26.648 +
  26.649 +  <sect1>
  26.650 +    <title>A short history of revision control</title>
  26.651 +
  26.652 +    <para id="x_c7">The best known of the old-time revision control tools is
  26.653 +      SCCS (Source Code Control System), which Marc Rochkind wrote at
  26.654 +      Bell Labs, in the early 1970s.  SCCS operated on individual
  26.655 +      files, and required every person working on a project to have
  26.656 +      access to a shared workspace on a single system.  Only one
  26.657 +      person could modify a file at any time; arbitration for access
  26.658 +      to files was via locks.  It was common for people to lock files,
  26.659 +      and later forget to unlock them, preventing anyone else from
  26.660 +      modifying those files without the help of an
  26.661 +      administrator.</para>
  26.662 +
  26.663 +    <para id="x_c8">Walter Tichy developed a free alternative to SCCS in the
  26.664 +      early 1980s; he called his program RCS (Revision Control System).
  26.665 +      Like SCCS, RCS required developers to work in a single shared
  26.666 +      workspace, and to lock files to prevent multiple people from
  26.667 +      modifying them simultaneously.</para>
  26.668 +
  26.669 +    <para id="x_c9">Later in the 1980s, Dick Grune used RCS as a building block
  26.670 +      for a set of shell scripts he initially called cmt, but then
  26.671 +      renamed to CVS (Concurrent Versions System).  The big innovation
  26.672 +      of CVS was that it let developers work simultaneously and
  26.673 +      somewhat independently in their own personal workspaces.  The
  26.674 +      personal workspaces prevented developers from stepping on each
  26.675 +      other's toes all the time, as was common with SCCS and RCS. Each
  26.676 +      developer had a copy of every project file, and could modify
  26.677 +      their copies independently.  They had to merge their edits prior
  26.678 +      to committing changes to the central repository.</para>
  26.679 +
  26.680 +    <para id="x_ca">Brian Berliner took Grune's original scripts and rewrote
  26.681 +      them in C, releasing in 1989 the code that has since developed
  26.682 +      into the modern version of CVS.  CVS subsequently acquired the
  26.683 +      ability to operate over a network connection, giving it a
  26.684 +      client/server architecture.  CVS's architecture is centralised;
  26.685 +      only the server has a copy of the history of the project. Client
  26.686 +      workspaces just contain copies of recent versions of the
  26.687 +      project's files, and a little metadata to tell them where the
  26.688 +      server is.  CVS has been enormously successful; it is probably
  26.689 +      the world's most widely used revision control system.</para>
  26.690 +
  26.691 +    <para id="x_cb">In the early 1990s, Sun Microsystems developed an early
  26.692 +      distributed revision control system, called TeamWare.  A
  26.693 +      TeamWare workspace contains a complete copy of the project's
  26.694 +      history.  TeamWare has no notion of a central repository.  (CVS
  26.695 +      relied upon RCS for its history storage; TeamWare used
  26.696 +      SCCS.)</para>
  26.697 +
  26.698 +    <para id="x_cc">As the 1990s progressed, awareness grew of a number of
  26.699 +      problems with CVS.  It records simultaneous changes to multiple
  26.700 +      files individually, instead of grouping them together as a
  26.701 +      single logically atomic operation.  It does not manage its file
  26.702 +      hierarchy well; it is easy to make a mess of a repository by
  26.703 +      renaming files and directories.  Worse, its source code is
  26.704 +      difficult to read and maintain, which made the <quote>pain
  26.705 +	level</quote> of fixing these architectural problems
  26.706 +      prohibitive.</para>
  26.707 +
  26.708 +    <para id="x_cd">In 2001, Jim Blandy and Karl Fogel, two developers who had
  26.709 +      worked on CVS, started a project to replace it with a tool that
  26.710 +      would have a better architecture and cleaner code.  The result,
  26.711 +      Subversion, does not stray from CVS's centralised client/server
  26.712 +      model, but it adds multi-file atomic commits, better namespace
  26.713 +      management, and a number of other features that make it a
  26.714 +      generally better tool than CVS. Since its initial release, it
  26.715 +      has rapidly grown in popularity.</para>
  26.716 +
  26.717 +    <para id="x_ce">More or less simultaneously, Graydon Hoare began working on
  26.718 +      an ambitious distributed revision control system that he named
  26.719 +      Monotone. While Monotone addresses many of CVS's design flaws
  26.720 +      and has a peer-to-peer architecture, it goes beyond earlier (and
  26.721 +      subsequent) revision control tools in a number of innovative
  26.722 +      ways.  It uses cryptographic hashes as identifiers, and has an
  26.723 +      integral notion of <quote>trust</quote> for code from different
  26.724 +      sources.</para>
  26.725 +
  26.726 +    <para id="x_cf">Mercurial began life in 2005.  While a few aspects of its
  26.727 +      design are influenced by Monotone, Mercurial focuses on ease of
  26.728 +      use, high performance, and scalability to very large
  26.729 +      projects.</para>
  26.730 +  </sect1>
  26.731 +</chapter>
  26.732 +
  26.733 +<!--
  26.734 +local variables: 
  26.735 +sgml-parent-document: ("00book.xml" "book" "chapter")
  26.736 +end:
  26.737 +-->