1.1 --- a/.hgignore	Fri Jul 21 22:42:19 2006 -0700
     1.2 +++ b/.hgignore	Mon Mar 05 20:16:36 2007 -0800
     1.3 @@ -5,6 +5,7 @@
     1.4  
     1.5  beta/*.tex
     1.6  build_id.tex
     1.7 +*.4[ct][ct]
     1.8  *.aux
     1.9  *.bbl
    1.10  *.bib
    1.11 @@ -20,6 +21,8 @@
    1.12  *.out
    1.13  *.pdf
    1.14  *.png
    1.15 +*.ps
    1.16 +*.run
    1.17  *.tmp
    1.18  *.toc
    1.19  *.xref

     2.1 --- a/en/00book.tex	Fri Jul 21 22:42:19 2006 -0700
     2.2 +++ b/en/00book.tex	Mon Mar 05 20:16:36 2007 -0800
     2.3 @@ -37,15 +37,27 @@
     2.4  
     2.5  \include{preface}
     2.6  \include{intro}
     2.7 +\include{tour-basic}
     2.8 +\include{tour-merge}
     2.9 +\include{concepts}
    2.10 +\include{daily}
    2.11 +\include{filenames}
    2.12 +\include{undo}
    2.13  \include{hook}
    2.14 +\include{template}
    2.15  \include{mq}
    2.16 +\include{mq-collab}
    2.17  
    2.18  \appendix
    2.19 +\include{cmdref}
    2.20 +\include{mq-ref}
    2.21 +\include{srcinstall}
    2.22  \include{license}
    2.23  \addcontentsline{toc}{chapter}{Bibliography}
    2.24  \bibliographystyle{alpha}
    2.25  \bibliography{99book}
    2.26  
    2.27 +\addcontentsline{toc}{chapter}{Index}
    2.28  \printindex
    2.29  
    2.30  \end{document}

     3.1 --- a/en/99book.bib	Fri Jul 21 22:42:19 2006 -0700
     3.2 +++ b/en/99book.bib	Mon Mar 05 20:16:36 2007 -0800
     3.3 @@ -36,7 +36,7 @@
     3.4  @Misc{web:rej,
     3.5    author = 	 {Chris Mason},
     3.6    title = 	 {\texttt{rej}--help solve patch rejects},
     3.7 -  note = 	 {\url{ftp://ftp.suse.com/pub/people/mason/rej/}},
     3.8 +  note = 	 {\url{http://oss.oracle.com/mercurial}},
     3.9  }
    3.10  
    3.11  @Misc{web:wiggle,
    3.12 @@ -45,3 +45,20 @@
    3.13    note = 	 {\url{http://cgi.cse.unsw.edu.au/~neilb/source/wiggle/}},
    3.14  }
    3.15  
    3.16 +@Misc{web:mysql-python,
    3.17 +  author =	 {Andy Dustman},
    3.18 +  title =	 {MySQL for Python},
    3.19 +  note =	 {\url{http://sourceforge.net/projects/mysql-python}},
    3.20 +}
    3.21 +
    3.22 +@Misc{web:changelog,
    3.23 +  author =	 {Richard Stallman, GNU Project volunteers},
    3.24 +  title =	 {GNU Coding Standards---Change Logs},
    3.25 +  note =	 {\url{http://www.gnu.org/prep/standards/html_node/Change-Logs.html}},
    3.26 +}
    3.27 +
    3.28 +@Misc{web:macpython,
    3.29 +  author =	 {Bob Ippolito, Ronald Oussoren},
    3.30 +  title =	 {Universal MacPython},
    3.31 +  note =	 {\url{http://bob.pythonmac.org/archives/2006/04/10/python-and-universal-binaries-on-mac-os-x/}},
    3.32 +}

     4.1 --- a/en/99defs.tex	Fri Jul 21 22:42:19 2006 -0700
     4.2 +++ b/en/99defs.tex	Mon Mar 05 20:16:36 2007 -0800
     4.3 @@ -29,6 +29,16 @@
     4.4  % Mercurial command, with arguments.
     4.5  \newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
     4.6  
     4.7 +\newcommand{\tplkword}[1]{\index{\texttt{#1} template keyword}\index{template keywords!\texttt{#1}}\texttt{#1}}
     4.8 +
     4.9 +\newcommand{\tplkwfilt}[2]{\index{\texttt{#1} template keyword!\texttt{#2}
    4.10 +    filter}\index{template filters!\texttt{#2}}\index{\texttt{#2}
    4.11 +    template filter}\texttt{#2}}
    4.12 +
    4.13 +\newcommand{\tplfilter}[1]{\index{template
    4.14 +    filters!\texttt{#1}}\index{\texttt{#1} template
    4.15 +    filter}\texttt{#1}}
    4.16 +
    4.17  % Shell/system command.
    4.18  \newcommand{\command}[1]{\index{\texttt{#1} command}\texttt{#1}}
    4.19  
    4.20 @@ -55,7 +65,7 @@
    4.21  
    4.22  % Named item in a hgrc file section.
    4.23  \newcommand{\rcitem}[2]{\index{\texttt{hgrc} file!\texttt{#1}
    4.24 -    section!\texttt{#2} entry}\texttt{#1.#2}}
    4.25 +    section!\texttt{#2} entry}\texttt{#2}}
    4.26  
    4.27  % hgrc file.
    4.28  \newcommand{\hgrc}{\index{\texttt{hgrc} file}\texttt{hgrc}}
    4.29 @@ -74,11 +84,18 @@
    4.30  \newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2}
    4.31      class}\texttt{#1.#2}}
    4.32  
    4.33 +% Python function in a module.
    4.34 +\newcommand{\pymodfunc}[2]{\index{\texttt{#1} module!\texttt{#2}
    4.35 +    function}\texttt{#1.#2}}
    4.36 +
    4.37  % Note: blah blah.
    4.38  \newsavebox{\notebox}
    4.39  \newenvironment{note}%
    4.40    {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Note:}\space}%
    4.41    {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
    4.42 +\newenvironment{caution}%
    4.43 +  {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Caution:}\space}%
    4.44 +  {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
    4.45  
    4.46  % Code sample, eating 4 characters of leading space.
    4.47  \DefineVerbatimEnvironment{codesample4}{Verbatim}{frame=single,gobble=4,numbers=left,commandchars=\\\{\}}
    4.48 @@ -89,6 +106,9 @@
    4.49  % Interaction from the examples directory.
    4.50  \newcommand{\interaction}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{examples/#1.out}}
    4.51  
    4.52 +% Example code from the examples directory.
    4.53 +\newcommand{\excode}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{../examples/#1}}
    4.54 +
    4.55  % Graphics inclusion.
    4.56  \ifpdf
    4.57    \newcommand{\grafix}[1]{\includegraphics{#1}}
    4.58 @@ -96,6 +116,15 @@
    4.59    \newcommand{\grafix}[1]{\includegraphics{#1.png}}
    4.60  \fi
    4.61  
    4.62 +% Reference entry for a command.
    4.63 +\newcommand{\cmdref}[2]{\section{\hgcmd{#1}---#2}\label{cmdref:#1}\index{\texttt{#1} command}}
    4.64 +
    4.65 +% Reference entry for a command option with long and short forms.
    4.66 +\newcommand{\optref}[3]{\subsubsection{\hgopt{#1}{--#3}, also \hgopt{#1}{-#2}}}
    4.67 +
    4.68 +% Reference entry for a command option with only long form.
    4.69 +\newcommand{\loptref}[2]{\subsubsection{\hgopt{#1}{--#2} option}}
    4.70 +
    4.71  %%% Local Variables: 
    4.72  %%% mode: latex
    4.73  %%% TeX-master: "00book"

     5.1 --- a/en/Makefile	Fri Jul 21 22:42:19 2006 -0700
     5.2 +++ b/en/Makefile	Mon Mar 05 20:16:36 2007 -0800
     5.3 @@ -1,28 +1,78 @@
     5.4  # This makefile requires GNU make.
     5.5  
     5.6 -hg_id := $(shell hg parents --template '{node|short}\n' | head -1)
     5.7 +hg_id := $(shell hg parents --template '{node|short}\n')
     5.8  
     5.9  sources := \
    5.10  	00book.tex \
    5.11  	99book.bib \
    5.12  	99defs.tex \
    5.13  	build_id.tex \
    5.14 +	cmdref.tex \
    5.15 +	concepts.tex \
    5.16 +	daily.tex \
    5.17 +	filenames.tex \
    5.18  	hook.tex \
    5.19  	intro.tex \
    5.20  	mq.tex \
    5.21 -	preface.tex
    5.22 +	mq-collab.tex \
    5.23 +	mq-ref.tex \
    5.24 +	preface.tex \
    5.25 +	srcinstall.tex \
    5.26 +	template.tex \
    5.27 +	tour-basic.tex \
    5.28 +	tour-merge.tex \
    5.29 +	undo.tex
    5.30  
    5.31  image-sources := \
    5.32 -	mq-stack.svg
    5.33 +	filelog.svg \
    5.34 +	kdiff3.png \
    5.35 +	metadata.svg \
    5.36 +	mq-stack.svg \
    5.37 +	revlog.svg \
    5.38 +	snapshot.svg \
    5.39 +	tour-history.svg \
    5.40 +	tour-merge-conflict.svg \
    5.41 +	tour-merge-merge.svg \
    5.42 +	tour-merge-pull.svg \
    5.43 +	tour-merge-sep-repos.svg \
    5.44 +	undo-manual.dot \
    5.45 +	undo-manual-merge.dot \
    5.46 +	undo-non-tip.dot \
    5.47 +	undo-simple.dot \
    5.48 +	wdir.svg \
    5.49 +	wdir-after-commit.svg \
    5.50 +	wdir-branch.svg \
    5.51 +	wdir-merge.svg \
    5.52 +	wdir-pre-branch.svg
    5.53 +
    5.54 +image-dot := $(filter %.dot,$(image-sources))
    5.55 +image-svg := $(filter %.svg,$(image-sources))
    5.56 +image-png := $(filter %.png,$(image-sources))
    5.57  
    5.58  example-sources := \
    5.59 -	examples/run-example \
    5.60 -	examples/hook.simple \
    5.61 -	examples/mq.qinit-help \
    5.62 -	examples/mq.diff \
    5.63 -	examples/mq.tarball \
    5.64 -	examples/mq.tools \
    5.65 -	examples/mq.tutorial
    5.66 +	backout \
    5.67 +	bisect \
    5.68 +	cmdref \
    5.69 +	daily.copy \
    5.70 +	daily.files \
    5.71 +	daily.rename \
    5.72 +	daily.revert \
    5.73 +	filenames \
    5.74 +	hook.msglen \
    5.75 +	hook.simple \
    5.76 +	hook.ws \
    5.77 +	mq.guards \
    5.78 +	mq.qinit-help \
    5.79 +	mq.dodiff \
    5.80 +	mq.id \
    5.81 +	mq.tarball \
    5.82 +	mq.tools \
    5.83 +	mq.tutorial \
    5.84 +	rollback \
    5.85 +	template.simple \
    5.86 +	template.svnstyle \
    5.87 +	tour \
    5.88 +	tour-merge-conflict
    5.89  
    5.90  latex-options = \
    5.91  	-interaction batchmode \
    5.92 @@ -44,7 +94,9 @@
    5.93  	if grep 'Reference.*undefined' $(@:.pdf=.log); then exit 1; fi
    5.94  endef
    5.95  
    5.96 -pdf/hgbook.pdf: $(sources) $(image-sources:%.svg=%.pdf) examples
    5.97 +image-pdf := $(image-dot:%.dot=%.pdf) $(image-svg:%.svg=%.pdf) $(image-png)
    5.98 +
    5.99 +pdf/hgbook.pdf: $(sources) $(image-pdf) examples
   5.100  	$(call pdf)
   5.101  
   5.102  html: html/onepage/hgbook.html html/split/hgbook.html
   5.103 @@ -69,11 +121,13 @@
   5.104  	perl -pi -e 's/&#x00([0-7][0-9a-f]);/chr(hex($$1))/egi' $(dir $(1))/*.html
   5.105  endef
   5.106  
   5.107 -html/onepage/hgbook.html: $(sources) $(image-sources:%.svg=%.png) examples
   5.108 +image-html := $(image-dot:%.dot=%.png) $(image-svg:%.svg=%.png) $(image-png)
   5.109 +
   5.110 +html/onepage/hgbook.html: $(sources) $(image-html) examples
   5.111  	$(call htlatex,$@,$<)
   5.112  	cp $(image-sources:%.svg=%.png) $(dir $@)
   5.113  
   5.114 -html/split/hgbook.html: $(sources) $(image-sources:%.svg=%.png) examples
   5.115 +html/split/hgbook.html: $(sources) $(image-html) examples
   5.116  	$(call htlatex,$@,$<,2)
   5.117  	cp $(image-sources:%.svg=%.png) $(dir $@)
   5.118  
   5.119 @@ -98,6 +152,9 @@
   5.120  %.png: %.svg
   5.121  	inkscape -D -e $@ $<
   5.122  
   5.123 +%.svg: %.dot
   5.124 +	dot -Tsvg -o $@ $<
   5.125 +
   5.126  # Produce eps & pdf for the pdf
   5.127  
   5.128  %.pdf: %.eps
   5.129 @@ -106,14 +163,24 @@
   5.130  %.eps: %.svg
   5.131  	inkscape -E $@ $<
   5.132  
   5.133 +%.eps: %.dot
   5.134 +	dot -Tps -o $@ $<
   5.135 +
   5.136  examples: examples/.run
   5.137  
   5.138 -examples/.run: $(example-sources)
   5.139 -	cd examples && ./run-example
   5.140 +examples/.run: $(example-sources:%=examples/%.run)
   5.141 +	touch examples/.run
   5.142 +
   5.143 +examples/%.run: examples/% examples/run-example
   5.144 +	cd examples && ./run-example $(notdir $<)
   5.145  
   5.146  build_id.tex: $(wildcard ../.hg/00changelog.[id])
   5.147  	echo -n $(hg_id) > build_id.tex
   5.148  
   5.149  clean:
   5.150 -	rm -rf beta html pdf *.eps *.pdf *.png *.aux *.dvi *.log *.out \
   5.151 -		examples/*.out examples/.run build_id.tex
   5.152 +	rm -rf beta html pdf \
   5.153 +		$(image-dot:%.dot=%.pdf) \
   5.154 +		$(image-dot:%.dot=%.png) \
   5.155 +		$(image-svg:%.svg=%.pdf) \
   5.156 +		$(image-svg:%.svg=%.png) \
   5.157 +		examples/*.{out,run} examples/.run build_id.tex

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/cmdref.py	Mon Mar 05 20:16:36 2007 -0800
     6.3 @@ -0,0 +1,156 @@
     6.4 +#!/usr/bin/env python
     6.5 +
     6.6 +import getopt
     6.7 +import itertools
     6.8 +import os
     6.9 +import re
    6.10 +import sys
    6.11 +
    6.12 +def usage(exitcode):
    6.13 +    print >> sys.stderr, ('usage: %s [-H|--hidden] hg_repo' % 
    6.14 +                          os.path.basename(sys.argv[0]))
    6.15 +    sys.exit(exitcode)
    6.16 +
    6.17 +try:
    6.18 +    opts, args = getopt.getopt(sys.argv[1:], 'AHh?', ['all', 'help', 'hidden'])
    6.19 +    opt_all = False
    6.20 +    opt_hidden = False
    6.21 +    for o, a in opts:
    6.22 +        if o in ('-h', '-?', '--help'):
    6.23 +            usage(0)
    6.24 +        if o in ('-A', '--all'):
    6.25 +            opt_all = True
    6.26 +        if o in ('-H', '--hidden'):
    6.27 +            opt_hidden = True
    6.28 +except getopt.GetoptError, err:
    6.29 +    print >> sys.stderr, 'error:', err
    6.30 +    usage(1)
    6.31 +
    6.32 +try:
    6.33 +    hg_repo, ltx_file = args
    6.34 +except ValueError:
    6.35 +    usage(1)
    6.36 +
    6.37 +if not os.path.isfile(os.path.join(hg_repo, 'mercurial', 'commands.py')):
    6.38 +    print >> sys.stderr, ('error: %r does not contain mercurial code' %
    6.39 +                          hg_repo)
    6.40 +    sys.exit(1)
    6.41 +
    6.42 +sys.path.insert(0, hg_repo)
    6.43 +
    6.44 +from mercurial import commands
    6.45 +
    6.46 +def get_commands():
    6.47 +    seen = {}
    6.48 +    for name, info in sorted(commands.table.iteritems()):
    6.49 +        aliases = name.split('|', 1)
    6.50 +        name = aliases.pop(0).lstrip('^')
    6.51 +        function, options, synopsis = info
    6.52 +        seen[name] = {}
    6.53 +        for shortopt, longopt, arg, desc in options:
    6.54 +            seen[name][longopt] = shortopt
    6.55 +    return seen
    6.56 +
    6.57 +def cmd_filter((name, aliases, options)):
    6.58 +    if opt_all:
    6.59 +        return True
    6.60 +    if opt_hidden:
    6.61 +        return name.startswith('debug')
    6.62 +    return not name.startswith('debug')
    6.63 +
    6.64 +def scan(ltx_file):
    6.65 +    cmdref_re = re.compile(r'^\\cmdref{(?P<cmd>\w+)}')
    6.66 +    optref_re = re.compile(r'^\\l?optref{(?P<cmd>\w+)}'
    6.67 +                           r'(?:{(?P<short>[^}])})?'
    6.68 +                           r'{(?P<long>[^}]+)}')
    6.69 +
    6.70 +    seen = {}
    6.71 +    locs = {}
    6.72 +    for lnum, line in enumerate(open(ltx_file)):
    6.73 +        m = cmdref_re.match(line)
    6.74 +        if m:
    6.75 +            d = m.groupdict()
    6.76 +            cmd = d['cmd']
    6.77 +            seen[cmd] = {}
    6.78 +            locs[cmd] = lnum + 1
    6.79 +            continue
    6.80 +        m = optref_re.match(line)
    6.81 +        if m:
    6.82 +            d = m.groupdict()
    6.83 +            seen[d['cmd']][d['long']] = d['short']
    6.84 +            continue
    6.85 +    return seen, locs
    6.86 +    
    6.87 +documented, locs = scan(ltx_file)
    6.88 +known = get_commands()
    6.89 +
    6.90 +doc_set = set(documented)
    6.91 +known_set = set(known)
    6.92 +
    6.93 +errors = 0
    6.94 +
    6.95 +for nonexistent in sorted(doc_set.difference(known_set)):
    6.96 +    print >> sys.stderr, ('%s:%d: %r command does not exist' %
    6.97 +                          (ltx_file, locs[nonexistent], nonexistent))
    6.98 +    errors += 1
    6.99 +
   6.100 +def optcmp(a, b):
   6.101 +    la, sa = a
   6.102 +    lb, sb = b
   6.103 +    sc = cmp(sa, sb)
   6.104 +    if sc:
   6.105 +        return sc
   6.106 +    return cmp(la, lb)
   6.107 +
   6.108 +for cmd in doc_set.intersection(known_set):
   6.109 +    doc_opts = documented[cmd]
   6.110 +    known_opts = known[cmd]
   6.111 +    
   6.112 +    do_set = set(doc_opts)
   6.113 +    ko_set = set(known_opts)
   6.114 +
   6.115 +    for nonexistent in sorted(do_set.difference(ko_set)):
   6.116 +        print >> sys.stderr, ('%s:%d: %r option to %r command does not exist' %
   6.117 +                              (ltx_file, locs[cmd], nonexistent, cmd))
   6.118 +        errors += 1
   6.119 +
   6.120 +    def mycmp(la, lb):
   6.121 +        sa = known_opts[la]
   6.122 +        sb = known_opts[lb]
   6.123 +        return optcmp((la, sa), (lb, sb))
   6.124 +
   6.125 +    for undocumented in sorted(ko_set.difference(do_set), cmp=mycmp):
   6.126 +        print >> sys.stderr, ('%s:%d: %r option to %r command not documented' %
   6.127 +                              (ltx_file, locs[cmd], undocumented, cmd))
   6.128 +        shortopt = known_opts[undocumented]
   6.129 +        if shortopt:
   6.130 +            print '\optref{%s}{%s}{%s}' % (cmd, shortopt, undocumented)
   6.131 +        else:
   6.132 +            print '\loptref{%s}{%s}' % (cmd, undocumented)
   6.133 +        errors += 1
   6.134 +    sys.stdout.flush()
   6.135 +
   6.136 +if errors:
   6.137 +    sys.exit(1)
   6.138 +
   6.139 +sorted_locs = sorted(locs.iteritems(), key=lambda x:x[1])
   6.140 +
   6.141 +def next_loc(cmd):
   6.142 +    for i, (name, loc) in enumerate(sorted_locs):
   6.143 +        if name >= cmd:
   6.144 +            return sorted_locs[i-1][1] + 1
   6.145 +    return loc
   6.146 +
   6.147 +for undocumented in sorted(known_set.difference(doc_set)):
   6.148 +    print >> sys.stderr, ('%s:%d: %r command not documented' %
   6.149 +                          (ltx_file, next_loc(undocumented), undocumented))
   6.150 +    print '\cmdref{%s}' % undocumented
   6.151 +    for longopt, shortopt in sorted(known[undocumented].items(), cmp=optcmp):
   6.152 +        if shortopt:
   6.153 +            print '\optref{%s}{%s}{%s}' % (undocumented, shortopt, longopt)
   6.154 +        else:
   6.155 +            print '\loptref{%s}{%s}' % (undocumented, longopt)
   6.156 +    sys.stdout.flush()
   6.157 +    errors += 1
   6.158 +
   6.159 +sys.exit(errors and 1 or 0)

     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/en/cmdref.tex	Mon Mar 05 20:16:36 2007 -0800
     7.3 @@ -0,0 +1,176 @@
     7.4 +\chapter{Command reference}
     7.5 +\label{cmdref}
     7.6 +
     7.7 +\cmdref{add}{add files at the next commit}
     7.8 +\optref{add}{I}{include}
     7.9 +\optref{add}{X}{exclude}
    7.10 +\optref{add}{n}{dry-run}
    7.11 +
    7.12 +\cmdref{diff}{print changes in history or working directory}
    7.13 +
    7.14 +Show differences between revisions for the specified files or
    7.15 +directories, using the unified diff format.  For a description of the
    7.16 +unified diff format, see section~\ref{sec:mq:patch}.
    7.17 +
    7.18 +By default, this command does not print diffs for files that Mercurial
    7.19 +considers to contain binary data.  To control this behaviour, see the
    7.20 +\hgopt{diff}{-a} and \hgopt{diff}{--git} options.
    7.21 +
    7.22 +\subsection{Options}
    7.23 +
    7.24 +\loptref{diff}{nodates}
    7.25 +
    7.26 +Omit date and time information when printing diff headers.
    7.27 +
    7.28 +\optref{diff}{B}{ignore-blank-lines}
    7.29 +
    7.30 +Do not print changes that only insert or delete blank lines.  A line
    7.31 +that contains only whitespace is not considered blank.
    7.32 +
    7.33 +\optref{diff}{I}{include}
    7.34 +
    7.35 +Exclude files and directories whose names match the given patterns.
    7.36 +
    7.37 +\optref{diff}{X}{exclude}
    7.38 +
    7.39 +Include files and directories whose names match the given patterns.
    7.40 +
    7.41 +\optref{diff}{a}{text}
    7.42 +
    7.43 +If this option is not specified, \hgcmd{diff} will refuse to print
    7.44 +diffs for files that it detects as binary. Specifying \hgopt{diff}{-a}
    7.45 +forces \hgcmd{diff} to treat all files as text, and generate diffs for
    7.46 +all of them.
    7.47 +
    7.48 +This option is useful for files that are ``mostly text'' but have a
    7.49 +few embedded NUL characters.  If you use it on files that contain a
    7.50 +lot of binary data, its output will be incomprehensible.
    7.51 +
    7.52 +\optref{diff}{b}{ignore-space-change}
    7.53 +
    7.54 +Do not print a line if the only change to that line is in the amount
    7.55 +of white space it contains.
    7.56 +
    7.57 +\optref{diff}{g}{git}
    7.58 +
    7.59 +Print \command{git}-compatible diffs.  XXX reference a format
    7.60 +description.
    7.61 +
    7.62 +\optref{diff}{p}{show-function}
    7.63 +
    7.64 +Display the name of the enclosing function in a hunk header, using a
    7.65 +simple heuristic.  This functionality is enabled by default, so the
    7.66 +\hgopt{diff}{-p} option has no effect unless you change the value of
    7.67 +the \rcitem{diff}{showfunc} config item, as in the following example.
    7.68 +\interaction{cmdref.diff-p}
    7.69 +
    7.70 +\optref{diff}{r}{rev}
    7.71 +
    7.72 +Specify one or more revisions to compare.  The \hgcmd{diff} command
    7.73 +accepts up to two \hgopt{diff}{-r} options to specify the revisions to
    7.74 +compare.
    7.75 +
    7.76 +\begin{enumerate}
    7.77 +\setcounter{enumi}{0}
    7.78 +\item Display the differences between the parent revision of the
    7.79 +  working directory and the working directory.
    7.80 +\item Display the differences between the specified changeset and the
    7.81 +  working directory.
    7.82 +\item Display the differences between the two specified changesets.
    7.83 +\end{enumerate}
    7.84 +
    7.85 +You can specify two revisions using either two \hgopt{diff}{-r}
    7.86 +options or revision range notation.  For example, the two revision
    7.87 +specifications below are equivalent.
    7.88 +\begin{codesample2}
    7.89 +  hg diff -r 10 -r 20
    7.90 +  hg diff -r10:20
    7.91 +\end{codesample2}
    7.92 +
    7.93 +When you provide two revisions, Mercurial treats the order of those
    7.94 +revisions as significant.  Thus, \hgcmdargs{diff}{-r10:20} will
    7.95 +produce a diff that will transform files from their contents as of
    7.96 +revision~10 to their contents as of revision~20, while
    7.97 +\hgcmdargs{diff}{-r20:10} means the opposite: the diff that will
    7.98 +transform files from their revision~20 contents to their revision~10
    7.99 +contents.  You cannot reverse the ordering in this way if you are
   7.100 +diffing against the working directory.
   7.101 +
   7.102 +\optref{diff}{w}{ignore-all-space}
   7.103 +
   7.104 +\cmdref{version}{print version and copyright information}
   7.105 +
   7.106 +This command displays the version of Mercurial you are running, and
   7.107 +its copyright license.  There are four kinds of version string that
   7.108 +you may see.
   7.109 +\begin{itemize}
   7.110 +\item The string ``\texttt{unknown}''. This version of Mercurial was
   7.111 +  not built in a Mercurial repository, and cannot determine its own
   7.112 +  version.
   7.113 +\item A short numeric string, such as ``\texttt{1.1}''. This is a
   7.114 +  build of a revision of Mercurial that was identified by a specific
   7.115 +  tag in the repository where it was built.  (This doesn't necessarily
   7.116 +  mean that you're running an official release; someone else could
   7.117 +  have added that tag to any revision in the repository where they
   7.118 +  built Mercurial.)
   7.119 +\item A hexadecimal string, such as ``\texttt{875489e31abe}''.  This
   7.120 +  is a build of the given revision of Mercurial.
   7.121 +\item A hexadecimal string followed by a date, such as
   7.122 +  ``\texttt{875489e31abe+20070205}''.  This is a build of the given
   7.123 +  revision of Mercurial, where the build repository contained some
   7.124 +  local changes that had not been committed.
   7.125 +\end{itemize}
   7.126 +
   7.127 +\subsection{Tips and tricks}
   7.128 +
   7.129 +\subsubsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
   7.130 +  differ?}
   7.131 +\label{cmdref:diff-vs-status}
   7.132 +
   7.133 +When you run the \hgcmd{status} command, you'll see a list of files
   7.134 +that Mercurial will record changes for the next time you perform a
   7.135 +commit.  If you run the \hgcmd{diff} command, you may notice that it
   7.136 +prints diffs for only a \emph{subset} of the files that \hgcmd{status}
   7.137 +listed.  There are two possible reasons for this.
   7.138 +
   7.139 +The first is that \hgcmd{status} prints some kinds of modifications
   7.140 +that \hgcmd{diff} doesn't normally display.  The \hgcmd{diff} command
   7.141 +normally outputs unified diffs, which don't have the ability to
   7.142 +represent some changes that Mercurial can track.  Most notably,
   7.143 +traditional diffs can't represent a change in whether or not a file is
   7.144 +executable, but Mercurial records this information.
   7.145 +
   7.146 +If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will
   7.147 +display \command{git}-compatible diffs that \emph{can} display this
   7.148 +extra information.
   7.149 +
   7.150 +The second possible reason that \hgcmd{diff} might be printing diffs
   7.151 +for a subset of the files displayed by \hgcmd{status} is that if you
   7.152 +invoke it without any arguments, \hgcmd{diff} prints diffs against the
   7.153 +first parent of the working directory.  If you have run \hgcmd{merge}
   7.154 +to merge two changesets, but you haven't yet committed the results of
   7.155 +the merge, your working directory has two parents (use \hgcmd{parents}
   7.156 +to see them).  While \hgcmd{status} prints modifications relative to
   7.157 +\emph{both} parents after an uncommitted merge, \hgcmd{diff} still
   7.158 +operates relative only to the first parent.  You can get it to print
   7.159 +diffs relative to the second parent by specifying that parent with the
   7.160 +\hgopt{diff}{-r} option.  There is no way to print diffs relative to
   7.161 +both parents.
   7.162 +
   7.163 +\subsubsection{Generating safe binary diffs}
   7.164 +
   7.165 +If you use the \hgopt{diff}{-a} option to force Mercurial to print
   7.166 +diffs of files that are either ``mostly text'' or contain lots of
   7.167 +binary data, those diffs cannot subsequently be applied by either
   7.168 +Mercurial's \hgcmd{import} command or the system's \command{patch}
   7.169 +command.  
   7.170 +
   7.171 +If you want to generate a diff of a binary file that is safe to use as
   7.172 +input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you
   7.173 +generate the patch.  The system \command{patch} command cannot handle
   7.174 +binary patches at all.
   7.175 +
   7.176 +%%% Local Variables: 
   7.177 +%%% mode: latex
   7.178 +%%% TeX-master: "00book"
   7.179 +%%% End: 

     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/en/concepts.tex	Mon Mar 05 20:16:36 2007 -0800
     8.3 @@ -0,0 +1,577 @@
     8.4 +\chapter{Behind the scenes}
     8.5 +\label{chap:concepts}
     8.6 +
     8.7 +Unlike many revision control systems, the concepts upon which
     8.8 +Mercurial is built are simple enough that it's easy to understand how
     8.9 +the software really works.  Knowing this certainly isn't necessary,
    8.10 +but I find it useful to have a ``mental model'' of what's going on.
    8.11 +
    8.12 +This understanding gives me confidence that Mercurial has been
    8.13 +carefully designed to be both \emph{safe} and \emph{efficient}.  And
    8.14 +just as importantly, if it's easy for me to retain a good idea of what
    8.15 +the software is doing when I perform a revision control task, I'm less
    8.16 +likely to be surprised by its behaviour.
    8.17 +
    8.18 +In this chapter, we'll initially cover the core concepts behind
    8.19 +Mercurial's design, then continue to discuss some of the interesting
    8.20 +details of its implementation.
    8.21 +
    8.22 +\section{Mercurial's historical record}
    8.23 +
    8.24 +\subsection{Tracking the history of a single file}
    8.25 +
    8.26 +When Mercurial tracks modifications to a file, it stores the history
    8.27 +of that file in a metadata object called a \emph{filelog}.  Each entry
    8.28 +in the filelog contains enough information to reconstruct one revision
    8.29 +of the file that is being tracked.  Filelogs are stored as files in
    8.30 +the \sdirname{.hg/data} directory.  A filelog contains two kinds of
    8.31 +information: revision data, and an index to help Mercurial to find a
    8.32 +revision efficiently.  
    8.33 +
    8.34 +A file that is large, or has a lot of history, has its filelog stored
    8.35 +in separate data (``\texttt{.d}'' suffix) and index (``\texttt{.i}''
    8.36 +suffix) files.  For small files without much history, the revision
    8.37 +data and index are combined in a single ``\texttt{.i}'' file.  The
    8.38 +correspondence between a file in the working directory and the filelog
    8.39 +that tracks its history in the repository is illustrated in
    8.40 +figure~\ref{fig:concepts:filelog}.
    8.41 +
    8.42 +\begin{figure}[ht]
    8.43 +  \centering
    8.44 +  \grafix{filelog}
    8.45 +  \caption{Relationships between files in working directory and
    8.46 +    filelogs in repository}
    8.47 +  \label{fig:concepts:filelog}
    8.48 +\end{figure}
    8.49 +
    8.50 +\subsection{Managing tracked files}
    8.51 +
    8.52 +Mercurial uses a structure called a \emph{manifest} to collect
    8.53 +together information about the files that it tracks.  Each entry in
    8.54 +the manifest contains information about the files present in a single
    8.55 +changeset.  An entry records which files are present in the changeset,
    8.56 +the revision of each file, and a few other pieces of file metadata.
    8.57 +
    8.58 +\subsection{Recording changeset information}
    8.59 +
    8.60 +The \emph{changelog} contains information about each changeset.  Each
    8.61 +revision records who committed a change, the changeset comment, other
    8.62 +pieces of changeset-related information, and the revision of the
    8.63 +manifest to use.
    8.64 +
    8.65 +\subsection{Relationships between revisions}
    8.66 +
    8.67 +Within a changelog, a manifest, or a filelog, each revision stores a
    8.68 +pointer to its immediate parent (or to its two parents, if it's a
    8.69 +merge revision).  As I mentioned above, there are also relationships
    8.70 +between revisions \emph{across} these structures, and they are
    8.71 +hierarchical in nature.
    8.72 +
    8.73 +For every changeset in a repository, there is exactly one revision
    8.74 +stored in the changelog.  Each revision of the changelog contains a
    8.75 +pointer to a single revision of the manifest.  A revision of the
    8.76 +manifest stores a pointer to a single revision of each filelog tracked
    8.77 +when that changeset was created.  These relationships are illustrated
    8.78 +in figure~\ref{fig:concepts:metadata}.
    8.79 +
    8.80 +\begin{figure}[ht]
    8.81 +  \centering
    8.82 +  \grafix{metadata}
    8.83 +  \caption{Metadata relationships}
    8.84 +  \label{fig:concepts:metadata}
    8.85 +\end{figure}
    8.86 +
    8.87 +As the illustration shows, there is \emph{not} a ``one to one''
    8.88 +relationship between revisions in the changelog, manifest, or filelog.
    8.89 +If the manifest hasn't changed between two changesets, the changelog
    8.90 +entries for those changesets will point to the same revision of the
    8.91 +manifest.  If a file that Mercurial tracks hasn't changed between two
    8.92 +changesets, the entry for that file in the two revisions of the
    8.93 +manifest will point to the same revision of its filelog.
    8.94 +
    8.95 +\section{Safe, efficient storage}
    8.96 +
    8.97 +The underpinnings of changelogs, manifests, and filelogs are provided
    8.98 +by a single structure called the \emph{revlog}.
    8.99 +
   8.100 +\subsection{Efficient storage}
   8.101 +
   8.102 +The revlog provides efficient storage of revisions using a
   8.103 +\emph{delta} mechanism.  Instead of storing a complete copy of a file
   8.104 +for each revision, it stores the changes needed to transform an older
   8.105 +revision into the new revision.  For many kinds of file data, these
   8.106 +deltas are typically a fraction of a percent of the size of a full
   8.107 +copy of a file.
   8.108 +
   8.109 +Some obsolete revision control systems can only work with deltas of
   8.110 +text files.  They must either store binary files as complete snapshots
   8.111 +or encoded into a text representation, both of which are wasteful
   8.112 +approaches.  Mercurial can efficiently handle deltas of files with
   8.113 +arbitrary binary contents; it doesn't need to treat text as special.
   8.114 +
   8.115 +\subsection{Safe operation}
   8.116 +\label{sec:concepts:txn}
   8.117 +
   8.118 +Mercurial only ever \emph{appends} data to the end of a revlog file.
   8.119 +It never modifies a section of a file after it has written it.  This
   8.120 +is both more robust and efficient than schemes that need to modify or
   8.121 +rewrite data.
   8.122 +
   8.123 +In addition, Mercurial treats every write as part of a
   8.124 +\emph{transaction} that can span a number of files.  A transaction is
   8.125 +\emph{atomic}: either the entire transaction succeeds and its effects
   8.126 +are all visible to readers in one go, or the whole thing is undone.
   8.127 +This guarantee of atomicity means that if you're running two copies of
   8.128 +Mercurial, where one is reading data and one is writing it, the reader
   8.129 +will never see a partially written result that might confuse it.
   8.130 +
   8.131 +The fact that Mercurial only appends to files makes it easier to
   8.132 +provide this transactional guarantee.  The easier it is to do stuff
   8.133 +like this, the more confident you should be that it's done correctly.
   8.134 +
   8.135 +\subsection{Fast retrieval}
   8.136 +
   8.137 +Mercurial cleverly avoids a pitfall common to all earlier
   8.138 +revision control systems: the problem of \emph{inefficient retrieval}.
   8.139 +Most revision control systems store the contents of a revision as an
   8.140 +incremental series of modifications against a ``snapshot''.  To
   8.141 +reconstruct a specific revision, you must first read the snapshot, and
   8.142 +then every one of the revisions between the snapshot and your target
   8.143 +revision.  The more history that a file accumulates, the more
   8.144 +revisions you must read, hence the longer it takes to reconstruct a
   8.145 +particular revision.
   8.146 +
   8.147 +\begin{figure}[ht]
   8.148 +  \centering
   8.149 +  \grafix{snapshot}
   8.150 +  \caption{Snapshot of a revlog, with incremental deltas}
   8.151 +  \label{fig:concepts:snapshot}
   8.152 +\end{figure}
   8.153 +
   8.154 +The innovation that Mercurial applies to this problem is simple but
   8.155 +effective.  Once the cumulative amount of delta information stored
   8.156 +since the last snapshot exceeds a fixed threshold, it stores a new
   8.157 +snapshot (compressed, of course), instead of another delta.  This
   8.158 +makes it possible to reconstruct \emph{any} revision of a file
   8.159 +quickly.  This approach works so well that it has since been copied by
   8.160 +several other revision control systems.
   8.161 +
   8.162 +Figure~\ref{fig:concepts:snapshot} illustrates the idea.  In an entry
   8.163 +in a revlog's index file, Mercurial stores the range of entries from
   8.164 +the data file that it must read to reconstruct a particular revision.
   8.165 +
   8.166 +\subsubsection{Aside: the influence of video compression}
   8.167 +
   8.168 +If you're familiar with video compression or have ever watched a TV
   8.169 +feed through a digital cable or satellite service, you may know that
   8.170 +most video compression schemes store each frame of video as a delta
   8.171 +against its predecessor frame.  In addition, these schemes use
   8.172 +``lossy'' compression techniques to increase the compression ratio, so
   8.173 +visual errors accumulate over the course of a number of inter-frame
   8.174 +deltas.
   8.175 +
   8.176 +Because it's possible for a video stream to ``drop out'' occasionally
   8.177 +due to signal glitches, and to limit the accumulation of artefacts
   8.178 +introduced by the lossy compression process, video encoders
   8.179 +periodically insert a complete frame (called a ``key frame'') into the
   8.180 +video stream; the next delta is generated against that frame.  This
   8.181 +means that if the video signal gets interrupted, it will resume once
   8.182 +the next key frame is received.  Also, the accumulation of encoding
   8.183 +errors restarts anew with each key frame.
   8.184 +
   8.185 +\subsection{Identification and strong integrity}
   8.186 +
   8.187 +Along with delta or snapshot information, a revlog entry contains a
   8.188 +cryptographic hash of the data that it represents.  This makes it
   8.189 +difficult to forge the contents of a revision, and easy to detect
   8.190 +accidental corruption.  
   8.191 +
   8.192 +Hashes provide more than a mere check against corruption; they are
   8.193 +used as the identifiers for revisions.  The changeset identification
   8.194 +hashes that you see as an end user are from revisions of the
   8.195 +changelog.  Although filelogs and the manifest also use hashes,
   8.196 +Mercurial only uses these behind the scenes.
   8.197 +
   8.198 +Mercurial verifies that hashes are correct when it retrieves file
   8.199 +revisions and when it pulls changes from another repository.  If it
   8.200 +encounters an integrity problem, it will complain and stop whatever
   8.201 +it's doing.
   8.202 +
   8.203 +In addition to the effect it has on retrieval efficiency, Mercurial's
   8.204 +use of periodic snapshots makes it more robust against partial data
   8.205 +corruption.  If a revlog becomes partly corrupted due to a hardware
   8.206 +error or system bug, it's often possible to reconstruct some or most
   8.207 +revisions from the uncorrupted sections of the revlog, both before and
   8.208 +after the corrupted section.  This would not be possible with a
   8.209 +delta-only storage model.
   8.210 +
   8.211 +\section{Revision history, branching,
   8.212 +  and merging}
   8.213 +
   8.214 +Every entry in a Mercurial revlog knows the identity of its immediate
   8.215 +ancestor revision, usually referred to as its \emph{parent}.  In fact,
   8.216 +a revision contains room for not one parent, but two.  Mercurial uses
   8.217 +a special hash, called the ``null ID'', to represent the idea ``there
   8.218 +is no parent here''.  This hash is simply a string of zeroes.
   8.219 +
   8.220 +In figure~\ref{fig:concepts:revlog}, you can see an example of the
   8.221 +conceptual structure of a revlog.  Filelogs, manifests, and changelogs
   8.222 +all have this same structure; they differ only in the kind of data
   8.223 +stored in each delta or snapshot.
   8.224 +
   8.225 +The first revision in a revlog (at the bottom of the image) has the
   8.226 +null ID in both of its parent slots.  For a ``normal'' revision, its
   8.227 +first parent slot contains the ID of its parent revision, and its
   8.228 +second contains the null ID, indicating that the revision has only one
   8.229 +real parent.  Any two revisions that have the same parent ID are
   8.230 +branches.  A revision that represents a merge between branches has two
   8.231 +normal revision IDs in its parent slots.
   8.232 +
   8.233 +\begin{figure}[ht]
   8.234 +  \centering
   8.235 +  \grafix{revlog}
   8.236 +  \caption{}
   8.237 +  \label{fig:concepts:revlog}
   8.238 +\end{figure}
   8.239 +
   8.240 +\section{The working directory}
   8.241 +
   8.242 +In the working directory, Mercurial stores a snapshot of the files
   8.243 +from the repository as of a particular changeset.
   8.244 +
   8.245 +The working directory ``knows'' which changeset it contains.  When you
   8.246 +update the working directory to contain a particular changeset,
   8.247 +Mercurial looks up the appropriate revision of the manifest to find
   8.248 +out which files it was tracking at the time that changeset was
   8.249 +committed, and which revision of each file was then current.  It then
   8.250 +recreates a copy of each of those files, with the same contents it had
   8.251 +when the changeset was committed.
   8.252 +
   8.253 +The \emph{dirstate} contains Mercurial's knowledge of the working
   8.254 +directory.  This details which changeset the working directory is
   8.255 +updated to, and all of the files that Mercurial is tracking in the
   8.256 +working directory.
   8.257 +
   8.258 +Just as a revision of a revlog has room for two parents, so that it
   8.259 +can represent either a normal revision (with one parent) or a merge of
   8.260 +two earlier revisions, the dirstate has slots for two parents.  When
   8.261 +you use the \hgcmd{update} command, the changeset that you update to
   8.262 +is stored in the ``first parent'' slot, and the null ID in the second.
   8.263 +When you \hgcmd{merge} with another changeset, the first parent
   8.264 +remains unchanged, and the second parent is filled in with the
   8.265 +changeset you're merging with.  The \hgcmd{parents} command tells you
   8.266 +what the parents of the dirstate are.
   8.267 +
   8.268 +\subsection{What happens when you commit}
   8.269 +
   8.270 +The dirstate stores parent information for more than just book-keeping
   8.271 +purposes.  Mercurial uses the parents of the dirstate as \emph{the
   8.272 +  parents of a new changeset} when you perform a commit.
   8.273 +
   8.274 +\begin{figure}[ht]
   8.275 +  \centering
   8.276 +  \grafix{wdir}
   8.277 +  \caption{The working directory can have two parents}
   8.278 +  \label{fig:concepts:wdir}
   8.279 +\end{figure}
   8.280 +
   8.281 +Figure~\ref{fig:concepts:wdir} shows the normal state of the working
   8.282 +directory, where it has a single changeset as parent.  That changeset
   8.283 +is the \emph{tip}, the newest changeset in the repository that has no
   8.284 +children.
   8.285 +
   8.286 +\begin{figure}[ht]
   8.287 +  \centering
   8.288 +  \grafix{wdir-after-commit}
   8.289 +  \caption{The working directory gains new parents after a commit}
   8.290 +  \label{fig:concepts:wdir-after-commit}
   8.291 +\end{figure}
   8.292 +
   8.293 +It's useful to think of the working directory as ``the changeset I'm
   8.294 +about to commit''.  Any files that you tell Mercurial that you've
   8.295 +added, removed, renamed, or copied will be reflected in that
   8.296 +changeset, as will modifications to any files that Mercurial is
   8.297 +already tracking; the new changeset will have the parents of the
   8.298 +working directory as its parents.
   8.299 +
   8.300 +After a commit, Mercurial will update the parents of the working
   8.301 +directory, so that the first parent is the ID of the new changeset,
   8.302 +and the second is the null ID.  This is shown in
   8.303 +figure~\ref{fig:concepts:wdir-after-commit}.  Mercurial doesn't touch
   8.304 +any of the files in the working directory when you commit; it just
   8.305 +modifies the dirstate to note its new parents.
   8.306 +
   8.307 +\subsection{Creating a new head}
   8.308 +
   8.309 +It's perfectly normal to update the working directory to a changeset
   8.310 +other than the current tip.  For example, you might want to know what
   8.311 +your project looked like last Tuesday, or you could be looking through
   8.312 +changesets to see which one introduced a bug.  In cases like this, the
   8.313 +natural thing to do is update the working directory to the changeset
   8.314 +you're interested in, and then examine the files in the working
   8.315 +directory directly to see their contents as they werea when you
   8.316 +committed that changeset.  The effect of this is shown in
   8.317 +figure~\ref{fig:concepts:wdir-pre-branch}.
   8.318 +
   8.319 +\begin{figure}[ht]
   8.320 +  \centering
   8.321 +  \grafix{wdir-pre-branch}
   8.322 +  \caption{The working directory, updated to an older changeset}
   8.323 +  \label{fig:concepts:wdir-pre-branch}
   8.324 +\end{figure}
   8.325 +
   8.326 +Having updated the working directory to an older changeset, what
   8.327 +happens if you make some changes, and then commit?  Mercurial behaves
   8.328 +in the same way as I outlined above.  The parents of the working
   8.329 +directory become the parents of the new changeset.  This new changeset
   8.330 +has no children, so it becomes the new tip.  And the repository now
   8.331 +contains two changesets that have no children; we call these
   8.332 +\emph{heads}.  You can see the structure that this creates in
   8.333 +figure~\ref{fig:concepts:wdir-branch}.
   8.334 +
   8.335 +\begin{figure}[ht]
   8.336 +  \centering
   8.337 +  \grafix{wdir-branch}
   8.338 +  \caption{After a commit made while synced to an older changeset}
   8.339 +  \label{fig:concepts:wdir-branch}
   8.340 +\end{figure}
   8.341 +
   8.342 +\begin{note}
   8.343 +  If you're new to Mercurial, you should keep in mind a common
   8.344 +  ``error'', which is to use the \hgcmd{pull} command without any
   8.345 +  options.  By default, the \hgcmd{pull} command \emph{does not}
   8.346 +  update the working directory, so you'll bring new changesets into
   8.347 +  your repository, but the working directory will stay synced at the
   8.348 +  same changeset as before the pull.  If you make some changes and
   8.349 +  commit afterwards, you'll thus create a new head, because your
   8.350 +  working directory isn't synced to whatever the current tip is.
   8.351 +
   8.352 +  I put the word ``error'' in quotes because all that you need to do
   8.353 +  to rectify this situation is \hgcmd{merge}, then \hgcmd{commit}.  In
   8.354 +  other words, this almost never has negative consequences; it just
   8.355 +  surprises people.  I'll discuss other ways to avoid this behaviour,
   8.356 +  and why Mercurial behaves in this initially surprising way, later
   8.357 +  on.
   8.358 +\end{note}
   8.359 +
   8.360 +\subsection{Merging heads}
   8.361 +
   8.362 +When you run the \hgcmd{merge} command, Mercurial leaves the first
   8.363 +parent of the working directory unchanged, and sets the second parent
   8.364 +to the changeset you're merging with, as shown in
   8.365 +figure~\ref{fig:concepts:wdir-merge}.
   8.366 +
   8.367 +\begin{figure}[ht]
   8.368 +  \centering
   8.369 +  \grafix{wdir-merge}
   8.370 +  \caption{Merging two hehads}
   8.371 +  \label{fig:concepts:wdir-merge}
   8.372 +\end{figure}
   8.373 +
   8.374 +Mercurial also has to modify the working directory, to merge the files
   8.375 +managed in the two changesets.  Simplified a little, the merging
   8.376 +process goes like this, for every file in the manifests of both
   8.377 +changesets.
   8.378 +\begin{itemize}
   8.379 +\item If neither changeset has modified a file, do nothing with that
   8.380 +  file.
   8.381 +\item If one changeset has modified a file, and the other hasn't,
   8.382 +  create the modified copy of the file in the working directory.
   8.383 +\item If one changeset has removed a file, and the other hasn't (or
   8.384 +  has also deleted it), delete the file from the working directory.
   8.385 +\item If one changeset has removed a file, but the other has modified
   8.386 +  the file, ask the user what to do: keep the modified file, or remove
   8.387 +  it?
   8.388 +\item If both changesets have modified a file, invoke an external
   8.389 +  merge program to choose the new contents for the merged file.  This
   8.390 +  may require input from the user.
   8.391 +\item If one changeset has modified a file, and the other has renamed
   8.392 +  or copied the file, make sure that the changes follow the new name
   8.393 +  of the file.
   8.394 +\end{itemize}
   8.395 +There are more details---merging has plenty of corner cases---but
   8.396 +these are the most common choices that are involved in a merge.  As
   8.397 +you can see, most cases are completely automatic, and indeed most
   8.398 +merges finish automatically, without requiring your input to resolve
   8.399 +any conflicts.
   8.400 +
   8.401 +When you're thinking about what happens when you commit after a merge,
   8.402 +once again the working directory is ``the changeset I'm about to
   8.403 +commit''.  After the \hgcmd{merge} command completes, the working
   8.404 +directory has two parents; these will become the parents of the new
   8.405 +changeset.
   8.406 +
   8.407 +Mercurial lets you perform multiple merges, but you must commit the
   8.408 +results of each individual merge as you go.  This is necessary because
   8.409 +Mercurial only tracks two parents for both revisions and the working
   8.410 +directory.  While it would be technically possible to merge multiple
   8.411 +changesets at once, the prospect of user confusion and making a
   8.412 +terrible mess of a merge immediately becomes overwhelming.
   8.413 +
   8.414 +\section{Other interesting design features}
   8.415 +
   8.416 +In the sections above, I've tried to highlight some of the most
   8.417 +important aspects of Mercurial's design, to illustrate that it pays
   8.418 +careful attention to reliability and performance.  However, the
   8.419 +attention to detail doesn't stop there.  There are a number of other
   8.420 +aspects of Mercurial's construction that I personally find
   8.421 +interesting.  I'll detail a few of them here, separate from the ``big
   8.422 +ticket'' items above, so that if you're interested, you can gain a
   8.423 +better idea of the amount of thinking that goes into a well-designed
   8.424 +system.
   8.425 +
   8.426 +\subsection{Clever compression}
   8.427 +
   8.428 +When appropriate, Mercurial will store both snapshots and deltas in
   8.429 +compressed form.  It does this by always \emph{trying to} compress a
   8.430 +snapshot or delta, but only storing the compressed version if it's
   8.431 +smaller than the uncompressed version.
   8.432 +
   8.433 +This means that Mercurial does ``the right thing'' when storing a file
   8.434 +whose native form is compressed, such as a \texttt{zip} archive or a
   8.435 +JPEG image.  When these types of files are compressed a second time,
   8.436 +the resulting file is usually bigger than the once-compressed form,
   8.437 +and so Mercurial will store the plain \texttt{zip} or JPEG.
   8.438 +
   8.439 +Deltas between revisions of a compressed file are usually larger than
   8.440 +snapshots of the file, and Mercurial again does ``the right thing'' in
   8.441 +these cases.  It finds that such a delta exceeds the threshold at
   8.442 +which it should store a complete snapshot of the file, so it stores
   8.443 +the snapshot, again saving space compared to a naive delta-only
   8.444 +approach.
   8.445 +
   8.446 +\subsubsection{Network recompression}
   8.447 +
   8.448 +When storing revisions on disk, Mercurial uses the ``deflate''
   8.449 +compression algorithm (the same one used by the popular \texttt{zip}
   8.450 +archive format), which balances good speed with a respectable
   8.451 +compression ratio.  However, when transmitting revision data over a
   8.452 +network connection, Mercurial uncompresses the compressed revision
   8.453 +data.
   8.454 +
   8.455 +If the connection is over HTTP, Mercurial recompresses the entire
   8.456 +stream of data using a compression algorithm that gives a etter
   8.457 +compression ratio (the Burrows-Wheeler algorithm from the widely used
   8.458 +\texttt{bzip2} compression package).  This combination of algorithm
   8.459 +and compression of the entire stream (instead of a revision at a time)
   8.460 +substantially reduces the number of bytes to be transferred, yielding
   8.461 +better network performance over almost all kinds of network.
   8.462 +
   8.463 +(If the connection is over \command{ssh}, Mercurial \emph{doesn't}
   8.464 +recompress the stream, because \command{ssh} can already do this
   8.465 +itself.)
   8.466 +
   8.467 +\subsection{Read/write ordering and atomicity}
   8.468 +
   8.469 +Appending to files isn't the whole story when it comes to guaranteeing
   8.470 +that a reader won't see a partial write.  If you recall
   8.471 +figure~\ref{fig:concepts:metadata}, revisions in the changelog point to
   8.472 +revisions in the manifest, and revisions in the manifest point to
   8.473 +revisions in filelogs.  This hierarchy is deliberate.
   8.474 +
   8.475 +A writer starts a transaction by writing filelog and manifest data,
   8.476 +and doesn't write any changelog data until those are finished.  A
   8.477 +reader starts by reading changelog data, then manifest data, followed
   8.478 +by filelog data.
   8.479 +
   8.480 +Since the writer has always finished writing filelog and manifest data
   8.481 +before it writes to the changelog, a reader will never read a pointer
   8.482 +to a partially written manifest revision from the changelog, and it will
   8.483 +never read a pointer to a partially written filelog revision from the
   8.484 +manifest.
   8.485 +
   8.486 +\subsection{Concurrent access}
   8.487 +
   8.488 +The read/write ordering and atomicity guarantees mean that Mercurial
   8.489 +never needs to \emph{lock} a repository when it's reading data, even
   8.490 +if the repository is being written to while the read is occurring.
   8.491 +This has a big effect on scalability; you can have an arbitrary number
   8.492 +of Mercurial processes safely reading data from a repository safely
   8.493 +all at once, no matter whether it's being written to or not.
   8.494 +
   8.495 +The lockless nature of reading means that if you're sharing a
   8.496 +repository on a multi-user system, you don't need to grant other local
   8.497 +users permission to \emph{write} to your repository in order for them
   8.498 +to be able to clone it or pull changes from it; they only need
   8.499 +\emph{read} permission.  (This is \emph{not} a common feature among
   8.500 +revision control systems, so don't take it for granted!  Most require
   8.501 +readers to be able to lock a repository to access it safely, and this
   8.502 +requires write permission on at least one directory, which of course
   8.503 +makes for all kinds of nasty and annoying security and administrative
   8.504 +problems.)
   8.505 +
   8.506 +Mercurial uses locks to ensure that only one process can write to a
   8.507 +repository at a time (the locking mechanism is safe even over
   8.508 +filesystems that are notoriously hostile to locking, such as NFS).  If
   8.509 +a repository is locked, a writer will wait for a while to retry if the
   8.510 +repository becomes unlocked, but if the repository remains locked for
   8.511 +too long, the process attempting to write will time out after a while.
   8.512 +This means that your daily automated scripts won't get stuck forever
   8.513 +and pile up if a system crashes unnoticed, for example.  (Yes, the
   8.514 +timeout is configurable, from zero to infinity.)
   8.515 +
   8.516 +\subsubsection{Safe dirstate access}
   8.517 +
   8.518 +As with revision data, Mercurial doesn't take a lock to read the
   8.519 +dirstate file; it does acquire a lock to write it.  To avoid the
   8.520 +possibility of reading a partially written copy of the dirstate file,
   8.521 +Mercurial writes to a file with a unique name in the same directory as
   8.522 +the dirstate file, then renames the temporary file atomically to
   8.523 +\filename{dirstate}.  The file named \filename{dirstate} is thus
   8.524 +guaranteed to be complete, not partially written.
   8.525 +
   8.526 +\subsection{Avoiding seeks}
   8.527 +
   8.528 +Critical to Mercurial's performance is the avoidance of seeks of the
   8.529 +disk head, since any seek is far more expensive than even a
   8.530 +comparatively large read operation.
   8.531 +
   8.532 +This is why, for example, the dirstate is stored in a single file.  If
   8.533 +there were a dirstate file per directory that Mercurial tracked, the
   8.534 +disk would seek once per directory.  Instead, Mercurial reads the
   8.535 +entire single dirstate file in one step.
   8.536 +
   8.537 +Mercurial also uses a ``copy on write'' scheme when cloning a
   8.538 +repository on local storage.  Instead of copying every revlog file
   8.539 +from the old repository into the new repository, it makes a ``hard
   8.540 +link'', which is a shorthand way to say ``these two names point to the
   8.541 +same file''.  When Mercurial is about to write to one of a revlog's
   8.542 +files, it checks to see if the number of names pointing at the file is
   8.543 +greater than one.  If it is, more than one repository is using the
   8.544 +file, so Mercurial makes a new copy of the file that is private to
   8.545 +this repository.
   8.546 +
   8.547 +A few revision control developers have pointed out that this idea of
   8.548 +making a complete private copy of a file is not very efficient in its
   8.549 +use of storage.  While this is true, storage is cheap, and this method
   8.550 +gives the highest performance while deferring most book-keeping to the
   8.551 +operating system.  An alternative scheme would most likely reduce
   8.552 +performance and increase the complexity of the software, each of which
   8.553 +is much more important to the ``feel'' of day-to-day use.
   8.554 +
   8.555 +\subsection{Other contents of the dirstate}
   8.556 +
   8.557 +Because Mercurial doesn't force you to tell it when you're modifying a
   8.558 +file, it uses the dirstate to store some extra information so it can
   8.559 +determine efficiently whether you have modified a file.  For each file
   8.560 +in the working directory, it stores the time that it last modified the
   8.561 +file itself, and the size of the file at that time.  
   8.562 +
   8.563 +When you explicitly \hgcmd{add}, \hgcmd{remove}, \hgcmd{rename} or
   8.564 +\hgcmd{copy} files, Mercurial updates the dirstate so that it knows
   8.565 +what to do with those files when you commit.
   8.566 +
   8.567 +When Mercurial is checking the states of files in the working
   8.568 +directory, it first checks a file's modification time.  If that has
   8.569 +not changed, the file must not have been modified.  If the file's size
   8.570 +has changed, the file must have been modified.  If the modification
   8.571 +time has changed, but the size has not, only then does Mercurial need
   8.572 +to read the actual contents of the file to see if they've changed.
   8.573 +Storing these few extra pieces of information dramatically reduces the
   8.574 +amount of data that Mercurial needs to read, which yields large
   8.575 +performance improvements compared to other revision control systems.
   8.576 +
   8.577 +%%% Local Variables: 
   8.578 +%%% mode: latex
   8.579 +%%% TeX-master: "00book"
   8.580 +%%% End:

     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/en/daily.tex	Mon Mar 05 20:16:36 2007 -0800
     9.3 @@ -0,0 +1,322 @@
     9.4 +\chapter{Mercurial in daily use}
     9.5 +\label{chap:daily}
     9.6 +
     9.7 +\section{Telling Mercurial which files to track}
     9.8 +
     9.9 +Mercurial does not work with files in your repository unless you tell
    9.10 +it to manage them.  The \hgcmd{status} command will tell you which
    9.11 +files Mercurial doesn't know about; it uses a ``\texttt{?}'' to
    9.12 +display such files.
    9.13 +
    9.14 +To tell Mercurial to track a file, use the \hgcmd{add} command.  Once
    9.15 +you have added a file, the entry in the output of \hgcmd{status} for
    9.16 +that file changes from ``\texttt{?}'' to ``\texttt{A}''.
    9.17 +\interaction{daily.files.add}
    9.18 +
    9.19 +After you run a \hgcmd{commit}, the files that you added before the
    9.20 +commit will no longer be listed in the output of \hgcmd{status}.  The
    9.21 +reason for this is that \hgcmd{status} only tells you about
    9.22 +``interesting'' files---those that you have modified or told Mercurial
    9.23 +to do something with---by default.  If you have a repository that
    9.24 +contains thousands of files, you will rarely want to know about files
    9.25 +that Mercurial is tracking, but that have not changed.  (You can still
    9.26 +get this information; we'll return to this later.)
    9.27 +
    9.28 +Once you add a file, Mercurial doesn't do anything with it
    9.29 +immediately.  Instead, it will take a snapshot of the file's state the
    9.30 +next time you perform a commit.  It will then continue to track the
    9.31 +changes you make to the file every time you commit, until you remove
    9.32 +the file.
    9.33 +
    9.34 +\subsection{Explicit versus implicit file naming}
    9.35 +
    9.36 +A useful behaviour that Mercurial has is that if you pass the name of
    9.37 +a directory to a command, every Mercurial command will treat this as
    9.38 +``I want to operate on every file in this directory and its
    9.39 +subdirectories''.
    9.40 +\interaction{daily.files.add-dir}
    9.41 +Notice in this example that Mercurial printed the names of the files
    9.42 +it added, whereas it didn't do so when we added the file named
    9.43 +\filename{a} in the earlier example.
    9.44 +
    9.45 +What's going on is that in the former case, we explicitly named the
    9.46 +file to add on the command line, so the assumption that Mercurial
    9.47 +makes in such cases is that we know what you were doing, and it
    9.48 +doesn't print any output.
    9.49 +
    9.50 +However, when we \emph{imply} the names of files by giving the name of
    9.51 +a directory, Mercurial takes the extra step of printing the name of
    9.52 +each file that it does something with.  This makes it more clear what
    9.53 +is happening, and reduces the likelihood of a silent and nasty
    9.54 +surprise.  This behaviour is common to most Mercurial commands.
    9.55 +
    9.56 +\subsection{Aside: Mercurial tracks files, not directories}
    9.57 +
    9.58 +Mercurial does not track directory information.  Instead, it tracks
    9.59 +the path to a file.  Before creating a file, it first creates any
    9.60 +missing directory components of the path.  After it deletes a file, it
    9.61 +then deletes any empty directories that were in the deleted file's
    9.62 +path.  This sounds like a trivial distinction, but it has one minor
    9.63 +practical consequence: it is not possible to represent a completely
    9.64 +empty directory in Mercurial.
    9.65 +
    9.66 +Empty directories are rarely useful, and there are unintrusive
    9.67 +workarounds that you can use to achieve an appropriate effect.  The
    9.68 +developers of Mercurial thus felt that the complexity that would be
    9.69 +required to manage empty directories was not worth the limited benefit
    9.70 +this feature would bring.
    9.71 +
    9.72 +If you need an empty directory in your repository, there are a few
    9.73 +ways to achieve this. One is to create a directory, then \hgcmd{add} a
    9.74 +``hidden'' file to that directory.  On Unix-like systems, any file
    9.75 +name that begins with a period (``\texttt{.}'') is treated as hidden
    9.76 +by most commands and GUI tools.  This approach is illustrated in
    9.77 +figure~\ref{ex:daily:hidden}.
    9.78 +
    9.79 +\begin{figure}[ht]
    9.80 +  \interaction{daily.files.hidden}
    9.81 +  \caption{Simulating an empty directory using a hidden file}
    9.82 +  \label{ex:daily:hidden}
    9.83 +\end{figure}
    9.84 +
    9.85 +Another way to tackle a need for an empty directory is to simply
    9.86 +create one in your automated build scripts before they will need it.
    9.87 +
    9.88 +\section{How to stop tracking a file}
    9.89 +
    9.90 +Once you decide that a file no longer belongs in your repository, use
    9.91 +the \hgcmd{remove} command; this deletes the file, and tells Mercurial
    9.92 +to stop tracking it.  A removed file is represented in the output of
    9.93 +\hgcmd{status} with a ``\texttt{R}''.
    9.94 +\interaction{daily.files.remove}
    9.95 +
    9.96 +After you \hgcmd{remove} a file, Mercurial will no longer track
    9.97 +changes to that file, even if you recreate a file with the same name
    9.98 +in your working directory.  If you do recreate a file with the same
    9.99 +name and want Mercurial to track the new file, simply \hgcmd{add} it.
   9.100 +Mercurial will know that the newly added file is not related to the
   9.101 +old file of the same name.
   9.102 +
   9.103 +\subsection{Removing a file does not affect its history}
   9.104 +
   9.105 +It is important to understand that removing a file has only two
   9.106 +effects.
   9.107 +\begin{itemize}
   9.108 +\item It removes the current version of the file from the working
   9.109 +  directory.
   9.110 +\item It stops Mercurial from tracking changes to the file, from the
   9.111 +  time of the next commit.
   9.112 +\end{itemize}
   9.113 +Removing a file \emph{does not} in any way alter the \emph{history} of
   9.114 +the file.
   9.115 +
   9.116 +If you update the working directory to a changeset in which a file
   9.117 +that you have removed was still tracked, it will reappear in the
   9.118 +working directory, with the contents it had when you committed that
   9.119 +changeset.  If you then update the working directory to a later
   9.120 +changeset, in which the file had been removed, Mercurial will once
   9.121 +again remove the file from the working directory.
   9.122 +
   9.123 +\subsection{Missing files}
   9.124 +
   9.125 +Mercurial considers a file that you have deleted, but not used
   9.126 +\hgcmd{remove} to delete, to be \emph{missing}.  A missing file is
   9.127 +represented with ``\texttt{!}'' in the output of \hgcmd{status}.
   9.128 +Mercurial commands will not generally do anything with missing files.
   9.129 +\interaction{daily.files.missing}
   9.130 +
   9.131 +If your repository contains a file that \hgcmd{status} reports as
   9.132 +missing, and you want the file to stay gone, you can run
   9.133 +\hgcmdargs{remove}{\hgopt{remove}{--after}} at any time later on, to
   9.134 +tell Mercurial that you really did mean to remove the file.
   9.135 +\interaction{daily.files.remove-after}
   9.136 +
   9.137 +On the other hand, if you deleted the missing file by accident, use
   9.138 +\hgcmdargs{revert}{\emph{filename}} to recover the file.  It will
   9.139 +reappear, in unmodified form.
   9.140 +\interaction{daily.files.recover-missing}
   9.141 +
   9.142 +\subsection{Aside: why tell Mercurial explicitly to 
   9.143 +  remove a file?}
   9.144 +
   9.145 +You might wonder why Mercurial requires you to explicitly tell it that
   9.146 +you are deleting a file.  Early during the development of Mercurial,
   9.147 +it let you delete a file however you pleased; Mercurial would notice
   9.148 +the absence of the file automatically when you next ran a
   9.149 +\hgcmd{commit}, and stop tracking the file.  In practice, this made it
   9.150 +too easy to accidentally remove a file without noticing.
   9.151 +
   9.152 +\subsection{Useful shorthand---adding and removing files
   9.153 +  in one step}
   9.154 +
   9.155 +Mercurial offers a combination command, \hgcmd{addremove}, that adds
   9.156 +untracked files and marks missing files as removed.  
   9.157 +\interaction{daily.files.addremove}
   9.158 +The \hgcmd{commit} command also provides a \hgopt{commit}{-A} option
   9.159 +that performs this same add-and-remove, immediately followed by a
   9.160 +commit.
   9.161 +\interaction{daily.files.commit-addremove}
   9.162 +
   9.163 +\section{Copying files}
   9.164 +
   9.165 +Mercurial provides a \hgcmd{copy} command that lets you make a new
   9.166 +copy of a file.  When you copy a file using this command, Mercurial
   9.167 +makes a record of the fact that the new file is a copy of the original
   9.168 +file.  It treats these copied files specially when you merge your work
   9.169 +with someone else's.
   9.170 +
   9.171 +\subsection{The results of copying during a merge}
   9.172 +
   9.173 +What happens during a merge is that changes ``follow'' a copy.  To
   9.174 +best illustrate what this means, let's create an example.  We'll start
   9.175 +with the usual tiny repository that contains a single file.
   9.176 +\interaction{daily.copy.init}
   9.177 +We need to do some work in parallel, so that we'll have something to
   9.178 +merge.  So let's clone our repository.
   9.179 +\interaction{daily.copy.clone}
   9.180 +Back in our initial repository, let's use the \hgcmd{copy} command to
   9.181 +make a copy of the first file we created.
   9.182 +\interaction{daily.copy.copy}
   9.183 +
   9.184 +If we look at the output of the \hgcmd{status} command afterwards, the
   9.185 +copied file looks just like a normal added file.
   9.186 +\interaction{daily.copy.status}
   9.187 +But if we pass the \hgopt{status}{-C} option to \hgcmd{status}, it
   9.188 +prints another line of output: this is the file that our newly-added
   9.189 +file was copied \emph{from}.
   9.190 +\interaction{daily.copy.status-copy}
   9.191 +
   9.192 +Now, back in the repository we cloned, let's make a change in
   9.193 +parallel.  We'll add a line of content to the original file that we
   9.194 +created.
   9.195 +\interaction{daily.copy.other}
   9.196 +Now we have a modified \filename{file} in this repository.  When we
   9.197 +pull the changes from the first repository, and merge the two heads,
   9.198 +Mercurial will propagate the changes that we made locally to
   9.199 +\filename{file} into its copy, \filename{new-file}.
   9.200 +\interaction{daily.copy.merge}
   9.201 +
   9.202 +\subsection{Why should changes follow copies?}
   9.203 +\label{sec:daily:why-copy}
   9.204 +
   9.205 +This behaviour, of changes to a file propagating out to copies of the
   9.206 +file, might seem esoteric, but in most cases it's highly desirable.
   9.207 +
   9.208 +First of all, remember that this propagation \emph{only} happens when
   9.209 +you merge.  So if you \hgcmd{copy} a file, and subsequently modify the
   9.210 +original file during the normal course of your work, nothing will
   9.211 +happen.
   9.212 +
   9.213 +The second thing to know is that modifications will only propagate
   9.214 +across a copy as long as the repository that you're pulling changes
   9.215 +from \emph{doesn't know} about the copy.
   9.216 +
   9.217 +The reason that Mercurial does this is as follows.  Let's say I make
   9.218 +an important bug fix in a source file, and commit my changes.
   9.219 +Meanwhile, you've decided to \hgcmd{copy} the file in your repository,
   9.220 +without knowing about the bug or having seen the fix, and you have
   9.221 +started hacking on your copy of the file.
   9.222 +
   9.223 +If you pulled and merged my changes, and Mercurial \emph{didn't}
   9.224 +propagate changes across copies, your source file would now contain
   9.225 +the bug, and unless you remembered to propagate the bug fix by hand,
   9.226 +the bug would \emph{remain} in your copy of the file.
   9.227 +
   9.228 +By automatically propagating the change that fixed the bug from the
   9.229 +original file to the copy, Mercurial prevents this class of problem.
   9.230 +To my knowledge, Mercurial is the \emph{only} revision control system
   9.231 +that propagates changes across copies like this.
   9.232 +
   9.233 +Once your change history has a record that the copy and subsequent
   9.234 +merge occurred, there's usually no further need to propagate changes
   9.235 +from the original file to the copied file, and that's why Mercurial
   9.236 +only propagates changes across copies until this point, and no
   9.237 +further.
   9.238 +
   9.239 +\subsection{How to make changes \emph{not} follow a copy}
   9.240 +
   9.241 +If, for some reason, you decide that this business of automatically
   9.242 +propagating changes across copies is not for you, simply use your
   9.243 +system's normal file copy command (on Unix-like systems, that's
   9.244 +\command{cp}) to make a copy of a file, then \hgcmd{add} the new copy
   9.245 +by hand.  Before you do so, though, please do reread
   9.246 +section~\ref{sec:daily:why-copy}, and make an informed decision that
   9.247 +this behaviour is not appropriate to your specific case.
   9.248 +
   9.249 +\subsection{Behaviour of the \hgcmd{copy} command}
   9.250 +
   9.251 +When you use the \hgcmd{copy} command, Mercurial makes a copy of each
   9.252 +source file as it currently stands in the working directory.  This
   9.253 +means that if you make some modifications to a file, then copy it
   9.254 +without first having committed those changes, the new copy will
   9.255 +contain your modifications.
   9.256 +
   9.257 +The \hgcmd{copy} command acts similarly to the Unix \command{cp}
   9.258 +command (you can use the \hgcmd{cp} alias if you prefer).  The last
   9.259 +argument is the \emph{destination}, and all prior arguments are
   9.260 +\emph{sources}.  If you pass it a single file as the source, and the
   9.261 +destination does not exist, it creates a new file with that name.
   9.262 +\interaction{daily.copy.simple}
   9.263 +If the destination is a directory, Mercurial copies its sources into
   9.264 +that directory.
   9.265 +\interaction{daily.copy.dir-dest}
   9.266 +Copying a directory is recursive, and preserves the directory
   9.267 +structure of the source.
   9.268 +\interaction{daily.copy.dir-src}
   9.269 +If the source and destination are both directories, the source tree is
   9.270 +recreated in the destination directory.
   9.271 +\interaction{daily.copy.dir-src-dest}
   9.272 +
   9.273 +As with the \hgcmd{rename} command, if you copy a file manually and
   9.274 +then want Mercurial to know that you've copied the file, simply use
   9.275 +the \hgopt{--after} option to \hgcmd{copy}.
   9.276 +\interaction{daily.copy.after}
   9.277 +
   9.278 +\section{Renaming files}
   9.279 +
   9.280 +It's rather more common to need to rename a file than to make a copy
   9.281 +of it.  The reason I discussed the \hgcmd{copy} command before talking
   9.282 +about renaming files is that Mercurial treats a rename in essentially
   9.283 +the same way as a copy.  Therefore, knowing what Mercurial does when
   9.284 +you copy a file tells you what to expect when you rename a file.
   9.285 +
   9.286 +When you use the \hgcmd{rename} command, Mercurial makes a copy of
   9.287 +each source file, then deletes it and marks the file as removed.
   9.288 +\interaction{daily.rename.rename}
   9.289 +The \hgcmd{status} command shows the newly copied file as added, and
   9.290 +the copied-from file as removed.
   9.291 +\interaction{daily.rename.status}
   9.292 +As with the results of a \hgcmd{copy}, we must use the
   9.293 +\hgopt{status}{-C} option to \hgcmd{status} to see that the added file
   9.294 +is really being tracked by Mercurial as a copy of the original, now
   9.295 +removed, file.
   9.296 +\interaction{daily.rename.status-copy}
   9.297 +
   9.298 +As with \hgcmd{remove} and \hgcmd{copy}, you can tell Mercurial about
   9.299 +a rename after the fact using the \hgopt{rename}{--after} option.  In
   9.300 +most other respects, the behaviour of the \hgcmd{rename} command, and
   9.301 +the options it accepts, are similar to the \hgcmd{copy} command.
   9.302 +
   9.303 +\subsection{Renaming files and merging changes}
   9.304 +
   9.305 +Since Mercurial's rename is implemented as copy-and-remove, the same
   9.306 +propagation of changes happens when you merge after a rename as after
   9.307 +a copy.
   9.308 +
   9.309 +If I modify a file, and you rename it to a new name, then we merge our
   9.310 +respective changes, my modifications to the file under its original
   9.311 +name will be propagated into the file under its new name.  (This is
   9.312 +something you might expect to ``simply work,'' but not all revision
   9.313 +control systems actually do this.)
   9.314 +
   9.315 +Whereas having changes follow a copy is a feature where you can
   9.316 +perhaps nod and say ``yes, that might be useful,'' it should be clear
   9.317 +that having them follow a rename is definitely important.  Without
   9.318 +this facility, it would simply be too easy for changes to become
   9.319 +orphaned when files are renamed.
   9.320 +
   9.321 +
   9.322 +%%% Local Variables: 
   9.323 +%%% mode: latex
   9.324 +%%% TeX-master: "00book"
   9.325 +%%% End: 

    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/en/examples/backout	Mon Mar 05 20:16:36 2007 -0800
    10.3 @@ -0,0 +1,82 @@
    10.4 +#!/bin/bash
    10.5 +
    10.6 +# We have to fake the merges here, because they cause conflicts with
    10.7 +# three-way command-line merge, and kdiff3 may not be available.
    10.8 +
    10.9 +export HGMERGE=$(mktemp)
   10.10 +echo '#!/bin/sh' >> $HGMERGE
   10.11 +echo 'echo first change > "$1"' >> $HGMERGE
   10.12 +echo 'echo third change > "$1"' >> $HGMERGE
   10.13 +chmod 700 $HGMERGE
   10.14 +
   10.15 +#$ name: init
   10.16 +
   10.17 +hg init myrepo
   10.18 +cd myrepo
   10.19 +echo first change >> myfile
   10.20 +hg add myfile
   10.21 +hg commit -m 'first change'
   10.22 +echo second change >> myfile
   10.23 +hg commit -m 'second change'
   10.24 +
   10.25 +#$ name: simple
   10.26 +
   10.27 +hg backout -m 'back out second change' tip
   10.28 +cat myfile
   10.29 +
   10.30 +#$ name: simple.log
   10.31 +
   10.32 +hg log --style compact
   10.33 +
   10.34 +#$ name: non-tip.clone
   10.35 +
   10.36 +cd ..
   10.37 +hg clone -r1 myrepo non-tip-repo
   10.38 +cd non-tip-repo
   10.39 +
   10.40 +#$ name: non-tip.backout
   10.41 +
   10.42 +echo third change >> myfile
   10.43 +hg commit -m 'third change'
   10.44 +hg backout --merge -m 'back out second change' 1
   10.45 +
   10.46 +#$ name: non-tip.cat
   10.47 +cat myfile
   10.48 +
   10.49 +#$ name: manual.clone
   10.50 +
   10.51 +cd ..
   10.52 +hg clone -r1 myrepo newrepo
   10.53 +cd newrepo
   10.54 +
   10.55 +#$ name: manual.backout
   10.56 +
   10.57 +echo third change >> myfile
   10.58 +hg commit -m 'third change'
   10.59 +hg backout -m 'back out second change' 1
   10.60 +
   10.61 +#$ name: manual.log
   10.62 +
   10.63 +hg log --style compact
   10.64 +
   10.65 +#$ name: manual.parents
   10.66 +
   10.67 +hg parents
   10.68 +
   10.69 +#$ name: manual.heads
   10.70 +
   10.71 +hg heads
   10.72 +
   10.73 +#$ name: manual.cat
   10.74 +
   10.75 +cat myfile
   10.76 +
   10.77 +#$ name: manual.merge
   10.78 +
   10.79 +hg merge
   10.80 +hg commit -m 'merged backout with previous tip'
   10.81 +cat myfile
   10.82 +
   10.83 +#$ name:
   10.84 +
   10.85 +rm $HGMERGE

    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/en/examples/bisect	Mon Mar 05 20:16:36 2007 -0800
    11.3 @@ -0,0 +1,80 @@
    11.4 +#!/bin/bash
    11.5 +
    11.6 +echo '[extensions]' >> $HGRC
    11.7 +echo 'hbisect =' >> $HGRC
    11.8 +
    11.9 +#$ name: init
   11.10 +
   11.11 +hg init mybug
   11.12 +cd mybug
   11.13 +
   11.14 +#$ name: commits
   11.15 +
   11.16 +buggy_change=37
   11.17 +
   11.18 +for (( i = 0; i < 50; i++ )); do
   11.19 +  if [[ $i = $buggy_change ]]; then
   11.20 +    echo 'i have a gub' > myfile$i
   11.21 +    hg commit -q -A -m 'buggy changeset'
   11.22 +  else
   11.23 +    echo 'nothing to see here, move along' > myfile$i
   11.24 +    hg commit -q -A -m 'normal changeset'
   11.25 +  fi
   11.26 +done
   11.27 +
   11.28 +#$ name: help
   11.29 +
   11.30 +hg help bisect
   11.31 +hg bisect help
   11.32 +
   11.33 +#$ name: search.init
   11.34 +
   11.35 +hg bisect init
   11.36 +
   11.37 +#$ name: search.bad-init
   11.38 +
   11.39 +hg bisect bad
   11.40 +
   11.41 +#$ name: search.good-init
   11.42 +
   11.43 +hg bisect good 10
   11.44 +
   11.45 +#$ name: search.step1
   11.46 +
   11.47 +if grep -q 'i have a gub' *
   11.48 +then
   11.49 +  result=bad
   11.50 +else
   11.51 +  result=good
   11.52 +fi
   11.53 +
   11.54 +echo this revision is $result
   11.55 +hg bisect $result
   11.56 +
   11.57 +#$ name: search.mytest
   11.58 +
   11.59 +mytest() {
   11.60 +  if grep -q 'i have a gub' *
   11.61 +  then
   11.62 +    result=bad
   11.63 +  else
   11.64 +    result=good
   11.65 +  fi
   11.66 +
   11.67 +  echo this revision is $result
   11.68 +  hg bisect $result
   11.69 +}
   11.70 +  
   11.71 +#$ name: search.step2
   11.72 +
   11.73 +mytest
   11.74 +
   11.75 +#$ name: search.rest
   11.76 +
   11.77 +mytest
   11.78 +mytest
   11.79 +mytest
   11.80 +
   11.81 +#$ name: search.reset
   11.82 +
   11.83 +hg bisect reset

    12.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    12.2 +++ b/en/examples/cmdref	Mon Mar 05 20:16:36 2007 -0800
    12.3 @@ -0,0 +1,22 @@
    12.4 +#!/bin/bash
    12.5 +
    12.6 +hg init diff
    12.7 +cd diff
    12.8 +cat > myfile.c <<EOF
    12.9 +int myfunc()
   12.10 +{
   12.11 +    return 1;
   12.12 +}
   12.13 +EOF
   12.14 +hg ci -Ama
   12.15 +
   12.16 +sed -ie 's/return 1/return 10/' myfile.c
   12.17 +
   12.18 +#$ name: diff-p
   12.19 +
   12.20 +echo '[diff]' >> $HGRC
   12.21 +echo 'showfunc = False' >> $HGRC
   12.22 +
   12.23 +hg diff
   12.24 +
   12.25 +hg diff -p

    13.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    13.2 +++ b/en/examples/daily.copy	Mon Mar 05 20:16:36 2007 -0800
    13.3 @@ -0,0 +1,80 @@
    13.4 +#!/bin/bash
    13.5 +
    13.6 +#$ name: init
    13.7 +
    13.8 +hg init my-copy
    13.9 +cd my-copy
   13.10 +echo line > file
   13.11 +hg add file
   13.12 +hg commit -m 'Added a file'
   13.13 +
   13.14 +#$ name: clone
   13.15 +
   13.16 +cd ..
   13.17 +hg clone my-copy your-copy
   13.18 +
   13.19 +#$ name: copy
   13.20 +
   13.21 +cd my-copy
   13.22 +hg copy file new-file
   13.23 +
   13.24 +#$ name: status
   13.25 +
   13.26 +hg status
   13.27 +
   13.28 +#$ name: status-copy
   13.29 +
   13.30 +hg status -C
   13.31 +hg commit -m 'Copied file'
   13.32 +
   13.33 +#$ name: other
   13.34 +
   13.35 +cd ../your-copy
   13.36 +echo 'new contents' >> file
   13.37 +hg commit -m 'Changed file'
   13.38 +
   13.39 +#$ name: cat
   13.40 +
   13.41 +cat file
   13.42 +cat ../my-copy/new-file
   13.43 +
   13.44 +#$ name: merge
   13.45 +
   13.46 +hg pull ../my-copy
   13.47 +hg merge
   13.48 +cat new-file
   13.49 +
   13.50 +#$ name:
   13.51 +
   13.52 +cd ..
   13.53 +hg init copy-example
   13.54 +cd copy-example
   13.55 +echo a > a
   13.56 +echo b > b
   13.57 +mkdir c
   13.58 +mkdir c/a
   13.59 +echo c > c/a/c
   13.60 +hg ci -Ama
   13.61 +
   13.62 +#$ name: simple
   13.63 +
   13.64 +hg copy a c
   13.65 +
   13.66 +#$ name: dir-dest
   13.67 +
   13.68 +mkdir d
   13.69 +hg copy a b d
   13.70 +ls d
   13.71 +
   13.72 +#$ name: dir-src
   13.73 +
   13.74 +hg copy c e
   13.75 +
   13.76 +#$ name: dir-src-dest
   13.77 +
   13.78 +hg copy c d
   13.79 +
   13.80 +#$ name: after
   13.81 +
   13.82 +cp a z
   13.83 +hg copy --after a z

    14.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    14.2 +++ b/en/examples/daily.files	Mon Mar 05 20:16:36 2007 -0800
    14.3 @@ -0,0 +1,97 @@
    14.4 +#!/bin/bash
    14.5 +
    14.6 +#$ name: add
    14.7 +
    14.8 +hg init add-example
    14.9 +cd add-example
   14.10 +echo a > a
   14.11 +hg status
   14.12 +hg add a
   14.13 +hg status
   14.14 +hg commit -m 'Added one file'
   14.15 +hg status
   14.16 +
   14.17 +#$ name: add-dir
   14.18 +
   14.19 +mkdir b
   14.20 +echo b > b/b
   14.21 +echo c > b/c
   14.22 +mkdir b/d
   14.23 +echo d > b/d/d
   14.24 +hg add b
   14.25 +hg commit -m 'Added all files in subdirectory'
   14.26 +
   14.27 +#$ name:
   14.28 +
   14.29 +cd ..
   14.30 +
   14.31 +#$ name: hidden
   14.32 +
   14.33 +hg init hidden-example
   14.34 +cd hidden-example
   14.35 +mkdir empty
   14.36 +touch empty/.hidden
   14.37 +hg add empty/.hidden
   14.38 +hg commit -m 'Manage an empty-looking directory'
   14.39 +ls empty
   14.40 +cd ..
   14.41 +hg clone hidden-example tmp
   14.42 +ls tmp
   14.43 +ls tmp/empty
   14.44 +
   14.45 +#$ name:
   14.46 +
   14.47 +cd ..
   14.48 +
   14.49 +#$ name: remove
   14.50 +
   14.51 +hg init remove-example
   14.52 +cd remove-example
   14.53 +echo a > a
   14.54 +mkdir b
   14.55 +echo b > b/b
   14.56 +hg add a b
   14.57 +hg commit -m 'Small example for file removal'
   14.58 +hg remove a
   14.59 +hg status
   14.60 +hg remove b
   14.61 +
   14.62 +#$ name:
   14.63 +
   14.64 +cd ..
   14.65 +
   14.66 +#$ name: missing
   14.67 +hg init missing-example
   14.68 +cd missing-example
   14.69 +echo a > a
   14.70 +hg add a
   14.71 +hg commit -m'File about to be missing'
   14.72 +rm a
   14.73 +hg status
   14.74 +
   14.75 +#$ name: remove-after
   14.76 +
   14.77 +hg remove --after a
   14.78 +hg status
   14.79 +
   14.80 +#$ name: recover-missing
   14.81 +hg revert a
   14.82 +cat a
   14.83 +hg status
   14.84 +
   14.85 +#$ name:
   14.86 +
   14.87 +cd ..
   14.88 +
   14.89 +#$ name: addremove
   14.90 +
   14.91 +hg init addremove-example
   14.92 +cd addremove-example
   14.93 +echo a > a
   14.94 +echo b > b
   14.95 +hg addremove
   14.96 +
   14.97 +#$ name: commit-addremove
   14.98 +
   14.99 +echo c > c
  14.100 +hg commit -A -m 'Commit with addremove'

    15.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    15.2 +++ b/en/examples/daily.rename	Mon Mar 05 20:16:36 2007 -0800
    15.3 @@ -0,0 +1,18 @@
    15.4 +#!/bin/bash
    15.5 +
    15.6 +hg init a
    15.7 +cd a
    15.8 +echo a > a
    15.9 +hg ci -Ama
   15.10 +
   15.11 +#$ name: rename
   15.12 +
   15.13 +hg rename a b
   15.14 +
   15.15 +#$ name: status
   15.16 +
   15.17 +hg status
   15.18 +
   15.19 +#$ name: status-copy
   15.20 +
   15.21 +hg status -C

    16.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    16.2 +++ b/en/examples/daily.revert	Mon Mar 05 20:16:36 2007 -0800
    16.3 @@ -0,0 +1,74 @@
    16.4 +#!/bin/bash
    16.5 +
    16.6 +hg init a
    16.7 +cd a
    16.8 +echo 'original content' > file
    16.9 +hg ci -Ama
   16.10 +
   16.11 +#$ name: modify
   16.12 +
   16.13 +cat file
   16.14 +echo unwanted change >> file
   16.15 +hg diff file
   16.16 +
   16.17 +#$ name: unmodify
   16.18 +
   16.19 +hg status
   16.20 +hg revert file
   16.21 +cat file
   16.22 +
   16.23 +#$ name: status
   16.24 +
   16.25 +hg status
   16.26 +cat file.orig
   16.27 +
   16.28 +#$ name:
   16.29 +
   16.30 +rm file.orig
   16.31 +
   16.32 +#$ name: add
   16.33 +
   16.34 +echo oops > oops
   16.35 +hg add oops
   16.36 +hg status oops
   16.37 +hg revert oops
   16.38 +hg status
   16.39 +
   16.40 +#$ name:
   16.41 +
   16.42 +rm oops
   16.43 +
   16.44 +#$ name: remove
   16.45 +
   16.46 +hg remove file
   16.47 +hg status
   16.48 +hg revert file
   16.49 +hg status
   16.50 +ls file
   16.51 +
   16.52 +#$ name: missing
   16.53 +
   16.54 +rm file
   16.55 +hg status
   16.56 +hg revert file
   16.57 +ls file
   16.58 +
   16.59 +#$ name: copy
   16.60 +
   16.61 +hg copy file new-file
   16.62 +hg revert new-file
   16.63 +hg status
   16.64 +
   16.65 +#$ name:
   16.66 +
   16.67 +rm new-file
   16.68 +
   16.69 +#$ name: rename
   16.70 +
   16.71 +hg rename file new-file
   16.72 +hg revert new-file
   16.73 +hg status
   16.74 +
   16.75 +#$ name: rename-orig
   16.76 +hg revert file
   16.77 +hg status

    17.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    17.2 +++ b/en/examples/data/check_whitespace.py	Mon Mar 05 20:16:36 2007 -0800
    17.3 @@ -0,0 +1,44 @@
    17.4 +#!/usr/bin/python
    17.5 +
    17.6 +import re
    17.7 +
    17.8 +def trailing_whitespace(difflines):
    17.9 +    added, linenum, header = [], 0, False
   17.10 +
   17.11 +    for line in difflines:
   17.12 +        if header:
   17.13 +            # remember the name of the file that this diff affects
   17.14 +            m = re.match(r'(?:---|\+\+\+) ([^\t]+)', line)
   17.15 +            if m and m.group(1) != '/dev/null':
   17.16 +                filename = m.group(1).split('/', 1)[-1]
   17.17 +            if line.startswith('+++ '):
   17.18 +                header = False
   17.19 +            continue
   17.20 +        if line.startswith('diff '):
   17.21 +            header = True
   17.22 +            continue
   17.23 +        # hunk header - save the line number
   17.24 +        m = re.match(r'@@ -\d+,\d+ \+(\d+),', line)
   17.25 +        if m:
   17.26 +            linenum = int(m.group(1))
   17.27 +            continue
   17.28 +        # hunk body - check for an added line with trailing whitespace
   17.29 +        m = re.match(r'\+.*\s$', line)
   17.30 +        if m:
   17.31 +            added.append((filename, linenum))
   17.32 +        if line and line[0] in ' +':
   17.33 +            linenum += 1
   17.34 +    return added
   17.35 +
   17.36 +if __name__ == '__main__':
   17.37 +    import os, sys
   17.38 +    
   17.39 +    added = trailing_whitespace(os.popen('hg export tip'))
   17.40 +    if added:
   17.41 +        for filename, linenum in added:
   17.42 +            print >> sys.stderr, ('%s, line %d: trailing whitespace added' %
   17.43 +                                  (filename, linenum))
   17.44 +        # save the commit message so we don't need to retype it
   17.45 +        os.system('hg tip --template "{desc}" > .hg/commit.save')
   17.46 +        print >> sys.stderr, 'commit message saved to .hg/commit.save'
   17.47 +        sys.exit(1)

    18.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    18.2 +++ b/en/examples/filenames	Mon Mar 05 20:16:36 2007 -0800
    18.3 @@ -0,0 +1,61 @@
    18.4 +#!/bin/bash
    18.5 +
    18.6 +hg init a
    18.7 +cd a
    18.8 +mkdir -p examples src/watcher
    18.9 +touch COPYING MANIFEST.in README setup.py
   18.10 +touch examples/performant.py examples/simple.py
   18.11 +touch src/main.py src/watcher/_watcher.c src/watcher/watcher.py src/xyzzy.txt
   18.12 +
   18.13 +#$ name: files
   18.14 +
   18.15 +hg add COPYING README examples/simple.py
   18.16 +
   18.17 +#$ name: dirs
   18.18 +
   18.19 +hg status src
   18.20 +
   18.21 +#$ name: wdir-subdir
   18.22 +
   18.23 +cd src
   18.24 +hg add -n
   18.25 +hg add -n .
   18.26 +
   18.27 +#$ name: wdir-relname
   18.28 +
   18.29 +hg status
   18.30 +hg status `hg root`
   18.31 +
   18.32 +#$ name: glob.star
   18.33 +
   18.34 +hg add 'glob:*.py'
   18.35 +
   18.36 +#$ name: glob.starstar
   18.37 +
   18.38 +cd ..
   18.39 +hg status 'glob:**.py'
   18.40 +
   18.41 +#$ name: glob.star-starstar
   18.42 +
   18.43 +hg status 'glob:*.py'
   18.44 +hg status 'glob:**.py'
   18.45 +
   18.46 +#$ name: glob.question
   18.47 +
   18.48 +hg status 'glob:**.?'
   18.49 +
   18.50 +#$ name: glob.range
   18.51 +
   18.52 +hg status 'glob:**[nr-t]'
   18.53 +
   18.54 +#$ name: glob.group
   18.55 +
   18.56 +hg status 'glob:*.{in,py}'
   18.57 +
   18.58 +#$ name: filter.include
   18.59 +
   18.60 +hg status -I '*.in'
   18.61 +
   18.62 +#$ name: filter.exclude
   18.63 +
   18.64 +hg status -X '**.py' src

    19.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    19.2 +++ b/en/examples/hook.msglen	Mon Mar 05 20:16:36 2007 -0800
    19.3 @@ -0,0 +1,14 @@
    19.4 +#!/bin/sh
    19.5 +
    19.6 +hg init a
    19.7 +cd a
    19.8 +echo '[hooks]' > .hg/hgrc
    19.9 +echo 'pretxncommit.msglen = test `hg tip --template {desc} | wc -c` -ge 10' >> .hg/hgrc
   19.10 +
   19.11 +#$ name: run
   19.12 +
   19.13 +cat .hg/hgrc
   19.14 +echo a > a
   19.15 +hg add a
   19.16 +hg commit -A -m 'too short'
   19.17 +hg commit -A -m 'long enough'

    20.1 --- a/en/examples/hook.simple	Fri Jul 21 22:42:19 2006 -0700
    20.2 +++ b/en/examples/hook.simple	Mon Mar 05 20:16:36 2007 -0800
    20.3 @@ -1,3 +1,5 @@
    20.4 +#!/bin/bash
    20.5 +
    20.6  #$ name: init
    20.7  
    20.8  hg init hook-test

    21.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    21.2 +++ b/en/examples/hook.ws	Mon Mar 05 20:16:36 2007 -0800
    21.3 @@ -0,0 +1,31 @@
    21.4 +#!/bin/bash
    21.5 +
    21.6 +hg init a
    21.7 +cd a
    21.8 +echo '[hooks]' > .hg/hgrc
    21.9 +echo "pretxncommit.whitespace = hg export tip | (! grep -qP '^\\+.*[ \\t]$')" >> .hg/hgrc
   21.10 +
   21.11 +#$ name: simple
   21.12 +
   21.13 +cat .hg/hgrc
   21.14 +echo 'a ' > a
   21.15 +hg commit -A -m 'test with trailing whitespace'
   21.16 +echo 'a' > a
   21.17 +hg commit -A -m 'drop trailing whitespace and try again'
   21.18 +
   21.19 +#$ name:
   21.20 +
   21.21 +echo '[hooks]' > .hg/hgrc
   21.22 +echo "pretxncommit.whitespace = check_whitespace.py" >> .hg/hgrc
   21.23 +cp $EXAMPLE_DIR/data/check_whitespace.py .
   21.24 +
   21.25 +#$ name: better
   21.26 +
   21.27 +cat .hg/hgrc
   21.28 +echo 'a ' >> a
   21.29 +hg commit -A -m 'add new line with trailing whitespace'
   21.30 +perl -pi -e 's,\s+$,,' a
   21.31 +hg commit -A -m 'trimmed trailing whitespace'
   21.32 +
   21.33 +#$ name:
   21.34 +exit 0

    22.1 --- a/en/examples/mq.diff	Fri Jul 21 22:42:19 2006 -0700
    22.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    22.3 @@ -1,12 +0,0 @@
    22.4 -#$ name: diff
    22.5 -
    22.6 -echo 'this is my first line' > oldfile
    22.7 -echo 'my first line is here' > newfile
    22.8 -
    22.9 -diff -u oldfile newfile > tiny.patch
   22.10 -
   22.11 -cat tiny.patch
   22.12 -
   22.13 -patch < tiny.patch
   22.14 -
   22.15 -cat newfile

    23.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    23.2 +++ b/en/examples/mq.dodiff	Mon Mar 05 20:16:36 2007 -0800
    23.3 @@ -0,0 +1,14 @@
    23.4 +#!/bin/bash
    23.5 +
    23.6 +#$ name: diff
    23.7 +
    23.8 +echo 'this is my first line' > oldfile
    23.9 +echo 'my first line is here' > newfile
   23.10 +
   23.11 +diff -u oldfile newfile > tiny.patch
   23.12 +
   23.13 +cat tiny.patch
   23.14 +
   23.15 +patch < tiny.patch
   23.16 +
   23.17 +cat newfile

    24.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    24.2 +++ b/en/examples/mq.guards	Mon Mar 05 20:16:36 2007 -0800
    24.3 @@ -0,0 +1,67 @@
    24.4 +#!/bin/bash
    24.5 +
    24.6 +echo '[extensions]' >> $HGRC
    24.7 +echo 'hgext.mq =' >> $HGRC
    24.8 +
    24.9 +hg init a
   24.10 +cd a
   24.11 +
   24.12 +#$ name: init
   24.13 +
   24.14 +hg qinit
   24.15 +hg qnew hello.patch
   24.16 +echo hello > hello
   24.17 +hg add hello
   24.18 +hg qrefresh
   24.19 +hg qnew goodbye.patch
   24.20 +echo goodbye > goodbye
   24.21 +hg add goodbye
   24.22 +hg qrefresh
   24.23 +
   24.24 +#$ name: qguard
   24.25 +
   24.26 +hg qguard
   24.27 +
   24.28 +#$ name: qguard.pos
   24.29 +
   24.30 +hg qguard +foo
   24.31 +hg qguard
   24.32 +
   24.33 +#$ name: qguard.neg
   24.34 +
   24.35 +hg qguard hello.patch -quux
   24.36 +hg qguard hello.patch
   24.37 +
   24.38 +#$ name: series
   24.39 +
   24.40 +cat .hg/patches/series
   24.41 +
   24.42 +#$ name: qselect.foo
   24.43 +
   24.44 +hg qpop -a
   24.45 +hg qselect
   24.46 +hg qselect foo
   24.47 +hg qselect
   24.48 +
   24.49 +#$ name: qselect.cat
   24.50 +
   24.51 +cat .hg/patches/guards
   24.52 +
   24.53 +#$ name: qselect.qpush
   24.54 +hg qpush -a
   24.55 +
   24.56 +#$ name: qselect.error
   24.57 +
   24.58 +hg qselect +foo
   24.59 +
   24.60 +#$ name: qselect.quux
   24.61 +
   24.62 +hg qselect quux
   24.63 +hg qpop -a
   24.64 +hg qpush -a
   24.65 +
   24.66 +#$ name: qselect.foobar
   24.67 +
   24.68 +hg qselect foo bar
   24.69 +hg qpop -a
   24.70 +hg qpush -a

    25.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    25.2 +++ b/en/examples/mq.id	Mon Mar 05 20:16:36 2007 -0800
    25.3 @@ -0,0 +1,28 @@
    25.4 +#!/bin/sh
    25.5 +
    25.6 +echo '[extensions]' >> $HGRC
    25.7 +echo 'hgext.mq =' >> $HGRC
    25.8 +
    25.9 +hg init a
   25.10 +cd a
   25.11 +hg qinit
   25.12 +echo 'int x;' > test.c
   25.13 +hg ci -Ama
   25.14 +
   25.15 +hg qnew first.patch
   25.16 +echo 'float c;' >> test.c
   25.17 +hg qrefresh
   25.18 +
   25.19 +hg qnew second.patch
   25.20 +echo 'double u;' > other.c
   25.21 +hg add other.c
   25.22 +hg qrefresh
   25.23 +
   25.24 +#$ name: out
   25.25 +
   25.26 +hg qapplied
   25.27 +hg log -r qbase:qtip
   25.28 +hg export second.patch
   25.29 +
   25.30 +#$ name:
   25.31 +exit 0

    26.1 --- a/en/examples/mq.qinit-help	Fri Jul 21 22:42:19 2006 -0700
    26.2 +++ b/en/examples/mq.qinit-help	Mon Mar 05 20:16:36 2007 -0800
    26.3 @@ -1,3 +1,5 @@
    26.4 +#!/bin/bash
    26.5 +
    26.6  echo '[extensions]' >> $HGRC
    26.7  echo 'hgext.mq =' >> $HGRC
    26.8  

    27.1 --- a/en/examples/mq.tarball	Fri Jul 21 22:42:19 2006 -0700
    27.2 +++ b/en/examples/mq.tarball	Mon Mar 05 20:16:36 2007 -0800
    27.3 @@ -1,3 +1,5 @@
    27.4 +#!/bin/bash
    27.5 +
    27.6  cp $EXAMPLE_DIR/data/netplug-*.tar.bz2 .
    27.7  ln -s /bin/true download
    27.8  

    28.1 --- a/en/examples/mq.tools	Fri Jul 21 22:42:19 2006 -0700
    28.2 +++ b/en/examples/mq.tools	Mon Mar 05 20:16:36 2007 -0800
    28.3 @@ -1,3 +1,5 @@
    28.4 +#!/bin/bash
    28.5 +
    28.6  cp $EXAMPLE_DIR/data/remove-redundant-null-checks.patch .
    28.7  
    28.8  #$ name: tools

    29.1 --- a/en/examples/mq.tutorial	Fri Jul 21 22:42:19 2006 -0700
    29.2 +++ b/en/examples/mq.tutorial	Mon Mar 05 20:16:36 2007 -0800
    29.3 @@ -1,3 +1,5 @@
    29.4 +#!/bin/bash
    29.5 +
    29.6  echo '[extensions]' >> $HGRC
    29.7  echo 'hgext.mq =' >> $HGRC
    29.8  
    29.9 @@ -66,3 +68,6 @@
   29.10  echo 'file 3, line 1' >> file3
   29.11  hg qnew add-file3.patch
   29.12  hg qnew -f add-file3.patch
   29.13 +
   29.14 +#$ name:
   29.15 +exit 0

    30.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    30.2 +++ b/en/examples/rollback	Mon Mar 05 20:16:36 2007 -0800
    30.3 @@ -0,0 +1,37 @@
    30.4 +#!/bin/bash
    30.5 +
    30.6 +hg init a
    30.7 +cd a
    30.8 +echo a > a
    30.9 +hg ci -A -m 'First commit'
   30.10 +
   30.11 +echo a >> a
   30.12 +
   30.13 +#$ name: tip
   30.14 +
   30.15 +#$ name: commit
   30.16 +
   30.17 +hg status
   30.18 +echo b > b
   30.19 +hg commit -m 'Add file b'
   30.20 +
   30.21 +#$ name: status
   30.22 +
   30.23 +hg status
   30.24 +hg tip
   30.25 +
   30.26 +#$ name: rollback
   30.27 +
   30.28 +hg rollback
   30.29 +hg tip
   30.30 +hg status
   30.31 +
   30.32 +#$ name: add
   30.33 +
   30.34 +hg add b
   30.35 +hg commit -m 'Add file b, this time for real'
   30.36 +
   30.37 +#$ name: twice
   30.38 +
   30.39 +hg rollback
   30.40 +hg rollback

    31.1 --- a/en/examples/run-example	Fri Jul 21 22:42:19 2006 -0700
    31.2 +++ b/en/examples/run-example	Mon Mar 05 20:16:36 2007 -0800
    31.3 @@ -1,13 +1,16 @@
    31.4 -#!/usr/bin/python
    31.5 +#!/usr/bin/env python
    31.6  #
    31.7  # This program takes something that resembles a shell script and runs
    31.8  # it, spitting input (commands from the script) and output into text
    31.9  # files, for use in examples.
   31.10  
   31.11  import cStringIO
   31.12 +import errno
   31.13 +import getopt
   31.14  import os
   31.15  import pty
   31.16  import re
   31.17 +import select
   31.18  import shutil
   31.19  import signal
   31.20  import stat
   31.21 @@ -15,22 +18,37 @@
   31.22  import tempfile
   31.23  import time
   31.24  
   31.25 +tex_subs = {
   31.26 +    '\\': '\\textbackslash{}',
   31.27 +    '{': '\\{',
   31.28 +    '}': '\\}',
   31.29 +    }
   31.30 +
   31.31 +def gensubs(s):
   31.32 +    start = 0
   31.33 +    for i, c in enumerate(s):
   31.34 +        sub = tex_subs.get(c)
   31.35 +        if sub:
   31.36 +            yield s[start:i]
   31.37 +            start = i + 1
   31.38 +            yield sub
   31.39 +    yield s[start:]
   31.40 +
   31.41  def tex_escape(s):
   31.42 -    if '\\' in s:
   31.43 -        s = s.replace('\\', '\\\\')
   31.44 -    if '{' in s:
   31.45 -        s = s.replace('{', '\\{')
   31.46 -    if '}' in s:
   31.47 -        s = s.replace('}', '\\}')
   31.48 -    return s
   31.49 +    return ''.join(gensubs(s))
   31.50          
   31.51  class example:
   31.52 -    shell = '/bin/bash'
   31.53 -    prompt = '__run_example_prompt__\n'
   31.54 -    pi_re = re.compile('#\$\s*(name):\s*(.*)$')
   31.55 +    shell = '/usr/bin/env bash'
   31.56 +    ps1 = '__run_example_ps1__ '
   31.57 +    ps2 = '__run_example_ps2__ '
   31.58 +    pi_re = re.compile(r'#\$\s*(name):\s*(.*)$')
   31.59      
   31.60 -    def __init__(self, name):
   31.61 +    timeout = 5
   31.62 +
   31.63 +    def __init__(self, name, verbose):
   31.64          self.name = name
   31.65 +        self.verbose = verbose
   31.66 +        self.poll = select.poll()
   31.67  
   31.68      def parse(self):
   31.69          '''yield each hunk of input from the file.'''
   31.70 @@ -49,35 +67,75 @@
   31.71              sys.stdout.flush()
   31.72  
   31.73      def send(self, s):
   31.74 -        self.cfp.write(s)
   31.75 -        self.cfp.flush()
   31.76 -
   31.77 +        if self.verbose:
   31.78 +            print >> sys.stderr, '>', self.debugrepr(s)
   31.79 +        while s:
   31.80 +            count = os.write(self.cfd, s)
   31.81 +            s = s[count:]
   31.82 +
   31.83 +    def debugrepr(self, s):
   31.84 +        rs = repr(s)
   31.85 +        limit = 60
   31.86 +        if len(rs) > limit:
   31.87 +            return ('%s%s ... [%d bytes]' % (rs[:limit], rs[0], len(s)))
   31.88 +        else:
   31.89 +            return rs
   31.90 +            
   31.91 +    timeout = 5
   31.92 +
   31.93 +    def read(self):
   31.94 +        events = self.poll.poll(self.timeout * 1000)
   31.95 +        if not events:
   31.96 +            print >> sys.stderr, '[timed out after %d seconds]' % self.timeout
   31.97 +            os.kill(self.pid, signal.SIGHUP)
   31.98 +            return ''
   31.99 +        return os.read(self.cfd, 1024)
  31.100 +        
  31.101      def receive(self):
  31.102          out = cStringIO.StringIO()
  31.103          while True:
  31.104 -            s = self.cfp.readline().replace('\r\n', '\n')
  31.105 -            if not s or s == self.prompt:
  31.106 -                break
  31.107 +            try:
  31.108 +                if self.verbose:
  31.109 +                    sys.stderr.write('< ')
  31.110 +                s = self.read()
  31.111 +            except OSError, err:
  31.112 +                if err.errno == errno.EIO:
  31.113 +                    return '', ''
  31.114 +                raise
  31.115 +            if self.verbose:
  31.116 +                print >> sys.stderr, self.debugrepr(s)
  31.117              out.write(s)
  31.118 -        return out.getvalue()
  31.119 +            s = out.getvalue()
  31.120 +            if s.endswith(self.ps1):
  31.121 +                return self.ps1, s.replace('\r\n', '\n')[:-len(self.ps1)]
  31.122 +            if s.endswith(self.ps2):
  31.123 +                return self.ps2, s.replace('\r\n', '\n')[:-len(self.ps2)]
  31.124          
  31.125      def sendreceive(self, s):
  31.126          self.send(s)
  31.127 -        r = self.receive()
  31.128 +        ps, r = self.receive()
  31.129          if r.startswith(s):
  31.130              r = r[len(s):]
  31.131 -        return r
  31.132 +        return ps, r
  31.133      
  31.134      def run(self):
  31.135          ofp = None
  31.136          basename = os.path.basename(self.name)
  31.137          self.status('running %s ' % basename)
  31.138          tmpdir = tempfile.mkdtemp(prefix=basename)
  31.139 +
  31.140 +        rcfile = os.path.join(tmpdir, '.hgrc')
  31.141 +        rcfp = open(rcfile, 'w')
  31.142 +        print >> rcfp, '[ui]'
  31.143 +        print >> rcfp, "username = Bryan O'Sullivan <bos@serpentine.com>"
  31.144 +        
  31.145          rcfile = os.path.join(tmpdir, '.bashrc')
  31.146          rcfp = open(rcfile, 'w')
  31.147 -        print >> rcfp, 'PS1="%s"' % self.prompt
  31.148 +        print >> rcfp, 'PS1="%s"' % self.ps1
  31.149 +        print >> rcfp, 'PS2="%s"' % self.ps2
  31.150          print >> rcfp, 'unset HISTFILE'
  31.151          print >> rcfp, 'export EXAMPLE_DIR="%s"' % os.getcwd()
  31.152 +        print >> rcfp, 'export HGMERGE=merge'
  31.153          print >> rcfp, 'export LANG=C'
  31.154          print >> rcfp, 'export LC_ALL=C'
  31.155          print >> rcfp, 'export TZ=GMT'
  31.156 @@ -85,69 +143,121 @@
  31.157          print >> rcfp, 'export HGRCPATH=$HGRC'
  31.158          print >> rcfp, 'cd %s' % tmpdir
  31.159          rcfp.close()
  31.160 -        pid, fd = pty.fork()
  31.161 -        if pid == 0:
  31.162 -            #os.execl(self.shell, self.shell)
  31.163 -            os.system('/bin/bash --noediting --noprofile --norc')
  31.164 -            sys.exit(0)
  31.165 -        self.cfp = os.fdopen(fd, 'w+')
  31.166 +        sys.stdout.flush()
  31.167 +        sys.stderr.flush()
  31.168 +        self.pid, self.cfd = pty.fork()
  31.169 +        if self.pid == 0:
  31.170 +            cmdline = ['/usr/bin/env', 'bash', '--noediting', '--noprofile',
  31.171 +                       '--norc']
  31.172 +            try:
  31.173 +                os.execv(cmdline[0], cmdline)
  31.174 +            except OSError, err:
  31.175 +                print >> sys.stderr, '%s: %s' % (cmdline[0], err.strerror)
  31.176 +                sys.stderr.flush()
  31.177 +                os._exit(0)
  31.178 +        self.poll.register(self.cfd, select.POLLIN | select.POLLERR |
  31.179 +                           select.POLLHUP)
  31.180 +
  31.181 +        prompts = {
  31.182 +            '': '',
  31.183 +            self.ps1: '$',
  31.184 +            self.ps2: '>',
  31.185 +            }
  31.186 +
  31.187          try:
  31.188 -            # setup env and prompt
  31.189 -            self.sendreceive('source %s\n\n' % rcfile)
  31.190 -            for hunk in self.parse():
  31.191 -                # is this line a processing instruction?
  31.192 -                m = self.pi_re.match(hunk)
  31.193 -                if m:
  31.194 -                    pi, rest = m.groups()
  31.195 -                    if pi == 'name':
  31.196 -                        self.status('.')
  31.197 -                        out = rest
  31.198 -                        assert os.sep not in out
  31.199 -                        if out:
  31.200 -                            ofp = open('%s.%s.out' % (self.name, out), 'w')
  31.201 -                        else:
  31.202 -                            ofp = None
  31.203 -                elif hunk.strip():
  31.204 -                    # it's something we should execute
  31.205 -                    output = self.sendreceive(hunk)
  31.206 -                    if not ofp:
  31.207 -                        continue
  31.208 -                    # first, print the command we ran
  31.209 -                    if not hunk.startswith('#'):
  31.210 -                        nl = hunk.endswith('\n')
  31.211 -                        hunk = ('$ \\textbf{%s}' %
  31.212 -                                tex_escape(hunk.rstrip('\n')))
  31.213 -                        if nl: hunk += '\n'
  31.214 -                    ofp.write(hunk)
  31.215 -                    # then its output
  31.216 -                    ofp.write(tex_escape(output))
  31.217 -            self.status('\n')
  31.218 +            try:
  31.219 +                # eat first prompt string from shell
  31.220 +                self.read()
  31.221 +                # setup env and prompt
  31.222 +                ps, output = self.sendreceive('source %s\n' % rcfile)
  31.223 +                for hunk in self.parse():
  31.224 +                    # is this line a processing instruction?
  31.225 +                    m = self.pi_re.match(hunk)
  31.226 +                    if m:
  31.227 +                        pi, rest = m.groups()
  31.228 +                        if pi == 'name':
  31.229 +                            self.status('.')
  31.230 +                            out = rest
  31.231 +                            assert os.sep not in out
  31.232 +                            if out:
  31.233 +                                ofp = open('%s.%s.out' % (self.name, out), 'w')
  31.234 +                            else:
  31.235 +                                ofp = None
  31.236 +                    elif hunk.strip():
  31.237 +                        # it's something we should execute
  31.238 +                        newps, output = self.sendreceive(hunk)
  31.239 +                        if not ofp:
  31.240 +                            continue
  31.241 +                        # first, print the command we ran
  31.242 +                        if not hunk.startswith('#'):
  31.243 +                            nl = hunk.endswith('\n')
  31.244 +                            hunk = ('%s \\textbf{%s}' %
  31.245 +                                    (prompts[ps],
  31.246 +                                     tex_escape(hunk.rstrip('\n'))))
  31.247 +                            if nl: hunk += '\n'
  31.248 +                        ofp.write(hunk)
  31.249 +                        # then its output
  31.250 +                        ofp.write(tex_escape(output))
  31.251 +                    ps = newps
  31.252 +                self.status('\n')
  31.253 +                open(self.name + '.run', 'w')
  31.254 +            except:
  31.255 +                print >> sys.stderr, '(killed)'
  31.256 +                os.kill(self.pid, signal.SIGKILL)
  31.257 +                pid, rc = os.wait()
  31.258 +                raise
  31.259 +            else:
  31.260 +                try:
  31.261 +                    ps, output = self.sendreceive('exit\n')
  31.262 +                    if ofp:
  31.263 +                        ofp.write(output)
  31.264 +                    os.close(self.cfd)
  31.265 +                except IOError:
  31.266 +                    pass
  31.267 +                os.kill(self.pid, signal.SIGTERM)
  31.268 +                pid, rc = os.wait()
  31.269 +                if rc:
  31.270 +                    if os.WIFEXITED(rc):
  31.271 +                        print >> sys.stderr, '(exit %s)' % os.WEXITSTATUS(rc)
  31.272 +                    elif os.WIFSIGNALED(rc):
  31.273 +                        print >> sys.stderr, '(signal %s)' % os.WTERMSIG(rc)
  31.274 +                return rc
  31.275          finally:
  31.276 -            try:
  31.277 -                output = self.sendreceive('exit\n')
  31.278 -                if ofp:
  31.279 -                    ofp.write(output)
  31.280 -                self.cfp.close()
  31.281 -            except IOError:
  31.282 -                pass
  31.283 -            os.kill(pid, signal.SIGTERM)
  31.284 -            os.wait()
  31.285              shutil.rmtree(tmpdir)
  31.286  
  31.287  def main(path='.'):
  31.288 -    args = sys.argv[1:]
  31.289 +    opts, args = getopt.getopt(sys.argv[1:], 'v', ['verbose'])
  31.290 +    verbose = False
  31.291 +    for o, a in opts:
  31.292 +        if o in ('-v', '--verbose'):
  31.293 +            verbose = True
  31.294 +    errs = 0
  31.295      if args:
  31.296          for a in args:
  31.297 -            example(a).run()
  31.298 -        return
  31.299 +            try:
  31.300 +                st = os.lstat(a)
  31.301 +            except OSError, err:
  31.302 +                print >> sys.stderr, '%s: %s' % (a, err.strerror)
  31.303 +                errs += 1
  31.304 +                continue
  31.305 +            if stat.S_ISREG(st.st_mode) and st.st_mode & 0111:
  31.306 +                if example(a, verbose).run():
  31.307 +                    errs += 1
  31.308 +            else:
  31.309 +                print >> sys.stderr, '%s: not a file, or not executable' % a
  31.310 +                errs += 1
  31.311 +        return errs
  31.312      for name in os.listdir(path):
  31.313          if name == 'run-example' or name.startswith('.'): continue
  31.314          if name.endswith('.out') or name.endswith('~'): continue
  31.315 +        if name.endswith('.run'): continue
  31.316          pathname = os.path.join(path, name)
  31.317          st = os.lstat(pathname)
  31.318          if stat.S_ISREG(st.st_mode) and st.st_mode & 0111:
  31.319 -            example(pathname).run()
  31.320 +            if example(pathname, verbose).run():
  31.321 +                errs += 1
  31.322      print >> open(os.path.join(path, '.run'), 'w'), time.asctime()
  31.323 +    return errs
  31.324  
  31.325  if __name__ == '__main__':
  31.326 -    main()
  31.327 +    sys.exit(main())

    32.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    32.2 +++ b/en/examples/svn-long.txt	Mon Mar 05 20:16:36 2007 -0800
    32.3 @@ -0,0 +1,11 @@
    32.4 +------------------------------------------------------------------------
    32.5 +r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 5 lines
    32.6 +Changed paths:
    32.7 +   M /gen2/trunk/src/linux-kernel/infiniband/core/cma.c
    32.8 +
    32.9 +On reporting a route error, also include the status for the error,
   32.10 +rather than indicating a status of 0 when an error has occurred.
   32.11 +
   32.12 +Signed-off-by: Sean Hefty <sean.hefty@intel.com>
   32.13 +
   32.14 +------------------------------------------------------------------------

    33.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    33.2 +++ b/en/examples/svn-short.txt	Mon Mar 05 20:16:36 2007 -0800
    33.3 @@ -0,0 +1,9 @@
    33.4 +------------------------------------------------------------------------
    33.5 +r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 5 lines
    33.6 +
    33.7 +On reporting a route error, also include the status for the error,
    33.8 +rather than indicating a status of 0 when an error has occurred.
    33.9 +
   33.10 +Signed-off-by: Sean Hefty <sean.hefty@intel.com>
   33.11 +
   33.12 +------------------------------------------------------------------------

    34.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    34.2 +++ b/en/examples/svn.style	Mon Mar 05 20:16:36 2007 -0800
    34.3 @@ -0,0 +1,2 @@
    34.4 +header = '------------------------------------------------------------------------\n\n'
    34.5 +changeset = svn.template

    35.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    35.2 +++ b/en/examples/svn.template	Mon Mar 05 20:16:36 2007 -0800
    35.3 @@ -0,0 +1,5 @@
    35.4 +r{rev} | {author|user} | {date|isodate} ({date|rfc822date})
    35.5 +
    35.6 +{desc|strip|fill76}
    35.7 +
    35.8 +------------------------------------------------------------------------

    36.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    36.2 +++ b/en/examples/template.simple	Mon Mar 05 20:16:36 2007 -0800
    36.3 @@ -0,0 +1,92 @@
    36.4 +#!/bin/bash
    36.5 +
    36.6 +hg init myrepo
    36.7 +cd myrepo
    36.8 +echo hello > hello
    36.9 +hg commit -Am'added hello'
   36.10 +
   36.11 +echo hello >> hello
   36.12 +echo goodbye > goodbye
   36.13 +echo '   added line to end of <<hello>> file.' > ../msg
   36.14 +echo '' >> ../msg
   36.15 +echo 'in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.' >> ../msg
   36.16 +
   36.17 +hg commit -Al../msg
   36.18 +
   36.19 +hg tag mytag
   36.20 +hg tag v0.1
   36.21 +
   36.22 +#$ name: normal
   36.23 +
   36.24 +hg log -r1
   36.25 +
   36.26 +#$ name: compact
   36.27 +
   36.28 +hg log --style compact
   36.29 +
   36.30 +#$ name: changelog
   36.31 +
   36.32 +hg log --style changelog
   36.33 +
   36.34 +#$ name: simplest
   36.35 +
   36.36 +hg log -r1 --template 'i saw a changeset\n'
   36.37 +
   36.38 +#$ name: simplesub
   36.39 +
   36.40 +hg log --template 'i saw a changeset: {desc}\n'
   36.41 +
   36.42 +#$ name: keywords
   36.43 +
   36.44 +hg log -r1 --template 'author: {author}\n'
   36.45 +hg log -r1 --template 'desc:\n{desc}\n'
   36.46 +hg log -r1 --template 'files: {files}\n'
   36.47 +hg log -r1 --template 'file_adds: {file_adds}\n'
   36.48 +hg log -r1 --template 'file_dels: {file_dels}\n'
   36.49 +hg log -r1 --template 'node: {node}\n'
   36.50 +hg log -r1 --template 'parents: {parents}\n'
   36.51 +hg log -r1 --template 'rev: {rev}\n'
   36.52 +hg log -r1 --template 'tags: {tags}\n'
   36.53 +
   36.54 +#$ name: datekeyword
   36.55 +
   36.56 +hg log -r1 --template 'date: {date}\n'
   36.57 +hg log -r1 --template 'date: {date|isodate}\n'
   36.58 +
   36.59 +#$ name: manyfilters
   36.60 +
   36.61 +hg log -r1 --template '{author}\n'
   36.62 +hg log -r1 --template '{author|domain}\n'
   36.63 +hg log -r1 --template '{author|email}\n'
   36.64 +hg log -r1 --template '{author|obfuscate}\n' | cut -c-76
   36.65 +hg log -r1 --template '{author|person}\n'
   36.66 +hg log -r1 --template '{author|user}\n'
   36.67 +
   36.68 +hg log -r1 --template 'looks almost right, but actually garbage: {date}\n'
   36.69 +hg log -r1 --template '{date|age}\n'
   36.70 +hg log -r1 --template '{date|date}\n'
   36.71 +hg log -r1 --template '{date|hgdate}\n'
   36.72 +hg log -r1 --template '{date|isodate}\n'
   36.73 +hg log -r1 --template '{date|rfc822date}\n'
   36.74 +hg log -r1 --template '{date|shortdate}\n'
   36.75 +
   36.76 +hg log -r1 --template '{desc}\n' | cut -c-76
   36.77 +hg log -r1 --template '{desc|addbreaks}\n' | cut -c-76
   36.78 +hg log -r1 --template '{desc|escape}\n' | cut -c-76
   36.79 +hg log -r1 --template '{desc|fill68}\n'
   36.80 +hg log -r1 --template '{desc|fill76}\n'
   36.81 +hg log -r1 --template '{desc|firstline}\n'
   36.82 +hg log -r1 --template '{desc|strip}\n' | cut -c-76
   36.83 +hg log -r1 --template '{desc|tabindent}\n' | expand | cut -c-76
   36.84 +
   36.85 +hg log -r1 --template '{node}\n'
   36.86 +hg log -r1 --template '{node|short}\n'
   36.87 +
   36.88 +#$ name: combine
   36.89 +
   36.90 +hg log -r1 --template 'description:\n\t{desc|strip|fill68|tabindent}\n'
   36.91 +
   36.92 +#$ name: rev
   36.93 +
   36.94 +echo 'changeset = "rev: {rev}\n"' > rev
   36.95 +hg log -l1 --style ./rev

    37.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    37.2 +++ b/en/examples/template.svnstyle	Mon Mar 05 20:16:36 2007 -0800
    37.3 @@ -0,0 +1,69 @@
    37.4 +#!/bin/bash
    37.5 +
    37.6 +svn() {
    37.7 +  cat $EXAMPLE_DIR/svn-short.txt
    37.8 +}
    37.9 +
   37.10 +#$ name: short
   37.11 +
   37.12 +svn log -r9653
   37.13 +
   37.14 +#$ name:
   37.15 +
   37.16 +hg init myrepo
   37.17 +cd myrepo
   37.18 +
   37.19 +echo hello > hello
   37.20 +hg commit -Am'added hello'
   37.21 +
   37.22 +echo hello >> hello
   37.23 +echo goodbye > goodbye
   37.24 +echo '   added line to end of <<hello>> file.' > ../msg
   37.25 +echo '' >> ../msg
   37.26 +echo 'in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.' >> ../msg
   37.27 +
   37.28 +hg commit -Al../msg
   37.29 +
   37.30 +hg tag mytag
   37.31 +hg tag v0.1
   37.32 +
   37.33 +echo 'changeset = "{node|short}\n"' > svn.style
   37.34 +
   37.35 +#$ name: id
   37.36 +
   37.37 +hg log -r0 --template '{node}'
   37.38 +
   37.39 +#$ name: simplest
   37.40 +
   37.41 +cat svn.style
   37.42 +hg log -r1 --style svn.style
   37.43 +
   37.44 +#$ name:
   37.45 +
   37.46 +echo 'changeset =' > broken.style
   37.47 +
   37.48 +#$ name: syntax.input
   37.49 +
   37.50 +cat broken.style
   37.51 +
   37.52 +#$ name: syntax.error
   37.53 +
   37.54 +hg log -r1 --style broken.style
   37.55 +
   37.56 +#$ name:
   37.57 +
   37.58 +cp $EXAMPLE_DIR/svn.style .
   37.59 +cp $EXAMPLE_DIR/svn.template .
   37.60 +
   37.61 +#$ name: template
   37.62 +
   37.63 +cat svn.template
   37.64 +
   37.65 +#$ name: style
   37.66 +
   37.67 +cat svn.style
   37.68 +
   37.69 +#$ name: result
   37.70 +
   37.71 +hg log -r1 --style svn.style
   37.72 +

    38.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    38.2 +++ b/en/examples/tour	Mon Mar 05 20:16:36 2007 -0800
    38.3 @@ -0,0 +1,186 @@
    38.4 +#!/bin/bash
    38.5 +
    38.6 +#$ name: version
    38.7 +
    38.8 +hg version
    38.9 +
   38.10 +#$ name: help
   38.11 +
   38.12 +hg help init
   38.13 +
   38.14 +#$ name: clone
   38.15 +
   38.16 +hg clone http://hg.serpentine.com/tutorial/hello
   38.17 +
   38.18 +#$ name: ls
   38.19 +
   38.20 +ls -l
   38.21 +ls hello
   38.22 +
   38.23 +#$ name: ls-a
   38.24 +
   38.25 +cd hello
   38.26 +ls -a
   38.27 +
   38.28 +#$ name: log
   38.29 +
   38.30 +hg log
   38.31 +
   38.32 +#$ name: log-r
   38.33 +
   38.34 +hg log -r 3
   38.35 +hg log -r ff5d7b70a2a9
   38.36 +hg log -r 1 -r 4
   38.37 +
   38.38 +#$ name: log.range
   38.39 +
   38.40 +hg log -r 2:4
   38.41 +
   38.42 +#$ name: log-v
   38.43 +
   38.44 +hg log -v -r 3
   38.45 +
   38.46 +#$ name: log-vp
   38.47 +
   38.48 +hg log -v -p -r 2
   38.49 +
   38.50 +#$ name: reclone
   38.51 +
   38.52 +cd ..
   38.53 +hg clone hello my-hello
   38.54 +cd my-hello
   38.55 +
   38.56 +#$ name: sed
   38.57 +
   38.58 +sed -i '/printf/a\\tprintf("hello again!\\n");' hello.c
   38.59 +
   38.60 +#$ name: status
   38.61 +
   38.62 +ls
   38.63 +hg status
   38.64 +
   38.65 +#$ name: diff
   38.66 +
   38.67 +hg diff
   38.68 +
   38.69 +#$ name:
   38.70 +
   38.71 +export HGEDITOR='echo Added an extra line of output >'
   38.72 +HGRCPATH_ORIG=$HGRCPATH
   38.73 +export HGRCPATH=
   38.74 +
   38.75 +#$ name: commit-no-user
   38.76 +
   38.77 +hg commit
   38.78 +
   38.79 +#$ name:
   38.80 +
   38.81 +export HGRCPATH=$HGRCPATH_ORIG
   38.82 +
   38.83 +#$ name: commit
   38.84 +
   38.85 +hg commit
   38.86 +
   38.87 +#$ name: tip
   38.88 +
   38.89 +hg tip -vp
   38.90 +
   38.91 +#$ name: clone-pull
   38.92 +
   38.93 +cd ..
   38.94 +hg clone hello hello-pull
   38.95 +
   38.96 +#$ name: incoming
   38.97 +
   38.98 +cd hello-pull
   38.99 +hg incoming ../my-hello
  38.100 +
  38.101 +#$ name: pull
  38.102 +
  38.103 +hg tip
  38.104 +hg pull ../my-hello
  38.105 +hg tip
  38.106 +
  38.107 +#$ name: update
  38.108 +
  38.109 +grep printf hello.c
  38.110 +hg update tip
  38.111 +grep printf hello.c
  38.112 +
  38.113 +#$ name: parents
  38.114 +
  38.115 +hg parents
  38.116 +
  38.117 +#$ name: older
  38.118 +
  38.119 +hg update 2
  38.120 +hg parents
  38.121 +hg update
  38.122 +
  38.123 +#$ name: clone-push
  38.124 +
  38.125 +cd ..
  38.126 +hg clone hello hello-push
  38.127 +
  38.128 +#$ name: outgoing
  38.129 +
  38.130 +cd my-hello
  38.131 +hg outgoing ../hello-push
  38.132 +
  38.133 +#$ name: push
  38.134 +
  38.135 +hg push ../hello-push
  38.136 +
  38.137 +#$ name: push.nothing
  38.138 +
  38.139 +hg push ../hello-push
  38.140 +
  38.141 +#$ name: outgoing.net
  38.142 +
  38.143 +hg outgoing http://hg.serpentine.com/tutorial/hello
  38.144 +
  38.145 +#$ name: push.net
  38.146 +
  38.147 +hg push http://hg.serpentine.com/tutorial/hello
  38.148 +
  38.149 +#$ name: merge.clone
  38.150 +
  38.151 +cd ..
  38.152 +hg clone hello my-new-hello
  38.153 +cd my-new-hello
  38.154 +sed -i '/printf/i\\tprintf("once more, hello.\\n");' hello.c
  38.155 +hg commit -m 'A new hello for a new day.'
  38.156 +
  38.157 +#$ name: merge.cat
  38.158 +
  38.159 +cat hello.c
  38.160 +cat ../my-hello/hello.c
  38.161 +
  38.162 +#$ name: merge.pull
  38.163 +
  38.164 +hg pull ../my-hello
  38.165 +
  38.166 +#$ name: merge.heads
  38.167 +
  38.168 +hg heads
  38.169 +
  38.170 +#$ name: merge.update
  38.171 +
  38.172 +hg update
  38.173 +
  38.174 +#$ name: merge.merge
  38.175 +
  38.176 +hg merge
  38.177 +
  38.178 +#$ name: merge.parents
  38.179 +
  38.180 +hg parents
  38.181 +cat hello.c
  38.182 +
  38.183 +#$ name: merge.commit
  38.184 +
  38.185 +hg commit -m 'Merged changes'
  38.186 +
  38.187 +#$ name: merge.tip
  38.188 +
  38.189 +hg tip

    39.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    39.2 +++ b/en/examples/tour-merge-conflict	Mon Mar 05 20:16:36 2007 -0800
    39.3 @@ -0,0 +1,71 @@
    39.4 +#!/bin/bash
    39.5 +
    39.6 +hg init scam
    39.7 +cd scam
    39.8 +
    39.9 +#$ name: wife
   39.10 +
   39.11 +cat > letter.txt <<EOF
   39.12 +Greetings!
   39.13 +
   39.14 +I am Mariam Abacha, the wife of former
   39.15 +Nigerian dictator Sani Abacha.
   39.16 +EOF
   39.17 +
   39.18 +hg add letter.txt
   39.19 +hg commit -m '419 scam, first draft'
   39.20 +
   39.21 +#$ name: cousin
   39.22 +
   39.23 +cd ..
   39.24 +hg clone scam scam-cousin
   39.25 +cd scam-cousin
   39.26 +
   39.27 +cat > letter.txt <<EOF
   39.28 +Greetings!
   39.29 +
   39.30 +I am Shehu Musa Abacha, cousin to the former
   39.31 +Nigerian dictator Sani Abacha.
   39.32 +EOF
   39.33 +
   39.34 +hg commit -m '419 scam, with cousin'
   39.35 +
   39.36 +#$ name: son
   39.37 +
   39.38 +cd ..
   39.39 +hg clone scam scam-son
   39.40 +cd scam-son
   39.41 +
   39.42 +cat > letter.txt <<EOF
   39.43 +Greetings!
   39.44 +
   39.45 +I am Alhaji Abba Abacha, son of the former
   39.46 +Nigerian dictator Sani Abacha.
   39.47 +EOF
   39.48 +
   39.49 +hg commit -m '419 scam, with son'
   39.50 +
   39.51 +#$ name: pull
   39.52 +
   39.53 +cd ..
   39.54 +hg clone scam-cousin scam-merge
   39.55 +cd scam-merge
   39.56 +hg pull -u ../scam-son
   39.57 +
   39.58 +#$ name: merge
   39.59 +
   39.60 +export HGMERGE=merge
   39.61 +hg merge
   39.62 +cat letter.txt
   39.63 +
   39.64 +#$ name: commit
   39.65 +
   39.66 +cat > letter.txt <<EOF
   39.67 +Greetings!
   39.68 +
   39.69 +I am Bryan O'Sullivan, no relation of the former
   39.70 +Nigerian dictator Sani Abacha.
   39.71 +EOF
   39.72 +
   39.73 +hg commit -m 'Send me your money'
   39.74 +hg tip

    40.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    40.2 +++ b/en/filelog.svg	Mon Mar 05 20:16:36 2007 -0800
    40.3 @@ -0,0 +1,371 @@
    40.4 +<?xml version="1.0" encoding="UTF-8" standalone="no"?>
    40.5 +<!-- Created with Inkscape (http://www.inkscape.org/) -->
    40.6 +<svg
    40.7 +   xmlns:dc="http://purl.org/dc/elements/1.1/"
    40.8 +   xmlns:cc="http://web.resource.org/cc/"
    40.9 +   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   40.10 +   xmlns:svg="http://www.w3.org/2000/svg"
   40.11 +   xmlns="http://www.w3.org/2000/svg"
   40.12 +   xmlns:xlink="http://www.w3.org/1999/xlink"
   40.13 +   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
   40.14 +   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
   40.15 +   width="744.09448819"
   40.16 +   height="1052.3622047"
   40.17 +   id="svg2"
   40.18 +   sodipodi:version="0.32"
   40.19 +   inkscape:version="0.44.1"
   40.20 +   sodipodi:docname="filelog.svg">
   40.21 +  <defs
   40.22 +     id="defs4">
   40.23 +    <marker
   40.24 +       inkscape:stockid="Arrow1Mend"
   40.25 +       orient="auto"
   40.26 +       refY="0.0"
   40.27 +       refX="0.0"
   40.28 +       id="Arrow1Mend"
   40.29 +       style="overflow:visible;">
   40.30 +      <path
   40.31 +         id="path3128"
   40.32 +         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
   40.33 +         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;"
   40.34 +         transform="scale(0.4) rotate(180) translate(10,0)" />
   40.35 +    </marker>
   40.36 +    <linearGradient
   40.37 +       id="linearGradient2887">
   40.38 +      <stop
   40.39 +         style="stop-color:#91cfcf;stop-opacity:1;"
   40.40 +         offset="0"
   40.41 +         id="stop2889" />
   40.42 +      <stop
   40.43 +         style="stop-color:aqua;stop-opacity:0;"
   40.44 +         offset="1"
   40.45 +         id="stop2891" />
   40.46 +    </linearGradient>
   40.47 +    <linearGradient
   40.48 +       id="linearGradient2795">
   40.49 +      <stop
   40.50 +         style="stop-color:#ccc;stop-opacity:1;"
   40.51 +         offset="0"
   40.52 +         id="stop2797" />
   40.53 +      <stop
   40.54 +         style="stop-color:#ccc;stop-opacity:0;"
   40.55 +         offset="1"
   40.56 +         id="stop2799" />
   40.57 +    </linearGradient>
   40.58 +    <linearGradient
   40.59 +       inkscape:collect="always"
   40.60 +       xlink:href="#linearGradient2795"
   40.61 +       id="linearGradient3170"
   40.62 +       gradientUnits="userSpaceOnUse"
   40.63 +       gradientTransform="translate(121.2183,94.95434)"
   40.64 +       x1="81.322357"
   40.65 +       y1="404.34424"
   40.66 +       x2="201.52036"
   40.67 +       y2="373.03967" />
   40.68 +    <linearGradient
   40.69 +       inkscape:collect="always"
   40.70 +       xlink:href="#linearGradient2887"
   40.71 +       id="linearGradient3172"
   40.72 +       gradientUnits="userSpaceOnUse"
   40.73 +       gradientTransform="translate(0,12)"
   40.74 +       x1="62.634491"
   40.75 +       y1="503.3392"
   40.76 +       x2="248.49242"
   40.77 +       y2="462.94327" />
   40.78 +    <linearGradient
   40.79 +       inkscape:collect="always"
   40.80 +       xlink:href="#linearGradient2795"
   40.81 +       id="linearGradient3174"
   40.82 +       gradientUnits="userSpaceOnUse"
   40.83 +       gradientTransform="matrix(1.001035,0,0,0.653159,236.7075,153.0415)"
   40.84 +       x1="81.322357"
   40.85 +       y1="404.34424"
   40.86 +       x2="201.52036"
   40.87 +       y2="373.03967" />
   40.88 +    <linearGradient
   40.89 +       inkscape:collect="always"
   40.90 +       xlink:href="#linearGradient2887"
   40.91 +       id="linearGradient3176"
   40.92 +       gradientUnits="userSpaceOnUse"
   40.93 +       gradientTransform="translate(0,12)"
   40.94 +       x1="62.634491"
   40.95 +       y1="503.3392"
   40.96 +       x2="248.49242"
   40.97 +       y2="462.94327" />
   40.98 +    <linearGradient
   40.99 +       inkscape:collect="always"
  40.100 +       xlink:href="#linearGradient2795"
  40.101 +       id="linearGradient3208"
  40.102 +       gradientUnits="userSpaceOnUse"
  40.103 +       gradientTransform="matrix(1.001035,0,0,0.653159,236.7075,153.0415)"
  40.104 +       x1="81.322357"
  40.105 +       y1="404.34424"
  40.106 +       x2="201.52036"
  40.107 +       y2="373.03967" />
  40.108 +    <linearGradient
  40.109 +       inkscape:collect="always"
  40.110 +       xlink:href="#linearGradient2887"
  40.111 +       id="linearGradient3210"
  40.112 +       gradientUnits="userSpaceOnUse"
  40.113 +       gradientTransform="translate(0,12)"
  40.114 +       x1="62.634491"
  40.115 +       y1="503.3392"
  40.116 +       x2="248.49242"
  40.117 +       y2="462.94327" />
  40.118 +    <linearGradient
  40.119 +       inkscape:collect="always"
  40.120 +       xlink:href="#linearGradient2795"
  40.121 +       id="linearGradient3212"
  40.122 +       gradientUnits="userSpaceOnUse"
  40.123 +       gradientTransform="translate(121.2183,94.95434)"
  40.124 +       x1="81.322357"
  40.125 +       y1="404.34424"
  40.126 +       x2="201.52036"
  40.127 +       y2="373.03967" />
  40.128 +    <linearGradient
  40.129 +       inkscape:collect="always"
  40.130 +       xlink:href="#linearGradient2887"
  40.131 +       id="linearGradient3214"
  40.132 +       gradientUnits="userSpaceOnUse"
  40.133 +       gradientTransform="translate(0,12)"
  40.134 +       x1="62.634491"
  40.135 +       y1="503.3392"
  40.136 +       x2="248.49242"
  40.137 +       y2="462.94327" />
  40.138 +    <linearGradient
  40.139 +       inkscape:collect="always"
  40.140 +       xlink:href="#linearGradient2795"
  40.141 +       id="linearGradient3256"
  40.142 +       gradientUnits="userSpaceOnUse"
  40.143 +       gradientTransform="translate(121.2183,94.95434)"
  40.144 +       x1="81.322357"
  40.145 +       y1="404.34424"
  40.146 +       x2="201.52036"
  40.147 +       y2="373.03967" />
  40.148 +    <linearGradient
  40.149 +       inkscape:collect="always"
  40.150 +       xlink:href="#linearGradient2887"
  40.151 +       id="linearGradient3258"
  40.152 +       gradientUnits="userSpaceOnUse"
  40.153 +       gradientTransform="translate(0,12)"
  40.154 +       x1="62.634491"
  40.155 +       y1="503.3392"
  40.156 +       x2="248.49242"
  40.157 +       y2="462.94327" />
  40.158 +    <linearGradient
  40.159 +       inkscape:collect="always"
  40.160 +       xlink:href="#linearGradient2795"
  40.161 +       id="linearGradient3260"
  40.162 +       gradientUnits="userSpaceOnUse"
  40.163 +       gradientTransform="matrix(1.001035,0,0,0.653159,236.7075,153.0415)"
  40.164 +       x1="81.322357"
  40.165 +       y1="404.34424"
  40.166 +       x2="201.52036"
  40.167 +       y2="373.03967" />
  40.168 +    <linearGradient
  40.169 +       inkscape:collect="always"
  40.170 +       xlink:href="#linearGradient2887"
  40.171 +       id="linearGradient3262"
  40.172 +       gradientUnits="userSpaceOnUse"
  40.173 +       gradientTransform="translate(0,12)"
  40.174 +       x1="62.634491"
  40.175 +       y1="503.3392"
  40.176 +       x2="248.49242"
  40.177 +       y2="462.94327" />
  40.178 +  </defs>
  40.179 +  <sodipodi:namedview
  40.180 +     id="base"
  40.181 +     pagecolor="#ffffff"
  40.182 +     bordercolor="#666666"
  40.183 +     borderopacity="1.0"
  40.184 +     gridtolerance="10000"
  40.185 +     guidetolerance="10"
  40.186 +     objecttolerance="10"
  40.187 +     inkscape:pageopacity="0.0"
  40.188 +     inkscape:pageshadow="2"
  40.189 +     inkscape:zoom="0.98994949"
  40.190 +     inkscape:cx="455.8122"
  40.191 +     inkscape:cy="520"
  40.192 +     inkscape:document-units="px"
  40.193 +     inkscape:current-layer="layer1"
  40.194 +     inkscape:window-width="906"
  40.195 +     inkscape:window-height="620"
  40.196 +     inkscape:window-x="5"
  40.197 +     inkscape:window-y="49" />
  40.198 +  <metadata
  40.199 +     id="metadata7">
  40.200 +    <rdf:RDF>
  40.201 +      <cc:Work
  40.202 +         rdf:about="">
  40.203 +        <dc:format>image/svg+xml</dc:format>
  40.204 +        <dc:type
  40.205 +           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
  40.206 +      </cc:Work>
  40.207 +    </rdf:RDF>
  40.208 +  </metadata>
  40.209 +  <g
  40.210 +     inkscape:label="Layer 1"
  40.211 +     inkscape:groupmode="layer"
  40.212 +     id="layer1">
  40.213 +    <rect
  40.214 +       style="opacity:1;fill:#abadf8;fill-opacity:1;stroke:#595959;stroke-width:0.86781615;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
  40.215 +       id="rect3180"
  40.216 +       width="234.48758"
  40.217 +       height="199.13225"
  40.218 +       x="322.67767"
  40.219 +       y="351.75531" />
  40.220 +    <rect
  40.221 +       style="opacity:1;fill:#a2f69c;fill-opacity:1;stroke:#595959;stroke-width:0.86781615;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
  40.222 +       id="rect3178"
  40.223 +       width="234.48756"
  40.224 +       height="199.13223"
  40.225 +       x="72.664886"
  40.226 +       y="351.75531" />
  40.227 +    <g
  40.228 +       id="g3144"
  40.229 +       transform="translate(34,0.71578)">
  40.230 +      <g
  40.231 +         id="g2940">
  40.232 +        <rect
  40.233 +           style="fill:url(#linearGradient3260);fill-opacity:1;stroke:black;stroke-width:0.80860078;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
  40.234 +           id="rect2914"
  40.235 +           width="185.04932"
  40.236 +           height="39.587399"
  40.237 +           x="311.53635"
  40.238 +           y="395.04291" />
  40.239 +        <text
  40.240 +           xml:space="preserve"
  40.241 +           style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
  40.242 +           x="323.72824"
  40.243 +           y="416.7626"
  40.244 +           id="text2918"><tspan
  40.245 +             sodipodi:role="line"
  40.246 +             id="tspan2920"
  40.247 +             x="323.72824"
  40.248 +             y="416.7626"
  40.249 +             style="font-family:Courier">.hg/data/README.i</tspan></text>
  40.250 +      </g>
  40.251 +      <g
  40.252 +         transform="translate(3.79093e-5,-80.1853)"
  40.253 +         id="g2945">
  40.254 +        <g
  40.255 +           id="g2955">
  40.256 +          <rect
  40.257 +             y="475.44327"
  40.258 +             x="63.134491"
  40.259 +             height="39.395935"
  40.260 +             width="184.85793"
  40.261 +             id="rect2947"
  40.262 +             style="fill:url(#linearGradient3262);fill-opacity:1;stroke:black;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
  40.263 +          <text
  40.264 +             id="text2949"
  40.265 +             y="498.35123"
  40.266 +             x="75.230644"
  40.267 +             style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
  40.268 +             xml:space="preserve"><tspan
  40.269 +               style="font-family:Courier"
  40.270 +               y="498.35123"
  40.271 +               x="75.230644"
  40.272 +               id="tspan2951"
  40.273 +               sodipodi:role="line">README</tspan></text>
  40.274 +        </g>
  40.275 +      </g>
  40.276 +      <path
  40.277 +         inkscape:connection-end="#g2940"
  40.278 +         inkscape:connection-start="#g2945"
  40.279 +         inkscape:connector-type="polyline"
  40.280 +         id="path2960"
  40.281 +         d="M 248.49245,414.91131 L 311.13205,414.88123"
  40.282 +         style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Mend);stroke-opacity:1" />
  40.283 +    </g>
  40.284 +    <g
  40.285 +       id="g3156"
  40.286 +       transform="translate(34,0.71578)">
  40.287 +      <g
  40.288 +         transform="translate(116,0)"
  40.289 +         id="g2831">
  40.290 +        <rect
  40.291 +           style="fill:url(#linearGradient3256);fill-opacity:1;stroke:black;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
  40.292 +           id="rect1906"
  40.293 +           width="184.85793"
  40.294 +           height="60.609138"
  40.295 +           x="195.96959"
  40.296 +           y="465.46356" />
  40.297 +        <g
  40.298 +           id="g2803"
  40.299 +           transform="translate(-0.893671,1.833581)">
  40.300 +          <text
  40.301 +             id="text1884"
  40.302 +             y="483.92801"
  40.303 +             x="208.95944"
  40.304 +             style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
  40.305 +             xml:space="preserve"><tspan
  40.306 +               style="font-family:Courier"
  40.307 +               y="483.92801"
  40.308 +               x="208.95944"
  40.309 +               id="tspan1886"
  40.310 +               sodipodi:role="line">.hg/data/src/hello.c.d</tspan></text>
  40.311 +          <text
  40.312 +             id="text1888"
  40.313 +             y="507.79309"
  40.314 +             x="208.95944"
  40.315 +             style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
  40.316 +             xml:space="preserve"><tspan
  40.317 +               style="font-family:Courier"
  40.318 +               y="507.79309"
  40.319 +               x="208.95944"
  40.320 +               id="tspan1890"
  40.321 +               sodipodi:role="line">.hg/data/src/hello.c.i</tspan></text>
  40.322 +        </g>
  40.323 +      </g>
  40.324 +      <g
  40.325 +         id="g2907">
  40.326 +        <rect
  40.327 +           style="fill:url(#linearGradient3258);fill-opacity:1;stroke:black;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
  40.328 +           id="rect2843"
  40.329 +           width="184.85793"
  40.330 +           height="39.395935"
  40.331 +           x="63.134491"
  40.332 +           y="475.44327" />
  40.333 +        <text
  40.334 +           xml:space="preserve"
  40.335 +           style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
  40.336 +           x="75.230644"
  40.337 +           y="498.35123"
  40.338 +           id="text2847"><tspan
  40.339 +             sodipodi:role="line"
  40.340 +             id="tspan2849"
  40.341 +             x="75.230644"
  40.342 +             y="498.35123"
  40.343 +             style="font-family:Courier">src/hello.c</tspan></text>
  40.344 +      </g>
  40.345 +      <path
  40.346 +         inkscape:connection-end="#g2831"
  40.347 +         inkscape:connection-start="#g2907"
  40.348 +         inkscape:connector-type="polyline"
  40.349 +         id="path2962"
  40.350 +         d="M 248.49242,495.37535 L 311.46959,495.53401"
  40.351 +         style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Mend);stroke-opacity:1" />
  40.352 +    </g>
  40.353 +    <text
  40.354 +       xml:space="preserve"
  40.355 +       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
  40.356 +       x="96.476799"
  40.357 +       y="373.96353"
  40.358 +       id="text3216"><tspan
  40.359 +         sodipodi:role="line"
  40.360 +         id="tspan3218"
  40.361 +         x="96.476799"
  40.362 +         y="373.96353">Working directory</tspan></text>
  40.363 +    <text
  40.364 +       xml:space="preserve"
  40.365 +       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
  40.366 +       x="344.92493"
  40.367 +       y="373.96353"
  40.368 +       id="text3228"><tspan
  40.369 +         sodipodi:role="line"
  40.370 +         id="tspan3230"
  40.371 +         x="344.92493"
  40.372 +         y="373.96353">Repository</tspan></text>
  40.373 +  </g>
  40.374 +</svg>

    41.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    41.2 +++ b/en/filenames.tex	Mon Mar 05 20:16:36 2007 -0800
    41.3 @@ -0,0 +1,306 @@
    41.4 +\chapter{File names and pattern matching}
    41.5 +\label{chap:names}
    41.6 +
    41.7 +Mercurial provides mechanisms that let you work with file names in a
    41.8 +consistent and expressive way.
    41.9 +
   41.10 +\section{Simple file naming}
   41.11 +
   41.12 +Mercurial uses a unified piece of machinery ``under the hood'' to
   41.13 +handle file names.  Every command behaves uniformly with respect to
   41.14 +file names.  The way in which commands work with file names is as
   41.15 +follows.
   41.16 +
   41.17 +If you explicitly name real files on the command line, Mercurial works
   41.18 +with exactly those files, as you would expect.
   41.19 +\interaction{filenames.files}
   41.20 +
   41.21 +When you provide a directory name, Mercurial will interpret this as
   41.22 +``operate on every file in this directory and its subdirectories''.
   41.23 +Mercurial traverses the files and subdirectories in a directory in
   41.24 +alphabetical order.  When it encounters a subdirectory, it will
   41.25 +traverse that subdirectory before continuing with the current
   41.26 +directory.
   41.27 +\interaction{filenames.dirs}
   41.28 +
   41.29 +\section{Running commands without any file names}
   41.30 +
   41.31 +Mercurial's commands that work with file names have useful default
   41.32 +behaviours when you invoke them without providing any file names or
   41.33 +patterns.  What kind of behaviour you should expect depends on what
   41.34 +the command does.  Here are a few rules of thumb you can use to
   41.35 +predict what a command is likely to do if you don't give it any names
   41.36 +to work with.
   41.37 +\begin{itemize}
   41.38 +\item Most commands will operate on the entire working directory.
   41.39 +  This is what the \hgcmd{add} command does, for example.
   41.40 +\item If the command has effects that are difficult or impossible to
   41.41 +  reverse, it will force you to explicitly provide at least one name
   41.42 +  or pattern (see below).  This protects you from accidentally
   41.43 +  deleting files by running \hgcmd{remove} with no arguments, for
   41.44 +  example.
   41.45 +\end{itemize}
   41.46 +
   41.47 +It's easy to work around these default behaviours if they don't suit
   41.48 +you.  If a command normally operates on the whole working directory,
   41.49 +you can invoke it on just the current directory and its subdirectories
   41.50 +by giving it the name ``\dirname{.}''.
   41.51 +\interaction{filenames.wdir-subdir}
   41.52 +
   41.53 +Along the same lines, some commands normally print file names relative
   41.54 +to the root of the repository, even if you're invoking them from a
   41.55 +subdirectory.  Such a command will print file names relative to your
   41.56 +subdirectory if you give it explicit names.  Here, we're going to run
   41.57 +\hgcmd{status} from a subdirectory, and get it to operate on the
   41.58 +entire working directory while printing file names relative to our
   41.59 +subdirectory, by passing it the output of the \hgcmd{root} command.
   41.60 +\interaction{filenames.wdir-relname}
   41.61 +
   41.62 +\section{Telling you what's going on}
   41.63 +
   41.64 +The \hgcmd{add} example in the preceding section illustrates something
   41.65 +else that's helpful about Mercurial commands.  If a command operates
   41.66 +on a file that you didn't name explicitly on the command line, it will
   41.67 +usually print the name of the file, so that you will not be surprised
   41.68 +what's going on.
   41.69 +
   41.70 +The principle here is of \emph{least surprise}.  If you've exactly
   41.71 +named a file on the command line, there's no point in repeating it
   41.72 +back at you.  If Mercurial is acting on a file \emph{implicitly},
   41.73 +because you provided no names, or a directory, or a pattern (see
   41.74 +below), it's safest to tell you what it's doing.
   41.75 +
   41.76 +For commands that behave this way, you can silence them using the
   41.77 +\hggopt{-q} option.  You can also get them to print the name of every
   41.78 +file, even those you've named explicitly, using the \hggopt{-v}
   41.79 +option.
   41.80 +
   41.81 +\section{Using patterns to identify files}
   41.82 +
   41.83 +In addition to working with file and directory names, Mercurial lets
   41.84 +you use \emph{patterns} to identify files.  Mercurial's pattern
   41.85 +handling is expressive.
   41.86 +
   41.87 +On Unix-like systems (Linux, MacOS, etc.), the job of matching file
   41.88 +names to patterns normally falls to the shell.  On these systems, you
   41.89 +must explicitly tell Mercurial that a name is a pattern.  On Windows,
   41.90 +the shell does not expand patterns, so Mercurial will automatically
   41.91 +identify names that are patterns, and expand them for you.
   41.92 +
   41.93 +To provide a pattern in place of a regular name on the command line,
   41.94 +the mechanism is simple:
   41.95 +\begin{codesample2}
   41.96 +  syntax:patternbody
   41.97 +\end{codesample2}
   41.98 +That is, a pattern is identified by a short text string that says what
   41.99 +kind of pattern this is, followed by a colon, followed by the actual
  41.100 +pattern.
  41.101 +
  41.102 +Mercurial supports two kinds of pattern syntax.  The most frequently
  41.103 +used is called \texttt{glob}; this is the same kind of pattern
  41.104 +matching used by the Unix shell, and should be familiar to Windows
  41.105 +command prompt users, too.  
  41.106 +
  41.107 +When Mercurial does automatic pattern matching on Windows, it uses
  41.108 +\texttt{glob} syntax.  You can thus omit the ``\texttt{glob:}'' prefix
  41.109 +on Windows, but it's safe to use it, too.
  41.110 +
  41.111 +The \texttt{re} syntax is more powerful; it lets you specify patterns
  41.112 +using regular expressions, also known as regexps.
  41.113 +
  41.114 +By the way, in the examples that follow, notice that I'm careful to
  41.115 +wrap all of my patterns in quote characters, so that they won't get
  41.116 +expanded by the shell before Mercurial sees them.
  41.117 +
  41.118 +\subsection{Shell-style \texttt{glob} patterns}
  41.119 +
  41.120 +This is an overview of the kinds of patterns you can use when you're
  41.121 +matching on glob patterns.
  41.122 +
  41.123 +The ``\texttt{*}'' character matches any string, within a single
  41.124 +directory.
  41.125 +\interaction{filenames.glob.star}
  41.126 +
  41.127 +The ``\texttt{**}'' pattern matches any string, and crosses directory
  41.128 +boundaries.  It's not a standard Unix glob token, but it's accepted by
  41.129 +several popular Unix shells, and is very useful.
  41.130 +\interaction{filenames.glob.starstar}
  41.131 +
  41.132 +The ``\texttt{?}'' pattern matches any single character.
  41.133 +\interaction{filenames.glob.question}
  41.134 +
  41.135 +The ``\texttt{[}'' character begins a \emph{character class}.  This
  41.136 +matches any single character within the class.  The class ends with a
  41.137 +``\texttt{]}'' character.  A class may contain multiple \emph{range}s
  41.138 +of the form ``\texttt{a-f}'', which is shorthand for
  41.139 +``\texttt{abcdef}''.
  41.140 +\interaction{filenames.glob.range}
  41.141 +If the first character after the ``\texttt{[}'' in a character class
  41.142 +is a ``\texttt{!}'', it \emph{negates} the class, making it match any
  41.143 +single character not in the class.
  41.144 +
  41.145 +A ``\texttt{\{}'' begins a group of subpatterns, where the whole group
  41.146 +matches if any subpattern in the group matches.  The ``\texttt{,}''
  41.147 +character separates subpatterns, and ``\texttt{\}}'' ends the group.
  41.148 +\interaction{filenames.glob.group}
  41.149 +
  41.150 +\subsubsection{Watch out!}
  41.151 +
  41.152 +Don't forget that if you want to match a pattern in any directory, you
  41.153 +should not be using the ``\texttt{*}'' match-any token, as this will
  41.154 +only match within one directory.  Instead, use the ``\texttt{**}''
  41.155 +token.  This small example illustrates the difference between the two.
  41.156 +\interaction{filenames.glob.star-starstar}
  41.157 +
  41.158 +\subsection{Regular expression matching with \texttt{re} patterns}
  41.159 +
  41.160 +Mercurial accepts the same regular expression syntax as the Python
  41.161 +programming language (it uses Python's regexp engine internally).
  41.162 +This is based on the Perl language's regexp syntax, which is the most
  41.163 +popular dialect in use (it's also used in Java, for example).
  41.164 +
  41.165 +I won't discuss Mercurial's regexp dialect in any detail here, as
  41.166 +regexps are not often used.  Perl-style regexps are in any case
  41.167 +already exhaustively documented on a multitude of web sites, and in
  41.168 +many books.  Instead, I will focus here on a few things you should
  41.169 +know if you find yourself needing to use regexps with Mercurial.
  41.170 +
  41.171 +A regexp is matched against an entire file name, relative to the root
  41.172 +of the repository.  In other words, even if you're already in
  41.173 +subbdirectory \dirname{foo}, if you want to match files under this
  41.174 +directory, your pattern must start with ``\texttt{foo/}''.
  41.175 +
  41.176 +One thing to note, if you're familiar with Perl-style regexps, is that
  41.177 +Mercurial's are \emph{rooted}.  That is, a regexp starts matching
  41.178 +against the beginning of a string; it doesn't look for a match
  41.179 +anywhere within the string it.  To match anywhere in a string, start
  41.180 +your pattern with ``\texttt{.*}''.
  41.181 +
  41.182 +\section{Filtering files}
  41.183 +
  41.184 +Not only does Mercurial give you a variety of ways to specify files;
  41.185 +it lets you further winnow those files using \emph{filters}.  Commands
  41.186 +that work with file names accept two filtering options.
  41.187 +\begin{itemize}
  41.188 +\item \hggopt{-I}, or \hggopt{--include}, lets you specify a pattern
  41.189 +  that file names must match in order to be processed.
  41.190 +\item \hggopt{-X}, or \hggopt{--exclude}, gives you a way to
  41.191 +  \emph{avoid} processing files, if they match this pattern.
  41.192 +\end{itemize}
  41.193 +You can provide multiple \hggopt{-I} and \hggopt{-X} options on the
  41.194 +command line, and intermix them as you please.  Mercurial interprets
  41.195 +the patterns you provide using glob syntax by default (but you can use
  41.196 +regexps if you need to).
  41.197 +
  41.198 +You can read a \hggopt{-I} filter as ``process only the files that
  41.199 +match this filter''.
  41.200 +\interaction{filenames.filter.include}
  41.201 +The \hggopt{-X} filter is best read as ``process only the files that
  41.202 +don't match this pattern''.
  41.203 +\interaction{filenames.filter.exclude}
  41.204 +
  41.205 +\section{Ignoring unwanted files and directories}
  41.206 +
  41.207 +XXX.
  41.208 +
  41.209 +\section{Case sensitivity}
  41.210 +\label{sec:names:case}
  41.211 +
  41.212 +If you're working in a mixed development environment that contains
  41.213 +both Linux (or other Unix) systems and Macs or Windows systems, you
  41.214 +should keep in the back of your mind the knowledge that they treat the
  41.215 +case (``N'' versus ``n'') of file names in incompatible ways.  This is
  41.216 +not very likely to affect you, and it's easy to deal with if it does,
  41.217 +but it could surprise you if you don't know about it.
  41.218 +
  41.219 +Operating systems and filesystems differ in the way they handle the
  41.220 +\emph{case} of characters in file and directory names.  There are
  41.221 +three common ways to handle case in names.
  41.222 +\begin{itemize}
  41.223 +\item Completely case insensitive.  Uppercase and lowercase versions
  41.224 +  of a letter are treated as identical, both when creating a file and
  41.225 +  during subsequent accesses.  This is common on older DOS-based
  41.226 +  systems.
  41.227 +\item Case preserving, but insensitive.  When a file or directory is
  41.228 +  created, the case of its name is stored, and can be retrieved and
  41.229 +  displayed by the operating system.  When an existing file is being
  41.230 +  looked up, its case is ignored.  This is the standard arrangement on
  41.231 +  Windows and MacOS.  The names \filename{foo} and \filename{FoO}
  41.232 +  identify the same file.  This treatment of uppercase and lowercase
  41.233 +  letters as interchangeable is also referred to as \emph{case
  41.234 +    folding}.
  41.235 +\item Case sensitive.  The case of a name is significant at all times.
  41.236 +  The names \filename{foo} and {FoO} identify different files.  This
  41.237 +  is the way Linux and Unix systems normally work.
  41.238 +\end{itemize}
  41.239 +
  41.240 +On Unix-like systems, it is possible to have any or all of the above
  41.241 +ways of handling case in action at once.  For example, if you use a
  41.242 +USB thumb drive formatted with a FAT32 filesystem on a Linux system,
  41.243 +Linux will handle names on that filesystem in a case preserving, but
  41.244 +insensitive, way.
  41.245 +
  41.246 +\subsection{Safe, portable repository storage}
  41.247 +
  41.248 +Mercurial's repository storage mechanism is \emph{case safe}.  It
  41.249 +translates file names so that they can be safely stored on both case
  41.250 +sensitive and case insensitive filesystems.  This means that you can
  41.251 +use normal file copying tools to transfer a Mercurial repository onto,
  41.252 +for example, a USB thumb drive, and safely move that drive and
  41.253 +repository back and forth between a Mac, a PC running Windows, and a
  41.254 +Linux box.
  41.255 +
  41.256 +\subsection{Detecting case conflicts}
  41.257 +
  41.258 +When operating in the working directory, Mercurial honours the naming
  41.259 +policy of the filesystem where the working directory is located.  If
  41.260 +the filesystem is case preserving, but insensitive, Mercurial will
  41.261 +treat names that differ only in case as the same.
  41.262 +
  41.263 +An important aspect of this approach is that it is possible to commit
  41.264 +a changeset on a case sensitive (typically Linux or Unix) filesystem
  41.265 +that will cause trouble for users on case insensitive (usually Windows
  41.266 +and MacOS) users.  If a Linux user commits changes to two files, one
  41.267 +named \filename{myfile.c} and the other named \filename{MyFile.C},
  41.268 +they will be stored correctly in the repository.  And in the working
  41.269 +directories of other Linux users, they will be correctly represented
  41.270 +as separate files.
  41.271 +
  41.272 +If a Windows or Mac user pulls this change, they will not initially
  41.273 +have a problem, because Mercurial's repository storage mechanism is
  41.274 +case safe.  However, once they try to \hgcmd{update} the working
  41.275 +directory to that changeset, or \hgcmd{merge} with that changeset,
  41.276 +Mercurial will spot the conflict between the two file names that the
  41.277 +filesystem would treat as the same, and forbid the update or merge
  41.278 +from occurring.
  41.279 +
  41.280 +\subsection{Fixing a case conflict}
  41.281 +
  41.282 +If you are using Windows or a Mac in a mixed environment where some of
  41.283 +your collaborators are using Linux or Unix, and Mercurial reports a
  41.284 +case folding conflict when you try to \hgcmd{update} or \hgcmd{merge},
  41.285 +the procedure to fix the problem is simple.
  41.286 +
  41.287 +Just find a nearby Linux or Unix box, clone the problem repository
  41.288 +onto it, and use Mercurial's \hgcmd{rename} command to change the
  41.289 +names of any offending files or directories so that they will no
  41.290 +longer cause case folding conflicts.  Commit this change, \hgcmd{pull}
  41.291 +or \hgcmd{push} it across to your Windows or MacOS system, and
  41.292 +\hgcmd{update} to the revision with the non-conflicting names.
  41.293 +
  41.294 +The changeset with case-conflicting names will remain in your
  41.295 +project's history, and you still won't be able to \hgcmd{update} your
  41.296 +working directory to that changeset on a Windows or MacOS system, but
  41.297 +you can continue development unimpeded.
  41.298 +
  41.299 +\begin{note}
  41.300 +  Prior to version~0.9.3, Mercurial did not use a case safe repository
  41.301 +  storage mechanism, and did not detect case folding conflicts.  If
  41.302 +  you are using an older version of Mercurial on Windows or MacOS, I
  41.303 +  strongly recommend that you upgrade.
  41.304 +\end{note}
  41.305 +
  41.306 +%%% Local Variables: 
  41.307 +%%% mode: latex
  41.308 +%%% TeX-master: "00book"
  41.309 +%%% End: 

    42.1 --- a/en/hook.tex	Fri Jul 21 22:42:19 2006 -0700
    42.2 +++ b/en/hook.tex	Mon Mar 05 20:16:36 2007 -0800
    42.3 @@ -177,7 +177,7 @@
    42.4  (which contains pointers to the new manifest data).  Before the first
    42.5  write to each file, it stores a record of where the end of the file
    42.6  was in its transaction log.  If the transaction must be rolled back,
    42.7 -Mercurial simply truncates each file back to te size it was before the
    42.8 +Mercurial simply truncates each file back to the size it was before the
    42.9  transaction began.
   42.10  
   42.11  When Mercurial \emph{reads} metadata, it reads the changelog first,
   42.12 @@ -358,8 +358,8 @@
   42.13  number 1 (for ``true'') or 0 (for ``false'') as an environment
   42.14  variable for an external hook.  If a hook parameter is named
   42.15  \texttt{foo}, the keyword argument for a Python hook will also be
   42.16 -named \texttt{foo} Python, while the environment variable for an
   42.17 -external hook will be named \texttt{HG\_FOO}.
   42.18 +named \texttt{foo}, while the environment variable for an external
   42.19 +hook will be named \texttt{HG\_FOO}.
   42.20  
   42.21  \subsection{Hook return values and activity control}
   42.22  
   42.23 @@ -430,7 +430,532 @@
   42.24  doesn't care about by dropping them into a keyword argument dict, as
   42.25  with \texttt{**kwargs} above.
   42.26  
   42.27 -\section{Hook reference}
   42.28 +\section{Some hook examples}
   42.29 +
   42.30 +\subsection{Writing meaningful commit messages}
   42.31 +
   42.32 +It's hard to imagine a useful commit message being very short.  The
   42.33 +simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.run}
   42.34 +will prevent you from committing a changeset with a message that is
   42.35 +less than ten bytes long.
   42.36 +
   42.37 +\begin{figure}[ht]
   42.38 +  \interaction{hook.msglen.run}
   42.39 +  \caption{A hook that forbids overly short commit messages}
   42.40 +  \label{ex:hook:msglen.run}
   42.41 +\end{figure}
   42.42 +
   42.43 +\subsection{Checking for trailing whitespace}
   42.44 +
   42.45 +An interesting use of a commit-related hook is to help you to write
   42.46 +cleaner code.  A simple example of ``cleaner code'' is the dictum that
   42.47 +a change should not add any new lines of text that contain ``trailing
   42.48 +whitespace''.  Trailing whitespace is a series of space and tab
   42.49 +characters at the end of a line of text.  In most cases, trailing
   42.50 +whitespace is unnecessary, invisible noise, but it is occasionally
   42.51 +problematic, and people often prefer to get rid of it.
   42.52 +
   42.53 +You can use either the \hook{precommit} or \hook{pretxncommit} hook to
   42.54 +tell whether you have a trailing whitespace problem.  If you use the
   42.55 +\hook{precommit} hook, the hook will not know which files you are
   42.56 +committing, so it will have to check every modified file in the
   42.57 +repository for trailing white space.  If you want to commit a change
   42.58 +to just the file \filename{foo}, but the file \filename{bar} contains
   42.59 +trailing whitespace, doing a check in the \hook{precommit} hook will
   42.60 +prevent you from committing \filename{foo} due to the problem with
   42.61 +\filename{bar}.  This doesn't seem right.
   42.62 +
   42.63 +Should you choose the \hook{pretxncommit} hook, the check won't occur
   42.64 +until just before the transaction for the commit completes.  This will
   42.65 +allow you to check for problems only the exact files that are being
   42.66 +committed.  However, if you entered the commit message interactively
   42.67 +and the hook fails, the transaction will roll back; you'll have to
   42.68 +re-enter the commit message after you fix the trailing whitespace and
   42.69 +run \hgcmd{commit} again.
   42.70 +
   42.71 +\begin{figure}[ht]
   42.72 +  \interaction{hook.ws.simple}
   42.73 +  \caption{A simple hook that checks for trailing whitespace}
   42.74 +  \label{ex:hook:ws.simple}
   42.75 +\end{figure}
   42.76 +
   42.77 +Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit}
   42.78 +hook that checks for trailing whitespace.  This hook is short, but not
   42.79 +very helpful.  It exits with an error status if a change adds a line
   42.80 +with trailing whitespace to any file, but does not print any
   42.81 +information that might help us to identify the offending file or
   42.82 +line.  It also has the nice property of not paying attention to
   42.83 +unmodified lines; only lines that introduce new trailing whitespace
   42.84 +cause problems.
   42.85 +
   42.86 +\begin{figure}[ht]
   42.87 +  \interaction{hook.ws.better}
   42.88 +  \caption{A better trailing whitespace hook}
   42.89 +  \label{ex:hook:ws.better}
   42.90 +\end{figure}
   42.91 +
   42.92 +The example of figure~\ref{ex:hook:ws.better} is much more complex,
   42.93 +but also more useful.  It parses a unified diff to see if any lines
   42.94 +add trailing whitespace, and prints the name of the file and the line
   42.95 +number of each such occurrence.  Even better, if the change adds
   42.96 +trailing whitespace, this hook saves the commit comment and prints the
   42.97 +name of the save file before exiting and telling Mercurial to roll the
   42.98 +transaction back, so you can use
   42.99 +\hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the
  42.100 +saved commit message once you've corrected the problem.
  42.101 +
  42.102 +As a final aside, note in figure~\ref{ex:hook:ws.better} the use of
  42.103 +\command{perl}'s in-place editing feature to get rid of trailing
  42.104 +whitespace from a file.  This is concise and useful enough that I will
  42.105 +reproduce it here.
  42.106 +\begin{codesample2}
  42.107 +  perl -pi -e 's,\\s+\$,,' filename
  42.108 +\end{codesample2}
  42.109 +
  42.110 +\section{Bundled hooks}
  42.111 +
  42.112 +Mercurial ships with several bundled hooks.  You can find them in the
  42.113 +\dirname{hgext} directory of a Mercurial source tree.  If you are
  42.114 +using a Mercurial binary package, the hooks will be located in the
  42.115 +\dirname{hgext} directory of wherever your package installer put
  42.116 +Mercurial.
  42.117 +
  42.118 +\subsection{\hgext{acl}---access control for parts of a repository}
  42.119 +
  42.120 +The \hgext{acl} extension lets you control which remote users are
  42.121 +allowed to push changesets to a networked server.  You can protect any
  42.122 +portion of a repository (including the entire repo), so that a
  42.123 +specific remote user can push changes that do not affect the protected
  42.124 +portion.
  42.125 +
  42.126 +This extension implements access control based on the identity of the
  42.127 +user performing a push, \emph{not} on who committed the changesets
  42.128 +they're pushing.  It makes sense to use this hook only if you have a
  42.129 +locked-down server environment that authenticates remote users, and
  42.130 +you want to be sure that only specific users are allowed to push
  42.131 +changes to that server.
  42.132 +
  42.133 +\subsubsection{Configuring the \hook{acl} hook}
  42.134 +
  42.135 +In order to manage incoming changesets, the \hgext{acl} hook must be
  42.136 +used as a \hook{pretxnchangegroup} hook.  This lets it see which files
  42.137 +are modified by each incoming changeset, and roll back a group of
  42.138 +changesets if they modify ``forbidden'' files.  Example:
  42.139 +\begin{codesample2}
  42.140 +  [hooks]
  42.141 +  pretxnchangegroup.acl = python:hgext.acl.hook
  42.142 +\end{codesample2}
  42.143 +
  42.144 +The \hgext{acl} extension is configured using three sections.  
  42.145 +
  42.146 +The \rcsection{acl} section has only one entry, \rcitem{acl}{sources},
  42.147 +which lists the sources of incoming changesets that the hook should
  42.148 +pay attention to.  You don't normally need to configure this section.
  42.149 +\begin{itemize}
  42.150 +\item[\rcitem{acl}{serve}] Control incoming changesets that are arriving
  42.151 +  from a remote repository over http or ssh.  This is the default
  42.152 +  value of \rcitem{acl}{sources}, and usually the only setting you'll
  42.153 +  need for this configuration item.
  42.154 +\item[\rcitem{acl}{pull}] Control incoming changesets that are
  42.155 +  arriving via a pull from a local repository.
  42.156 +\item[\rcitem{acl}{push}] Control incoming changesets that are
  42.157 +  arriving via a push from a local repository.
  42.158 +\item[\rcitem{acl}{bundle}] Control incoming changesets that are
  42.159 +  arriving from another repository via a bundle.
  42.160 +\end{itemize}
  42.161 +
  42.162 +The \rcsection{acl.allow} section controls the users that are allowed to
  42.163 +add changesets to the repository.  If this section is not present, all
  42.164 +users that are not explicitly denied are allowed.  If this section is
  42.165 +present, all users that are not explicitly allowed are denied (so an
  42.166 +empty section means that all users are denied).
  42.167 +
  42.168 +The \rcsection{acl.deny} section determines which users are denied
  42.169 +from adding changesets to the repository.  If this section is not
  42.170 +present or is empty, no users are denied.
  42.171 +
  42.172 +The syntaxes for the \rcsection{acl.allow} and \rcsection{acl.deny}
  42.173 +sections are identical.  On the left of each entry is a glob pattern
  42.174 +that matches files or directories, relative to the root of the
  42.175 +repository; on the right, a user name.
  42.176 +
  42.177 +In the following example, the user \texttt{docwriter} can only push
  42.178 +changes to the \dirname{docs} subtree of the repository, while
  42.179 +\texttt{intern} can push changes to any file or directory except
  42.180 +\dirname{source/sensitive}.
  42.181 +\begin{codesample2}
  42.182 +  [acl.allow]
  42.183 +  docs/** = docwriter
  42.184 +
  42.185 +  [acl.deny]
  42.186 +  source/sensitive/** = intern
  42.187 +\end{codesample2}
  42.188 +
  42.189 +\subsubsection{Testing and troubleshooting}
  42.190 +
  42.191 +If you want to test the \hgext{acl} hook, run it with Mercurial's
  42.192 +debugging output enabled.  Since you'll probably be running it on a
  42.193 +server where it's not convenient (or sometimes possible) to pass in
  42.194 +the \hggopt{--debug} option, don't forget that you can enable
  42.195 +debugging output in your \hgrc:
  42.196 +\begin{codesample2}
  42.197 +  [ui]
  42.198 +  debug = true
  42.199 +\end{codesample2}
  42.200 +With this enabled, the \hgext{acl} hook will print enough information
  42.201 +to let you figure out why it is allowing or forbidding pushes from
  42.202 +specific users.
  42.203 +
  42.204 +\subsection{\hgext{bugzilla}---integration with Bugzilla}
  42.205 +
  42.206 +The \hgext{bugzilla} extension adds a comment to a Bugzilla bug
  42.207 +whenever it finds a reference to that bug ID in a commit comment.  You
  42.208 +can install this hook on a shared server, so that any time a remote
  42.209 +user pushes changes to this server, the hook gets run.  
  42.210 +
  42.211 +It adds a comment to the bug that looks like this (you can configure
  42.212 +the contents of the comment---see below):
  42.213 +\begin{codesample2}
  42.214 +  Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in
  42.215 +  the frobnitz repository, refers to this bug.
  42.216 +
  42.217 +  For complete details, see
  42.218 +  http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
  42.219 +
  42.220 +  Changeset description:
  42.221 +        Fix bug 10483 by guarding against some NULL pointers
  42.222 +\end{codesample2}
  42.223 +The value of this hook is that it automates the process of updating a
  42.224 +bug any time a changeset refers to it.  If you configure the hook
  42.225 +properly, it makes it easy for people to browse straight from a
  42.226 +Bugzilla bug to a changeset that refers to that bug.
  42.227 +
  42.228 +You can use the code in this hook as a starting point for some more
  42.229 +exotic Bugzilla integration recipes.  Here are a few possibilities:
  42.230 +\begin{itemize}
  42.231 +\item Require that every changeset pushed to the server have a valid
  42.232 +  bug~ID in its commit comment.  In this case, you'd want to configure
  42.233 +  the hook as a \hook{pretxncommit} hook.  This would allow the hook
  42.234 +  to reject changes that didn't contain bug IDs.
  42.235 +\item Allow incoming changesets to automatically modify the
  42.236 +  \emph{state} of a bug, as well as simply adding a comment.  For
  42.237 +  example, the hook could recognise the string ``fixed bug 31337'' as
  42.238 +  indicating that it should update the state of bug 31337 to
  42.239 +  ``requires testing''.
  42.240 +\end{itemize}
  42.241 +
  42.242 +\subsubsection{Configuring the \hook{bugzilla} hook}
  42.243 +\label{sec:hook:bugzilla:config}
  42.244 +
  42.245 +You should configure this hook in your server's \hgrc\ as an
  42.246 +\hook{incoming} hook, for example as follows:
  42.247 +\begin{codesample2}
  42.248 +  [hooks]
  42.249 +  incoming.bugzilla = python:hgext.bugzilla.hook
  42.250 +\end{codesample2}
  42.251 +
  42.252 +Because of the specialised nature of this hook, and because Bugzilla
  42.253 +was not written with this kind of integration in mind, configuring
  42.254 +this hook is a somewhat involved process.
  42.255 +
  42.256 +Before you begin, you must install the MySQL bindings for Python on
  42.257 +the host(s) where you'll be running the hook.  If this is not
  42.258 +available as a binary package for your system, you can download it
  42.259 +from~\cite{web:mysql-python}.
  42.260 +
  42.261 +Configuration information for this hook lives in the
  42.262 +\rcsection{bugzilla} section of your \hgrc.
  42.263 +\begin{itemize}
  42.264 +\item[\rcitem{bugzilla}{version}] The version of Bugzilla installed on
  42.265 +  the server.  The database schema that Bugzilla uses changes
  42.266 +  occasionally, so this hook has to know exactly which schema to use.
  42.267 +  At the moment, the only version supported is \texttt{2.16}.
  42.268 +\item[\rcitem{bugzilla}{host}] The hostname of the MySQL server that
  42.269 +  stores your Bugzilla data.  The database must be configured to allow
  42.270 +  connections from whatever host you are running the \hook{bugzilla}
  42.271 +  hook on.
  42.272 +\item[\rcitem{bugzilla}{user}] The username with which to connect to
  42.273 +  the MySQL server.  The database must be configured to allow this
  42.274 +  user to connect from whatever host you are running the
  42.275 +  \hook{bugzilla} hook on.  This user must be able to access and
  42.276 +  modify Bugzilla tables.  The default value of this item is
  42.277 +  \texttt{bugs}, which is the standard name of the Bugzilla user in a
  42.278 +  MySQL database.
  42.279 +\item[\rcitem{bugzilla}{password}] The MySQL password for the user you
  42.280 +  configured above.  This is stored as plain text, so you should make
  42.281 +  sure that unauthorised users cannot read the \hgrc\ file where you
  42.282 +  store this information.
  42.283 +\item[\rcitem{bugzilla}{db}] The name of the Bugzilla database on the
  42.284 +  MySQL server.  The default value of this item is \texttt{bugs},
  42.285 +  which is the standard name of the MySQL database where Bugzilla
  42.286 +  stores its data.
  42.287 +\item[\rcitem{bugzilla}{notify}] If you want Bugzilla to send out a
  42.288 +  notification email to subscribers after this hook has added a
  42.289 +  comment to a bug, you will need this hook to run a command whenever
  42.290 +  it updates the database.  The command to run depends on where you
  42.291 +  have installed Bugzilla, but it will typically look something like
  42.292 +  this, if you have Bugzilla installed in
  42.293 +  \dirname{/var/www/html/bugzilla}:
  42.294 +  \begin{codesample4}
  42.295 +    cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com
  42.296 +  \end{codesample4}
  42.297 +  The Bugzilla \texttt{processmail} program expects to be given a
  42.298 +  bug~ID (the hook replaces ``\texttt{\%s}'' with the bug~ID) and an
  42.299 +  email address.  It also expects to be able to write to some files in
  42.300 +  the directory that it runs in.  If Bugzilla and this hook are not
  42.301 +  installed on the same machine, you will need to find a way to run
  42.302 +  \texttt{processmail} on the server where Bugzilla is installed.
  42.303 +\end{itemize}
  42.304 +
  42.305 +\subsubsection{Mapping committer names to Bugzilla user names}
  42.306 +
  42.307 +By default, the \hgext{bugzilla} hook tries to use the email address
  42.308 +of a changeset's committer as the Bugzilla user name with which to
  42.309 +update a bug.  If this does not suit your needs, you can map committer
  42.310 +email addresses to Bugzilla user names using a \rcsection{usermap}
  42.311 +section.
  42.312 +
  42.313 +Each item in the \rcsection{usermap} section contains an email address
  42.314 +on the left, and a Bugzilla user name on the right.
  42.315 +\begin{codesample2}
  42.316 +  [usermap]
  42.317 +  jane.user@example.com = jane
  42.318 +\end{codesample2}
  42.319 +You can either keep the \rcsection{usermap} data in a normal \hgrc, or
  42.320 +tell the \hgext{bugzilla} hook to read the information from an
  42.321 +external \filename{usermap} file.  In the latter case, you can store
  42.322 +\filename{usermap} data by itself in (for example) a user-modifiable
  42.323 +repository.  This makes it possible to let your users maintain their
  42.324 +own \rcitem{bugzilla}{usermap} entries.  The main \hgrc\ file might
  42.325 +look like this:
  42.326 +\begin{codesample2}
  42.327 +  # regular hgrc file refers to external usermap file
  42.328 +  [bugzilla]
  42.329 +  usermap = /home/hg/repos/userdata/bugzilla-usermap.conf
  42.330 +\end{codesample2}
  42.331 +While the \filename{usermap} file that it refers to might look like
  42.332 +this:
  42.333 +\begin{codesample2}
  42.334 +  # bugzilla-usermap.conf - inside a hg repository
  42.335 +  [usermap]
  42.336 +  stephanie@example.com = steph
  42.337 +\end{codesample2}
  42.338 +
  42.339 +\subsubsection{Configuring the text that gets added to a bug}
  42.340 +
  42.341 +You can configure the text that this hook adds as a comment; you
  42.342 +specify it in the form of a Mercurial template.  Several \hgrc\
  42.343 +entries (still in the \rcsection{bugzilla} section) control this
  42.344 +behaviour.
  42.345 +\begin{itemize}
  42.346 +\item[\texttt{strip}] The number of leading path elements to strip
  42.347 +  from a repository's path name to construct a partial path for a URL.
  42.348 +  For example, if the repositories on your server live under
  42.349 +  \dirname{/home/hg/repos}, and you have a repository whose path is
  42.350 +  \dirname{/home/hg/repos/app/tests}, then setting \texttt{strip} to
  42.351 +  \texttt{4} will give a partial path of \dirname{app/tests}.  The
  42.352 +  hook will make this partial path available when expanding a
  42.353 +  template, as \texttt{webroot}.
  42.354 +\item[\texttt{template}] The text of the template to use.  In addition
  42.355 +  to the usual changeset-related variables, this template can use
  42.356 +  \texttt{hgweb} (the value of the \texttt{hgweb} configuration item
  42.357 +  above) and \texttt{webroot} (the path constructed using
  42.358 +  \texttt{strip} above).
  42.359 +\end{itemize}
  42.360 +
  42.361 +In addition, you can add a \rcitem{web}{baseurl} item to the
  42.362 +\rcsection{web} section of your \hgrc.  The \hgext{bugzilla} hook will
  42.363 +make this available when expanding a template, as the base string to
  42.364 +use when constructing a URL that will let users browse from a Bugzilla
  42.365 +comment to view a changeset.  Example:
  42.366 +\begin{codesample2}
  42.367 +  [web]
  42.368 +  baseurl = http://hg.domain.com/
  42.369 +\end{codesample2}
  42.370 +
  42.371 +Here is an example set of \hgext{bugzilla} hook config information.
  42.372 +\begin{codesample2}
  42.373 +  [bugzilla]
  42.374 +  host = bugzilla.example.com
  42.375 +  password = mypassword
  42.376 +  version = 2.16
  42.377 +  # server-side repos live in /home/hg/repos, so strip 4 leading
  42.378 +  # separators
  42.379 +  strip = 4
  42.380 +  hgweb = http://hg.example.com/
  42.381 +  usermap = /home/hg/repos/notify/bugzilla.conf
  42.382 +  template = Changeset \{node|short\}, made by \{author\} in the \{webroot\}
  42.383 +    repo, refers to this bug.\\nFor complete details, see 
  42.384 +    \{hgweb\}\{webroot\}?cmd=changeset;node=\{node|short\}\\nChangeset
  42.385 +    description:\\n\\t\{desc|tabindent\}
  42.386 +\end{codesample2}
  42.387 +
  42.388 +\subsubsection{Testing and troubleshooting}
  42.389 +
  42.390 +The most common problems with configuring the \hgext{bugzilla} hook
  42.391 +relate to running Bugzilla's \filename{processmail} script and mapping
  42.392 +committer names to user names.
  42.393 +
  42.394 +Recall from section~\ref{sec:hook:bugzilla:config} above that the user
  42.395 +that runs the Mercurial process on the server is also the one that
  42.396 +will run the \filename{processmail} script.  The
  42.397 +\filename{processmail} script sometimes causes Bugzilla to write to
  42.398 +files in its configuration directory, and Bugzilla's configuration
  42.399 +files are usually owned by the user that your web server runs under.
  42.400 +
  42.401 +You can cause \filename{processmail} to be run with the suitable
  42.402 +user's identity using the \command{sudo} command.  Here is an example
  42.403 +entry for a \filename{sudoers} file.
  42.404 +\begin{codesample2}
  42.405 +  hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s
  42.406 +\end{codesample2}
  42.407 +This allows the \texttt{hg\_user} user to run a
  42.408 +\filename{processmail-wrapper} program under the identity of
  42.409 +\texttt{httpd\_user}.
  42.410 +
  42.411 +This indirection through a wrapper script is necessary, because
  42.412 +\filename{processmail} expects to be run with its current directory
  42.413 +set to wherever you installed Bugzilla; you can't specify that kind of
  42.414 +constraint in a \filename{sudoers} file.  The contents of the wrapper
  42.415 +script are simple:
  42.416 +\begin{codesample2}
  42.417 +  #!/bin/sh
  42.418 +  cd `dirname $0` && ./processmail "$1" nobody@example.com
  42.419 +\end{codesample2}
  42.420 +It doesn't seem to matter what email address you pass to
  42.421 +\filename{processmail}.
  42.422 +
  42.423 +If your \rcsection{usermap} is not set up correctly, users will see an
  42.424 +error message from the \hgext{bugzilla} hook when they push changes
  42.425 +to the server.  The error message will look like this:
  42.426 +\begin{codesample2}
  42.427 +  cannot find bugzilla user id for john.q.public@example.com
  42.428 +\end{codesample2}
  42.429 +What this means is that the committer's address,
  42.430 +\texttt{john.q.public@example.com}, is not a valid Bugzilla user name,
  42.431 +nor does it have an entry in your \rcsection{usermap} that maps it to
  42.432 +a valid Bugzilla user name.
  42.433 +
  42.434 +\subsection{\hgext{notify}---send email notifications}
  42.435 +
  42.436 +Although Mercurial's built-in web server provides RSS feeds of changes
  42.437 +in every repository, many people prefer to receive change
  42.438 +notifications via email.  The \hgext{notify} hook lets you send out
  42.439 +notifications to a set of email addresses whenever changesets arrive
  42.440 +that those subscribers are interested in.
  42.441 +
  42.442 +As with the \hgext{bugzilla} hook, the \hgext{notify} hook is
  42.443 +template-driven, so you can customise the contents of the notification
  42.444 +messages that it sends.
  42.445 +
  42.446 +By default, the \hgext{notify} hook includes a diff of every changeset
  42.447 +that it sends out; you can limit the size of the diff, or turn this
  42.448 +feature off entirely.  It is useful for letting subscribers review
  42.449 +changes immediately, rather than clicking to follow a URL.
  42.450 +
  42.451 +\subsubsection{Configuring the \hgext{notify} hook}
  42.452 +
  42.453 +You can set up the \hgext{notify} hook to send one email message per
  42.454 +incoming changeset, or one per incoming group of changesets (all those
  42.455 +that arrived in a single pull or push).
  42.456 +\begin{codesample2}
  42.457 +  [hooks]
  42.458 +  # send one email per group of changes
  42.459 +  changegroup.notify = python:hgext.notify.hook
  42.460 +  # send one email per change
  42.461 +  incoming.notify = python:hgext.notify.hook
  42.462 +\end{codesample2}
  42.463 +
  42.464 +Configuration information for this hook lives in the
  42.465 +\rcsection{notify} section of a \hgrc\ file.
  42.466 +\begin{itemize}
  42.467 +\item[\rcitem{notify}{test}] By default, this hook does not send out
  42.468 +  email at all; instead, it prints the message that it \emph{would}
  42.469 +  send.  Set this item to \texttt{false} to allow email to be sent.
  42.470 +  The reason that sending of email is turned off by default is that it
  42.471 +  takes several tries to configure this extension exactly as you would
  42.472 +  like, and it would be bad form to spam subscribers with a number of
  42.473 +  ``broken'' notifications while you debug your configuration.
  42.474 +\item[\rcitem{notify}{config}] The path to a configuration file that
  42.475 +  contains subscription information.  This is kept separate from the
  42.476 +  main \hgrc\ so that you can maintain it in a repository of its own.
  42.477 +  People can then clone that repository, update their subscriptions,
  42.478 +  and push the changes back to your server.
  42.479 +\item[\rcitem{notify}{strip}] The number of leading path separator
  42.480 +  characters to strip from a repository's path, when deciding whether
  42.481 +  a repository has subscribers.  For example, if the repositories on
  42.482 +  your server live in \dirname{/home/hg/repos}, and \hgext{notify} is
  42.483 +  considering a repository named \dirname{/home/hg/repos/shared/test},
  42.484 +  setting \rcitem{notify}{strip} to \texttt{4} will cause
  42.485 +  \hgext{notify} to trim the path it considers down to
  42.486 +  \dirname{shared/test}, and it will match subscribers against that.
  42.487 +\item[\rcitem{notify}{template}] The template text to use when sending
  42.488 +  messages.  This specifies both the contents of the message header
  42.489 +  and its body.
  42.490 +\item[\rcitem{notify}{maxdiff}] The maximum number of lines of diff
  42.491 +  data to append to the end of a message.  If a diff is longer than
  42.492 +  this, it is truncated.  By default, this is set to 300.  Set this to
  42.493 +  \texttt{0} to omit diffs from notification emails.
  42.494 +\item[\rcitem{notify}{sources}] A list of sources of changesets to
  42.495 +  consider.  This lets you limit \hgext{notify} to only sending out
  42.496 +  email about changes that remote users pushed into this repository
  42.497 +  via a server, for example.  See section~\ref{sec:hook:sources} for
  42.498 +  the sources you can specify here.
  42.499 +\end{itemize}
  42.500 +
  42.501 +If you set the \rcitem{web}{baseurl} item in the \rcsection{web}
  42.502 +section, you can use it in a template; it will be available as
  42.503 +\texttt{webroot}.
  42.504 +
  42.505 +Here is an example set of \hgext{notify} configuration information.
  42.506 +\begin{codesample2}
  42.507 +  [notify]
  42.508 +  # really send email
  42.509 +  test = false
  42.510 +  # subscriber data lives in the notify repo
  42.511 +  config = /home/hg/repos/notify/notify.conf
  42.512 +  # repos live in /home/hg/repos on server, so strip 4 "/" chars
  42.513 +  strip = 4
  42.514 +  template = X-Hg-Repo: \{webroot\}\\n\\\\
  42.515 +    Subject: \{webroot\}: \{desc|firstline|strip\}\\n\\\\
  42.516 +    From: \{author\}\\n\\\\
  42.517 +    \\n\\\\
  42.518 +    changeset \{node|short\} in \{root\}\\n\\\\
  42.519 +    details: \{baseurl\}\{webroot\}?cmd=changeset;node=\{node|short\}\\n\\\\
  42.520 +    description:\\n\\\\
  42.521 +    \\t\{desc|tabindent|strip\}
  42.522 +
  42.523 +  [web]
  42.524 +  baseurl = http://hg.example.com/
  42.525 +\end{codesample2}
  42.526 +
  42.527 +This will produce a message that looks like the following:
  42.528 +\begin{codesample2}
  42.529 +  X-Hg-Repo: tests/slave
  42.530 +  Subject: tests/slave: Handle error case when slave has no buffers
  42.531 +  Date: Wed,  2 Aug 2006 15:25:46 -0700 (PDT)
  42.532 +
  42.533 +  changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
  42.534 +  details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
  42.535 +  description:
  42.536 +          Handle error case when slave has no buffers
  42.537 +  diffs (54 lines):
  42.538 +
  42.539 +  diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
  42.540 +  --- a/include/tests.h      Wed Aug 02 15:19:52 2006 -0700
  42.541 +  +++ b/include/tests.h      Wed Aug 02 15:25:26 2006 -0700
  42.542 +  @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h)
  42.543 +  [...snip...]
  42.544 +\end{codesample2}
  42.545 +
  42.546 +\subsubsection{Testing and troubleshooting}
  42.547 +
  42.548 +Do not forget that by default, the \hgext{notify} extension \emph{will
  42.549 +  not send any mail} until you explicitly configure it to do so, by
  42.550 +setting \rcitem{notify}{test} to \texttt{false}.  Until you do that,
  42.551 +it simply prints the message it \emph{would} send.
  42.552 +
  42.553 +\section{Information for writers of hooks}
  42.554  \label{sec:hook:ref}
  42.555  
  42.556  \subsection{In-process hook execution}
  42.557 @@ -450,26 +975,34 @@
  42.558    \texttt{parent\emph{N}}, it will contain a hexadecimal changeset ID.
  42.559    The empty string is used to represent ``null changeset ID'' instead
  42.560    of a string of zeroes.
  42.561 +\item If a parameter is named \texttt{url}, it will contain the URL of
  42.562 +  a remote repository, if that can be determined.
  42.563  \item Boolean-valued parameters are represented as Python
  42.564    \texttt{bool} objects.
  42.565  \end{itemize}
  42.566  
  42.567  An in-process hook is called without a change to the process's working
  42.568  directory (unlike external hooks, which are run in the root of the
  42.569 -repository).  It must not change the process's working directory.  If
  42.570 -it were to do so, it would probably cause calls to the Mercurial API,
  42.571 -or operations after the hook finishes, to fail.
  42.572 -
  42.573 -If a hook returns a boolean ``false'' value, it is considered to
  42.574 -have succeeded.  If it returns a boolean ``true'' value or raises an
  42.575 -exception, it is considered to have failed.
  42.576 +repository).  It must not change the process's working directory, or
  42.577 +it will cause any calls it makes into the Mercurial API to fail.
  42.578 +
  42.579 +If a hook returns a boolean ``false'' value, it is considered to have
  42.580 +succeeded.  If it returns a boolean ``true'' value or raises an
  42.581 +exception, it is considered to have failed.  A useful way to think of
  42.582 +the calling convention is ``tell me if you fail''.
  42.583 +
  42.584 +Note that changeset IDs are passed into Python hooks as hexadecimal
  42.585 +strings, not the binary hashes that Mercurial's APIs normally use.  To
  42.586 +convert a hash from hex to binary, use the
  42.587 +\pymodfunc{mercurial.node}{bin} function.
  42.588  
  42.589  \subsection{External hook execution}
  42.590  
  42.591 -An external hook is passed to the user's shell for execution, so
  42.592 -features of that shell, such as variable substitution and command
  42.593 +An external hook is passed to the shell of the user running Mercurial.
  42.594 +Features of that shell, such as variable substitution and command
  42.595  redirection, are available.  The hook is run in the root directory of
  42.596 -the repository.
  42.597 +the repository (unlike in-process hooks, which are run in the same
  42.598 +directory that Mercurial was run in).
  42.599  
  42.600  Hook parameters are passed to the hook as environment variables.  Each
  42.601  environment variable's name is converted in upper case and prefixed
  42.602 @@ -482,13 +1015,67 @@
  42.603  named \envar{HG\_NODE}, \envar{HG\_PARENT1} or \envar{HG\_PARENT2}, it
  42.604  contains a changeset ID represented as a hexadecimal string.  The
  42.605  empty string is used to represent ``null changeset ID'' instead of a
  42.606 -string of zeroes.
  42.607 +string of zeroes.  If an environment variable is named
  42.608 +\envar{HG\_URL}, it will contain the URL of a remote repository, if
  42.609 +that can be determined.
  42.610  
  42.611  If a hook exits with a status of zero, it is considered to have
  42.612  succeeded.  If it exits with a non-zero status, it is considered to
  42.613  have failed.
  42.614  
  42.615 -\subsection{The \hook{changegroup} hook}
  42.616 +\subsection{Finding out where changesets come from}
  42.617 +
  42.618 +A hook that involves the transfer of changesets between a local
  42.619 +repository and another may be able to find out information about the
  42.620 +``far side''.  Mercurial knows \emph{how} changes are being
  42.621 +transferred, and in many cases \emph{where} they are being transferred
  42.622 +to or from.
  42.623 +
  42.624 +\subsubsection{Sources of changesets}
  42.625 +\label{sec:hook:sources}
  42.626 +
  42.627 +Mercurial will tell a hook what means are, or were, used to transfer
  42.628 +changesets between repositories.  This is provided by Mercurial in a
  42.629 +Python parameter named \texttt{source}, or an environment variable named
  42.630 +\envar{HG\_SOURCE}.
  42.631 +
  42.632 +\begin{itemize}
  42.633 +\item[\texttt{serve}] Changesets are transferred to or from a remote
  42.634 +  repository over http or ssh.
  42.635 +\item[\texttt{pull}] Changesets are being transferred via a pull from
  42.636 +  one repository into another.
  42.637 +\item[\texttt{push}] Changesets are being transferred via a push from
  42.638 +  one repository into another.
  42.639 +\item[\texttt{bundle}] Changesets are being transferred to or from a
  42.640 +  bundle.
  42.641 +\end{itemize}
  42.642 +
  42.643 +\subsubsection{Where changes are going---remote repository URLs}
  42.644 +\label{sec:hook:url}
  42.645 +
  42.646 +When possible, Mercurial will tell a hook the location of the ``far
  42.647 +side'' of an activity that transfers changeset data between
  42.648 +repositories.  This is provided by Mercurial in a Python parameter
  42.649 +named \texttt{url}, or an environment variable named \envar{HG\_URL}.
  42.650 +
  42.651 +This information is not always known.  If a hook is invoked in a
  42.652 +repository that is being served via http or ssh, Mercurial cannot tell
  42.653 +where the remote repository is, but it may know where the client is
  42.654 +connecting from.  In such cases, the URL will take one of the
  42.655 +following forms:
  42.656 +\begin{itemize}
  42.657 +\item \texttt{remote:ssh:\emph{ip-address}}---remote ssh client, at
  42.658 +  the given IP address.
  42.659 +\item \texttt{remote:http:\emph{ip-address}}---remote http client, at
  42.660 +  the given IP address.  If the client is using SSL, this will be of
  42.661 +  the form \texttt{remote:https:\emph{ip-address}}.
  42.662 +\item Empty---no information could be discovered about the remote
  42.663 +  client.
  42.664 +\end{itemize}
  42.665 +
  42.666 +\section{Hook reference}
  42.667 +
  42.668 +\subsection{\hook{changegroup}---after remote changesets added}
  42.669  \label{sec:hook:changegroup}
  42.670  
  42.671  This hook is run after a group of pre-existing changesets has been
  42.672 @@ -508,13 +1095,17 @@
  42.673    changeset in the group that was added.  All changesets between this
  42.674    and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
  42.675    a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
  42.676 +\item[\texttt{source}] A string.  The source of these changes.  See
  42.677 +  section~\ref{sec:hook:sources} for details.
  42.678 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  42.679 +  known.  See section~\ref{sec:hook:url} for more information.
  42.680  \end{itemize}
  42.681  
  42.682  See also: \hook{incoming} (section~\ref{sec:hook:incoming}),
  42.683  \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}),
  42.684  \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
  42.685  
  42.686 -\subsection{The \hook{commit} hook}
  42.687 +\subsection{\hook{commit}---after a new changeset is created}
  42.688  \label{sec:hook:commit}
  42.689  
  42.690  This hook is run after a new changeset has been created.
  42.691 @@ -532,7 +1123,7 @@
  42.692  See also: \hook{precommit} (section~\ref{sec:hook:precommit}),
  42.693  \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
  42.694  
  42.695 -\subsection{The \hook{incoming} hook}
  42.696 +\subsection{\hook{incoming}---after one remote changeset is added}
  42.697  \label{sec:hook:incoming}
  42.698  
  42.699  This hook is run after a pre-existing changeset has been added to the
  42.700 @@ -542,18 +1133,22 @@
  42.701  
  42.702  You can use this hook for the same purposes as the \hook{changegroup}
  42.703  hook (section~\ref{sec:hook:changegroup}); it's simply more convenient
  42.704 -sometimes to run a hook once per group of changesets, while othher
  42.705 +sometimes to run a hook once per group of changesets, while other
  42.706  times it's handier once per changeset.
  42.707  
  42.708  Parameters to this hook:
  42.709  \begin{itemize}
  42.710  \item[\texttt{node}] A changeset ID.  The ID of the newly added
  42.711    changeset.
  42.712 +\item[\texttt{source}] A string.  The source of these changes.  See
  42.713 +  section~\ref{sec:hook:sources} for details.
  42.714 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  42.715 +  known.  See section~\ref{sec:hook:url} for more information.
  42.716  \end{itemize}
  42.717  
  42.718  See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}) \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}), \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
  42.719  
  42.720 -\subsection{The \hook{outgoing} hook}
  42.721 +\subsection{\hook{outgoing}---after changesets are propagated}
  42.722  \label{sec:hook:outgoing}
  42.723  
  42.724  This hook is run after a group of changesets has been propagated out
  42.725 @@ -567,17 +1162,20 @@
  42.726  \begin{itemize}
  42.727  \item[\texttt{node}] A changeset ID.  The changeset ID of the first
  42.728    changeset of the group that was sent.
  42.729 -\item[\texttt{source}] A string.  The source of the of the operation.
  42.730 -  If a remote client pulled changes from this repository,
  42.731 -  \texttt{source} will be \texttt{serve}.  If the client that obtained
  42.732 -  changes from this repository was local, \texttt{source} will be
  42.733 -  \texttt{bundle}, \texttt{pull}, or \texttt{push}, depending on the
  42.734 -  operation the client performed.
  42.735 +\item[\texttt{source}] A string.  The source of the of the operation
  42.736 +  (see section~\ref{sec:hook:sources}).  If a remote client pulled
  42.737 +  changes from this repository, \texttt{source} will be
  42.738 +  \texttt{serve}.  If the client that obtained changes from this
  42.739 +  repository was local, \texttt{source} will be \texttt{bundle},
  42.740 +  \texttt{pull}, or \texttt{push}, depending on the operation the
  42.741 +  client performed.
  42.742 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  42.743 +  known.  See section~\ref{sec:hook:url} for more information.
  42.744  \end{itemize}
  42.745  
  42.746  See also: \hook{preoutgoing} (section~\ref{sec:hook:preoutgoing})
  42.747  
  42.748 -\subsection{The \hook{prechangegroup} hook}
  42.749 +\subsection{\hook{prechangegroup}---before starting to add remote changesets}
  42.750  \label{sec:hook:prechangegroup}
  42.751  
  42.752  This controlling hook is run before Mercurial begins to add a group of
  42.753 @@ -589,16 +1187,24 @@
  42.754  transmitted.
  42.755  
  42.756  One use for this hook is to prevent external changes from being added
  42.757 -to a repository, for example to ``freeze'' a server-hosted branch
  42.758 -temporarily or permanently.
  42.759 -
  42.760 -This hook is not passed any parameters.
  42.761 +to a repository.  For example, you could use this to ``freeze'' a
  42.762 +server-hosted branch temporarily or permanently so that users cannot
  42.763 +push to it, while still allowing a local administrator to modify the
  42.764 +repository.
  42.765 +
  42.766 +Parameters to this hook:
  42.767 +\begin{itemize}
  42.768 +\item[\texttt{source}] A string.  The source of these changes.  See
  42.769 +  section~\ref{sec:hook:sources} for details.
  42.770 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  42.771 +  known.  See section~\ref{sec:hook:url} for more information.
  42.772 +\end{itemize}
  42.773  
  42.774  See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
  42.775  \hook{incoming} (section~\ref{sec:hook:incoming}), ,
  42.776  \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
  42.777  
  42.778 -\subsection{The \hook{precommit} hook}
  42.779 +\subsection{\hook{precommit}---before starting to commit a changeset}
  42.780  \label{sec:hook:precommit}
  42.781  
  42.782  This hook is run before Mercurial begins to commit a new changeset.
  42.783 @@ -624,7 +1230,7 @@
  42.784  See also: \hook{commit} (section~\ref{sec:hook:commit}),
  42.785  \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
  42.786  
  42.787 -\subsection{The \hook{preoutgoing} hook}
  42.788 +\subsection{\hook{preoutgoing}---before starting to propagate changesets}
  42.789  \label{sec:hook:preoutgoing}
  42.790  
  42.791  This hook is invoked before Mercurial knows the identities of the
  42.792 @@ -636,15 +1242,18 @@
  42.793  Parameters to this hook:
  42.794  \begin{itemize}
  42.795  \item[\texttt{source}] A string.  The source of the operation that is
  42.796 -  attempting to obtain changes from this repository.  See the
  42.797 -  documentation for the \texttt{source} parameter to the
  42.798 -  \hook{outgoing} hook, in section~\ref{sec:hook:outgoing}, for
  42.799 -  possible values of this parameter..
  42.800 +  attempting to obtain changes from this repository (see
  42.801 +  section~\ref{sec:hook:sources}).  See the documentation for the
  42.802 +  \texttt{source} parameter to the \hook{outgoing} hook, in
  42.803 +  section~\ref{sec:hook:outgoing}, for possible values of this
  42.804 +  parameter.
  42.805 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  42.806 +  known.  See section~\ref{sec:hook:url} for more information.
  42.807  \end{itemize}
  42.808  
  42.809  See also: \hook{outgoing} (section~\ref{sec:hook:outgoing})
  42.810  
  42.811 -\subsection{The \hook{pretag} hook}
  42.812 +\subsection{\hook{pretag}---before tagging a changeset}
  42.813  \label{sec:hook:pretag}
  42.814  
  42.815  This controlling hook is run before a tag is created.  If the hook
  42.816 @@ -666,7 +1275,8 @@
  42.817  
  42.818  See also: \hook{tag} (section~\ref{sec:hook:tag})
  42.819  
  42.820 -\subsection{The \hook{pretxnchangegroup} hook}
  42.821 +\subsection{\hook{pretxnchangegroup}---before completing addition of
  42.822 +  remote changesets}
  42.823  \label{sec:hook:pretxnchangegroup}
  42.824  
  42.825  This controlling hook is run before a transaction---that manages the
  42.826 @@ -689,14 +1299,23 @@
  42.827  the hook fails, all of the changesets are ``rejected'' when the
  42.828  transaction rolls back.
  42.829  
  42.830 -Parameters to this hook are the same as for the \hook{changegroup}
  42.831 -hook; see section~\ref{sec:hook:changegroup} for details.
  42.832 +Parameters to this hook:
  42.833 +\begin{itemize}
  42.834 +\item[\texttt{node}] A changeset ID.  The changeset ID of the first
  42.835 +  changeset in the group that was added.  All changesets between this
  42.836 +  and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
  42.837 +  a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
  42.838 +\item[\texttt{source}] A string.  The source of these changes.  See
  42.839 +  section~\ref{sec:hook:sources} for details.
  42.840 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  42.841 +  known.  See section~\ref{sec:hook:url} for more information.
  42.842 +\end{itemize}
  42.843  
  42.844  See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
  42.845  \hook{incoming} (section~\ref{sec:hook:incoming}),
  42.846  \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup})
  42.847  
  42.848 -\subsection{The \hook{pretxncommit} hook}
  42.849 +\subsection{\hook{pretxncommit}---before completing commit of new changeset}
  42.850  \label{sec:hook:pretxncommit}
  42.851  
  42.852  This controlling hook is run before a transaction---that manages a new
  42.853 @@ -714,12 +1333,19 @@
  42.854  is permanent.  This may lead to race conditions if you do not take
  42.855  steps to avoid them.
  42.856  
  42.857 -Parameters to this hook are the same as for the \hook{commit} hook;
  42.858 -see section~\ref{sec:hook:commit} for details.
  42.859 +Parameters to this hook:
  42.860 +\begin{itemize}
  42.861 +\item[\texttt{node}] A changeset ID.  The changeset ID of the newly
  42.862 +  committed changeset.
  42.863 +\item[\texttt{parent1}] A changeset ID.  The changeset ID of the first
  42.864 +  parent of the newly committed changeset.
  42.865 +\item[\texttt{parent2}] A changeset ID.  The changeset ID of the second
  42.866 +  parent of the newly committed changeset.
  42.867 +\end{itemize}
  42.868  
  42.869  See also: \hook{precommit} (section~\ref{sec:hook:precommit})
  42.870  
  42.871 -\subsection{The \hook{preupdate} hook}
  42.872 +\subsection{\hook{preupdate}---before updating or merging working directory}
  42.873  \label{sec:hook:preupdate}
  42.874  
  42.875  This controlling hook is run before an update or merge of the working
  42.876 @@ -740,20 +1366,27 @@
  42.877  
  42.878  See also: \hook{update} (section~\ref{sec:hook:update})
  42.879  
  42.880 -\subsection{The \hook{tag} hook}
  42.881 +\subsection{\hook{tag}---after tagging a changeset}
  42.882  \label{sec:hook:tag}
  42.883  
  42.884  This hook is run after a tag has been created.
  42.885  
  42.886 -Parameters to this hook are the same as for the \hook{pretag} hook;
  42.887 -see section~\ref{sec:hook:pretag} for details.
  42.888 +Parameters to this hook:
  42.889 +\begin{itemize}
  42.890 +\item[\texttt{local}] A boolean.  Whether the new tag is local to this
  42.891 +  repository instance (i.e.~stored in \sfilename{.hg/tags}) or managed
  42.892 +  by Mercurial (stored in \sfilename{.hgtags}).
  42.893 +\item[\texttt{node}] A changeset ID.  The ID of the changeset that was
  42.894 +  tagged.
  42.895 +\item[\texttt{tag}] A string.  The name of the tag that was created.
  42.896 +\end{itemize}
  42.897  
  42.898  If the created tag is revision-controlled, the \hook{commit} hook
  42.899  (section~\ref{sec:hook:commit}) is run before this hook.
  42.900  
  42.901  See also: \hook{pretag} (section~\ref{sec:hook:pretag})
  42.902  
  42.903 -\subsection{The \hook{update} hook}
  42.904 +\subsection{\hook{update}---after updating or merging working directory}
  42.905  \label{sec:hook:update}
  42.906  
  42.907  This hook is run after an update or merge of the working directory