hgbook
changeset 562:f916a8c80554
Get rid of .tex files.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Mar 09 21:13:56 2009 -0700 (2009-03-09) |
parents | 21c62e09b99f |
children | 44d1363234d2 |
files | en/00book.tex en/99defs.tex en/appA-cmdref.tex en/appB-mq-ref.tex en/appC-srcinstall.tex en/appD-license.tex en/ch00-preface.tex en/ch01-intro.tex en/ch02-tour-basic.tex en/ch03-tour-merge.tex en/ch04-concepts.tex en/ch05-daily.tex en/ch06-collab.tex en/ch07-filenames.tex en/ch08-branch.tex en/ch09-undo.tex en/ch10-hook.tex en/ch11-template.tex en/ch12-mq.tex en/ch13-mq-collab.tex en/ch14-hgext.tex |
line diff
1.1 --- a/en/00book.tex Thu Mar 05 21:52:23 2009 +0200 1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 1.3 @@ -1,76 +0,0 @@ 1.4 -% The use of oneside here is a temporary hack; \marginpar entries 1.5 -% don't show up on odd pages of PDF output without it. Sigh. 1.6 -\documentclass[oneside]{book} 1.7 -\usepackage{enumerate} 1.8 -\usepackage{fullpage} 1.9 -\usepackage{makeidx} 1.10 -\usepackage{ifpdf} 1.11 -\usepackage{graphicx} 1.12 -\usepackage{pslatex} 1.13 -\usepackage{fancyvrb} 1.14 -% leave hyperref until last 1.15 -\usepackage[colorlinks=true,bookmarks=true,pdftitle={Distributed 1.16 - revision control with Mercurial},pdfsubject={Revision 1.17 - control},pdfkeywords={Mercurial, Revision control, Distributed 1.18 - revision control},pdfauthor={Bryan O'Sullivan}]{hyperref} 1.19 - 1.20 -\include{99defs} 1.21 - 1.22 -\title{Distributed revision control with Mercurial} \author{Bryan 1.23 - O'Sullivan} 1.24 -\date{Copyright \copyright\ 2006, 2007 Bryan O'Sullivan.\\ 1.25 - This material may be distributed only subject to the terms and 1.26 - conditions set forth in version 1.0 of the Open Publication License. 1.27 - Please refer to Appendix~\ref{cha:opl} for the license text.\\ 1.28 - This book was prepared from 1.29 - \href{http://hg.serpentine.com/mercurial/book/}{rev~\input{build_id}} 1.30 - using \href{http://www.selenic.com/hg/}{rev~\input{hg_id}} of Mercurial.} 1.31 - 1.32 -\makeindex 1.33 - 1.34 -\begin{document} 1.35 - 1.36 -\maketitle 1.37 - 1.38 -\addcontentsline{toc}{chapter}{Contents} 1.39 -\pagenumbering{roman} 1.40 -\tableofcontents 1.41 -\listoffigures 1.42 -%\listoftables 1.43 - 1.44 -\pagenumbering{arabic} 1.45 - 1.46 -\include{ch00-preface} 1.47 -\include{ch01-intro} 1.48 -\include{ch02-tour-basic} 1.49 -\include{ch03-tour-merge} 1.50 -\include{ch04-concepts} 1.51 -\include{ch05-daily} 1.52 -\include{ch06-collab} 1.53 -\include{ch07-filenames} 1.54 -\include{ch08-branch} 1.55 -\include{ch09-undo} 1.56 -\include{ch10-hook} 1.57 -\include{ch11-template} 1.58 -\include{ch12-mq} 1.59 -\include{ch13-mq-collab} 1.60 -\include{ch14-hgext} 1.61 - 1.62 -\appendix 1.63 -\include{appA-cmdref} 1.64 -\include{appB-mq-ref} 1.65 -\include{appC-srcinstall} 1.66 -\include{appD-license} 1.67 -\addcontentsline{toc}{chapter}{Bibliography} 1.68 -\bibliographystyle{alpha} 1.69 -\bibliography{99book} 1.70 - 1.71 -\addcontentsline{toc}{chapter}{Index} 1.72 -\printindex 1.73 - 1.74 -\end{document} 1.75 - 1.76 -%%% Local Variables: 1.77 -%%% mode: latex 1.78 -%%% TeX-master: t 1.79 -%%% End:
2.1 --- a/en/99defs.tex Thu Mar 05 21:52:23 2009 +0200 2.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 2.3 @@ -1,146 +0,0 @@ 2.4 -% Bug ID. 2.5 -\newcommand{\bug}[1]{\index{Mercurial bug 2.6 - database!\href{http://www.selenic.com/mercurial/bts/issue#1}{bug 2.7 - ~#1}}\href{http://www.selenic.com/mercurial/bts/issue#1}{Mercurial 2.8 - bug no.~#1}} 2.9 - 2.10 -% File name in the user's home directory. 2.11 -\newcommand{\tildefile}[1]{\texttt{\~{}/#1}} 2.12 - 2.13 -% File name. 2.14 -\newcommand{\filename}[1]{\texttt{#1}} 2.15 - 2.16 -% Directory name. 2.17 -\newcommand{\dirname}[1]{\texttt{#1}} 2.18 - 2.19 -% File name, with index entry. 2.20 -% The ``s'' prefix comes from ``special''. 2.21 -\newcommand{\sfilename}[1]{\index{\texttt{#1} file}\texttt{#1}} 2.22 - 2.23 -% Directory name, with index entry. 2.24 -\newcommand{\sdirname}[1]{\index{\texttt{#1} directory}\texttt{#1}} 2.25 - 2.26 -% Mercurial extension. 2.27 -\newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}} 2.28 - 2.29 -% Command provided by a Mercurial extension. 2.30 -\newcommand{\hgxcmd}[2]{\index{\texttt{#2} command (\texttt{#1} 2.31 - extension)}\index{\texttt{#1} extension!\texttt{#2} command}``\texttt{hg #2}''} 2.32 - 2.33 -% Mercurial command. 2.34 -\newcommand{\hgcmd}[1]{\index{\texttt{#1} command}``\texttt{hg #1}''} 2.35 - 2.36 -% Mercurial command, with arguments. 2.37 -\newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''} 2.38 - 2.39 -\newcommand{\tplkword}[1]{\index{\texttt{#1} template keyword}\index{template keywords!\texttt{#1}}\texttt{#1}} 2.40 - 2.41 -\newcommand{\tplkwfilt}[2]{\index{\texttt{#1} template keyword!\texttt{#2} 2.42 - filter}\index{template filters!\texttt{#2}}\index{\texttt{#2} 2.43 - template filter}\texttt{#2}} 2.44 - 2.45 -\newcommand{\tplfilter}[1]{\index{template 2.46 - filters!\texttt{#1}}\index{\texttt{#1} template 2.47 - filter}\texttt{#1}} 2.48 - 2.49 -% Shell/system command. 2.50 -\newcommand{\command}[1]{\index{\texttt{#1} system command}\texttt{#1}} 2.51 - 2.52 -% Shell/system command, with arguments. 2.53 -\newcommand{\cmdargs}[2]{\index{\texttt{#1} system command}``\texttt{#1 #2}''} 2.54 - 2.55 -% Mercurial command option. 2.56 -\newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}} 2.57 - 2.58 -% Mercurial command option, provided by an extension command. 2.59 -\newcommand{\hgxopt}[3]{\index{\texttt{#2} command (\texttt{#1} extension)!\texttt{#3} option}\index{\texttt{#1} extension!\texttt{#2} command!\texttt{#3} option}\texttt{#3}} 2.60 - 2.61 -% Mercurial global option. 2.62 -\newcommand{\hggopt}[1]{\index{global options!\texttt{#1} option}\texttt{#1}} 2.63 - 2.64 -% Shell/system command option. 2.65 -\newcommand{\cmdopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}} 2.66 - 2.67 -% Command option. 2.68 -\newcommand{\option}[1]{\texttt{#1}} 2.69 - 2.70 -% Software package. 2.71 -\newcommand{\package}[1]{\index{\texttt{#1} package}\texttt{#1}} 2.72 - 2.73 -% Section name from a hgrc file. 2.74 -\newcommand{\rcsection}[1]{\index{\texttt{hgrc} file!\texttt{#1} section}\texttt{[#1]}} 2.75 - 2.76 -% Named item in a hgrc file section. 2.77 -\newcommand{\rcitem}[2]{\index{\texttt{hgrc} file!\texttt{#1} 2.78 - section!\texttt{#2} entry}\texttt{#2}} 2.79 - 2.80 -% hgrc file. 2.81 -\newcommand{\hgrc}{\index{configuration file!\texttt{hgrc} 2.82 - (Linux/Unix)}\index{\texttt{hgrc} configuration file}\texttt{hgrc}} 2.83 - 2.84 -% Mercurial.ini file. 2.85 -\newcommand{\hgini}{\index{configuration file!\texttt{Mercurial.ini} 2.86 - (Windows)}\index{\texttt{Mercurial.ini} configuration file}\texttt{Mercurial.ini}} 2.87 - 2.88 -% Hook name. 2.89 -\newcommand{\hook}[1]{\index{\texttt{#1} hook}\index{hooks!\texttt{#1}}\texttt{#1}} 2.90 - 2.91 -% Environment variable. 2.92 -\newcommand{\envar}[1]{\index{\texttt{#1} environment 2.93 - variable}\index{environment variables!\texttt{#1}}\texttt{#1}} 2.94 - 2.95 -% Python module. 2.96 -\newcommand{\pymod}[1]{\index{\texttt{#1} module}\texttt{#1}} 2.97 - 2.98 -% Python class in a module. 2.99 -\newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2} 2.100 - class}\texttt{#1.#2}} 2.101 - 2.102 -% Python function in a module. 2.103 -\newcommand{\pymodfunc}[2]{\index{\texttt{#1} module!\texttt{#2} 2.104 - function}\texttt{#1.#2}} 2.105 - 2.106 -% Note: blah blah. 2.107 -\newsavebox{\notebox} 2.108 -\newenvironment{note}% 2.109 - {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Note:}\space}% 2.110 - {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}} 2.111 -\newenvironment{caution}% 2.112 - {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Caution:}\space}% 2.113 - {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}} 2.114 - 2.115 -% Code sample, eating 4 characters of leading space. 2.116 -\DefineVerbatimEnvironment{codesample4}{Verbatim}{frame=single,gobble=4,numbers=left,commandchars=\\\{\}} 2.117 - 2.118 -% Code sample, eating 2 characters of leading space. 2.119 -\DefineVerbatimEnvironment{codesample2}{Verbatim}{frame=single,gobble=2,numbers=left,commandchars=\\\{\}} 2.120 - 2.121 -% Interaction from the examples directory. 2.122 -\newcommand{\interaction}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{examples/#1.lxo}} 2.123 -% Example code from the examples directory. 2.124 -\newcommand{\excode}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{../examples/#1}} 2.125 - 2.126 -% Graphics inclusion. 2.127 -\ifpdf 2.128 - \newcommand{\grafix}[1]{\includegraphics{#1}} 2.129 -\else 2.130 - \newcommand{\grafix}[1]{\includegraphics{#1.png}} 2.131 -\fi 2.132 - 2.133 -% Reference entry for a command. 2.134 -\newcommand{\cmdref}[2]{\section{\hgcmd{#1}---#2}\label{cmdref:#1}\index{\texttt{#1} command}} 2.135 - 2.136 -% Reference entry for a command option with long and short forms. 2.137 -\newcommand{\optref}[3]{\subsubsection{\hgopt{#1}{--#3}, also \hgopt{#1}{-#2}}} 2.138 - 2.139 -% Reference entry for a command option with only long form. 2.140 -\newcommand{\loptref}[2]{\subsubsection{\hgopt{#1}{--#2} option}} 2.141 - 2.142 -% command to generate a footnote to be used as a translator's note 2.143 -\newcommand{\ndt}[1]{\footnote{\textbf{N. del T.} #1}} 2.144 - 2.145 - 2.146 -%%% Local Variables: 2.147 -%%% mode: latex 2.148 -%%% TeX-master: "00book" 2.149 -%%% End:
3.1 --- a/en/appA-cmdref.tex Thu Mar 05 21:52:23 2009 +0200 3.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 3.3 @@ -1,175 +0,0 @@ 3.4 -\chapter{Command reference} 3.5 -\label{cmdref} 3.6 - 3.7 -\cmdref{add}{add files at the next commit} 3.8 -\optref{add}{I}{include} 3.9 -\optref{add}{X}{exclude} 3.10 -\optref{add}{n}{dry-run} 3.11 - 3.12 -\cmdref{diff}{print changes in history or working directory} 3.13 - 3.14 -Show differences between revisions for the specified files or 3.15 -directories, using the unified diff format. For a description of the 3.16 -unified diff format, see section~\ref{sec:mq:patch}. 3.17 - 3.18 -By default, this command does not print diffs for files that Mercurial 3.19 -considers to contain binary data. To control this behaviour, see the 3.20 -\hgopt{diff}{-a} and \hgopt{diff}{--git} options. 3.21 - 3.22 -\subsection{Options} 3.23 - 3.24 -\loptref{diff}{nodates} 3.25 - 3.26 -Omit date and time information when printing diff headers. 3.27 - 3.28 -\optref{diff}{B}{ignore-blank-lines} 3.29 - 3.30 -Do not print changes that only insert or delete blank lines. A line 3.31 -that contains only whitespace is not considered blank. 3.32 - 3.33 -\optref{diff}{I}{include} 3.34 - 3.35 -Include files and directories whose names match the given patterns. 3.36 - 3.37 -\optref{diff}{X}{exclude} 3.38 - 3.39 -Exclude files and directories whose names match the given patterns. 3.40 - 3.41 -\optref{diff}{a}{text} 3.42 - 3.43 -If this option is not specified, \hgcmd{diff} will refuse to print 3.44 -diffs for files that it detects as binary. Specifying \hgopt{diff}{-a} 3.45 -forces \hgcmd{diff} to treat all files as text, and generate diffs for 3.46 -all of them. 3.47 - 3.48 -This option is useful for files that are ``mostly text'' but have a 3.49 -few embedded NUL characters. If you use it on files that contain a 3.50 -lot of binary data, its output will be incomprehensible. 3.51 - 3.52 -\optref{diff}{b}{ignore-space-change} 3.53 - 3.54 -Do not print a line if the only change to that line is in the amount 3.55 -of white space it contains. 3.56 - 3.57 -\optref{diff}{g}{git} 3.58 - 3.59 -Print \command{git}-compatible diffs. XXX reference a format 3.60 -description. 3.61 - 3.62 -\optref{diff}{p}{show-function} 3.63 - 3.64 -Display the name of the enclosing function in a hunk header, using a 3.65 -simple heuristic. This functionality is enabled by default, so the 3.66 -\hgopt{diff}{-p} option has no effect unless you change the value of 3.67 -the \rcitem{diff}{showfunc} config item, as in the following example. 3.68 -\interaction{cmdref.diff-p} 3.69 - 3.70 -\optref{diff}{r}{rev} 3.71 - 3.72 -Specify one or more revisions to compare. The \hgcmd{diff} command 3.73 -accepts up to two \hgopt{diff}{-r} options to specify the revisions to 3.74 -compare. 3.75 - 3.76 -\begin{enumerate} 3.77 -\setcounter{enumi}{0} 3.78 -\item Display the differences between the parent revision of the 3.79 - working directory and the working directory. 3.80 -\item Display the differences between the specified changeset and the 3.81 - working directory. 3.82 -\item Display the differences between the two specified changesets. 3.83 -\end{enumerate} 3.84 - 3.85 -You can specify two revisions using either two \hgopt{diff}{-r} 3.86 -options or revision range notation. For example, the two revision 3.87 -specifications below are equivalent. 3.88 -\begin{codesample2} 3.89 - hg diff -r 10 -r 20 3.90 - hg diff -r10:20 3.91 -\end{codesample2} 3.92 - 3.93 -When you provide two revisions, Mercurial treats the order of those 3.94 -revisions as significant. Thus, \hgcmdargs{diff}{-r10:20} will 3.95 -produce a diff that will transform files from their contents as of 3.96 -revision~10 to their contents as of revision~20, while 3.97 -\hgcmdargs{diff}{-r20:10} means the opposite: the diff that will 3.98 -transform files from their revision~20 contents to their revision~10 3.99 -contents. You cannot reverse the ordering in this way if you are 3.100 -diffing against the working directory. 3.101 - 3.102 -\optref{diff}{w}{ignore-all-space} 3.103 - 3.104 -\cmdref{version}{print version and copyright information} 3.105 - 3.106 -This command displays the version of Mercurial you are running, and 3.107 -its copyright license. There are four kinds of version string that 3.108 -you may see. 3.109 -\begin{itemize} 3.110 -\item The string ``\texttt{unknown}''. This version of Mercurial was 3.111 - not built in a Mercurial repository, and cannot determine its own 3.112 - version. 3.113 -\item A short numeric string, such as ``\texttt{1.1}''. This is a 3.114 - build of a revision of Mercurial that was identified by a specific 3.115 - tag in the repository where it was built. (This doesn't necessarily 3.116 - mean that you're running an official release; someone else could 3.117 - have added that tag to any revision in the repository where they 3.118 - built Mercurial.) 3.119 -\item A hexadecimal string, such as ``\texttt{875489e31abe}''. This 3.120 - is a build of the given revision of Mercurial. 3.121 -\item A hexadecimal string followed by a date, such as 3.122 - ``\texttt{875489e31abe+20070205}''. This is a build of the given 3.123 - revision of Mercurial, where the build repository contained some 3.124 - local changes that had not been committed. 3.125 -\end{itemize} 3.126 - 3.127 -\subsection{Tips and tricks} 3.128 - 3.129 -\subsubsection{Why do the results of \hgcmd{diff} and \hgcmd{status} differ?} 3.130 -\label{cmdref:diff-vs-status} 3.131 - 3.132 -When you run the \hgcmd{status} command, you'll see a list of files 3.133 -that Mercurial will record changes for the next time you perform a 3.134 -commit. If you run the \hgcmd{diff} command, you may notice that it 3.135 -prints diffs for only a \emph{subset} of the files that \hgcmd{status} 3.136 -listed. There are two possible reasons for this. 3.137 - 3.138 -The first is that \hgcmd{status} prints some kinds of modifications 3.139 -that \hgcmd{diff} doesn't normally display. The \hgcmd{diff} command 3.140 -normally outputs unified diffs, which don't have the ability to 3.141 -represent some changes that Mercurial can track. Most notably, 3.142 -traditional diffs can't represent a change in whether or not a file is 3.143 -executable, but Mercurial records this information. 3.144 - 3.145 -If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will 3.146 -display \command{git}-compatible diffs that \emph{can} display this 3.147 -extra information. 3.148 - 3.149 -The second possible reason that \hgcmd{diff} might be printing diffs 3.150 -for a subset of the files displayed by \hgcmd{status} is that if you 3.151 -invoke it without any arguments, \hgcmd{diff} prints diffs against the 3.152 -first parent of the working directory. If you have run \hgcmd{merge} 3.153 -to merge two changesets, but you haven't yet committed the results of 3.154 -the merge, your working directory has two parents (use \hgcmd{parents} 3.155 -to see them). While \hgcmd{status} prints modifications relative to 3.156 -\emph{both} parents after an uncommitted merge, \hgcmd{diff} still 3.157 -operates relative only to the first parent. You can get it to print 3.158 -diffs relative to the second parent by specifying that parent with the 3.159 -\hgopt{diff}{-r} option. There is no way to print diffs relative to 3.160 -both parents. 3.161 - 3.162 -\subsubsection{Generating safe binary diffs} 3.163 - 3.164 -If you use the \hgopt{diff}{-a} option to force Mercurial to print 3.165 -diffs of files that are either ``mostly text'' or contain lots of 3.166 -binary data, those diffs cannot subsequently be applied by either 3.167 -Mercurial's \hgcmd{import} command or the system's \command{patch} 3.168 -command. 3.169 - 3.170 -If you want to generate a diff of a binary file that is safe to use as 3.171 -input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you 3.172 -generate the patch. The system \command{patch} command cannot handle 3.173 -binary patches at all. 3.174 - 3.175 -%%% Local Variables: 3.176 -%%% mode: latex 3.177 -%%% TeX-master: "00book" 3.178 -%%% End:
4.1 --- a/en/appB-mq-ref.tex Thu Mar 05 21:52:23 2009 +0200 4.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 4.3 @@ -1,349 +0,0 @@ 4.4 -\chapter{Mercurial Queues reference} 4.5 -\label{chap:mqref} 4.6 - 4.7 -\section{MQ command reference} 4.8 -\label{sec:mqref:cmdref} 4.9 - 4.10 -For an overview of the commands provided by MQ, use the command 4.11 -\hgcmdargs{help}{mq}. 4.12 - 4.13 -\subsection{\hgxcmd{mq}{qapplied}---print applied patches} 4.14 - 4.15 -The \hgxcmd{mq}{qapplied} command prints the current stack of applied 4.16 -patches. Patches are printed in oldest-to-newest order, so the last 4.17 -patch in the list is the ``top'' patch. 4.18 - 4.19 -\subsection{\hgxcmd{mq}{qcommit}---commit changes in the queue repository} 4.20 - 4.21 -The \hgxcmd{mq}{qcommit} command commits any outstanding changes in the 4.22 -\sdirname{.hg/patches} repository. This command only works if the 4.23 -\sdirname{.hg/patches} directory is a repository, i.e.~you created the 4.24 -directory using \hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} or ran 4.25 -\hgcmd{init} in the directory after running \hgxcmd{mq}{qinit}. 4.26 - 4.27 -This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}. 4.28 - 4.29 -\subsection{\hgxcmd{mq}{qdelete}---delete a patch from the 4.30 - \sfilename{series} file} 4.31 - 4.32 -The \hgxcmd{mq}{qdelete} command removes the entry for a patch from the 4.33 -\sfilename{series} file in the \sdirname{.hg/patches} directory. It 4.34 -does not pop the patch if the patch is already applied. By default, 4.35 -it does not delete the patch file; use the \hgxopt{mq}{qdel}{-f} option to 4.36 -do that. 4.37 - 4.38 -Options: 4.39 -\begin{itemize} 4.40 -\item[\hgxopt{mq}{qdel}{-f}] Delete the patch file. 4.41 -\end{itemize} 4.42 - 4.43 -\subsection{\hgxcmd{mq}{qdiff}---print a diff of the topmost applied patch} 4.44 - 4.45 -The \hgxcmd{mq}{qdiff} command prints a diff of the topmost applied patch. 4.46 -It is equivalent to \hgcmdargs{diff}{-r-2:-1}. 4.47 - 4.48 -\subsection{\hgxcmd{mq}{qfold}---merge (``fold'') several patches into one} 4.49 - 4.50 -The \hgxcmd{mq}{qfold} command merges multiple patches into the topmost 4.51 -applied patch, so that the topmost applied patch makes the union of 4.52 -all of the changes in the patches in question. 4.53 - 4.54 -The patches to fold must not be applied; \hgxcmd{mq}{qfold} will exit with 4.55 -an error if any is. The order in which patches are folded is 4.56 -significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost 4.57 -patch, followed by \texttt{a}, followed by \texttt{b}''. 4.58 - 4.59 -The comments from the folded patches are appended to the comments of 4.60 -the destination patch, with each block of comments separated by three 4.61 -asterisk (``\texttt{*}'') characters. Use the \hgxopt{mq}{qfold}{-e} 4.62 -option to edit the commit message for the combined patch/changeset 4.63 -after the folding has completed. 4.64 - 4.65 -Options: 4.66 -\begin{itemize} 4.67 -\item[\hgxopt{mq}{qfold}{-e}] Edit the commit message and patch description 4.68 - for the newly folded patch. 4.69 -\item[\hgxopt{mq}{qfold}{-l}] Use the contents of the given file as the new 4.70 - commit message and patch description for the folded patch. 4.71 -\item[\hgxopt{mq}{qfold}{-m}] Use the given text as the new commit message 4.72 - and patch description for the folded patch. 4.73 -\end{itemize} 4.74 - 4.75 -\subsection{\hgxcmd{mq}{qheader}---display the header/description of a patch} 4.76 - 4.77 -The \hgxcmd{mq}{qheader} command prints the header, or description, of a 4.78 -patch. By default, it prints the header of the topmost applied patch. 4.79 -Given an argument, it prints the header of the named patch. 4.80 - 4.81 -\subsection{\hgxcmd{mq}{qimport}---import a third-party patch into the queue} 4.82 - 4.83 -The \hgxcmd{mq}{qimport} command adds an entry for an external patch to the 4.84 -\sfilename{series} file, and copies the patch into the 4.85 -\sdirname{.hg/patches} directory. It adds the entry immediately after 4.86 -the topmost applied patch, but does not push the patch. 4.87 - 4.88 -If the \sdirname{.hg/patches} directory is a repository, 4.89 -\hgxcmd{mq}{qimport} automatically does an \hgcmd{add} of the imported 4.90 -patch. 4.91 - 4.92 -\subsection{\hgxcmd{mq}{qinit}---prepare a repository to work with MQ} 4.93 - 4.94 -The \hgxcmd{mq}{qinit} command prepares a repository to work with MQ. It 4.95 -creates a directory called \sdirname{.hg/patches}. 4.96 - 4.97 -Options: 4.98 -\begin{itemize} 4.99 -\item[\hgxopt{mq}{qinit}{-c}] Create \sdirname{.hg/patches} as a repository 4.100 - in its own right. Also creates a \sfilename{.hgignore} file that 4.101 - will ignore the \sfilename{status} file. 4.102 -\end{itemize} 4.103 - 4.104 -When the \sdirname{.hg/patches} directory is a repository, the 4.105 -\hgxcmd{mq}{qimport} and \hgxcmd{mq}{qnew} commands automatically \hgcmd{add} 4.106 -new patches. 4.107 - 4.108 -\subsection{\hgxcmd{mq}{qnew}---create a new patch} 4.109 - 4.110 -The \hgxcmd{mq}{qnew} command creates a new patch. It takes one mandatory 4.111 -argument, the name to use for the patch file. The newly created patch 4.112 -is created empty by default. It is added to the \sfilename{series} 4.113 -file after the current topmost applied patch, and is immediately 4.114 -pushed on top of that patch. 4.115 - 4.116 -If \hgxcmd{mq}{qnew} finds modified files in the working directory, it will 4.117 -refuse to create a new patch unless the \hgxopt{mq}{qnew}{-f} option is 4.118 -used (see below). This behaviour allows you to \hgxcmd{mq}{qrefresh} your 4.119 -topmost applied patch before you apply a new patch on top of it. 4.120 - 4.121 -Options: 4.122 -\begin{itemize} 4.123 -\item[\hgxopt{mq}{qnew}{-f}] Create a new patch if the contents of the 4.124 - working directory are modified. Any outstanding modifications are 4.125 - added to the newly created patch, so after this command completes, 4.126 - the working directory will no longer be modified. 4.127 -\item[\hgxopt{mq}{qnew}{-m}] Use the given text as the commit message. 4.128 - This text will be stored at the beginning of the patch file, before 4.129 - the patch data. 4.130 -\end{itemize} 4.131 - 4.132 -\subsection{\hgxcmd{mq}{qnext}---print the name of the next patch} 4.133 - 4.134 -The \hgxcmd{mq}{qnext} command prints the name name of the next patch in 4.135 -the \sfilename{series} file after the topmost applied patch. This 4.136 -patch will become the topmost applied patch if you run \hgxcmd{mq}{qpush}. 4.137 - 4.138 -\subsection{\hgxcmd{mq}{qpop}---pop patches off the stack} 4.139 - 4.140 -The \hgxcmd{mq}{qpop} command removes applied patches from the top of the 4.141 -stack of applied patches. By default, it removes only one patch. 4.142 - 4.143 -This command removes the changesets that represent the popped patches 4.144 -from the repository, and updates the working directory to undo the 4.145 -effects of the patches. 4.146 - 4.147 -This command takes an optional argument, which it uses as the name or 4.148 -index of the patch to pop to. If given a name, it will pop patches 4.149 -until the named patch is the topmost applied patch. If given a 4.150 -number, \hgxcmd{mq}{qpop} treats the number as an index into the entries in 4.151 -the series file, counting from zero (empty lines and lines containing 4.152 -only comments do not count). It pops patches until the patch 4.153 -identified by the given index is the topmost applied patch. 4.154 - 4.155 -The \hgxcmd{mq}{qpop} command does not read or write patches or the 4.156 -\sfilename{series} file. It is thus safe to \hgxcmd{mq}{qpop} a patch that 4.157 -you have removed from the \sfilename{series} file, or a patch that you 4.158 -have renamed or deleted entirely. In the latter two cases, use the 4.159 -name of the patch as it was when you applied it. 4.160 - 4.161 -By default, the \hgxcmd{mq}{qpop} command will not pop any patches if the 4.162 -working directory has been modified. You can override this behaviour 4.163 -using the \hgxopt{mq}{qpop}{-f} option, which reverts all modifications in 4.164 -the working directory. 4.165 - 4.166 -Options: 4.167 -\begin{itemize} 4.168 -\item[\hgxopt{mq}{qpop}{-a}] Pop all applied patches. This returns the 4.169 - repository to its state before you applied any patches. 4.170 -\item[\hgxopt{mq}{qpop}{-f}] Forcibly revert any modifications to the 4.171 - working directory when popping. 4.172 -\item[\hgxopt{mq}{qpop}{-n}] Pop a patch from the named queue. 4.173 -\end{itemize} 4.174 - 4.175 -The \hgxcmd{mq}{qpop} command removes one line from the end of the 4.176 -\sfilename{status} file for each patch that it pops. 4.177 - 4.178 -\subsection{\hgxcmd{mq}{qprev}---print the name of the previous patch} 4.179 - 4.180 -The \hgxcmd{mq}{qprev} command prints the name of the patch in the 4.181 -\sfilename{series} file that comes before the topmost applied patch. 4.182 -This will become the topmost applied patch if you run \hgxcmd{mq}{qpop}. 4.183 - 4.184 -\subsection{\hgxcmd{mq}{qpush}---push patches onto the stack} 4.185 -\label{sec:mqref:cmd:qpush} 4.186 - 4.187 -The \hgxcmd{mq}{qpush} command adds patches onto the applied stack. By 4.188 -default, it adds only one patch. 4.189 - 4.190 -This command creates a new changeset to represent each applied patch, 4.191 -and updates the working directory to apply the effects of the patches. 4.192 - 4.193 -The default data used when creating a changeset are as follows: 4.194 -\begin{itemize} 4.195 -\item The commit date and time zone are the current date and time 4.196 - zone. Because these data are used to compute the identity of a 4.197 - changeset, this means that if you \hgxcmd{mq}{qpop} a patch and 4.198 - \hgxcmd{mq}{qpush} it again, the changeset that you push will have a 4.199 - different identity than the changeset you popped. 4.200 -\item The author is the same as the default used by the \hgcmd{commit} 4.201 - command. 4.202 -\item The commit message is any text from the patch file that comes 4.203 - before the first diff header. If there is no such text, a default 4.204 - commit message is used that identifies the name of the patch. 4.205 -\end{itemize} 4.206 -If a patch contains a Mercurial patch header (XXX add link), the 4.207 -information in the patch header overrides these defaults. 4.208 - 4.209 -Options: 4.210 -\begin{itemize} 4.211 -\item[\hgxopt{mq}{qpush}{-a}] Push all unapplied patches from the 4.212 - \sfilename{series} file until there are none left to push. 4.213 -\item[\hgxopt{mq}{qpush}{-l}] Add the name of the patch to the end 4.214 - of the commit message. 4.215 -\item[\hgxopt{mq}{qpush}{-m}] If a patch fails to apply cleanly, use the 4.216 - entry for the patch in another saved queue to compute the parameters 4.217 - for a three-way merge, and perform a three-way merge using the 4.218 - normal Mercurial merge machinery. Use the resolution of the merge 4.219 - as the new patch content. 4.220 -\item[\hgxopt{mq}{qpush}{-n}] Use the named queue if merging while pushing. 4.221 -\end{itemize} 4.222 - 4.223 -The \hgxcmd{mq}{qpush} command reads, but does not modify, the 4.224 -\sfilename{series} file. It appends one line to the \hgcmd{status} 4.225 -file for each patch that it pushes. 4.226 - 4.227 -\subsection{\hgxcmd{mq}{qrefresh}---update the topmost applied patch} 4.228 - 4.229 -The \hgxcmd{mq}{qrefresh} command updates the topmost applied patch. It 4.230 -modifies the patch, removes the old changeset that represented the 4.231 -patch, and creates a new changeset to represent the modified patch. 4.232 - 4.233 -The \hgxcmd{mq}{qrefresh} command looks for the following modifications: 4.234 -\begin{itemize} 4.235 -\item Changes to the commit message, i.e.~the text before the first 4.236 - diff header in the patch file, are reflected in the new changeset 4.237 - that represents the patch. 4.238 -\item Modifications to tracked files in the working directory are 4.239 - added to the patch. 4.240 -\item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy}, 4.241 - \hgcmd{remove}, or \hgcmd{rename}. Added files and copy and rename 4.242 - destinations are added to the patch, while removed files and rename 4.243 - sources are removed. 4.244 -\end{itemize} 4.245 - 4.246 -Even if \hgxcmd{mq}{qrefresh} detects no changes, it still recreates the 4.247 -changeset that represents the patch. This causes the identity of the 4.248 -changeset to differ from the previous changeset that identified the 4.249 -patch. 4.250 - 4.251 -Options: 4.252 -\begin{itemize} 4.253 -\item[\hgxopt{mq}{qrefresh}{-e}] Modify the commit and patch description, 4.254 - using the preferred text editor. 4.255 -\item[\hgxopt{mq}{qrefresh}{-m}] Modify the commit message and patch 4.256 - description, using the given text. 4.257 -\item[\hgxopt{mq}{qrefresh}{-l}] Modify the commit message and patch 4.258 - description, using text from the given file. 4.259 -\end{itemize} 4.260 - 4.261 -\subsection{\hgxcmd{mq}{qrename}---rename a patch} 4.262 - 4.263 -The \hgxcmd{mq}{qrename} command renames a patch, and changes the entry for 4.264 -the patch in the \sfilename{series} file. 4.265 - 4.266 -With a single argument, \hgxcmd{mq}{qrename} renames the topmost applied 4.267 -patch. With two arguments, it renames its first argument to its 4.268 -second. 4.269 - 4.270 -\subsection{\hgxcmd{mq}{qrestore}---restore saved queue state} 4.271 - 4.272 -XXX No idea what this does. 4.273 - 4.274 -\subsection{\hgxcmd{mq}{qsave}---save current queue state} 4.275 - 4.276 -XXX Likewise. 4.277 - 4.278 -\subsection{\hgxcmd{mq}{qseries}---print the entire patch series} 4.279 - 4.280 -The \hgxcmd{mq}{qseries} command prints the entire patch series from the 4.281 -\sfilename{series} file. It prints only patch names, not empty lines 4.282 -or comments. It prints in order from first to be applied to last. 4.283 - 4.284 -\subsection{\hgxcmd{mq}{qtop}---print the name of the current patch} 4.285 - 4.286 -The \hgxcmd{mq}{qtop} prints the name of the topmost currently applied 4.287 -patch. 4.288 - 4.289 -\subsection{\hgxcmd{mq}{qunapplied}---print patches not yet applied} 4.290 - 4.291 -The \hgxcmd{mq}{qunapplied} command prints the names of patches from the 4.292 -\sfilename{series} file that are not yet applied. It prints them in 4.293 -order from the next patch that will be pushed to the last. 4.294 - 4.295 -\subsection{\hgcmd{strip}---remove a revision and descendants} 4.296 - 4.297 -The \hgcmd{strip} command removes a revision, and all of its 4.298 -descendants, from the repository. It undoes the effects of the 4.299 -removed revisions from the repository, and updates the working 4.300 -directory to the first parent of the removed revision. 4.301 - 4.302 -The \hgcmd{strip} command saves a backup of the removed changesets in 4.303 -a bundle, so that they can be reapplied if removed in error. 4.304 - 4.305 -Options: 4.306 -\begin{itemize} 4.307 -\item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed 4.308 - with the stripped changesets in the backup bundle. 4.309 -\item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all 4.310 - heads. XXX This should be renamed, and use \texttt{-f} to strip revs 4.311 - when there are pending changes. 4.312 -\item[\hgopt{strip}{-n}] Do not save a backup bundle. 4.313 -\end{itemize} 4.314 - 4.315 -\section{MQ file reference} 4.316 - 4.317 -\subsection{The \sfilename{series} file} 4.318 - 4.319 -The \sfilename{series} file contains a list of the names of all 4.320 -patches that MQ can apply. It is represented as a list of names, with 4.321 -one name saved per line. Leading and trailing white space in each 4.322 -line are ignored. 4.323 - 4.324 -Lines may contain comments. A comment begins with the ``\texttt{\#}'' 4.325 -character, and extends to the end of the line. Empty lines, and lines 4.326 -that contain only comments, are ignored. 4.327 - 4.328 -You will often need to edit the \sfilename{series} file by hand, hence 4.329 -the support for comments and empty lines noted above. For example, 4.330 -you can comment out a patch temporarily, and \hgxcmd{mq}{qpush} will skip 4.331 -over that patch when applying patches. You can also change the order 4.332 -in which patches are applied by reordering their entries in the 4.333 -\sfilename{series} file. 4.334 - 4.335 -Placing the \sfilename{series} file under revision control is also 4.336 -supported; it is a good idea to place all of the patches that it 4.337 -refers to under revision control, as well. If you create a patch 4.338 -directory using the \hgxopt{mq}{qinit}{-c} option to \hgxcmd{mq}{qinit}, this 4.339 -will be done for you automatically. 4.340 - 4.341 -\subsection{The \sfilename{status} file} 4.342 - 4.343 -The \sfilename{status} file contains the names and changeset hashes of 4.344 -all patches that MQ currently has applied. Unlike the 4.345 -\sfilename{series} file, this file is not intended for editing. You 4.346 -should not place this file under revision control, or modify it in any 4.347 -way. It is used by MQ strictly for internal book-keeping. 4.348 - 4.349 -%%% Local Variables: 4.350 -%%% mode: latex 4.351 -%%% TeX-master: "00book" 4.352 -%%% End:
5.1 --- a/en/appC-srcinstall.tex Thu Mar 05 21:52:23 2009 +0200 5.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 5.3 @@ -1,53 +0,0 @@ 5.4 -\chapter{Installing Mercurial from source} 5.5 -\label{chap:srcinstall} 5.6 - 5.7 -\section{On a Unix-like system} 5.8 -\label{sec:srcinstall:unixlike} 5.9 - 5.10 -If you are using a Unix-like system that has a sufficiently recent 5.11 -version of Python (2.3~or newer) available, it is easy to install 5.12 -Mercurial from source. 5.13 -\begin{enumerate} 5.14 -\item Download a recent source tarball from 5.15 - \url{http://www.selenic.com/mercurial/download}. 5.16 -\item Unpack the tarball: 5.17 - \begin{codesample4} 5.18 - gzip -dc mercurial-\emph{version}.tar.gz | tar xf - 5.19 - \end{codesample4} 5.20 -\item Go into the source directory and run the installer script. This 5.21 - will build Mercurial and install it in your home directory. 5.22 - \begin{codesample4} 5.23 - cd mercurial-\emph{version} 5.24 - python setup.py install --force --home=\$HOME 5.25 - \end{codesample4} 5.26 -\end{enumerate} 5.27 -Once the install finishes, Mercurial will be in the \texttt{bin} 5.28 -subdirectory of your home directory. Don't forget to make sure that 5.29 -this directory is present in your shell's search path. 5.30 - 5.31 -You will probably need to set the \envar{PYTHONPATH} environment 5.32 -variable so that the Mercurial executable can find the rest of the 5.33 -Mercurial packages. For example, on my laptop, I have set it to 5.34 -\texttt{/home/bos/lib/python}. The exact path that you will need to 5.35 -use depends on how Python was built for your system, but should be 5.36 -easy to figure out. If you're uncertain, look through the output of 5.37 -the installer script above, and see where the contents of the 5.38 -\texttt{mercurial} directory were installed to. 5.39 - 5.40 -\section{On Windows} 5.41 - 5.42 -Building and installing Mercurial on Windows requires a variety of 5.43 -tools, a fair amount of technical knowledge, and considerable 5.44 -patience. I very much \emph{do not recommend} this route if you are a 5.45 -``casual user''. Unless you intend to hack on Mercurial, I strongly 5.46 -suggest that you use a binary package instead. 5.47 - 5.48 -If you are intent on building Mercurial from source on Windows, follow 5.49 -the ``hard way'' directions on the Mercurial wiki at 5.50 -\url{http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall}, 5.51 -and expect the process to involve a lot of fiddly work. 5.52 - 5.53 -%%% Local Variables: 5.54 -%%% mode: latex 5.55 -%%% TeX-master: "00book" 5.56 -%%% End:
6.1 --- a/en/appD-license.tex Thu Mar 05 21:52:23 2009 +0200 6.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 6.3 @@ -1,138 +0,0 @@ 6.4 -\chapter{Open Publication License} 6.5 -\label{cha:opl} 6.6 - 6.7 -Version 1.0, 8 June 1999 6.8 - 6.9 -\section{Requirements on both unmodified and modified versions} 6.10 - 6.11 -The Open Publication works may be reproduced and distributed in whole 6.12 -or in part, in any medium physical or electronic, provided that the 6.13 -terms of this license are adhered to, and that this license or an 6.14 -incorporation of it by reference (with any options elected by the 6.15 -author(s) and/or publisher) is displayed in the reproduction. 6.16 - 6.17 -Proper form for an incorporation by reference is as follows: 6.18 - 6.19 -\begin{quote} 6.20 - Copyright (c) \emph{year} by \emph{author's name or designee}. This 6.21 - material may be distributed only subject to the terms and conditions 6.22 - set forth in the Open Publication License, v\emph{x.y} or later (the 6.23 - latest version is presently available at 6.24 - \url{http://www.opencontent.org/openpub/}). 6.25 -\end{quote} 6.26 - 6.27 -The reference must be immediately followed with any options elected by 6.28 -the author(s) and/or publisher of the document (see 6.29 -section~\ref{sec:opl:options}). 6.30 - 6.31 -Commercial redistribution of Open Publication-licensed material is 6.32 -permitted. 6.33 - 6.34 -Any publication in standard (paper) book form shall require the 6.35 -citation of the original publisher and author. The publisher and 6.36 -author's names shall appear on all outer surfaces of the book. On all 6.37 -outer surfaces of the book the original publisher's name shall be as 6.38 -large as the title of the work and cited as possessive with respect to 6.39 -the title. 6.40 - 6.41 -\section{Copyright} 6.42 - 6.43 -The copyright to each Open Publication is owned by its author(s) or 6.44 -designee. 6.45 - 6.46 -\section{Scope of license} 6.47 - 6.48 -The following license terms apply to all Open Publication works, 6.49 -unless otherwise explicitly stated in the document. 6.50 - 6.51 -Mere aggregation of Open Publication works or a portion of an Open 6.52 -Publication work with other works or programs on the same media shall 6.53 -not cause this license to apply to those other works. The aggregate 6.54 -work shall contain a notice specifying the inclusion of the Open 6.55 -Publication material and appropriate copyright notice. 6.56 - 6.57 -\textbf{Severability}. If any part of this license is found to be 6.58 -unenforceable in any jurisdiction, the remaining portions of the 6.59 -license remain in force. 6.60 - 6.61 -\textbf{No warranty}. Open Publication works are licensed and provided 6.62 -``as is'' without warranty of any kind, express or implied, including, 6.63 -but not limited to, the implied warranties of merchantability and 6.64 -fitness for a particular purpose or a warranty of non-infringement. 6.65 - 6.66 -\section{Requirements on modified works} 6.67 - 6.68 -All modified versions of documents covered by this license, including 6.69 -translations, anthologies, compilations and partial documents, must 6.70 -meet the following requirements: 6.71 - 6.72 -\begin{enumerate} 6.73 -\item The modified version must be labeled as such. 6.74 -\item The person making the modifications must be identified and the 6.75 - modifications dated. 6.76 -\item Acknowledgement of the original author and publisher if 6.77 - applicable must be retained according to normal academic citation 6.78 - practices. 6.79 -\item The location of the original unmodified document must be 6.80 - identified. 6.81 -\item The original author's (or authors') name(s) may not be used to 6.82 - assert or imply endorsement of the resulting document without the 6.83 - original author's (or authors') permission. 6.84 -\end{enumerate} 6.85 - 6.86 -\section{Good-practice recommendations} 6.87 - 6.88 -In addition to the requirements of this license, it is requested from 6.89 -and strongly recommended of redistributors that: 6.90 - 6.91 -\begin{enumerate} 6.92 -\item If you are distributing Open Publication works on hardcopy or 6.93 - CD-ROM, you provide email notification to the authors of your intent 6.94 - to redistribute at least thirty days before your manuscript or media 6.95 - freeze, to give the authors time to provide updated documents. This 6.96 - notification should describe modifications, if any, made to the 6.97 - document. 6.98 -\item All substantive modifications (including deletions) be either 6.99 - clearly marked up in the document or else described in an attachment 6.100 - to the document. 6.101 -\item Finally, while it is not mandatory under this license, it is 6.102 - considered good form to offer a free copy of any hardcopy and CD-ROM 6.103 - expression of an Open Publication-licensed work to its author(s). 6.104 -\end{enumerate} 6.105 - 6.106 -\section{License options} 6.107 -\label{sec:opl:options} 6.108 - 6.109 -The author(s) and/or publisher of an Open Publication-licensed 6.110 -document may elect certain options by appending language to the 6.111 -reference to or copy of the license. These options are considered part 6.112 -of the license instance and must be included with the license (or its 6.113 -incorporation by reference) in derived works. 6.114 - 6.115 -\begin{enumerate}[A] 6.116 -\item To prohibit distribution of substantively modified versions 6.117 - without the explicit permission of the author(s). ``Substantive 6.118 - modification'' is defined as a change to the semantic content of the 6.119 - document, and excludes mere changes in format or typographical 6.120 - corrections. 6.121 - 6.122 - To accomplish this, add the phrase ``Distribution of substantively 6.123 - modified versions of this document is prohibited without the 6.124 - explicit permission of the copyright holder.'' to the license 6.125 - reference or copy. 6.126 - 6.127 -\item To prohibit any publication of this work or derivative works in 6.128 - whole or in part in standard (paper) book form for commercial 6.129 - purposes is prohibited unless prior permission is obtained from the 6.130 - copyright holder. 6.131 - 6.132 - To accomplish this, add the phrase ``Distribution of the work or 6.133 - derivative of the work in any standard (paper) book form is 6.134 - prohibited unless prior permission is obtained from the copyright 6.135 - holder.'' to the license reference or copy. 6.136 -\end{enumerate} 6.137 - 6.138 -%%% Local Variables: 6.139 -%%% mode: latex 6.140 -%%% TeX-master: "00book" 6.141 -%%% End:
7.1 --- a/en/ch00-preface.tex Thu Mar 05 21:52:23 2009 +0200 7.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 7.3 @@ -1,67 +0,0 @@ 7.4 -\chapter*{Preface} 7.5 -\addcontentsline{toc}{chapter}{Preface} 7.6 -\label{chap:preface} 7.7 - 7.8 -Distributed revision control is a relatively new territory, and has 7.9 -thus far grown due to people's willingness to strike out into 7.10 -ill-charted territory. 7.11 - 7.12 -I am writing a book about distributed revision control because I 7.13 -believe that it is an important subject that deserves a field guide. 7.14 -I chose to write about Mercurial because it is the easiest tool to 7.15 -learn the terrain with, and yet it scales to the demands of real, 7.16 -challenging environments where many other revision control tools fail. 7.17 - 7.18 -\section{This book is a work in progress} 7.19 - 7.20 -I am releasing this book while I am still writing it, in the hope that 7.21 -it will prove useful to others. I also hope that readers will 7.22 -contribute as they see fit. 7.23 - 7.24 -\section{About the examples in this book} 7.25 - 7.26 -This book takes an unusual approach to code samples. Every example is 7.27 -``live''---each one is actually the result of a shell script that 7.28 -executes the Mercurial commands you see. Every time an image of the 7.29 -book is built from its sources, all the example scripts are 7.30 -automatically run, and their current results compared against their 7.31 -expected results. 7.32 - 7.33 -The advantage of this approach is that the examples are always 7.34 -accurate; they describe \emph{exactly} the behaviour of the version of 7.35 -Mercurial that's mentioned at the front of the book. If I update the 7.36 -version of Mercurial that I'm documenting, and the output of some 7.37 -command changes, the build fails. 7.38 - 7.39 -There is a small disadvantage to this approach, which is that the 7.40 -dates and times you'll see in examples tend to be ``squashed'' 7.41 -together in a way that they wouldn't be if the same commands were 7.42 -being typed by a human. Where a human can issue no more than one 7.43 -command every few seconds, with any resulting timestamps 7.44 -correspondingly spread out, my automated example scripts run many 7.45 -commands in one second. 7.46 - 7.47 -As an instance of this, several consecutive commits in an example can 7.48 -show up as having occurred during the same second. You can see this 7.49 -occur in the \hgext{bisect} example in section~\ref{sec:undo:bisect}, 7.50 -for instance. 7.51 - 7.52 -So when you're reading examples, don't place too much weight on the 7.53 -dates or times you see in the output of commands. But \emph{do} be 7.54 -confident that the behaviour you're seeing is consistent and 7.55 -reproducible. 7.56 - 7.57 -\section{Colophon---this book is Free} 7.58 - 7.59 -This book is licensed under the Open Publication License, and is 7.60 -produced entirely using Free Software tools. It is typeset with 7.61 -\LaTeX{}; illustrations are drawn and rendered with 7.62 -\href{http://www.inkscape.org/}{Inkscape}. 7.63 - 7.64 -The complete source code for this book is published as a Mercurial 7.65 -repository, at \url{http://hg.serpentine.com/mercurial/book}. 7.66 - 7.67 -%%% Local Variables: 7.68 -%%% mode: latex 7.69 -%%% TeX-master: "00book" 7.70 -%%% End:
8.1 --- a/en/ch01-intro.tex Thu Mar 05 21:52:23 2009 +0200 8.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 8.3 @@ -1,560 +0,0 @@ 8.4 -\chapter{Introduction} 8.5 -\label{chap:intro} 8.6 - 8.7 -\section{About revision control} 8.8 - 8.9 -Revision control is the process of managing multiple versions of a 8.10 -piece of information. In its simplest form, this is something that 8.11 -many people do by hand: every time you modify a file, save it under a 8.12 -new name that contains a number, each one higher than the number of 8.13 -the preceding version. 8.14 - 8.15 -Manually managing multiple versions of even a single file is an 8.16 -error-prone task, though, so software tools to help automate this 8.17 -process have long been available. The earliest automated revision 8.18 -control tools were intended to help a single user to manage revisions 8.19 -of a single file. Over the past few decades, the scope of revision 8.20 -control tools has expanded greatly; they now manage multiple files, 8.21 -and help multiple people to work together. The best modern revision 8.22 -control tools have no problem coping with thousands of people working 8.23 -together on projects that consist of hundreds of thousands of files. 8.24 - 8.25 -\subsection{Why use revision control?} 8.26 - 8.27 -There are a number of reasons why you or your team might want to use 8.28 -an automated revision control tool for a project. 8.29 -\begin{itemize} 8.30 -\item It will track the history and evolution of your project, so you 8.31 - don't have to. For every change, you'll have a log of \emph{who} 8.32 - made it; \emph{why} they made it; \emph{when} they made it; and 8.33 - \emph{what} the change was. 8.34 -\item When you're working with other people, revision control software 8.35 - makes it easier for you to collaborate. For example, when people 8.36 - more or less simultaneously make potentially incompatible changes, 8.37 - the software will help you to identify and resolve those conflicts. 8.38 -\item It can help you to recover from mistakes. If you make a change 8.39 - that later turns out to be in error, you can revert to an earlier 8.40 - version of one or more files. In fact, a \emph{really} good 8.41 - revision control tool will even help you to efficiently figure out 8.42 - exactly when a problem was introduced (see 8.43 - section~\ref{sec:undo:bisect} for details). 8.44 -\item It will help you to work simultaneously on, and manage the drift 8.45 - between, multiple versions of your project. 8.46 -\end{itemize} 8.47 -Most of these reasons are equally valid---at least in theory---whether 8.48 -you're working on a project by yourself, or with a hundred other 8.49 -people. 8.50 - 8.51 -A key question about the practicality of revision control at these two 8.52 -different scales (``lone hacker'' and ``huge team'') is how its 8.53 -\emph{benefits} compare to its \emph{costs}. A revision control tool 8.54 -that's difficult to understand or use is going to impose a high cost. 8.55 - 8.56 -A five-hundred-person project is likely to collapse under its own 8.57 -weight almost immediately without a revision control tool and process. 8.58 -In this case, the cost of using revision control might hardly seem 8.59 -worth considering, since \emph{without} it, failure is almost 8.60 -guaranteed. 8.61 - 8.62 -On the other hand, a one-person ``quick hack'' might seem like a poor 8.63 -place to use a revision control tool, because surely the cost of using 8.64 -one must be close to the overall cost of the project. Right? 8.65 - 8.66 -Mercurial uniquely supports \emph{both} of these scales of 8.67 -development. You can learn the basics in just a few minutes, and due 8.68 -to its low overhead, you can apply revision control to the smallest of 8.69 -projects with ease. Its simplicity means you won't have a lot of 8.70 -abstruse concepts or command sequences competing for mental space with 8.71 -whatever you're \emph{really} trying to do. At the same time, 8.72 -Mercurial's high performance and peer-to-peer nature let you scale 8.73 -painlessly to handle large projects. 8.74 - 8.75 -No revision control tool can rescue a poorly run project, but a good 8.76 -choice of tools can make a huge difference to the fluidity with which 8.77 -you can work on a project. 8.78 - 8.79 -\subsection{The many names of revision control} 8.80 - 8.81 -Revision control is a diverse field, so much so that it doesn't 8.82 -actually have a single name or acronym. Here are a few of the more 8.83 -common names and acronyms you'll encounter: 8.84 -\begin{itemize} 8.85 -\item Revision control (RCS) 8.86 -\item Software configuration management (SCM), or configuration management 8.87 -\item Source code management 8.88 -\item Source code control, or source control 8.89 -\item Version control (VCS) 8.90 -\end{itemize} 8.91 -Some people claim that these terms actually have different meanings, 8.92 -but in practice they overlap so much that there's no agreed or even 8.93 -useful way to tease them apart. 8.94 - 8.95 -\section{A short history of revision control} 8.96 - 8.97 -The best known of the old-time revision control tools is SCCS (Source 8.98 -Code Control System), which Marc Rochkind wrote at Bell Labs, in the 8.99 -early 1970s. SCCS operated on individual files, and required every 8.100 -person working on a project to have access to a shared workspace on a 8.101 -single system. Only one person could modify a file at any time; 8.102 -arbitration for access to files was via locks. It was common for 8.103 -people to lock files, and later forget to unlock them, preventing 8.104 -anyone else from modifying those files without the help of an 8.105 -administrator. 8.106 - 8.107 -Walter Tichy developed a free alternative to SCCS in the early 1980s; 8.108 -he called his program RCS (Revison Control System). Like SCCS, RCS 8.109 -required developers to work in a single shared workspace, and to lock 8.110 -files to prevent multiple people from modifying them simultaneously. 8.111 - 8.112 -Later in the 1980s, Dick Grune used RCS as a building block for a set 8.113 -of shell scripts he initially called cmt, but then renamed to CVS 8.114 -(Concurrent Versions System). The big innovation of CVS was that it 8.115 -let developers work simultaneously and somewhat independently in their 8.116 -own personal workspaces. The personal workspaces prevented developers 8.117 -from stepping on each other's toes all the time, as was common with 8.118 -SCCS and RCS. Each developer had a copy of every project file, and 8.119 -could modify their copies independently. They had to merge their 8.120 -edits prior to committing changes to the central repository. 8.121 - 8.122 -Brian Berliner took Grune's original scripts and rewrote them in~C, 8.123 -releasing in 1989 the code that has since developed into the modern 8.124 -version of CVS. CVS subsequently acquired the ability to operate over 8.125 -a network connection, giving it a client/server architecture. CVS's 8.126 -architecture is centralised; only the server has a copy of the history 8.127 -of the project. Client workspaces just contain copies of recent 8.128 -versions of the project's files, and a little metadata to tell them 8.129 -where the server is. CVS has been enormously successful; it is 8.130 -probably the world's most widely used revision control system. 8.131 - 8.132 -In the early 1990s, Sun Microsystems developed an early distributed 8.133 -revision control system, called TeamWare. A TeamWare workspace 8.134 -contains a complete copy of the project's history. TeamWare has no 8.135 -notion of a central repository. (CVS relied upon RCS for its history 8.136 -storage; TeamWare used SCCS.) 8.137 - 8.138 -As the 1990s progressed, awareness grew of a number of problems with 8.139 -CVS. It records simultaneous changes to multiple files individually, 8.140 -instead of grouping them together as a single logically atomic 8.141 -operation. It does not manage its file hierarchy well; it is easy to 8.142 -make a mess of a repository by renaming files and directories. Worse, 8.143 -its source code is difficult to read and maintain, which made the 8.144 -``pain level'' of fixing these architectural problems prohibitive. 8.145 - 8.146 -In 2001, Jim Blandy and Karl Fogel, two developers who had worked on 8.147 -CVS, started a project to replace it with a tool that would have a 8.148 -better architecture and cleaner code. The result, Subversion, does 8.149 -not stray from CVS's centralised client/server model, but it adds 8.150 -multi-file atomic commits, better namespace management, and a number 8.151 -of other features that make it a generally better tool than CVS. 8.152 -Since its initial release, it has rapidly grown in popularity. 8.153 - 8.154 -More or less simultaneously, Graydon Hoare began working on an 8.155 -ambitious distributed revision control system that he named Monotone. 8.156 -While Monotone addresses many of CVS's design flaws and has a 8.157 -peer-to-peer architecture, it goes beyond earlier (and subsequent) 8.158 -revision control tools in a number of innovative ways. It uses 8.159 -cryptographic hashes as identifiers, and has an integral notion of 8.160 -``trust'' for code from different sources. 8.161 - 8.162 -Mercurial began life in 2005. While a few aspects of its design are 8.163 -influenced by Monotone, Mercurial focuses on ease of use, high 8.164 -performance, and scalability to very large projects. 8.165 - 8.166 -\section{Trends in revision control} 8.167 - 8.168 -There has been an unmistakable trend in the development and use of 8.169 -revision control tools over the past four decades, as people have 8.170 -become familiar with the capabilities of their tools and constrained 8.171 -by their limitations. 8.172 - 8.173 -The first generation began by managing single files on individual 8.174 -computers. Although these tools represented a huge advance over 8.175 -ad-hoc manual revision control, their locking model and reliance on a 8.176 -single computer limited them to small, tightly-knit teams. 8.177 - 8.178 -The second generation loosened these constraints by moving to 8.179 -network-centered architectures, and managing entire projects at a 8.180 -time. As projects grew larger, they ran into new problems. With 8.181 -clients needing to talk to servers very frequently, server scaling 8.182 -became an issue for large projects. An unreliable network connection 8.183 -could prevent remote users from being able to talk to the server at 8.184 -all. As open source projects started making read-only access 8.185 -available anonymously to anyone, people without commit privileges 8.186 -found that they could not use the tools to interact with a project in 8.187 -a natural way, as they could not record their changes. 8.188 - 8.189 -The current generation of revision control tools is peer-to-peer in 8.190 -nature. All of these systems have dropped the dependency on a single 8.191 -central server, and allow people to distribute their revision control 8.192 -data to where it's actually needed. Collaboration over the Internet 8.193 -has moved from constrained by technology to a matter of choice and 8.194 -consensus. Modern tools can operate offline indefinitely and 8.195 -autonomously, with a network connection only needed when syncing 8.196 -changes with another repository. 8.197 - 8.198 -\section{A few of the advantages of distributed revision control} 8.199 - 8.200 -Even though distributed revision control tools have for several years 8.201 -been as robust and usable as their previous-generation counterparts, 8.202 -people using older tools have not yet necessarily woken up to their 8.203 -advantages. There are a number of ways in which distributed tools 8.204 -shine relative to centralised ones. 8.205 - 8.206 -For an individual developer, distributed tools are almost always much 8.207 -faster than centralised tools. This is for a simple reason: a 8.208 -centralised tool needs to talk over the network for many common 8.209 -operations, because most metadata is stored in a single copy on the 8.210 -central server. A distributed tool stores all of its metadata 8.211 -locally. All else being equal, talking over the network adds overhead 8.212 -to a centralised tool. Don't underestimate the value of a snappy, 8.213 -responsive tool: you're going to spend a lot of time interacting with 8.214 -your revision control software. 8.215 - 8.216 -Distributed tools are indifferent to the vagaries of your server 8.217 -infrastructure, again because they replicate metadata to so many 8.218 -locations. If you use a centralised system and your server catches 8.219 -fire, you'd better hope that your backup media are reliable, and that 8.220 -your last backup was recent and actually worked. With a distributed 8.221 -tool, you have many backups available on every contributor's computer. 8.222 - 8.223 -The reliability of your network will affect distributed tools far less 8.224 -than it will centralised tools. You can't even use a centralised tool 8.225 -without a network connection, except for a few highly constrained 8.226 -commands. With a distributed tool, if your network connection goes 8.227 -down while you're working, you may not even notice. The only thing 8.228 -you won't be able to do is talk to repositories on other computers, 8.229 -something that is relatively rare compared with local operations. If 8.230 -you have a far-flung team of collaborators, this may be significant. 8.231 - 8.232 -\subsection{Advantages for open source projects} 8.233 - 8.234 -If you take a shine to an open source project and decide that you 8.235 -would like to start hacking on it, and that project uses a distributed 8.236 -revision control tool, you are at once a peer with the people who 8.237 -consider themselves the ``core'' of that project. If they publish 8.238 -their repositories, you can immediately copy their project history, 8.239 -start making changes, and record your work, using the same tools in 8.240 -the same ways as insiders. By contrast, with a centralised tool, you 8.241 -must use the software in a ``read only'' mode unless someone grants 8.242 -you permission to commit changes to their central server. Until then, 8.243 -you won't be able to record changes, and your local modifications will 8.244 -be at risk of corruption any time you try to update your client's view 8.245 -of the repository. 8.246 - 8.247 -\subsubsection{The forking non-problem} 8.248 - 8.249 -It has been suggested that distributed revision control tools pose 8.250 -some sort of risk to open source projects because they make it easy to 8.251 -``fork'' the development of a project. A fork happens when there are 8.252 -differences in opinion or attitude between groups of developers that 8.253 -cause them to decide that they can't work together any longer. Each 8.254 -side takes a more or less complete copy of the project's source code, 8.255 -and goes off in its own direction. 8.256 - 8.257 -Sometimes the camps in a fork decide to reconcile their differences. 8.258 -With a centralised revision control system, the \emph{technical} 8.259 -process of reconciliation is painful, and has to be performed largely 8.260 -by hand. You have to decide whose revision history is going to 8.261 -``win'', and graft the other team's changes into the tree somehow. 8.262 -This usually loses some or all of one side's revision history. 8.263 - 8.264 -What distributed tools do with respect to forking is they make forking 8.265 -the \emph{only} way to develop a project. Every single change that 8.266 -you make is potentially a fork point. The great strength of this 8.267 -approach is that a distributed revision control tool has to be really 8.268 -good at \emph{merging} forks, because forks are absolutely 8.269 -fundamental: they happen all the time. 8.270 - 8.271 -If every piece of work that everybody does, all the time, is framed in 8.272 -terms of forking and merging, then what the open source world refers 8.273 -to as a ``fork'' becomes \emph{purely} a social issue. If anything, 8.274 -distributed tools \emph{lower} the likelihood of a fork: 8.275 -\begin{itemize} 8.276 -\item They eliminate the social distinction that centralised tools 8.277 - impose: that between insiders (people with commit access) and 8.278 - outsiders (people without). 8.279 -\item They make it easier to reconcile after a social fork, because 8.280 - all that's involved from the perspective of the revision control 8.281 - software is just another merge. 8.282 -\end{itemize} 8.283 - 8.284 -Some people resist distributed tools because they want to retain tight 8.285 -control over their projects, and they believe that centralised tools 8.286 -give them this control. However, if you're of this belief, and you 8.287 -publish your CVS or Subversion repositories publically, there are 8.288 -plenty of tools available that can pull out your entire project's 8.289 -history (albeit slowly) and recreate it somewhere that you don't 8.290 -control. So while your control in this case is illusory, you are 8.291 -forgoing the ability to fluidly collaborate with whatever people feel 8.292 -compelled to mirror and fork your history. 8.293 - 8.294 -\subsection{Advantages for commercial projects} 8.295 - 8.296 -Many commercial projects are undertaken by teams that are scattered 8.297 -across the globe. Contributors who are far from a central server will 8.298 -see slower command execution and perhaps less reliability. Commercial 8.299 -revision control systems attempt to ameliorate these problems with 8.300 -remote-site replication add-ons that are typically expensive to buy 8.301 -and cantankerous to administer. A distributed system doesn't suffer 8.302 -from these problems in the first place. Better yet, you can easily 8.303 -set up multiple authoritative servers, say one per site, so that 8.304 -there's no redundant communication between repositories over expensive 8.305 -long-haul network links. 8.306 - 8.307 -Centralised revision control systems tend to have relatively low 8.308 -scalability. It's not unusual for an expensive centralised system to 8.309 -fall over under the combined load of just a few dozen concurrent 8.310 -users. Once again, the typical response tends to be an expensive and 8.311 -clunky replication facility. Since the load on a central server---if 8.312 -you have one at all---is many times lower with a distributed 8.313 -tool (because all of the data is replicated everywhere), a single 8.314 -cheap server can handle the needs of a much larger team, and 8.315 -replication to balance load becomes a simple matter of scripting. 8.316 - 8.317 -If you have an employee in the field, troubleshooting a problem at a 8.318 -customer's site, they'll benefit from distributed revision control. 8.319 -The tool will let them generate custom builds, try different fixes in 8.320 -isolation from each other, and search efficiently through history for 8.321 -the sources of bugs and regressions in the customer's environment, all 8.322 -without needing to connect to your company's network. 8.323 - 8.324 -\section{Why choose Mercurial?} 8.325 - 8.326 -Mercurial has a unique set of properties that make it a particularly 8.327 -good choice as a revision control system. 8.328 -\begin{itemize} 8.329 -\item It is easy to learn and use. 8.330 -\item It is lightweight. 8.331 -\item It scales excellently. 8.332 -\item It is easy to customise. 8.333 -\end{itemize} 8.334 - 8.335 -If you are at all familiar with revision control systems, you should 8.336 -be able to get up and running with Mercurial in less than five 8.337 -minutes. Even if not, it will take no more than a few minutes 8.338 -longer. Mercurial's command and feature sets are generally uniform 8.339 -and consistent, so you can keep track of a few general rules instead 8.340 -of a host of exceptions. 8.341 - 8.342 -On a small project, you can start working with Mercurial in moments. 8.343 -Creating new changes and branches; transferring changes around 8.344 -(whether locally or over a network); and history and status operations 8.345 -are all fast. Mercurial attempts to stay nimble and largely out of 8.346 -your way by combining low cognitive overhead with blazingly fast 8.347 -operations. 8.348 - 8.349 -The usefulness of Mercurial is not limited to small projects: it is 8.350 -used by projects with hundreds to thousands of contributors, each 8.351 -containing tens of thousands of files and hundreds of megabytes of 8.352 -source code. 8.353 - 8.354 -If the core functionality of Mercurial is not enough for you, it's 8.355 -easy to build on. Mercurial is well suited to scripting tasks, and 8.356 -its clean internals and implementation in Python make it easy to add 8.357 -features in the form of extensions. There are a number of popular and 8.358 -useful extensions already available, ranging from helping to identify 8.359 -bugs to improving performance. 8.360 - 8.361 -\section{Mercurial compared with other tools} 8.362 - 8.363 -Before you read on, please understand that this section necessarily 8.364 -reflects my own experiences, interests, and (dare I say it) biases. I 8.365 -have used every one of the revision control tools listed below, in 8.366 -most cases for several years at a time. 8.367 - 8.368 - 8.369 -\subsection{Subversion} 8.370 - 8.371 -Subversion is a popular revision control tool, developed to replace 8.372 -CVS. It has a centralised client/server architecture. 8.373 - 8.374 -Subversion and Mercurial have similarly named commands for performing 8.375 -the same operations, so if you're familiar with one, it is easy to 8.376 -learn to use the other. Both tools are portable to all popular 8.377 -operating systems. 8.378 - 8.379 -Prior to version 1.5, Subversion had no useful support for merges. 8.380 -At the time of writing, its merge tracking capability is new, and known to be 8.381 -\href{http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword}{complicated and buggy}. 8.382 - 8.383 -Mercurial has a substantial performance advantage over Subversion on 8.384 -every revision control operation I have benchmarked. I have measured 8.385 -its advantage as ranging from a factor of two to a factor of six when 8.386 -compared with Subversion~1.4.3's \emph{ra\_local} file store, which is 8.387 -the fastest access method available. In more realistic deployments 8.388 -involving a network-based store, Subversion will be at a substantially 8.389 -larger disadvantage. Because many Subversion commands must talk to 8.390 -the server and Subversion does not have useful replication facilities, 8.391 -server capacity and network bandwidth become bottlenecks for modestly 8.392 -large projects. 8.393 - 8.394 -Additionally, Subversion incurs substantial storage overhead to avoid 8.395 -network transactions for a few common operations, such as finding 8.396 -modified files (\texttt{status}) and displaying modifications against 8.397 -the current revision (\texttt{diff}). As a result, a Subversion 8.398 -working copy is often the same size as, or larger than, a Mercurial 8.399 -repository and working directory, even though the Mercurial repository 8.400 -contains a complete history of the project. 8.401 - 8.402 -Subversion is widely supported by third party tools. Mercurial 8.403 -currently lags considerably in this area. This gap is closing, 8.404 -however, and indeed some of Mercurial's GUI tools now outshine their 8.405 -Subversion equivalents. Like Mercurial, Subversion has an excellent 8.406 -user manual. 8.407 - 8.408 -Because Subversion doesn't store revision history on the client, it is 8.409 -well suited to managing projects that deal with lots of large, opaque 8.410 -binary files. If you check in fifty revisions to an incompressible 8.411 -10MB file, Subversion's client-side space usage stays constant The 8.412 -space used by any distributed SCM will grow rapidly in proportion to 8.413 -the number of revisions, because the differences between each revision 8.414 -are large. 8.415 - 8.416 -In addition, it's often difficult or, more usually, impossible to 8.417 -merge different versions of a binary file. Subversion's ability to 8.418 -let a user lock a file, so that they temporarily have the exclusive 8.419 -right to commit changes to it, can be a significant advantage to a 8.420 -project where binary files are widely used. 8.421 - 8.422 -Mercurial can import revision history from a Subversion repository. 8.423 -It can also export revision history to a Subversion repository. This 8.424 -makes it easy to ``test the waters'' and use Mercurial and Subversion 8.425 -in parallel before deciding to switch. History conversion is 8.426 -incremental, so you can perform an initial conversion, then small 8.427 -additional conversions afterwards to bring in new changes. 8.428 - 8.429 - 8.430 -\subsection{Git} 8.431 - 8.432 -Git is a distributed revision control tool that was developed for 8.433 -managing the Linux kernel source tree. Like Mercurial, its early 8.434 -design was somewhat influenced by Monotone. 8.435 - 8.436 -Git has a very large command set, with version~1.5.0 providing~139 8.437 -individual commands. It has something of a reputation for being 8.438 -difficult to learn. Compared to Git, Mercurial has a strong focus on 8.439 -simplicity. 8.440 - 8.441 -In terms of performance, Git is extremely fast. In several cases, it 8.442 -is faster than Mercurial, at least on Linux, while Mercurial performs 8.443 -better on other operations. However, on Windows, the performance and 8.444 -general level of support that Git provides is, at the time of writing, 8.445 -far behind that of Mercurial. 8.446 - 8.447 -While a Mercurial repository needs no maintenance, a Git repository 8.448 -requires frequent manual ``repacks'' of its metadata. Without these, 8.449 -performance degrades, while space usage grows rapidly. A server that 8.450 -contains many Git repositories that are not rigorously and frequently 8.451 -repacked will become heavily disk-bound during backups, and there have 8.452 -been instances of daily backups taking far longer than~24 hours as a 8.453 -result. A freshly packed Git repository is slightly smaller than a 8.454 -Mercurial repository, but an unpacked repository is several orders of 8.455 -magnitude larger. 8.456 - 8.457 -The core of Git is written in C. Many Git commands are implemented as 8.458 -shell or Perl scripts, and the quality of these scripts varies widely. 8.459 -I have encountered several instances where scripts charged along 8.460 -blindly in the presence of errors that should have been fatal. 8.461 - 8.462 -Mercurial can import revision history from a Git repository. 8.463 - 8.464 - 8.465 -\subsection{CVS} 8.466 - 8.467 -CVS is probably the most widely used revision control tool in the 8.468 -world. Due to its age and internal untidiness, it has been only 8.469 -lightly maintained for many years. 8.470 - 8.471 -It has a centralised client/server architecture. It does not group 8.472 -related file changes into atomic commits, making it easy for people to 8.473 -``break the build'': one person can successfully commit part of a 8.474 -change and then be blocked by the need for a merge, causing other 8.475 -people to see only a portion of the work they intended to do. This 8.476 -also affects how you work with project history. If you want to see 8.477 -all of the modifications someone made as part of a task, you will need 8.478 -to manually inspect the descriptions and timestamps of the changes 8.479 -made to each file involved (if you even know what those files were). 8.480 - 8.481 -CVS has a muddled notion of tags and branches that I will not attempt 8.482 -to even describe. It does not support renaming of files or 8.483 -directories well, making it easy to corrupt a repository. It has 8.484 -almost no internal consistency checking capabilities, so it is usually 8.485 -not even possible to tell whether or how a repository is corrupt. I 8.486 -would not recommend CVS for any project, existing or new. 8.487 - 8.488 -Mercurial can import CVS revision history. However, there are a few 8.489 -caveats that apply; these are true of every other revision control 8.490 -tool's CVS importer, too. Due to CVS's lack of atomic changes and 8.491 -unversioned filesystem hierarchy, it is not possible to reconstruct 8.492 -CVS history completely accurately; some guesswork is involved, and 8.493 -renames will usually not show up. Because a lot of advanced CVS 8.494 -administration has to be done by hand and is hence error-prone, it's 8.495 -common for CVS importers to run into multiple problems with corrupted 8.496 -repositories (completely bogus revision timestamps and files that have 8.497 -remained locked for over a decade are just two of the less interesting 8.498 -problems I can recall from personal experience). 8.499 - 8.500 -Mercurial can import revision history from a CVS repository. 8.501 - 8.502 - 8.503 -\subsection{Commercial tools} 8.504 - 8.505 -Perforce has a centralised client/server architecture, with no 8.506 -client-side caching of any data. Unlike modern revision control 8.507 -tools, Perforce requires that a user run a command to inform the 8.508 -server about every file they intend to edit. 8.509 - 8.510 -The performance of Perforce is quite good for small teams, but it 8.511 -falls off rapidly as the number of users grows beyond a few dozen. 8.512 -Modestly large Perforce installations require the deployment of 8.513 -proxies to cope with the load their users generate. 8.514 - 8.515 - 8.516 -\subsection{Choosing a revision control tool} 8.517 - 8.518 -With the exception of CVS, all of the tools listed above have unique 8.519 -strengths that suit them to particular styles of work. There is no 8.520 -single revision control tool that is best in all situations. 8.521 - 8.522 -As an example, Subversion is a good choice for working with frequently 8.523 -edited binary files, due to its centralised nature and support for 8.524 -file locking. 8.525 - 8.526 -I personally find Mercurial's properties of simplicity, performance, 8.527 -and good merge support to be a compelling combination that has served 8.528 -me well for several years. 8.529 - 8.530 - 8.531 -\section{Switching from another tool to Mercurial} 8.532 - 8.533 -Mercurial is bundled with an extension named \hgext{convert}, which 8.534 -can incrementally import revision history from several other revision 8.535 -control tools. By ``incremental'', I mean that you can convert all of 8.536 -a project's history to date in one go, then rerun the conversion later 8.537 -to obtain new changes that happened after the initial conversion. 8.538 - 8.539 -The revision control tools supported by \hgext{convert} are as 8.540 -follows: 8.541 -\begin{itemize} 8.542 -\item Subversion 8.543 -\item CVS 8.544 -\item Git 8.545 -\item Darcs 8.546 -\end{itemize} 8.547 - 8.548 -In addition, \hgext{convert} can export changes from Mercurial to 8.549 -Subversion. This makes it possible to try Subversion and Mercurial in 8.550 -parallel before committing to a switchover, without risking the loss 8.551 -of any work. 8.552 - 8.553 -The \hgxcmd{conver}{convert} command is easy to use. Simply point it 8.554 -at the path or URL of the source repository, optionally give it the 8.555 -name of the destination repository, and it will start working. After 8.556 -the initial conversion, just run the same command again to import new 8.557 -changes. 8.558 - 8.559 - 8.560 -%%% Local Variables: 8.561 -%%% mode: latex 8.562 -%%% TeX-master: "00book" 8.563 -%%% End:
9.1 --- a/en/ch02-tour-basic.tex Thu Mar 05 21:52:23 2009 +0200 9.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 9.3 @@ -1,622 +0,0 @@ 9.4 -\chapter{A tour of Mercurial: the basics} 9.5 -\label{chap:tour-basic} 9.6 - 9.7 -\section{Installing Mercurial on your system} 9.8 -\label{sec:tour:install} 9.9 - 9.10 -Prebuilt binary packages of Mercurial are available for every popular 9.11 -operating system. These make it easy to start using Mercurial on your 9.12 -computer immediately. 9.13 - 9.14 -\subsection{Linux} 9.15 - 9.16 -Because each Linux distribution has its own packaging tools, policies, 9.17 -and rate of development, it's difficult to give a comprehensive set of 9.18 -instructions on how to install Mercurial binaries. The version of 9.19 -Mercurial that you will end up with can vary depending on how active 9.20 -the person is who maintains the package for your distribution. 9.21 - 9.22 -To keep things simple, I will focus on installing Mercurial from the 9.23 -command line under the most popular Linux distributions. Most of 9.24 -these distributions provide graphical package managers that will let 9.25 -you install Mercurial with a single click; the package name to look 9.26 -for is \texttt{mercurial}. 9.27 - 9.28 -\begin{itemize} 9.29 -\item[Debian] 9.30 - \begin{codesample4} 9.31 - apt-get install mercurial 9.32 - \end{codesample4} 9.33 - 9.34 -\item[Fedora Core] 9.35 - \begin{codesample4} 9.36 - yum install mercurial 9.37 - \end{codesample4} 9.38 - 9.39 -\item[Gentoo] 9.40 - \begin{codesample4} 9.41 - emerge mercurial 9.42 - \end{codesample4} 9.43 - 9.44 -\item[OpenSUSE] 9.45 - \begin{codesample4} 9.46 - yum install mercurial 9.47 - \end{codesample4} 9.48 - 9.49 -\item[Ubuntu] Ubuntu's Mercurial package is based on Debian's. To 9.50 - install it, run the following command. 9.51 - \begin{codesample4} 9.52 - apt-get install mercurial 9.53 - \end{codesample4} 9.54 - The Ubuntu package for Mercurial tends to lag behind the Debian 9.55 - version by a considerable time margin (at the time of writing, seven 9.56 - months), which in some cases will mean that on Ubuntu, you may run 9.57 - into problems that have since been fixed in the Debian package. 9.58 -\end{itemize} 9.59 - 9.60 -\subsection{Solaris} 9.61 - 9.62 -SunFreeWare, at \url{http://www.sunfreeware.com}, is a good source for a 9.63 -large number of pre-built Solaris packages for 32 and 64 bit Intel and 9.64 -Sparc architectures, including current versions of Mercurial. 9.65 - 9.66 -\subsection{Mac OS X} 9.67 - 9.68 -Lee Cantey publishes an installer of Mercurial for Mac OS~X at 9.69 -\url{http://mercurial.berkwood.com}. This package works on both 9.70 -Intel-~and Power-based Macs. Before you can use it, you must install 9.71 -a compatible version of Universal MacPython~\cite{web:macpython}. This 9.72 -is easy to do; simply follow the instructions on Lee's site. 9.73 - 9.74 -It's also possible to install Mercurial using Fink or MacPorts, 9.75 -two popular free package managers for Mac OS X. If you have Fink, 9.76 -use \command{sudo apt-get install mercurial-py25}. If MacPorts, 9.77 -\command{sudo port install mercurial}. 9.78 - 9.79 -\subsection{Windows} 9.80 - 9.81 -Lee Cantey publishes an installer of Mercurial for Windows at 9.82 -\url{http://mercurial.berkwood.com}. This package has no external 9.83 -dependencies; it ``just works''. 9.84 - 9.85 -\begin{note} 9.86 - The Windows version of Mercurial does not automatically convert line 9.87 - endings between Windows and Unix styles. If you want to share work 9.88 - with Unix users, you must do a little additional configuration 9.89 - work. XXX Flesh this out. 9.90 -\end{note} 9.91 - 9.92 -\section{Getting started} 9.93 - 9.94 -To begin, we'll use the \hgcmd{version} command to find out whether 9.95 -Mercurial is actually installed properly. The actual version 9.96 -information that it prints isn't so important; it's whether it prints 9.97 -anything at all that we care about. 9.98 -\interaction{tour.version} 9.99 - 9.100 -\subsection{Built-in help} 9.101 - 9.102 -Mercurial provides a built-in help system. This is invaluable for those 9.103 -times when you find yourself stuck trying to remember how to run a 9.104 -command. If you are completely stuck, simply run \hgcmd{help}; it 9.105 -will print a brief list of commands, along with a description of what 9.106 -each does. If you ask for help on a specific command (as below), it 9.107 -prints more detailed information. 9.108 -\interaction{tour.help} 9.109 -For a more impressive level of detail (which you won't usually need) 9.110 -run \hgcmdargs{help}{\hggopt{-v}}. The \hggopt{-v} option is short 9.111 -for \hggopt{--verbose}, and tells Mercurial to print more information 9.112 -than it usually would. 9.113 - 9.114 -\section{Working with a repository} 9.115 - 9.116 -In Mercurial, everything happens inside a \emph{repository}. The 9.117 -repository for a project contains all of the files that ``belong to'' 9.118 -that project, along with a historical record of the project's files. 9.119 - 9.120 -There's nothing particularly magical about a repository; it is simply 9.121 -a directory tree in your filesystem that Mercurial treats as special. 9.122 -You can rename or delete a repository any time you like, using either the 9.123 -command line or your file browser. 9.124 - 9.125 -\subsection{Making a local copy of a repository} 9.126 - 9.127 -\emph{Copying} a repository is just a little bit special. While you 9.128 -could use a normal file copying command to make a copy of a 9.129 -repository, it's best to use a built-in command that Mercurial 9.130 -provides. This command is called \hgcmd{clone}, because it creates an 9.131 -identical copy of an existing repository. 9.132 -\interaction{tour.clone} 9.133 -If our clone succeeded, we should now have a local directory called 9.134 -\dirname{hello}. This directory will contain some files. 9.135 -\interaction{tour.ls} 9.136 -These files have the same contents and history in our repository as 9.137 -they do in the repository we cloned. 9.138 - 9.139 -Every Mercurial repository is complete, self-contained, and 9.140 -independent. It contains its own private copy of a project's files 9.141 -and history. A cloned repository remembers the location of the 9.142 -repository it was cloned from, but it does not communicate with that 9.143 -repository, or any other, unless you tell it to. 9.144 - 9.145 -What this means for now is that we're free to experiment with our 9.146 -repository, safe in the knowledge that it's a private ``sandbox'' that 9.147 -won't affect anyone else. 9.148 - 9.149 -\subsection{What's in a repository?} 9.150 - 9.151 -When we take a more detailed look inside a repository, we can see that 9.152 -it contains a directory named \dirname{.hg}. This is where Mercurial 9.153 -keeps all of its metadata for the repository. 9.154 -\interaction{tour.ls-a} 9.155 - 9.156 -The contents of the \dirname{.hg} directory and its subdirectories are 9.157 -private to Mercurial. Every other file and directory in the 9.158 -repository is yours to do with as you please. 9.159 - 9.160 -To introduce a little terminology, the \dirname{.hg} directory is the 9.161 -``real'' repository, and all of the files and directories that coexist 9.162 -with it are said to live in the \emph{working directory}. An easy way 9.163 -to remember the distinction is that the \emph{repository} contains the 9.164 -\emph{history} of your project, while the \emph{working directory} 9.165 -contains a \emph{snapshot} of your project at a particular point in 9.166 -history. 9.167 - 9.168 -\section{A tour through history} 9.169 - 9.170 -One of the first things we might want to do with a new, unfamiliar 9.171 -repository is understand its history. The \hgcmd{log} command gives 9.172 -us a view of history. 9.173 -\interaction{tour.log} 9.174 -By default, this command prints a brief paragraph of output for each 9.175 -change to the project that was recorded. In Mercurial terminology, we 9.176 -call each of these recorded events a \emph{changeset}, because it can 9.177 -contain a record of changes to several files. 9.178 - 9.179 -The fields in a record of output from \hgcmd{log} are as follows. 9.180 -\begin{itemize} 9.181 -\item[\texttt{changeset}] This field has the format of a number, 9.182 - followed by a colon, followed by a hexadecimal string. These are 9.183 - \emph{identifiers} for the changeset. There are two identifiers 9.184 - because the number is shorter and easier to type than the hex 9.185 - string. 9.186 -\item[\texttt{user}] The identity of the person who created the 9.187 - changeset. This is a free-form field, but it most often contains a 9.188 - person's name and email address. 9.189 -\item[\texttt{date}] The date and time on which the changeset was 9.190 - created, and the timezone in which it was created. (The date and 9.191 - time are local to that timezone; they display what time and date it 9.192 - was for the person who created the changeset.) 9.193 -\item[\texttt{summary}] The first line of the text message that the 9.194 - creator of the changeset entered to describe the changeset. 9.195 -\end{itemize} 9.196 -The default output printed by \hgcmd{log} is purely a summary; it is 9.197 -missing a lot of detail. 9.198 - 9.199 -Figure~\ref{fig:tour-basic:history} provides a graphical representation of 9.200 -the history of the \dirname{hello} repository, to make it a little 9.201 -easier to see which direction history is ``flowing'' in. We'll be 9.202 -returning to this figure several times in this chapter and the chapter 9.203 -that follows. 9.204 - 9.205 -\begin{figure}[ht] 9.206 - \centering 9.207 - \grafix{tour-history} 9.208 - \caption{Graphical history of the \dirname{hello} repository} 9.209 - \label{fig:tour-basic:history} 9.210 -\end{figure} 9.211 - 9.212 -\subsection{Changesets, revisions, and talking to other people} 9.213 - 9.214 -As English is a notoriously sloppy language, and computer science has 9.215 -a hallowed history of terminological confusion (why use one term when 9.216 -four will do?), revision control has a variety of words and phrases 9.217 -that mean the same thing. If you are talking about Mercurial history 9.218 -with other people, you will find that the word ``changeset'' is often 9.219 -compressed to ``change'' or (when written) ``cset'', and sometimes a 9.220 -changeset is referred to as a ``revision'' or a ``rev''. 9.221 - 9.222 -While it doesn't matter what \emph{word} you use to refer to the 9.223 -concept of ``a~changeset'', the \emph{identifier} that you use to 9.224 -refer to ``a~\emph{specific} changeset'' is of great importance. 9.225 -Recall that the \texttt{changeset} field in the output from 9.226 -\hgcmd{log} identifies a changeset using both a number and a 9.227 -hexadecimal string. 9.228 -\begin{itemize} 9.229 -\item The revision number is \emph{only valid in that repository}, 9.230 -\item while the hex string is the \emph{permanent, unchanging identifier} that will always identify that exact changeset in 9.231 - \emph{every} copy of the repository. 9.232 -\end{itemize} 9.233 -This distinction is important. If you send someone an email talking 9.234 -about ``revision~33'', there's a high likelihood that their 9.235 -revision~33 will \emph{not be the same} as yours. The reason for this 9.236 -is that a revision number depends on the order in which changes 9.237 -arrived in a repository, and there is no guarantee that the same 9.238 -changes will happen in the same order in different repositories. 9.239 -Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, 9.240 -while in another as $1,0,2$. 9.241 - 9.242 -Mercurial uses revision numbers purely as a convenient shorthand. If 9.243 -you need to discuss a changeset with someone, or make a record of a 9.244 -changeset for some other reason (for example, in a bug report), use 9.245 -the hexadecimal identifier. 9.246 - 9.247 -\subsection{Viewing specific revisions} 9.248 - 9.249 -To narrow the output of \hgcmd{log} down to a single revision, use the 9.250 -\hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a 9.251 -revision number or a long-form changeset identifier, and you can 9.252 -provide as many revisions as you want. \interaction{tour.log-r} 9.253 - 9.254 -If you want to see the history of several revisions without having to 9.255 -list each one, you can use \emph{range notation}; this lets you 9.256 -express the idea ``I want all revisions between $a$ and $b$, 9.257 -inclusive''. 9.258 -\interaction{tour.log.range} 9.259 -Mercurial also honours the order in which you specify revisions, so 9.260 -\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} 9.261 -prints $4,3,2$. 9.262 - 9.263 -\subsection{More detailed information} 9.264 - 9.265 -While the summary information printed by \hgcmd{log} is useful if you 9.266 -already know what you're looking for, you may need to see a complete 9.267 -description of the change, or a list of the files changed, if you're 9.268 -trying to decide whether a changeset is the one you're looking for. 9.269 -The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) 9.270 -option gives you this extra detail. 9.271 -\interaction{tour.log-v} 9.272 - 9.273 -If you want to see both the description and content of a change, add 9.274 -the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays 9.275 -the content of a change as a \emph{unified diff} (if you've never seen 9.276 -a unified diff before, see section~\ref{sec:mq:patch} for an overview). 9.277 -\interaction{tour.log-vp} 9.278 - 9.279 -\section{All about command options} 9.280 - 9.281 -Let's take a brief break from exploring Mercurial commands to discuss 9.282 -a pattern in the way that they work; you may find this useful to keep 9.283 -in mind as we continue our tour. 9.284 - 9.285 -Mercurial has a consistent and straightforward approach to dealing 9.286 -with the options that you can pass to commands. It follows the 9.287 -conventions for options that are common to modern Linux and Unix 9.288 -systems. 9.289 -\begin{itemize} 9.290 -\item Every option has a long name. For example, as we've already 9.291 - seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. 9.292 -\item Most options have short names, too. Instead of 9.293 - \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that 9.294 - some options don't have short names is that the options in question 9.295 - are rarely used.) 9.296 -\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), 9.297 - while short options start with one (e.g.~\hgopt{log}{-r}). 9.298 -\item Option naming and usage is consistent across commands. For 9.299 - example, every command that lets you specify a changeset~ID or 9.300 - revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} 9.301 - arguments. 9.302 -\end{itemize} 9.303 -In the examples throughout this book, I use short options instead of 9.304 -long. This just reflects my own preference, so don't read anything 9.305 -significant into it. 9.306 - 9.307 -Most commands that print output of some kind will print more output 9.308 -when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less 9.309 -when passed \hggopt{-q} (or \hggopt{--quiet}). 9.310 - 9.311 -\section{Making and reviewing changes} 9.312 - 9.313 -Now that we have a grasp of viewing history in Mercurial, let's take a 9.314 -look at making some changes and examining them. 9.315 - 9.316 -The first thing we'll do is isolate our experiment in a repository of 9.317 -its own. We use the \hgcmd{clone} command, but we don't need to 9.318 -clone a copy of the remote repository. Since we already have a copy 9.319 -of it locally, we can just clone that instead. This is much faster 9.320 -than cloning over the network, and cloning a local repository uses 9.321 -less disk space in most cases, too. 9.322 -\interaction{tour.reclone} 9.323 -As an aside, it's often good practice to keep a ``pristine'' copy of a 9.324 -remote repository around, which you can then make temporary clones of 9.325 -to create sandboxes for each task you want to work on. This lets you 9.326 -work on multiple tasks in parallel, each isolated from the others 9.327 -until it's complete and you're ready to integrate it back. Because 9.328 -local clones are so cheap, there's almost no overhead to cloning and 9.329 -destroying repositories whenever you want. 9.330 - 9.331 -In our \dirname{my-hello} repository, we have a file 9.332 -\filename{hello.c} that contains the classic ``hello, world'' program. 9.333 -Let's use the ancient and venerable \command{sed} command to edit this 9.334 -file so that it prints a second line of output. (I'm only using 9.335 -\command{sed} to do this because it's easy to write a scripted example 9.336 -this way. Since you're not under the same constraint, you probably 9.337 -won't want to use \command{sed}; simply use your preferred text editor to 9.338 -do the same thing.) 9.339 -\interaction{tour.sed} 9.340 - 9.341 -Mercurial's \hgcmd{status} command will tell us what Mercurial knows 9.342 -about the files in the repository. 9.343 -\interaction{tour.status} 9.344 -The \hgcmd{status} command prints no output for some files, but a line 9.345 -starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell 9.346 -it to, \hgcmd{status} will not print any output for files that have 9.347 -not been modified. 9.348 - 9.349 -The ``\texttt{M}'' indicates that Mercurial has noticed that we 9.350 -modified \filename{hello.c}. We didn't need to \emph{inform} 9.351 -Mercurial that we were going to modify the file before we started, or 9.352 -that we had modified the file after we were done; it was able to 9.353 -figure this out itself. 9.354 - 9.355 -It's a little bit helpful to know that we've modified 9.356 -\filename{hello.c}, but we might prefer to know exactly \emph{what} 9.357 -changes we've made to it. To do this, we use the \hgcmd{diff} 9.358 -command. 9.359 -\interaction{tour.diff} 9.360 - 9.361 -\section{Recording changes in a new changeset} 9.362 - 9.363 -We can modify files, build and test our changes, and use 9.364 -\hgcmd{status} and \hgcmd{diff} to review our changes, until we're 9.365 -satisfied with what we've done and arrive at a natural stopping point 9.366 -where we want to record our work in a new changeset. 9.367 - 9.368 -The \hgcmd{commit} command lets us create a new changeset; we'll 9.369 -usually refer to this as ``making a commit'' or ``committing''. 9.370 - 9.371 -\subsection{Setting up a username} 9.372 - 9.373 -When you try to run \hgcmd{commit} for the first time, it is not 9.374 -guaranteed to succeed. Mercurial records your name and address with 9.375 -each change that you commit, so that you and others will later be able 9.376 -to tell who made each change. Mercurial tries to automatically figure 9.377 -out a sensible username to commit the change with. It will attempt 9.378 -each of the following methods, in order: 9.379 -\begin{enumerate} 9.380 -\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit} 9.381 - command on the command line, followed by a username, this is always 9.382 - given the highest precedence. 9.383 -\item If you have set the \envar{HGUSER} environment variable, this is 9.384 - checked next. 9.385 -\item If you create a file in your home directory called 9.386 - \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be 9.387 - used next. To see what the contents of this file should look like, 9.388 - refer to section~\ref{sec:tour-basic:username} below. 9.389 -\item If you have set the \envar{EMAIL} environment variable, this 9.390 - will be used next. 9.391 -\item Mercurial will query your system to find out your local user 9.392 - name and host name, and construct a username from these components. 9.393 - Since this often results in a username that is not very useful, it 9.394 - will print a warning if it has to do this. 9.395 -\end{enumerate} 9.396 -If all of these mechanisms fail, Mercurial will fail, printing an 9.397 -error message. In this case, it will not let you commit until you set 9.398 -up a username. 9.399 - 9.400 -You should think of the \envar{HGUSER} environment variable and the 9.401 -\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to 9.402 -\emph{override} Mercurial's default selection of username. For normal 9.403 -use, the simplest and most robust way to set a username for yourself 9.404 -is by creating a \sfilename{.hgrc} file; see below for details. 9.405 - 9.406 -\subsubsection{Creating a Mercurial configuration file} 9.407 -\label{sec:tour-basic:username} 9.408 - 9.409 -To set a user name, use your favourite editor to create a file called 9.410 -\sfilename{.hgrc} in your home directory. Mercurial will use this 9.411 -file to look up your personalised configuration settings. The initial 9.412 -contents of your \sfilename{.hgrc} should look like this. 9.413 -\begin{codesample2} 9.414 - # This is a Mercurial configuration file. 9.415 - [ui] 9.416 - username = Firstname Lastname <email.address@domain.net> 9.417 -\end{codesample2} 9.418 -The ``\texttt{[ui]}'' line begins a \emph{section} of the config file, 9.419 -so you can read the ``\texttt{username = ...}'' line as meaning ``set 9.420 -the value of the \texttt{username} item in the \texttt{ui} section''. 9.421 -A section continues until a new section begins, or the end of the 9.422 -file. Mercurial ignores empty lines and treats any text from 9.423 -``\texttt{\#}'' to the end of a line as a comment. 9.424 - 9.425 -\subsubsection{Choosing a user name} 9.426 - 9.427 -You can use any text you like as the value of the \texttt{username} 9.428 -config item, since this information is for reading by other people, 9.429 -but for interpreting by Mercurial. The convention that most people 9.430 -follow is to use their name and email address, as in the example 9.431 -above. 9.432 - 9.433 -\begin{note} 9.434 - Mercurial's built-in web server obfuscates email addresses, to make 9.435 - it more difficult for the email harvesting tools that spammers use. 9.436 - This reduces the likelihood that you'll start receiving more junk 9.437 - email if you publish a Mercurial repository on the web. 9.438 -\end{note} 9.439 - 9.440 -\subsection{Writing a commit message} 9.441 - 9.442 -When we commit a change, Mercurial drops us into a text editor, to 9.443 -enter a message that will describe the modifications we've made in 9.444 -this changeset. This is called the \emph{commit message}. It will be 9.445 -a record for readers of what we did and why, and it will be printed by 9.446 -\hgcmd{log} after we've finished committing. 9.447 -\interaction{tour.commit} 9.448 - 9.449 -The editor that the \hgcmd{commit} command drops us into will contain 9.450 -an empty line, followed by a number of lines starting with 9.451 -``\texttt{HG:}''. 9.452 -\begin{codesample2} 9.453 - \emph{empty line} 9.454 - HG: changed hello.c 9.455 -\end{codesample2} 9.456 -Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses 9.457 -them only to tell us which files it's recording changes to. Modifying 9.458 -or deleting these lines has no effect. 9.459 - 9.460 -\subsection{Writing a good commit message} 9.461 - 9.462 -Since \hgcmd{log} only prints the first line of a commit message by 9.463 -default, it's best to write a commit message whose first line stands 9.464 -alone. Here's a real example of a commit message that \emph{doesn't} 9.465 -follow this guideline, and hence has a summary that is not readable. 9.466 -\begin{codesample2} 9.467 - changeset: 73:584af0e231be 9.468 - user: Censored Person <censored.person@example.org> 9.469 - date: Tue Sep 26 21:37:07 2006 -0700 9.470 - summary: include buildmeister/commondefs. Add an exports and install 9.471 -\end{codesample2} 9.472 - 9.473 -As far as the remainder of the contents of the commit message are 9.474 -concerned, there are no hard-and-fast rules. Mercurial itself doesn't 9.475 -interpret or care about the contents of the commit message, though 9.476 -your project may have policies that dictate a certain kind of 9.477 -formatting. 9.478 - 9.479 -My personal preference is for short, but informative, commit messages 9.480 -that tell me something that I can't figure out with a quick glance at 9.481 -the output of \hgcmdargs{log}{--patch}. 9.482 - 9.483 -\subsection{Aborting a commit} 9.484 - 9.485 -If you decide that you don't want to commit while in the middle of 9.486 -editing a commit message, simply exit from your editor without saving 9.487 -the file that it's editing. This will cause nothing to happen to 9.488 -either the repository or the working directory. 9.489 - 9.490 -If we run the \hgcmd{commit} command without any arguments, it records 9.491 -all of the changes we've made, as reported by \hgcmd{status} and 9.492 -\hgcmd{diff}. 9.493 - 9.494 -\subsection{Admiring our new handiwork} 9.495 - 9.496 -Once we've finished the commit, we can use the \hgcmd{tip} command to 9.497 -display the changeset we just created. This command produces output 9.498 -that is identical to \hgcmd{log}, but it only displays the newest 9.499 -revision in the repository. 9.500 -\interaction{tour.tip} 9.501 -We refer to the newest revision in the repository as the tip revision, 9.502 -or simply the tip. 9.503 - 9.504 -\section{Sharing changes} 9.505 - 9.506 -We mentioned earlier that repositories in Mercurial are 9.507 -self-contained. This means that the changeset we just created exists 9.508 -only in our \dirname{my-hello} repository. Let's look at a few ways 9.509 -that we can propagate this change into other repositories. 9.510 - 9.511 -\subsection{Pulling changes from another repository} 9.512 -\label{sec:tour:pull} 9.513 - 9.514 -To get started, let's clone our original \dirname{hello} repository, 9.515 -which does not contain the change we just committed. We'll call our 9.516 -temporary repository \dirname{hello-pull}. 9.517 -\interaction{tour.clone-pull} 9.518 - 9.519 -We'll use the \hgcmd{pull} command to bring changes from 9.520 -\dirname{my-hello} into \dirname{hello-pull}. However, blindly 9.521 -pulling unknown changes into a repository is a somewhat scary 9.522 -prospect. Mercurial provides the \hgcmd{incoming} command to tell us 9.523 -what changes the \hgcmd{pull} command \emph{would} pull into the 9.524 -repository, without actually pulling the changes in. 9.525 -\interaction{tour.incoming} 9.526 -(Of course, someone could cause more changesets to appear in the 9.527 -repository that we ran \hgcmd{incoming} in, before we get a chance to 9.528 -\hgcmd{pull} the changes, so that we could end up pulling changes that we 9.529 -didn't expect.) 9.530 - 9.531 -Bringing changes into a repository is a simple matter of running the 9.532 -\hgcmd{pull} command, and telling it which repository to pull from. 9.533 -\interaction{tour.pull} 9.534 -As you can see from the before-and-after output of \hgcmd{tip}, we 9.535 -have successfully pulled changes into our repository. There remains 9.536 -one step before we can see these changes in the working directory. 9.537 - 9.538 -\subsection{Updating the working directory} 9.539 - 9.540 -We have so far glossed over the relationship between a repository and 9.541 -its working directory. The \hgcmd{pull} command that we ran in 9.542 -section~\ref{sec:tour:pull} brought changes into the repository, but 9.543 -if we check, there's no sign of those changes in the working 9.544 -directory. This is because \hgcmd{pull} does not (by default) touch 9.545 -the working directory. Instead, we use the \hgcmd{update} command to 9.546 -do this. 9.547 -\interaction{tour.update} 9.548 - 9.549 -It might seem a bit strange that \hgcmd{pull} doesn't update the 9.550 -working directory automatically. There's actually a good reason for 9.551 -this: you can use \hgcmd{update} to update the working directory to 9.552 -the state it was in at \emph{any revision} in the history of the 9.553 -repository. If you had the working directory updated to an old 9.554 -revision---to hunt down the origin of a bug, say---and ran a 9.555 -\hgcmd{pull} which automatically updated the working directory to a 9.556 -new revision, you might not be terribly happy. 9.557 - 9.558 -However, since pull-then-update is such a common thing to do, 9.559 -Mercurial lets you combine the two by passing the \hgopt{pull}{-u} 9.560 -option to \hgcmd{pull}. 9.561 -\begin{codesample2} 9.562 - hg pull -u 9.563 -\end{codesample2} 9.564 -If you look back at the output of \hgcmd{pull} in 9.565 -section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u}, 9.566 -you can see that it printed a helpful reminder that we'd have to take 9.567 -an explicit step to update the working directory: 9.568 -\begin{codesample2} 9.569 - (run 'hg update' to get a working copy) 9.570 -\end{codesample2} 9.571 - 9.572 -To find out what revision the working directory is at, use the 9.573 -\hgcmd{parents} command. 9.574 -\interaction{tour.parents} 9.575 -If you look back at figure~\ref{fig:tour-basic:history}, you'll see 9.576 -arrows connecting each changeset. The node that the arrow leads 9.577 -\emph{from} in each case is a parent, and the node that the arrow 9.578 -leads \emph{to} is its child. The working directory has a parent in 9.579 -just the same way; this is the changeset that the working directory 9.580 -currently contains. 9.581 - 9.582 -To update the working directory to a particular revision, give a 9.583 -revision number or changeset~ID to the \hgcmd{update} command. 9.584 -\interaction{tour.older} 9.585 -If you omit an explicit revision, \hgcmd{update} will update to the 9.586 -tip revision, as shown by the second call to \hgcmd{update} in the 9.587 -example above. 9.588 - 9.589 -\subsection{Pushing changes to another repository} 9.590 - 9.591 -Mercurial lets us push changes to another repository, from the 9.592 -repository we're currently visiting. As with the example of 9.593 -\hgcmd{pull} above, we'll create a temporary repository to push our 9.594 -changes into. 9.595 -\interaction{tour.clone-push} 9.596 -The \hgcmd{outgoing} command tells us what changes would be pushed 9.597 -into another repository. 9.598 -\interaction{tour.outgoing} 9.599 -And the \hgcmd{push} command does the actual push. 9.600 -\interaction{tour.push} 9.601 -As with \hgcmd{pull}, the \hgcmd{push} command does not update the 9.602 -working directory in the repository that it's pushing changes into. 9.603 -(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u} 9.604 -option that updates the other repository's working directory.) 9.605 - 9.606 -What happens if we try to pull or push changes and the receiving 9.607 -repository already has those changes? Nothing too exciting. 9.608 -\interaction{tour.push.nothing} 9.609 - 9.610 -\subsection{Sharing changes over a network} 9.611 - 9.612 -The commands we have covered in the previous few sections are not 9.613 -limited to working with local repositories. Each works in exactly the 9.614 -same fashion over a network connection; simply pass in a URL instead 9.615 -of a local path. 9.616 -\interaction{tour.outgoing.net} 9.617 -In this example, we can see what changes we could push to the remote 9.618 -repository, but the repository is understandably not set up to let 9.619 -anonymous users push to it. 9.620 -\interaction{tour.push.net} 9.621 - 9.622 -%%% Local Variables: 9.623 -%%% mode: latex 9.624 -%%% TeX-master: "00book" 9.625 -%%% End:
10.1 --- a/en/ch03-tour-merge.tex Thu Mar 05 21:52:23 2009 +0200 10.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 10.3 @@ -1,285 +0,0 @@ 10.4 -\chapter{A tour of Mercurial: merging work} 10.5 -\label{chap:tour-merge} 10.6 - 10.7 -We've now covered cloning a repository, making changes in a 10.8 -repository, and pulling or pushing changes from one repository into 10.9 -another. Our next step is \emph{merging} changes from separate 10.10 -repositories. 10.11 - 10.12 -\section{Merging streams of work} 10.13 - 10.14 -Merging is a fundamental part of working with a distributed revision 10.15 -control tool. 10.16 -\begin{itemize} 10.17 -\item Alice and Bob each have a personal copy of a repository for a 10.18 - project they're collaborating on. Alice fixes a bug in her 10.19 - repository; Bob adds a new feature in his. They want the shared 10.20 - repository to contain both the bug fix and the new feature. 10.21 -\item I frequently work on several different tasks for a single 10.22 - project at once, each safely isolated in its own repository. 10.23 - Working this way means that I often need to merge one piece of my 10.24 - own work with another. 10.25 -\end{itemize} 10.26 - 10.27 -Because merging is such a common thing to need to do, Mercurial makes 10.28 -it easy. Let's walk through the process. We'll begin by cloning yet 10.29 -another repository (see how often they spring up?) and making a change 10.30 -in it. 10.31 -\interaction{tour.merge.clone} 10.32 -We should now have two copies of \filename{hello.c} with different 10.33 -contents. The histories of the two repositories have also diverged, 10.34 -as illustrated in figure~\ref{fig:tour-merge:sep-repos}. 10.35 -\interaction{tour.merge.cat} 10.36 - 10.37 -\begin{figure}[ht] 10.38 - \centering 10.39 - \grafix{tour-merge-sep-repos} 10.40 - \caption{Divergent recent histories of the \dirname{my-hello} and 10.41 - \dirname{my-new-hello} repositories} 10.42 - \label{fig:tour-merge:sep-repos} 10.43 -\end{figure} 10.44 - 10.45 -We already know that pulling changes from our \dirname{my-hello} 10.46 -repository will have no effect on the working directory. 10.47 -\interaction{tour.merge.pull} 10.48 -However, the \hgcmd{pull} command says something about ``heads''. 10.49 - 10.50 -\subsection{Head changesets} 10.51 - 10.52 -A head is a change that has no descendants, or children, as they're 10.53 -also known. The tip revision is thus a head, because the newest 10.54 -revision in a repository doesn't have any children, but a repository 10.55 -can contain more than one head. 10.56 - 10.57 -\begin{figure}[ht] 10.58 - \centering 10.59 - \grafix{tour-merge-pull} 10.60 - \caption{Repository contents after pulling from \dirname{my-hello} into 10.61 - \dirname{my-new-hello}} 10.62 - \label{fig:tour-merge:pull} 10.63 -\end{figure} 10.64 - 10.65 -In figure~\ref{fig:tour-merge:pull}, you can see the effect of the 10.66 -pull from \dirname{my-hello} into \dirname{my-new-hello}. The history 10.67 -that was already present in \dirname{my-new-hello} is untouched, but a 10.68 -new revision has been added. By referring to 10.69 -figure~\ref{fig:tour-merge:sep-repos}, we can see that the 10.70 -\emph{changeset ID} remains the same in the new repository, but the 10.71 -\emph{revision number} has changed. (This, incidentally, is a fine 10.72 -example of why it's not safe to use revision numbers when discussing 10.73 -changesets.) We can view the heads in a repository using the 10.74 -\hgcmd{heads} command. 10.75 -\interaction{tour.merge.heads} 10.76 - 10.77 -\subsection{Performing the merge} 10.78 - 10.79 -What happens if we try to use the normal \hgcmd{update} command to 10.80 -update to the new tip? 10.81 -\interaction{tour.merge.update} 10.82 -Mercurial is telling us that the \hgcmd{update} command won't do a 10.83 -merge; it won't update the working directory when it thinks we might 10.84 -be wanting to do a merge, unless we force it to do so. Instead, we 10.85 -use the \hgcmd{merge} command to merge the two heads. 10.86 -\interaction{tour.merge.merge} 10.87 - 10.88 -\begin{figure}[ht] 10.89 - \centering 10.90 - \grafix{tour-merge-merge} 10.91 - \caption{Working directory and repository during merge, and following commit} 10.92 - \label{fig:tour-merge:merge} 10.93 -\end{figure} 10.94 - 10.95 -This updates the working directory so that it contains changes from 10.96 -\emph{both} heads, which is reflected in both the output of 10.97 -\hgcmd{parents} and the contents of \filename{hello.c}. 10.98 -\interaction{tour.merge.parents} 10.99 - 10.100 -\subsection{Committing the results of the merge} 10.101 - 10.102 -Whenever we've done a merge, \hgcmd{parents} will display two parents 10.103 -until we \hgcmd{commit} the results of the merge. 10.104 -\interaction{tour.merge.commit} 10.105 -We now have a new tip revision; notice that it has \emph{both} of 10.106 -our former heads as its parents. These are the same revisions that 10.107 -were previously displayed by \hgcmd{parents}. 10.108 -\interaction{tour.merge.tip} 10.109 -In figure~\ref{fig:tour-merge:merge}, you can see a representation of 10.110 -what happens to the working directory during the merge, and how this 10.111 -affects the repository when the commit happens. During the merge, the 10.112 -working directory has two parent changesets, and these become the 10.113 -parents of the new changeset. 10.114 - 10.115 -\section{Merging conflicting changes} 10.116 - 10.117 -Most merges are simple affairs, but sometimes you'll find yourself 10.118 -merging changes where each modifies the same portions of the same 10.119 -files. Unless both modifications are identical, this results in a 10.120 -\emph{conflict}, where you have to decide how to reconcile the 10.121 -different changes into something coherent. 10.122 - 10.123 -\begin{figure}[ht] 10.124 - \centering 10.125 - \grafix{tour-merge-conflict} 10.126 - \caption{Conflicting changes to a document} 10.127 - \label{fig:tour-merge:conflict} 10.128 -\end{figure} 10.129 - 10.130 -Figure~\ref{fig:tour-merge:conflict} illustrates an instance of two 10.131 -conflicting changes to a document. We started with a single version 10.132 -of the file; then we made some changes; while someone else made 10.133 -different changes to the same text. Our task in resolving the 10.134 -conflicting changes is to decide what the file should look like. 10.135 - 10.136 -Mercurial doesn't have a built-in facility for handling conflicts. 10.137 -Instead, it runs an external program called \command{hgmerge}. This 10.138 -is a shell script that is bundled with Mercurial; you can change it to 10.139 -behave however you please. What it does by default is try to find one 10.140 -of several different merging tools that are likely to be installed on 10.141 -your system. It first tries a few fully automatic merging tools; if 10.142 -these don't succeed (because the resolution process requires human 10.143 -guidance) or aren't present, the script tries a few different 10.144 -graphical merging tools. 10.145 - 10.146 -It's also possible to get Mercurial to run another program or script 10.147 -instead of \command{hgmerge}, by setting the \envar{HGMERGE} 10.148 -environment variable to the name of your preferred program. 10.149 - 10.150 -\subsection{Using a graphical merge tool} 10.151 - 10.152 -My preferred graphical merge tool is \command{kdiff3}, which I'll use 10.153 -to describe the features that are common to graphical file merging 10.154 -tools. You can see a screenshot of \command{kdiff3} in action in 10.155 -figure~\ref{fig:tour-merge:kdiff3}. The kind of merge it is 10.156 -performing is called a \emph{three-way merge}, because there are three 10.157 -different versions of the file of interest to us. The tool thus 10.158 -splits the upper portion of the window into three panes: 10.159 -\begin{itemize} 10.160 -\item At the left is the \emph{base} version of the file, i.e.~the 10.161 - most recent version from which the two versions we're trying to 10.162 - merge are descended. 10.163 -\item In the middle is ``our'' version of the file, with the contents 10.164 - that we modified. 10.165 -\item On the right is ``their'' version of the file, the one that 10.166 - from the changeset that we're trying to merge with. 10.167 -\end{itemize} 10.168 -In the pane below these is the current \emph{result} of the merge. 10.169 -Our task is to replace all of the red text, which indicates unresolved 10.170 -conflicts, with some sensible merger of the ``ours'' and ``theirs'' 10.171 -versions of the file. 10.172 - 10.173 -All four of these panes are \emph{locked together}; if we scroll 10.174 -vertically or horizontally in any of them, the others are updated to 10.175 -display the corresponding sections of their respective files. 10.176 - 10.177 -\begin{figure}[ht] 10.178 - \centering 10.179 - \grafix{kdiff3} 10.180 - \caption{Using \command{kdiff3} to merge versions of a file} 10.181 - \label{fig:tour-merge:kdiff3} 10.182 -\end{figure} 10.183 - 10.184 -For each conflicting portion of the file, we can choose to resolve 10.185 -the conflict using some combination of text from the base version, 10.186 -ours, or theirs. We can also manually edit the merged file at any 10.187 -time, in case we need to make further modifications. 10.188 - 10.189 -There are \emph{many} file merging tools available, too many to cover 10.190 -here. They vary in which platforms they are available for, and in 10.191 -their particular strengths and weaknesses. Most are tuned for merging 10.192 -files containing plain text, while a few are aimed at specialised file 10.193 -formats (generally XML). 10.194 - 10.195 -\subsection{A worked example} 10.196 - 10.197 -In this example, we will reproduce the file modification history of 10.198 -figure~\ref{fig:tour-merge:conflict} above. Let's begin by creating a 10.199 -repository with a base version of our document. 10.200 -\interaction{tour-merge-conflict.wife} 10.201 -We'll clone the repository and make a change to the file. 10.202 -\interaction{tour-merge-conflict.cousin} 10.203 -And another clone, to simulate someone else making a change to the 10.204 -file. (This hints at the idea that it's not all that unusual to merge 10.205 -with yourself when you isolate tasks in separate repositories, and 10.206 -indeed to find and resolve conflicts while doing so.) 10.207 -\interaction{tour-merge-conflict.son} 10.208 -Having created two different versions of the file, we'll set up an 10.209 -environment suitable for running our merge. 10.210 -\interaction{tour-merge-conflict.pull} 10.211 - 10.212 -In this example, I won't use Mercurial's normal \command{hgmerge} 10.213 -program to do the merge, because it would drop my nice automated 10.214 -example-running tool into a graphical user interface. Instead, I'll 10.215 -set \envar{HGMERGE} to tell Mercurial to use the non-interactive 10.216 -\command{merge} command. This is bundled with many Unix-like systems. 10.217 -If you're following this example on your computer, don't bother 10.218 -setting \envar{HGMERGE}. 10.219 - 10.220 -\textbf{XXX FIX THIS EXAMPLE.} 10.221 - 10.222 -\interaction{tour-merge-conflict.merge} 10.223 -Because \command{merge} can't resolve the conflicting changes, it 10.224 -leaves \emph{merge markers} inside the file that has conflicts, 10.225 -indicating which lines have conflicts, and whether they came from our 10.226 -version of the file or theirs. 10.227 - 10.228 -Mercurial can tell from the way \command{merge} exits that it wasn't 10.229 -able to merge successfully, so it tells us what commands we'll need to 10.230 -run if we want to redo the merging operation. This could be useful 10.231 -if, for example, we were running a graphical merge tool and quit 10.232 -because we were confused or realised we had made a mistake. 10.233 - 10.234 -If automatic or manual merges fail, there's nothing to prevent us from 10.235 -``fixing up'' the affected files ourselves, and committing the results 10.236 -of our merge: 10.237 -\interaction{tour-merge-conflict.commit} 10.238 - 10.239 -\section{Simplifying the pull-merge-commit sequence} 10.240 -\label{sec:tour-merge:fetch} 10.241 - 10.242 -The process of merging changes as outlined above is straightforward, 10.243 -but requires running three commands in sequence. 10.244 -\begin{codesample2} 10.245 - hg pull 10.246 - hg merge 10.247 - hg commit -m 'Merged remote changes' 10.248 -\end{codesample2} 10.249 -In the case of the final commit, you also need to enter a commit 10.250 -message, which is almost always going to be a piece of uninteresting 10.251 -``boilerplate'' text. 10.252 - 10.253 -It would be nice to reduce the number of steps needed, if this were 10.254 -possible. Indeed, Mercurial is distributed with an extension called 10.255 -\hgext{fetch} that does just this. 10.256 - 10.257 -Mercurial provides a flexible extension mechanism that lets people 10.258 -extend its functionality, while keeping the core of Mercurial small 10.259 -and easy to deal with. Some extensions add new commands that you can 10.260 -use from the command line, while others work ``behind the scenes,'' 10.261 -for example adding capabilities to the server. 10.262 - 10.263 -The \hgext{fetch} extension adds a new command called, not 10.264 -surprisingly, \hgcmd{fetch}. This extension acts as a combination of 10.265 -\hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}. It begins by pulling 10.266 -changes from another repository into the current repository. If it 10.267 -finds that the changes added a new head to the repository, it begins a 10.268 -merge, then commits the result of the merge with an 10.269 -automatically-generated commit message. If no new heads were added, 10.270 -it updates the working directory to the new tip changeset. 10.271 - 10.272 -Enabling the \hgext{fetch} extension is easy. Edit your 10.273 -\sfilename{.hgrc}, and either go to the \rcsection{extensions} section 10.274 -or create an \rcsection{extensions} section. Then add a line that 10.275 -simply reads ``\Verb+fetch +''. 10.276 -\begin{codesample2} 10.277 - [extensions] 10.278 - fetch = 10.279 -\end{codesample2} 10.280 -(Normally, on the right-hand side of the ``\texttt{=}'' would appear 10.281 -the location of the extension, but since the \hgext{fetch} extension 10.282 -is in the standard distribution, Mercurial knows where to search for 10.283 -it.) 10.284 - 10.285 -%%% Local Variables: 10.286 -%%% mode: latex 10.287 -%%% TeX-master: "00book" 10.288 -%%% End:
11.1 --- a/en/ch04-concepts.tex Thu Mar 05 21:52:23 2009 +0200 11.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 11.3 @@ -1,574 +0,0 @@ 11.4 -\chapter{Behind the scenes} 11.5 -\label{chap:concepts} 11.6 - 11.7 -Unlike many revision control systems, the concepts upon which 11.8 -Mercurial is built are simple enough that it's easy to understand how 11.9 -the software really works. Knowing this certainly isn't necessary, 11.10 -but I find it useful to have a ``mental model'' of what's going on. 11.11 - 11.12 -This understanding gives me confidence that Mercurial has been 11.13 -carefully designed to be both \emph{safe} and \emph{efficient}. And 11.14 -just as importantly, if it's easy for me to retain a good idea of what 11.15 -the software is doing when I perform a revision control task, I'm less 11.16 -likely to be surprised by its behaviour. 11.17 - 11.18 -In this chapter, we'll initially cover the core concepts behind 11.19 -Mercurial's design, then continue to discuss some of the interesting 11.20 -details of its implementation. 11.21 - 11.22 -\section{Mercurial's historical record} 11.23 - 11.24 -\subsection{Tracking the history of a single file} 11.25 - 11.26 -When Mercurial tracks modifications to a file, it stores the history 11.27 -of that file in a metadata object called a \emph{filelog}. Each entry 11.28 -in the filelog contains enough information to reconstruct one revision 11.29 -of the file that is being tracked. Filelogs are stored as files in 11.30 -the \sdirname{.hg/store/data} directory. A filelog contains two kinds 11.31 -of information: revision data, and an index to help Mercurial to find 11.32 -a revision efficiently. 11.33 - 11.34 -A file that is large, or has a lot of history, has its filelog stored 11.35 -in separate data (``\texttt{.d}'' suffix) and index (``\texttt{.i}'' 11.36 -suffix) files. For small files without much history, the revision 11.37 -data and index are combined in a single ``\texttt{.i}'' file. The 11.38 -correspondence between a file in the working directory and the filelog 11.39 -that tracks its history in the repository is illustrated in 11.40 -figure~\ref{fig:concepts:filelog}. 11.41 - 11.42 -\begin{figure}[ht] 11.43 - \centering 11.44 - \grafix{filelog} 11.45 - \caption{Relationships between files in working directory and filelogs in repository} 11.46 - \label{fig:concepts:filelog} 11.47 -\end{figure} 11.48 - 11.49 -\subsection{Managing tracked files} 11.50 - 11.51 -Mercurial uses a structure called a \emph{manifest} to collect 11.52 -together information about the files that it tracks. Each entry in 11.53 -the manifest contains information about the files present in a single 11.54 -changeset. An entry records which files are present in the changeset, 11.55 -the revision of each file, and a few other pieces of file metadata. 11.56 - 11.57 -\subsection{Recording changeset information} 11.58 - 11.59 -The \emph{changelog} contains information about each changeset. Each 11.60 -revision records who committed a change, the changeset comment, other 11.61 -pieces of changeset-related information, and the revision of the 11.62 -manifest to use. 11.63 - 11.64 -\subsection{Relationships between revisions} 11.65 - 11.66 -Within a changelog, a manifest, or a filelog, each revision stores a 11.67 -pointer to its immediate parent (or to its two parents, if it's a 11.68 -merge revision). As I mentioned above, there are also relationships 11.69 -between revisions \emph{across} these structures, and they are 11.70 -hierarchical in nature. 11.71 - 11.72 -For every changeset in a repository, there is exactly one revision 11.73 -stored in the changelog. Each revision of the changelog contains a 11.74 -pointer to a single revision of the manifest. A revision of the 11.75 -manifest stores a pointer to a single revision of each filelog tracked 11.76 -when that changeset was created. These relationships are illustrated 11.77 -in figure~\ref{fig:concepts:metadata}. 11.78 - 11.79 -\begin{figure}[ht] 11.80 - \centering 11.81 - \grafix{metadata} 11.82 - \caption{Metadata relationships} 11.83 - \label{fig:concepts:metadata} 11.84 -\end{figure} 11.85 - 11.86 -As the illustration shows, there is \emph{not} a ``one to one'' 11.87 -relationship between revisions in the changelog, manifest, or filelog. 11.88 -If the manifest hasn't changed between two changesets, the changelog 11.89 -entries for those changesets will point to the same revision of the 11.90 -manifest. If a file that Mercurial tracks hasn't changed between two 11.91 -changesets, the entry for that file in the two revisions of the 11.92 -manifest will point to the same revision of its filelog. 11.93 - 11.94 -\section{Safe, efficient storage} 11.95 - 11.96 -The underpinnings of changelogs, manifests, and filelogs are provided 11.97 -by a single structure called the \emph{revlog}. 11.98 - 11.99 -\subsection{Efficient storage} 11.100 - 11.101 -The revlog provides efficient storage of revisions using a 11.102 -\emph{delta} mechanism. Instead of storing a complete copy of a file 11.103 -for each revision, it stores the changes needed to transform an older 11.104 -revision into the new revision. For many kinds of file data, these 11.105 -deltas are typically a fraction of a percent of the size of a full 11.106 -copy of a file. 11.107 - 11.108 -Some obsolete revision control systems can only work with deltas of 11.109 -text files. They must either store binary files as complete snapshots 11.110 -or encoded into a text representation, both of which are wasteful 11.111 -approaches. Mercurial can efficiently handle deltas of files with 11.112 -arbitrary binary contents; it doesn't need to treat text as special. 11.113 - 11.114 -\subsection{Safe operation} 11.115 -\label{sec:concepts:txn} 11.116 - 11.117 -Mercurial only ever \emph{appends} data to the end of a revlog file. 11.118 -It never modifies a section of a file after it has written it. This 11.119 -is both more robust and efficient than schemes that need to modify or 11.120 -rewrite data. 11.121 - 11.122 -In addition, Mercurial treats every write as part of a 11.123 -\emph{transaction} that can span a number of files. A transaction is 11.124 -\emph{atomic}: either the entire transaction succeeds and its effects 11.125 -are all visible to readers in one go, or the whole thing is undone. 11.126 -This guarantee of atomicity means that if you're running two copies of 11.127 -Mercurial, where one is reading data and one is writing it, the reader 11.128 -will never see a partially written result that might confuse it. 11.129 - 11.130 -The fact that Mercurial only appends to files makes it easier to 11.131 -provide this transactional guarantee. The easier it is to do stuff 11.132 -like this, the more confident you should be that it's done correctly. 11.133 - 11.134 -\subsection{Fast retrieval} 11.135 - 11.136 -Mercurial cleverly avoids a pitfall common to all earlier 11.137 -revision control systems: the problem of \emph{inefficient retrieval}. 11.138 -Most revision control systems store the contents of a revision as an 11.139 -incremental series of modifications against a ``snapshot''. To 11.140 -reconstruct a specific revision, you must first read the snapshot, and 11.141 -then every one of the revisions between the snapshot and your target 11.142 -revision. The more history that a file accumulates, the more 11.143 -revisions you must read, hence the longer it takes to reconstruct a 11.144 -particular revision. 11.145 - 11.146 -\begin{figure}[ht] 11.147 - \centering 11.148 - \grafix{snapshot} 11.149 - \caption{Snapshot of a revlog, with incremental deltas} 11.150 - \label{fig:concepts:snapshot} 11.151 -\end{figure} 11.152 - 11.153 -The innovation that Mercurial applies to this problem is simple but 11.154 -effective. Once the cumulative amount of delta information stored 11.155 -since the last snapshot exceeds a fixed threshold, it stores a new 11.156 -snapshot (compressed, of course), instead of another delta. This 11.157 -makes it possible to reconstruct \emph{any} revision of a file 11.158 -quickly. This approach works so well that it has since been copied by 11.159 -several other revision control systems. 11.160 - 11.161 -Figure~\ref{fig:concepts:snapshot} illustrates the idea. In an entry 11.162 -in a revlog's index file, Mercurial stores the range of entries from 11.163 -the data file that it must read to reconstruct a particular revision. 11.164 - 11.165 -\subsubsection{Aside: the influence of video compression} 11.166 - 11.167 -If you're familiar with video compression or have ever watched a TV 11.168 -feed through a digital cable or satellite service, you may know that 11.169 -most video compression schemes store each frame of video as a delta 11.170 -against its predecessor frame. In addition, these schemes use 11.171 -``lossy'' compression techniques to increase the compression ratio, so 11.172 -visual errors accumulate over the course of a number of inter-frame 11.173 -deltas. 11.174 - 11.175 -Because it's possible for a video stream to ``drop out'' occasionally 11.176 -due to signal glitches, and to limit the accumulation of artefacts 11.177 -introduced by the lossy compression process, video encoders 11.178 -periodically insert a complete frame (called a ``key frame'') into the 11.179 -video stream; the next delta is generated against that frame. This 11.180 -means that if the video signal gets interrupted, it will resume once 11.181 -the next key frame is received. Also, the accumulation of encoding 11.182 -errors restarts anew with each key frame. 11.183 - 11.184 -\subsection{Identification and strong integrity} 11.185 - 11.186 -Along with delta or snapshot information, a revlog entry contains a 11.187 -cryptographic hash of the data that it represents. This makes it 11.188 -difficult to forge the contents of a revision, and easy to detect 11.189 -accidental corruption. 11.190 - 11.191 -Hashes provide more than a mere check against corruption; they are 11.192 -used as the identifiers for revisions. The changeset identification 11.193 -hashes that you see as an end user are from revisions of the 11.194 -changelog. Although filelogs and the manifest also use hashes, 11.195 -Mercurial only uses these behind the scenes. 11.196 - 11.197 -Mercurial verifies that hashes are correct when it retrieves file 11.198 -revisions and when it pulls changes from another repository. If it 11.199 -encounters an integrity problem, it will complain and stop whatever 11.200 -it's doing. 11.201 - 11.202 -In addition to the effect it has on retrieval efficiency, Mercurial's 11.203 -use of periodic snapshots makes it more robust against partial data 11.204 -corruption. If a revlog becomes partly corrupted due to a hardware 11.205 -error or system bug, it's often possible to reconstruct some or most 11.206 -revisions from the uncorrupted sections of the revlog, both before and 11.207 -after the corrupted section. This would not be possible with a 11.208 -delta-only storage model. 11.209 - 11.210 -\section{Revision history, branching, and merging} 11.211 - 11.212 -Every entry in a Mercurial revlog knows the identity of its immediate 11.213 -ancestor revision, usually referred to as its \emph{parent}. In fact, 11.214 -a revision contains room for not one parent, but two. Mercurial uses 11.215 -a special hash, called the ``null ID'', to represent the idea ``there 11.216 -is no parent here''. This hash is simply a string of zeroes. 11.217 - 11.218 -In figure~\ref{fig:concepts:revlog}, you can see an example of the 11.219 -conceptual structure of a revlog. Filelogs, manifests, and changelogs 11.220 -all have this same structure; they differ only in the kind of data 11.221 -stored in each delta or snapshot. 11.222 - 11.223 -The first revision in a revlog (at the bottom of the image) has the 11.224 -null ID in both of its parent slots. For a ``normal'' revision, its 11.225 -first parent slot contains the ID of its parent revision, and its 11.226 -second contains the null ID, indicating that the revision has only one 11.227 -real parent. Any two revisions that have the same parent ID are 11.228 -branches. A revision that represents a merge between branches has two 11.229 -normal revision IDs in its parent slots. 11.230 - 11.231 -\begin{figure}[ht] 11.232 - \centering 11.233 - \grafix{revlog} 11.234 - \caption{} 11.235 - \label{fig:concepts:revlog} 11.236 -\end{figure} 11.237 - 11.238 -\section{The working directory} 11.239 - 11.240 -In the working directory, Mercurial stores a snapshot of the files 11.241 -from the repository as of a particular changeset. 11.242 - 11.243 -The working directory ``knows'' which changeset it contains. When you 11.244 -update the working directory to contain a particular changeset, 11.245 -Mercurial looks up the appropriate revision of the manifest to find 11.246 -out which files it was tracking at the time that changeset was 11.247 -committed, and which revision of each file was then current. It then 11.248 -recreates a copy of each of those files, with the same contents it had 11.249 -when the changeset was committed. 11.250 - 11.251 -The \emph{dirstate} contains Mercurial's knowledge of the working 11.252 -directory. This details which changeset the working directory is 11.253 -updated to, and all of the files that Mercurial is tracking in the 11.254 -working directory. 11.255 - 11.256 -Just as a revision of a revlog has room for two parents, so that it 11.257 -can represent either a normal revision (with one parent) or a merge of 11.258 -two earlier revisions, the dirstate has slots for two parents. When 11.259 -you use the \hgcmd{update} command, the changeset that you update to 11.260 -is stored in the ``first parent'' slot, and the null ID in the second. 11.261 -When you \hgcmd{merge} with another changeset, the first parent 11.262 -remains unchanged, and the second parent is filled in with the 11.263 -changeset you're merging with. The \hgcmd{parents} command tells you 11.264 -what the parents of the dirstate are. 11.265 - 11.266 -\subsection{What happens when you commit} 11.267 - 11.268 -The dirstate stores parent information for more than just book-keeping 11.269 -purposes. Mercurial uses the parents of the dirstate as \emph{the parents of a new changeset} when you perform a commit. 11.270 - 11.271 -\begin{figure}[ht] 11.272 - \centering 11.273 - \grafix{wdir} 11.274 - \caption{The working directory can have two parents} 11.275 - \label{fig:concepts:wdir} 11.276 -\end{figure} 11.277 - 11.278 -Figure~\ref{fig:concepts:wdir} shows the normal state of the working 11.279 -directory, where it has a single changeset as parent. That changeset 11.280 -is the \emph{tip}, the newest changeset in the repository that has no 11.281 -children. 11.282 - 11.283 -\begin{figure}[ht] 11.284 - \centering 11.285 - \grafix{wdir-after-commit} 11.286 - \caption{The working directory gains new parents after a commit} 11.287 - \label{fig:concepts:wdir-after-commit} 11.288 -\end{figure} 11.289 - 11.290 -It's useful to think of the working directory as ``the changeset I'm 11.291 -about to commit''. Any files that you tell Mercurial that you've 11.292 -added, removed, renamed, or copied will be reflected in that 11.293 -changeset, as will modifications to any files that Mercurial is 11.294 -already tracking; the new changeset will have the parents of the 11.295 -working directory as its parents. 11.296 - 11.297 -After a commit, Mercurial will update the parents of the working 11.298 -directory, so that the first parent is the ID of the new changeset, 11.299 -and the second is the null ID. This is shown in 11.300 -figure~\ref{fig:concepts:wdir-after-commit}. Mercurial doesn't touch 11.301 -any of the files in the working directory when you commit; it just 11.302 -modifies the dirstate to note its new parents. 11.303 - 11.304 -\subsection{Creating a new head} 11.305 - 11.306 -It's perfectly normal to update the working directory to a changeset 11.307 -other than the current tip. For example, you might want to know what 11.308 -your project looked like last Tuesday, or you could be looking through 11.309 -changesets to see which one introduced a bug. In cases like this, the 11.310 -natural thing to do is update the working directory to the changeset 11.311 -you're interested in, and then examine the files in the working 11.312 -directory directly to see their contents as they were when you 11.313 -committed that changeset. The effect of this is shown in 11.314 -figure~\ref{fig:concepts:wdir-pre-branch}. 11.315 - 11.316 -\begin{figure}[ht] 11.317 - \centering 11.318 - \grafix{wdir-pre-branch} 11.319 - \caption{The working directory, updated to an older changeset} 11.320 - \label{fig:concepts:wdir-pre-branch} 11.321 -\end{figure} 11.322 - 11.323 -Having updated the working directory to an older changeset, what 11.324 -happens if you make some changes, and then commit? Mercurial behaves 11.325 -in the same way as I outlined above. The parents of the working 11.326 -directory become the parents of the new changeset. This new changeset 11.327 -has no children, so it becomes the new tip. And the repository now 11.328 -contains two changesets that have no children; we call these 11.329 -\emph{heads}. You can see the structure that this creates in 11.330 -figure~\ref{fig:concepts:wdir-branch}. 11.331 - 11.332 -\begin{figure}[ht] 11.333 - \centering 11.334 - \grafix{wdir-branch} 11.335 - \caption{After a commit made while synced to an older changeset} 11.336 - \label{fig:concepts:wdir-branch} 11.337 -\end{figure} 11.338 - 11.339 -\begin{note} 11.340 - If you're new to Mercurial, you should keep in mind a common 11.341 - ``error'', which is to use the \hgcmd{pull} command without any 11.342 - options. By default, the \hgcmd{pull} command \emph{does not} 11.343 - update the working directory, so you'll bring new changesets into 11.344 - your repository, but the working directory will stay synced at the 11.345 - same changeset as before the pull. If you make some changes and 11.346 - commit afterwards, you'll thus create a new head, because your 11.347 - working directory isn't synced to whatever the current tip is. 11.348 - 11.349 - I put the word ``error'' in quotes because all that you need to do 11.350 - to rectify this situation is \hgcmd{merge}, then \hgcmd{commit}. In 11.351 - other words, this almost never has negative consequences; it just 11.352 - surprises people. I'll discuss other ways to avoid this behaviour, 11.353 - and why Mercurial behaves in this initially surprising way, later 11.354 - on. 11.355 -\end{note} 11.356 - 11.357 -\subsection{Merging heads} 11.358 - 11.359 -When you run the \hgcmd{merge} command, Mercurial leaves the first 11.360 -parent of the working directory unchanged, and sets the second parent 11.361 -to the changeset you're merging with, as shown in 11.362 -figure~\ref{fig:concepts:wdir-merge}. 11.363 - 11.364 -\begin{figure}[ht] 11.365 - \centering 11.366 - \grafix{wdir-merge} 11.367 - \caption{Merging two heads} 11.368 - \label{fig:concepts:wdir-merge} 11.369 -\end{figure} 11.370 - 11.371 -Mercurial also has to modify the working directory, to merge the files 11.372 -managed in the two changesets. Simplified a little, the merging 11.373 -process goes like this, for every file in the manifests of both 11.374 -changesets. 11.375 -\begin{itemize} 11.376 -\item If neither changeset has modified a file, do nothing with that 11.377 - file. 11.378 -\item If one changeset has modified a file, and the other hasn't, 11.379 - create the modified copy of the file in the working directory. 11.380 -\item If one changeset has removed a file, and the other hasn't (or 11.381 - has also deleted it), delete the file from the working directory. 11.382 -\item If one changeset has removed a file, but the other has modified 11.383 - the file, ask the user what to do: keep the modified file, or remove 11.384 - it? 11.385 -\item If both changesets have modified a file, invoke an external 11.386 - merge program to choose the new contents for the merged file. This 11.387 - may require input from the user. 11.388 -\item If one changeset has modified a file, and the other has renamed 11.389 - or copied the file, make sure that the changes follow the new name 11.390 - of the file. 11.391 -\end{itemize} 11.392 -There are more details---merging has plenty of corner cases---but 11.393 -these are the most common choices that are involved in a merge. As 11.394 -you can see, most cases are completely automatic, and indeed most 11.395 -merges finish automatically, without requiring your input to resolve 11.396 -any conflicts. 11.397 - 11.398 -When you're thinking about what happens when you commit after a merge, 11.399 -once again the working directory is ``the changeset I'm about to 11.400 -commit''. After the \hgcmd{merge} command completes, the working 11.401 -directory has two parents; these will become the parents of the new 11.402 -changeset. 11.403 - 11.404 -Mercurial lets you perform multiple merges, but you must commit the 11.405 -results of each individual merge as you go. This is necessary because 11.406 -Mercurial only tracks two parents for both revisions and the working 11.407 -directory. While it would be technically possible to merge multiple 11.408 -changesets at once, the prospect of user confusion and making a 11.409 -terrible mess of a merge immediately becomes overwhelming. 11.410 - 11.411 -\section{Other interesting design features} 11.412 - 11.413 -In the sections above, I've tried to highlight some of the most 11.414 -important aspects of Mercurial's design, to illustrate that it pays 11.415 -careful attention to reliability and performance. However, the 11.416 -attention to detail doesn't stop there. There are a number of other 11.417 -aspects of Mercurial's construction that I personally find 11.418 -interesting. I'll detail a few of them here, separate from the ``big 11.419 -ticket'' items above, so that if you're interested, you can gain a 11.420 -better idea of the amount of thinking that goes into a well-designed 11.421 -system. 11.422 - 11.423 -\subsection{Clever compression} 11.424 - 11.425 -When appropriate, Mercurial will store both snapshots and deltas in 11.426 -compressed form. It does this by always \emph{trying to} compress a 11.427 -snapshot or delta, but only storing the compressed version if it's 11.428 -smaller than the uncompressed version. 11.429 - 11.430 -This means that Mercurial does ``the right thing'' when storing a file 11.431 -whose native form is compressed, such as a \texttt{zip} archive or a 11.432 -JPEG image. When these types of files are compressed a second time, 11.433 -the resulting file is usually bigger than the once-compressed form, 11.434 -and so Mercurial will store the plain \texttt{zip} or JPEG. 11.435 - 11.436 -Deltas between revisions of a compressed file are usually larger than 11.437 -snapshots of the file, and Mercurial again does ``the right thing'' in 11.438 -these cases. It finds that such a delta exceeds the threshold at 11.439 -which it should store a complete snapshot of the file, so it stores 11.440 -the snapshot, again saving space compared to a naive delta-only 11.441 -approach. 11.442 - 11.443 -\subsubsection{Network recompression} 11.444 - 11.445 -When storing revisions on disk, Mercurial uses the ``deflate'' 11.446 -compression algorithm (the same one used by the popular \texttt{zip} 11.447 -archive format), which balances good speed with a respectable 11.448 -compression ratio. However, when transmitting revision data over a 11.449 -network connection, Mercurial uncompresses the compressed revision 11.450 -data. 11.451 - 11.452 -If the connection is over HTTP, Mercurial recompresses the entire 11.453 -stream of data using a compression algorithm that gives a better 11.454 -compression ratio (the Burrows-Wheeler algorithm from the widely used 11.455 -\texttt{bzip2} compression package). This combination of algorithm 11.456 -and compression of the entire stream (instead of a revision at a time) 11.457 -substantially reduces the number of bytes to be transferred, yielding 11.458 -better network performance over almost all kinds of network. 11.459 - 11.460 -(If the connection is over \command{ssh}, Mercurial \emph{doesn't} 11.461 -recompress the stream, because \command{ssh} can already do this 11.462 -itself.) 11.463 - 11.464 -\subsection{Read/write ordering and atomicity} 11.465 - 11.466 -Appending to files isn't the whole story when it comes to guaranteeing 11.467 -that a reader won't see a partial write. If you recall 11.468 -figure~\ref{fig:concepts:metadata}, revisions in the changelog point to 11.469 -revisions in the manifest, and revisions in the manifest point to 11.470 -revisions in filelogs. This hierarchy is deliberate. 11.471 - 11.472 -A writer starts a transaction by writing filelog and manifest data, 11.473 -and doesn't write any changelog data until those are finished. A 11.474 -reader starts by reading changelog data, then manifest data, followed 11.475 -by filelog data. 11.476 - 11.477 -Since the writer has always finished writing filelog and manifest data 11.478 -before it writes to the changelog, a reader will never read a pointer 11.479 -to a partially written manifest revision from the changelog, and it will 11.480 -never read a pointer to a partially written filelog revision from the 11.481 -manifest. 11.482 - 11.483 -\subsection{Concurrent access} 11.484 - 11.485 -The read/write ordering and atomicity guarantees mean that Mercurial 11.486 -never needs to \emph{lock} a repository when it's reading data, even 11.487 -if the repository is being written to while the read is occurring. 11.488 -This has a big effect on scalability; you can have an arbitrary number 11.489 -of Mercurial processes safely reading data from a repository safely 11.490 -all at once, no matter whether it's being written to or not. 11.491 - 11.492 -The lockless nature of reading means that if you're sharing a 11.493 -repository on a multi-user system, you don't need to grant other local 11.494 -users permission to \emph{write} to your repository in order for them 11.495 -to be able to clone it or pull changes from it; they only need 11.496 -\emph{read} permission. (This is \emph{not} a common feature among 11.497 -revision control systems, so don't take it for granted! Most require 11.498 -readers to be able to lock a repository to access it safely, and this 11.499 -requires write permission on at least one directory, which of course 11.500 -makes for all kinds of nasty and annoying security and administrative 11.501 -problems.) 11.502 - 11.503 -Mercurial uses locks to ensure that only one process can write to a 11.504 -repository at a time (the locking mechanism is safe even over 11.505 -filesystems that are notoriously hostile to locking, such as NFS). If 11.506 -a repository is locked, a writer will wait for a while to retry if the 11.507 -repository becomes unlocked, but if the repository remains locked for 11.508 -too long, the process attempting to write will time out after a while. 11.509 -This means that your daily automated scripts won't get stuck forever 11.510 -and pile up if a system crashes unnoticed, for example. (Yes, the 11.511 -timeout is configurable, from zero to infinity.) 11.512 - 11.513 -\subsubsection{Safe dirstate access} 11.514 - 11.515 -As with revision data, Mercurial doesn't take a lock to read the 11.516 -dirstate file; it does acquire a lock to write it. To avoid the 11.517 -possibility of reading a partially written copy of the dirstate file, 11.518 -Mercurial writes to a file with a unique name in the same directory as 11.519 -the dirstate file, then renames the temporary file atomically to 11.520 -\filename{dirstate}. The file named \filename{dirstate} is thus 11.521 -guaranteed to be complete, not partially written. 11.522 - 11.523 -\subsection{Avoiding seeks} 11.524 - 11.525 -Critical to Mercurial's performance is the avoidance of seeks of the 11.526 -disk head, since any seek is far more expensive than even a 11.527 -comparatively large read operation. 11.528 - 11.529 -This is why, for example, the dirstate is stored in a single file. If 11.530 -there were a dirstate file per directory that Mercurial tracked, the 11.531 -disk would seek once per directory. Instead, Mercurial reads the 11.532 -entire single dirstate file in one step. 11.533 - 11.534 -Mercurial also uses a ``copy on write'' scheme when cloning a 11.535 -repository on local storage. Instead of copying every revlog file 11.536 -from the old repository into the new repository, it makes a ``hard 11.537 -link'', which is a shorthand way to say ``these two names point to the 11.538 -same file''. When Mercurial is about to write to one of a revlog's 11.539 -files, it checks to see if the number of names pointing at the file is 11.540 -greater than one. If it is, more than one repository is using the 11.541 -file, so Mercurial makes a new copy of the file that is private to 11.542 -this repository. 11.543 - 11.544 -A few revision control developers have pointed out that this idea of 11.545 -making a complete private copy of a file is not very efficient in its 11.546 -use of storage. While this is true, storage is cheap, and this method 11.547 -gives the highest performance while deferring most book-keeping to the 11.548 -operating system. An alternative scheme would most likely reduce 11.549 -performance and increase the complexity of the software, each of which 11.550 -is much more important to the ``feel'' of day-to-day use. 11.551 - 11.552 -\subsection{Other contents of the dirstate} 11.553 - 11.554 -Because Mercurial doesn't force you to tell it when you're modifying a 11.555 -file, it uses the dirstate to store some extra information so it can 11.556 -determine efficiently whether you have modified a file. For each file 11.557 -in the working directory, it stores the time that it last modified the 11.558 -file itself, and the size of the file at that time. 11.559 - 11.560 -When you explicitly \hgcmd{add}, \hgcmd{remove}, \hgcmd{rename} or 11.561 -\hgcmd{copy} files, Mercurial updates the dirstate so that it knows 11.562 -what to do with those files when you commit. 11.563 - 11.564 -When Mercurial is checking the states of files in the working 11.565 -directory, it first checks a file's modification time. If that has 11.566 -not changed, the file must not have been modified. If the file's size 11.567 -has changed, the file must have been modified. If the modification 11.568 -time has changed, but the size has not, only then does Mercurial need 11.569 -to read the actual contents of the file to see if they've changed. 11.570 -Storing these few extra pieces of information dramatically reduces the 11.571 -amount of data that Mercurial needs to read, which yields large 11.572 -performance improvements compared to other revision control systems. 11.573 - 11.574 -%%% Local Variables: 11.575 -%%% mode: latex 11.576 -%%% TeX-master: "00book" 11.577 -%%% End:
12.1 --- a/en/ch05-daily.tex Thu Mar 05 21:52:23 2009 +0200 12.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 12.3 @@ -1,379 +0,0 @@ 12.4 -\chapter{Mercurial in daily use} 12.5 -\label{chap:daily} 12.6 - 12.7 -\section{Telling Mercurial which files to track} 12.8 - 12.9 -Mercurial does not work with files in your repository unless you tell 12.10 -it to manage them. The \hgcmd{status} command will tell you which 12.11 -files Mercurial doesn't know about; it uses a ``\texttt{?}'' to 12.12 -display such files. 12.13 - 12.14 -To tell Mercurial to track a file, use the \hgcmd{add} command. Once 12.15 -you have added a file, the entry in the output of \hgcmd{status} for 12.16 -that file changes from ``\texttt{?}'' to ``\texttt{A}''. 12.17 -\interaction{daily.files.add} 12.18 - 12.19 -After you run a \hgcmd{commit}, the files that you added before the 12.20 -commit will no longer be listed in the output of \hgcmd{status}. The 12.21 -reason for this is that \hgcmd{status} only tells you about 12.22 -``interesting'' files---those that you have modified or told Mercurial 12.23 -to do something with---by default. If you have a repository that 12.24 -contains thousands of files, you will rarely want to know about files 12.25 -that Mercurial is tracking, but that have not changed. (You can still 12.26 -get this information; we'll return to this later.) 12.27 - 12.28 -Once you add a file, Mercurial doesn't do anything with it 12.29 -immediately. Instead, it will take a snapshot of the file's state the 12.30 -next time you perform a commit. It will then continue to track the 12.31 -changes you make to the file every time you commit, until you remove 12.32 -the file. 12.33 - 12.34 -\subsection{Explicit versus implicit file naming} 12.35 - 12.36 -A useful behaviour that Mercurial has is that if you pass the name of 12.37 -a directory to a command, every Mercurial command will treat this as 12.38 -``I want to operate on every file in this directory and its 12.39 -subdirectories''. 12.40 -\interaction{daily.files.add-dir} 12.41 -Notice in this example that Mercurial printed the names of the files 12.42 -it added, whereas it didn't do so when we added the file named 12.43 -\filename{a} in the earlier example. 12.44 - 12.45 -What's going on is that in the former case, we explicitly named the 12.46 -file to add on the command line, so the assumption that Mercurial 12.47 -makes in such cases is that you know what you were doing, and it 12.48 -doesn't print any output. 12.49 - 12.50 -However, when we \emph{imply} the names of files by giving the name of 12.51 -a directory, Mercurial takes the extra step of printing the name of 12.52 -each file that it does something with. This makes it more clear what 12.53 -is happening, and reduces the likelihood of a silent and nasty 12.54 -surprise. This behaviour is common to most Mercurial commands. 12.55 - 12.56 -\subsection{Aside: Mercurial tracks files, not directories} 12.57 - 12.58 -Mercurial does not track directory information. Instead, it tracks 12.59 -the path to a file. Before creating a file, it first creates any 12.60 -missing directory components of the path. After it deletes a file, it 12.61 -then deletes any empty directories that were in the deleted file's 12.62 -path. This sounds like a trivial distinction, but it has one minor 12.63 -practical consequence: it is not possible to represent a completely 12.64 -empty directory in Mercurial. 12.65 - 12.66 -Empty directories are rarely useful, and there are unintrusive 12.67 -workarounds that you can use to achieve an appropriate effect. The 12.68 -developers of Mercurial thus felt that the complexity that would be 12.69 -required to manage empty directories was not worth the limited benefit 12.70 -this feature would bring. 12.71 - 12.72 -If you need an empty directory in your repository, there are a few 12.73 -ways to achieve this. One is to create a directory, then \hgcmd{add} a 12.74 -``hidden'' file to that directory. On Unix-like systems, any file 12.75 -name that begins with a period (``\texttt{.}'') is treated as hidden 12.76 -by most commands and GUI tools. This approach is illustrated in 12.77 -figure~\ref{ex:daily:hidden}. 12.78 - 12.79 -\begin{figure}[ht] 12.80 - \interaction{daily.files.hidden} 12.81 - \caption{Simulating an empty directory using a hidden file} 12.82 - \label{ex:daily:hidden} 12.83 -\end{figure} 12.84 - 12.85 -Another way to tackle a need for an empty directory is to simply 12.86 -create one in your automated build scripts before they will need it. 12.87 - 12.88 -\section{How to stop tracking a file} 12.89 - 12.90 -Once you decide that a file no longer belongs in your repository, use 12.91 -the \hgcmd{remove} command; this deletes the file, and tells Mercurial 12.92 -to stop tracking it. A removed file is represented in the output of 12.93 -\hgcmd{status} with a ``\texttt{R}''. 12.94 -\interaction{daily.files.remove} 12.95 - 12.96 -After you \hgcmd{remove} a file, Mercurial will no longer track 12.97 -changes to that file, even if you recreate a file with the same name 12.98 -in your working directory. If you do recreate a file with the same 12.99 -name and want Mercurial to track the new file, simply \hgcmd{add} it. 12.100 -Mercurial will know that the newly added file is not related to the 12.101 -old file of the same name. 12.102 - 12.103 -\subsection{Removing a file does not affect its history} 12.104 - 12.105 -It is important to understand that removing a file has only two 12.106 -effects. 12.107 -\begin{itemize} 12.108 -\item It removes the current version of the file from the working 12.109 - directory. 12.110 -\item It stops Mercurial from tracking changes to the file, from the 12.111 - time of the next commit. 12.112 -\end{itemize} 12.113 -Removing a file \emph{does not} in any way alter the \emph{history} of 12.114 -the file. 12.115 - 12.116 -If you update the working directory to a changeset in which a file 12.117 -that you have removed was still tracked, it will reappear in the 12.118 -working directory, with the contents it had when you committed that 12.119 -changeset. If you then update the working directory to a later 12.120 -changeset, in which the file had been removed, Mercurial will once 12.121 -again remove the file from the working directory. 12.122 - 12.123 -\subsection{Missing files} 12.124 - 12.125 -Mercurial considers a file that you have deleted, but not used 12.126 -\hgcmd{remove} to delete, to be \emph{missing}. A missing file is 12.127 -represented with ``\texttt{!}'' in the output of \hgcmd{status}. 12.128 -Mercurial commands will not generally do anything with missing files. 12.129 -\interaction{daily.files.missing} 12.130 - 12.131 -If your repository contains a file that \hgcmd{status} reports as 12.132 -missing, and you want the file to stay gone, you can run 12.133 -\hgcmdargs{remove}{\hgopt{remove}{--after}} at any time later on, to 12.134 -tell Mercurial that you really did mean to remove the file. 12.135 -\interaction{daily.files.remove-after} 12.136 - 12.137 -On the other hand, if you deleted the missing file by accident, use 12.138 -\hgcmdargs{revert}{\emph{filename}} to recover the file. It will 12.139 -reappear, in unmodified form. 12.140 -\interaction{daily.files.recover-missing} 12.141 - 12.142 -\subsection{Aside: why tell Mercurial explicitly to remove a file?} 12.143 - 12.144 -You might wonder why Mercurial requires you to explicitly tell it that 12.145 -you are deleting a file. Early during the development of Mercurial, 12.146 -it let you delete a file however you pleased; Mercurial would notice 12.147 -the absence of the file automatically when you next ran a 12.148 -\hgcmd{commit}, and stop tracking the file. In practice, this made it 12.149 -too easy to accidentally remove a file without noticing. 12.150 - 12.151 -\subsection{Useful shorthand---adding and removing files in one step} 12.152 - 12.153 -Mercurial offers a combination command, \hgcmd{addremove}, that adds 12.154 -untracked files and marks missing files as removed. 12.155 -\interaction{daily.files.addremove} 12.156 -The \hgcmd{commit} command also provides a \hgopt{commit}{-A} option 12.157 -that performs this same add-and-remove, immediately followed by a 12.158 -commit. 12.159 -\interaction{daily.files.commit-addremove} 12.160 - 12.161 -\section{Copying files} 12.162 - 12.163 -Mercurial provides a \hgcmd{copy} command that lets you make a new 12.164 -copy of a file. When you copy a file using this command, Mercurial 12.165 -makes a record of the fact that the new file is a copy of the original 12.166 -file. It treats these copied files specially when you merge your work 12.167 -with someone else's. 12.168 - 12.169 -\subsection{The results of copying during a merge} 12.170 - 12.171 -What happens during a merge is that changes ``follow'' a copy. To 12.172 -best illustrate what this means, let's create an example. We'll start 12.173 -with the usual tiny repository that contains a single file. 12.174 -\interaction{daily.copy.init} 12.175 -We need to do some work in parallel, so that we'll have something to 12.176 -merge. So let's clone our repository. 12.177 -\interaction{daily.copy.clone} 12.178 -Back in our initial repository, let's use the \hgcmd{copy} command to 12.179 -make a copy of the first file we created. 12.180 -\interaction{daily.copy.copy} 12.181 - 12.182 -If we look at the output of the \hgcmd{status} command afterwards, the 12.183 -copied file looks just like a normal added file. 12.184 -\interaction{daily.copy.status} 12.185 -But if we pass the \hgopt{status}{-C} option to \hgcmd{status}, it 12.186 -prints another line of output: this is the file that our newly-added 12.187 -file was copied \emph{from}. 12.188 -\interaction{daily.copy.status-copy} 12.189 - 12.190 -Now, back in the repository we cloned, let's make a change in 12.191 -parallel. We'll add a line of content to the original file that we 12.192 -created. 12.193 -\interaction{daily.copy.other} 12.194 -Now we have a modified \filename{file} in this repository. When we 12.195 -pull the changes from the first repository, and merge the two heads, 12.196 -Mercurial will propagate the changes that we made locally to 12.197 -\filename{file} into its copy, \filename{new-file}. 12.198 -\interaction{daily.copy.merge} 12.199 - 12.200 -\subsection{Why should changes follow copies?} 12.201 -\label{sec:daily:why-copy} 12.202 - 12.203 -This behaviour, of changes to a file propagating out to copies of the 12.204 -file, might seem esoteric, but in most cases it's highly desirable. 12.205 - 12.206 -First of all, remember that this propagation \emph{only} happens when 12.207 -you merge. So if you \hgcmd{copy} a file, and subsequently modify the 12.208 -original file during the normal course of your work, nothing will 12.209 -happen. 12.210 - 12.211 -The second thing to know is that modifications will only propagate 12.212 -across a copy as long as the repository that you're pulling changes 12.213 -from \emph{doesn't know} about the copy. 12.214 - 12.215 -The reason that Mercurial does this is as follows. Let's say I make 12.216 -an important bug fix in a source file, and commit my changes. 12.217 -Meanwhile, you've decided to \hgcmd{copy} the file in your repository, 12.218 -without knowing about the bug or having seen the fix, and you have 12.219 -started hacking on your copy of the file. 12.220 - 12.221 -If you pulled and merged my changes, and Mercurial \emph{didn't} 12.222 -propagate changes across copies, your source file would now contain 12.223 -the bug, and unless you remembered to propagate the bug fix by hand, 12.224 -the bug would \emph{remain} in your copy of the file. 12.225 - 12.226 -By automatically propagating the change that fixed the bug from the 12.227 -original file to the copy, Mercurial prevents this class of problem. 12.228 -To my knowledge, Mercurial is the \emph{only} revision control system 12.229 -that propagates changes across copies like this. 12.230 - 12.231 -Once your change history has a record that the copy and subsequent 12.232 -merge occurred, there's usually no further need to propagate changes 12.233 -from the original file to the copied file, and that's why Mercurial 12.234 -only propagates changes across copies until this point, and no 12.235 -further. 12.236 - 12.237 -\subsection{How to make changes \emph{not} follow a copy} 12.238 - 12.239 -If, for some reason, you decide that this business of automatically 12.240 -propagating changes across copies is not for you, simply use your 12.241 -system's normal file copy command (on Unix-like systems, that's 12.242 -\command{cp}) to make a copy of a file, then \hgcmd{add} the new copy 12.243 -by hand. Before you do so, though, please do reread 12.244 -section~\ref{sec:daily:why-copy}, and make an informed decision that 12.245 -this behaviour is not appropriate to your specific case. 12.246 - 12.247 -\subsection{Behaviour of the \hgcmd{copy} command} 12.248 - 12.249 -When you use the \hgcmd{copy} command, Mercurial makes a copy of each 12.250 -source file as it currently stands in the working directory. This 12.251 -means that if you make some modifications to a file, then \hgcmd{copy} 12.252 -it without first having committed those changes, the new copy will 12.253 -also contain the modifications you have made up until that point. (I 12.254 -find this behaviour a little counterintuitive, which is why I mention 12.255 -it here.) 12.256 - 12.257 -The \hgcmd{copy} command acts similarly to the Unix \command{cp} 12.258 -command (you can use the \hgcmd{cp} alias if you prefer). The last 12.259 -argument is the \emph{destination}, and all prior arguments are 12.260 -\emph{sources}. If you pass it a single file as the source, and the 12.261 -destination does not exist, it creates a new file with that name. 12.262 -\interaction{daily.copy.simple} 12.263 -If the destination is a directory, Mercurial copies its sources into 12.264 -that directory. 12.265 -\interaction{daily.copy.dir-dest} 12.266 -Copying a directory is recursive, and preserves the directory 12.267 -structure of the source. 12.268 -\interaction{daily.copy.dir-src} 12.269 -If the source and destination are both directories, the source tree is 12.270 -recreated in the destination directory. 12.271 -\interaction{daily.copy.dir-src-dest} 12.272 - 12.273 -As with the \hgcmd{rename} command, if you copy a file manually and 12.274 -then want Mercurial to know that you've copied the file, simply use 12.275 -the \hgopt{copy}{--after} option to \hgcmd{copy}. 12.276 -\interaction{daily.copy.after} 12.277 - 12.278 -\section{Renaming files} 12.279 - 12.280 -It's rather more common to need to rename a file than to make a copy 12.281 -of it. The reason I discussed the \hgcmd{copy} command before talking 12.282 -about renaming files is that Mercurial treats a rename in essentially 12.283 -the same way as a copy. Therefore, knowing what Mercurial does when 12.284 -you copy a file tells you what to expect when you rename a file. 12.285 - 12.286 -When you use the \hgcmd{rename} command, Mercurial makes a copy of 12.287 -each source file, then deletes it and marks the file as removed. 12.288 -\interaction{daily.rename.rename} 12.289 -The \hgcmd{status} command shows the newly copied file as added, and 12.290 -the copied-from file as removed. 12.291 -\interaction{daily.rename.status} 12.292 -As with the results of a \hgcmd{copy}, we must use the 12.293 -\hgopt{status}{-C} option to \hgcmd{status} to see that the added file 12.294 -is really being tracked by Mercurial as a copy of the original, now 12.295 -removed, file. 12.296 -\interaction{daily.rename.status-copy} 12.297 - 12.298 -As with \hgcmd{remove} and \hgcmd{copy}, you can tell Mercurial about 12.299 -a rename after the fact using the \hgopt{rename}{--after} option. In 12.300 -most other respects, the behaviour of the \hgcmd{rename} command, and 12.301 -the options it accepts, are similar to the \hgcmd{copy} command. 12.302 - 12.303 -\subsection{Renaming files and merging changes} 12.304 - 12.305 -Since Mercurial's rename is implemented as copy-and-remove, the same 12.306 -propagation of changes happens when you merge after a rename as after 12.307 -a copy. 12.308 - 12.309 -If I modify a file, and you rename it to a new name, and then we merge 12.310 -our respective changes, my modifications to the file under its 12.311 -original name will be propagated into the file under its new name. 12.312 -(This is something you might expect to ``simply work,'' but not all 12.313 -revision control systems actually do this.) 12.314 - 12.315 -Whereas having changes follow a copy is a feature where you can 12.316 -perhaps nod and say ``yes, that might be useful,'' it should be clear 12.317 -that having them follow a rename is definitely important. Without 12.318 -this facility, it would simply be too easy for changes to become 12.319 -orphaned when files are renamed. 12.320 - 12.321 -\subsection{Divergent renames and merging} 12.322 - 12.323 -The case of diverging names occurs when two developers start with a 12.324 -file---let's call it \filename{foo}---in their respective 12.325 -repositories. 12.326 - 12.327 -\interaction{rename.divergent.clone} 12.328 -Anne renames the file to \filename{bar}. 12.329 -\interaction{rename.divergent.rename.anne} 12.330 -Meanwhile, Bob renames it to \filename{quux}. 12.331 -\interaction{rename.divergent.rename.bob} 12.332 - 12.333 -I like to think of this as a conflict because each developer has 12.334 -expressed different intentions about what the file ought to be named. 12.335 - 12.336 -What do you think should happen when they merge their work? 12.337 -Mercurial's actual behaviour is that it always preserves \emph{both} 12.338 -names when it merges changesets that contain divergent renames. 12.339 -\interaction{rename.divergent.merge} 12.340 - 12.341 -Notice that Mercurial does warn about the divergent renames, but it 12.342 -leaves it up to you to do something about the divergence after the merge. 12.343 - 12.344 -\subsection{Convergent renames and merging} 12.345 - 12.346 -Another kind of rename conflict occurs when two people choose to 12.347 -rename different \emph{source} files to the same \emph{destination}. 12.348 -In this case, Mercurial runs its normal merge machinery, and lets you 12.349 -guide it to a suitable resolution. 12.350 - 12.351 -\subsection{Other name-related corner cases} 12.352 - 12.353 -Mercurial has a longstanding bug in which it fails to handle a merge 12.354 -where one side has a file with a given name, while another has a 12.355 -directory with the same name. This is documented as~\bug{29}. 12.356 -\interaction{issue29.go} 12.357 - 12.358 -\section{Recovering from mistakes} 12.359 - 12.360 -Mercurial has some useful commands that will help you to recover from 12.361 -some common mistakes. 12.362 - 12.363 -The \hgcmd{revert} command lets you undo changes that you have made to 12.364 -your working directory. For example, if you \hgcmd{add} a file by 12.365 -accident, just run \hgcmd{revert} with the name of the file you added, 12.366 -and while the file won't be touched in any way, it won't be tracked 12.367 -for adding by Mercurial any longer, either. You can also use 12.368 -\hgcmd{revert} to get rid of erroneous changes to a file. 12.369 - 12.370 -It's useful to remember that the \hgcmd{revert} command is useful for 12.371 -changes that you have not yet committed. Once you've committed a 12.372 -change, if you decide it was a mistake, you can still do something 12.373 -about it, though your options may be more limited. 12.374 - 12.375 -For more information about the \hgcmd{revert} command, and details 12.376 -about how to deal with changes you have already committed, see 12.377 -chapter~\ref{chap:undo}. 12.378 - 12.379 -%%% Local Variables: 12.380 -%%% mode: latex 12.381 -%%% TeX-master: "00book" 12.382 -%%% End:
13.1 --- a/en/ch06-collab.tex Thu Mar 05 21:52:23 2009 +0200 13.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 13.3 @@ -1,1117 +0,0 @@ 13.4 -\chapter{Collaborating with other people} 13.5 -\label{cha:collab} 13.6 - 13.7 -As a completely decentralised tool, Mercurial doesn't impose any 13.8 -policy on how people ought to work with each other. However, if 13.9 -you're new to distributed revision control, it helps to have some 13.10 -tools and examples in mind when you're thinking about possible 13.11 -workflow models. 13.12 - 13.13 -\section{Mercurial's web interface} 13.14 - 13.15 -Mercurial has a powerful web interface that provides several 13.16 -useful capabilities. 13.17 - 13.18 -For interactive use, the web interface lets you browse a single 13.19 -repository or a collection of repositories. You can view the history 13.20 -of a repository, examine each change (comments and diffs), and view 13.21 -the contents of each directory and file. 13.22 - 13.23 -Also for human consumption, the web interface provides an RSS feed of 13.24 -the changes in a repository. This lets you ``subscribe'' to a 13.25 -repository using your favourite feed reader, and be automatically 13.26 -notified of activity in that repository as soon as it happens. I find 13.27 -this capability much more convenient than the model of subscribing to 13.28 -a mailing list to which notifications are sent, as it requires no 13.29 -additional configuration on the part of whoever is serving the 13.30 -repository. 13.31 - 13.32 -The web interface also lets remote users clone a repository, pull 13.33 -changes from it, and (when the server is configured to permit it) push 13.34 -changes back to it. Mercurial's HTTP tunneling protocol aggressively 13.35 -compresses data, so that it works efficiently even over low-bandwidth 13.36 -network connections. 13.37 - 13.38 -The easiest way to get started with the web interface is to use your 13.39 -web browser to visit an existing repository, such as the master 13.40 -Mercurial repository at 13.41 -\url{http://www.selenic.com/repo/hg?style=gitweb}. 13.42 - 13.43 -If you're interested in providing a web interface to your own 13.44 -repositories, Mercurial provides two ways to do this. The first is 13.45 -using the \hgcmd{serve} command, which is best suited to short-term 13.46 -``lightweight'' serving. See section~\ref{sec:collab:serve} below for 13.47 -details of how to use this command. If you have a long-lived 13.48 -repository that you'd like to make permanently available, Mercurial 13.49 -has built-in support for the CGI (Common Gateway Interface) standard, 13.50 -which all common web servers support. See 13.51 -section~\ref{sec:collab:cgi} for details of CGI configuration. 13.52 - 13.53 -\section{Collaboration models} 13.54 - 13.55 -With a suitably flexible tool, making decisions about workflow is much 13.56 -more of a social engineering challenge than a technical one. 13.57 -Mercurial imposes few limitations on how you can structure the flow of 13.58 -work in a project, so it's up to you and your group to set up and live 13.59 -with a model that matches your own particular needs. 13.60 - 13.61 -\subsection{Factors to keep in mind} 13.62 - 13.63 -The most important aspect of any model that you must keep in mind is 13.64 -how well it matches the needs and capabilities of the people who will 13.65 -be using it. This might seem self-evident; even so, you still can't 13.66 -afford to forget it for a moment. 13.67 - 13.68 -I once put together a workflow model that seemed to make perfect sense 13.69 -to me, but that caused a considerable amount of consternation and 13.70 -strife within my development team. In spite of my attempts to explain 13.71 -why we needed a complex set of branches, and how changes ought to flow 13.72 -between them, a few team members revolted. Even though they were 13.73 -smart people, they didn't want to pay attention to the constraints we 13.74 -were operating under, or face the consequences of those constraints in 13.75 -the details of the model that I was advocating. 13.76 - 13.77 -Don't sweep foreseeable social or technical problems under the rug. 13.78 -Whatever scheme you put into effect, you should plan for mistakes and 13.79 -problem scenarios. Consider adding automated machinery to prevent, or 13.80 -quickly recover from, trouble that you can anticipate. As an example, 13.81 -if you intend to have a branch with not-for-release changes in it, 13.82 -you'd do well to think early about the possibility that someone might 13.83 -accidentally merge those changes into a release branch. You could 13.84 -avoid this particular problem by writing a hook that prevents changes 13.85 -from being merged from an inappropriate branch. 13.86 - 13.87 -\subsection{Informal anarchy} 13.88 - 13.89 -I wouldn't suggest an ``anything goes'' approach as something 13.90 -sustainable, but it's a model that's easy to grasp, and it works 13.91 -perfectly well in a few unusual situations. 13.92 - 13.93 -As one example, many projects have a loose-knit group of collaborators 13.94 -who rarely physically meet each other. Some groups like to overcome 13.95 -the isolation of working at a distance by organising occasional 13.96 -``sprints''. In a sprint, a number of people get together in a single 13.97 -location (a company's conference room, a hotel meeting room, that kind 13.98 -of place) and spend several days more or less locked in there, hacking 13.99 -intensely on a handful of projects. 13.100 - 13.101 -A sprint is the perfect place to use the \hgcmd{serve} command, since 13.102 -\hgcmd{serve} does not require any fancy server infrastructure. You 13.103 -can get started with \hgcmd{serve} in moments, by reading 13.104 -section~\ref{sec:collab:serve} below. Then simply tell the person 13.105 -next to you that you're running a server, send the URL to them in an 13.106 -instant message, and you immediately have a quick-turnaround way to 13.107 -work together. They can type your URL into their web browser and 13.108 -quickly review your changes; or they can pull a bugfix from you and 13.109 -verify it; or they can clone a branch containing a new feature and try 13.110 -it out. 13.111 - 13.112 -The charm, and the problem, with doing things in an ad hoc fashion 13.113 -like this is that only people who know about your changes, and where 13.114 -they are, can see them. Such an informal approach simply doesn't 13.115 -scale beyond a handful people, because each individual needs to know 13.116 -about $n$ different repositories to pull from. 13.117 - 13.118 -\subsection{A single central repository} 13.119 - 13.120 -For smaller projects migrating from a centralised revision control 13.121 -tool, perhaps the easiest way to get started is to have changes flow 13.122 -through a single shared central repository. This is also the 13.123 -most common ``building block'' for more ambitious workflow schemes. 13.124 - 13.125 -Contributors start by cloning a copy of this repository. They can 13.126 -pull changes from it whenever they need to, and some (perhaps all) 13.127 -developers have permission to push a change back when they're ready 13.128 -for other people to see it. 13.129 - 13.130 -Under this model, it can still often make sense for people to pull 13.131 -changes directly from each other, without going through the central 13.132 -repository. Consider a case in which I have a tentative bug fix, but 13.133 -I am worried that if I were to publish it to the central repository, 13.134 -it might subsequently break everyone else's trees as they pull it. To 13.135 -reduce the potential for damage, I can ask you to clone my repository 13.136 -into a temporary repository of your own and test it. This lets us put 13.137 -off publishing the potentially unsafe change until it has had a little 13.138 -testing. 13.139 - 13.140 -In this kind of scenario, people usually use the \command{ssh} 13.141 -protocol to securely push changes to the central repository, as 13.142 -documented in section~\ref{sec:collab:ssh}. It's also usual to 13.143 -publish a read-only copy of the repository over HTTP using CGI, as in 13.144 -section~\ref{sec:collab:cgi}. Publishing over HTTP satisfies the 13.145 -needs of people who don't have push access, and those who want to use 13.146 -web browsers to browse the repository's history. 13.147 - 13.148 -\subsection{Working with multiple branches} 13.149 - 13.150 -Projects of any significant size naturally tend to make progress on 13.151 -several fronts simultaneously. In the case of software, it's common 13.152 -for a project to go through periodic official releases. A release 13.153 -might then go into ``maintenance mode'' for a while after its first 13.154 -publication; maintenance releases tend to contain only bug fixes, not 13.155 -new features. In parallel with these maintenance releases, one or 13.156 -more future releases may be under development. People normally use 13.157 -the word ``branch'' to refer to one of these many slightly different 13.158 -directions in which development is proceeding. 13.159 - 13.160 -Mercurial is particularly well suited to managing a number of 13.161 -simultaneous, but not identical, branches. Each ``development 13.162 -direction'' can live in its own central repository, and you can merge 13.163 -changes from one to another as the need arises. Because repositories 13.164 -are independent of each other, unstable changes in a development 13.165 -branch will never affect a stable branch unless someone explicitly 13.166 -merges those changes in. 13.167 - 13.168 -Here's an example of how this can work in practice. Let's say you 13.169 -have one ``main branch'' on a central server. 13.170 -\interaction{branching.init} 13.171 -People clone it, make changes locally, test them, and push them back. 13.172 - 13.173 -Once the main branch reaches a release milestone, you can use the 13.174 -\hgcmd{tag} command to give a permanent name to the milestone 13.175 -revision. 13.176 -\interaction{branching.tag} 13.177 -Let's say some ongoing development occurs on the main branch. 13.178 -\interaction{branching.main} 13.179 -Using the tag that was recorded at the milestone, people who clone 13.180 -that repository at any time in the future can use \hgcmd{update} to 13.181 -get a copy of the working directory exactly as it was when that tagged 13.182 -revision was committed. 13.183 -\interaction{branching.update} 13.184 - 13.185 -In addition, immediately after the main branch is tagged, someone can 13.186 -then clone the main branch on the server to a new ``stable'' branch, 13.187 -also on the server. 13.188 -\interaction{branching.clone} 13.189 - 13.190 -Someone who needs to make a change to the stable branch can then clone 13.191 -\emph{that} repository, make their changes, commit, and push their 13.192 -changes back there. 13.193 -\interaction{branching.stable} 13.194 -Because Mercurial repositories are independent, and Mercurial doesn't 13.195 -move changes around automatically, the stable and main branches are 13.196 -\emph{isolated} from each other. The changes that you made on the 13.197 -main branch don't ``leak'' to the stable branch, and vice versa. 13.198 - 13.199 -You'll often want all of your bugfixes on the stable branch to show up 13.200 -on the main branch, too. Rather than rewrite a bugfix on the main 13.201 -branch, you can simply pull and merge changes from the stable to the 13.202 -main branch, and Mercurial will bring those bugfixes in for you. 13.203 -\interaction{branching.merge} 13.204 -The main branch will still contain changes that are not on the stable 13.205 -branch, but it will also contain all of the bugfixes from the stable 13.206 -branch. The stable branch remains unaffected by these changes. 13.207 - 13.208 -\subsection{Feature branches} 13.209 - 13.210 -For larger projects, an effective way to manage change is to break up 13.211 -a team into smaller groups. Each group has a shared branch of its 13.212 -own, cloned from a single ``master'' branch used by the entire 13.213 -project. People working on an individual branch are typically quite 13.214 -isolated from developments on other branches. 13.215 - 13.216 -\begin{figure}[ht] 13.217 - \centering 13.218 - \grafix{feature-branches} 13.219 - \caption{Feature branches} 13.220 - \label{fig:collab:feature-branches} 13.221 -\end{figure} 13.222 - 13.223 -When a particular feature is deemed to be in suitable shape, someone 13.224 -on that feature team pulls and merges from the master branch into the 13.225 -feature branch, then pushes back up to the master branch. 13.226 - 13.227 -\subsection{The release train} 13.228 - 13.229 -Some projects are organised on a ``train'' basis: a release is 13.230 -scheduled to happen every few months, and whatever features are ready 13.231 -when the ``train'' is ready to leave are allowed in. 13.232 - 13.233 -This model resembles working with feature branches. The difference is 13.234 -that when a feature branch misses a train, someone on the feature team 13.235 -pulls and merges the changes that went out on that train release into 13.236 -the feature branch, and the team continues its work on top of that 13.237 -release so that their feature can make the next release. 13.238 - 13.239 -\subsection{The Linux kernel model} 13.240 - 13.241 -The development of the Linux kernel has a shallow hierarchical 13.242 -structure, surrounded by a cloud of apparent chaos. Because most 13.243 -Linux developers use \command{git}, a distributed revision control 13.244 -tool with capabilities similar to Mercurial, it's useful to describe 13.245 -the way work flows in that environment; if you like the ideas, the 13.246 -approach translates well across tools. 13.247 - 13.248 -At the center of the community sits Linus Torvalds, the creator of 13.249 -Linux. He publishes a single source repository that is considered the 13.250 -``authoritative'' current tree by the entire developer community. 13.251 -Anyone can clone Linus's tree, but he is very choosy about whose trees 13.252 -he pulls from. 13.253 - 13.254 -Linus has a number of ``trusted lieutenants''. As a general rule, he 13.255 -pulls whatever changes they publish, in most cases without even 13.256 -reviewing those changes. Some of those lieutenants are generally 13.257 -agreed to be ``maintainers'', responsible for specific subsystems 13.258 -within the kernel. If a random kernel hacker wants to make a change 13.259 -to a subsystem that they want to end up in Linus's tree, they must 13.260 -find out who the subsystem's maintainer is, and ask that maintainer to 13.261 -take their change. If the maintainer reviews their changes and agrees 13.262 -to take them, they'll pass them along to Linus in due course. 13.263 - 13.264 -Individual lieutenants have their own approaches to reviewing, 13.265 -accepting, and publishing changes; and for deciding when to feed them 13.266 -to Linus. In addition, there are several well known branches that 13.267 -people use for different purposes. For example, a few people maintain 13.268 -``stable'' repositories of older versions of the kernel, to which they 13.269 -apply critical fixes as needed. Some maintainers publish multiple 13.270 -trees: one for experimental changes; one for changes that they are 13.271 -about to feed upstream; and so on. Others just publish a single 13.272 -tree. 13.273 - 13.274 -This model has two notable features. The first is that it's ``pull 13.275 -only''. You have to ask, convince, or beg another developer to take a 13.276 -change from you, because there are almost no trees to which more than 13.277 -one person can push, and there's no way to push changes into a tree 13.278 -that someone else controls. 13.279 - 13.280 -The second is that it's based on reputation and acclaim. If you're an 13.281 -unknown, Linus will probably ignore changes from you without even 13.282 -responding. But a subsystem maintainer will probably review them, and 13.283 -will likely take them if they pass their criteria for suitability. 13.284 -The more ``good'' changes you contribute to a maintainer, the more 13.285 -likely they are to trust your judgment and accept your changes. If 13.286 -you're well-known and maintain a long-lived branch for something Linus 13.287 -hasn't yet accepted, people with similar interests may pull your 13.288 -changes regularly to keep up with your work. 13.289 - 13.290 -Reputation and acclaim don't necessarily cross subsystem or ``people'' 13.291 -boundaries. If you're a respected but specialised storage hacker, and 13.292 -you try to fix a networking bug, that change will receive a level of 13.293 -scrutiny from a network maintainer comparable to a change from a 13.294 -complete stranger. 13.295 - 13.296 -To people who come from more orderly project backgrounds, the 13.297 -comparatively chaotic Linux kernel development process often seems 13.298 -completely insane. It's subject to the whims of individuals; people 13.299 -make sweeping changes whenever they deem it appropriate; and the pace 13.300 -of development is astounding. And yet Linux is a highly successful, 13.301 -well-regarded piece of software. 13.302 - 13.303 -\subsection{Pull-only versus shared-push collaboration} 13.304 - 13.305 -A perpetual source of heat in the open source community is whether a 13.306 -development model in which people only ever pull changes from others 13.307 -is ``better than'' one in which multiple people can push changes to a 13.308 -shared repository. 13.309 - 13.310 -Typically, the backers of the shared-push model use tools that 13.311 -actively enforce this approach. If you're using a centralised 13.312 -revision control tool such as Subversion, there's no way to make a 13.313 -choice over which model you'll use: the tool gives you shared-push, 13.314 -and if you want to do anything else, you'll have to roll your own 13.315 -approach on top (such as applying a patch by hand). 13.316 - 13.317 -A good distributed revision control tool, such as Mercurial, will 13.318 -support both models. You and your collaborators can then structure 13.319 -how you work together based on your own needs and preferences, not on 13.320 -what contortions your tools force you into. 13.321 - 13.322 -\subsection{Where collaboration meets branch management} 13.323 - 13.324 -Once you and your team set up some shared repositories and start 13.325 -propagating changes back and forth between local and shared repos, you 13.326 -begin to face a related, but slightly different challenge: that of 13.327 -managing the multiple directions in which your team may be moving at 13.328 -once. Even though this subject is intimately related to how your team 13.329 -collaborates, it's dense enough to merit treatment of its own, in 13.330 -chapter~\ref{chap:branch}. 13.331 - 13.332 -\section{The technical side of sharing} 13.333 - 13.334 -The remainder of this chapter is devoted to the question of serving 13.335 -data to your collaborators. 13.336 - 13.337 -\section{Informal sharing with \hgcmd{serve}} 13.338 -\label{sec:collab:serve} 13.339 - 13.340 -Mercurial's \hgcmd{serve} command is wonderfully suited to small, 13.341 -tight-knit, and fast-paced group environments. It also provides a 13.342 -great way to get a feel for using Mercurial commands over a network. 13.343 - 13.344 -Run \hgcmd{serve} inside a repository, and in under a second it will 13.345 -bring up a specialised HTTP server; this will accept connections from 13.346 -any client, and serve up data for that repository until you terminate 13.347 -it. Anyone who knows the URL of the server you just started, and can 13.348 -talk to your computer over the network, can then use a web browser or 13.349 -Mercurial to read data from that repository. A URL for a 13.350 -\hgcmd{serve} instance running on a laptop is likely to look something 13.351 -like \Verb|http://my-laptop.local:8000/|. 13.352 - 13.353 -The \hgcmd{serve} command is \emph{not} a general-purpose web server. 13.354 -It can do only two things: 13.355 -\begin{itemize} 13.356 -\item Allow people to browse the history of the repository it's 13.357 - serving, from their normal web browsers. 13.358 -\item Speak Mercurial's wire protocol, so that people can 13.359 - \hgcmd{clone} or \hgcmd{pull} changes from that repository. 13.360 -\end{itemize} 13.361 -In particular, \hgcmd{serve} won't allow remote users to \emph{modify} 13.362 -your repository. It's intended for read-only use. 13.363 - 13.364 -If you're getting started with Mercurial, there's nothing to prevent 13.365 -you from using \hgcmd{serve} to serve up a repository on your own 13.366 -computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and 13.367 -so on to talk to that server as if the repository was hosted remotely. 13.368 -This can help you to quickly get acquainted with using commands on 13.369 -network-hosted repositories. 13.370 - 13.371 -\subsection{A few things to keep in mind} 13.372 - 13.373 -Because it provides unauthenticated read access to all clients, you 13.374 -should only use \hgcmd{serve} in an environment where you either don't 13.375 -care, or have complete control over, who can access your network and 13.376 -pull data from your repository. 13.377 - 13.378 -The \hgcmd{serve} command knows nothing about any firewall software 13.379 -you might have installed on your system or network. It cannot detect 13.380 -or control your firewall software. If other people are unable to talk 13.381 -to a running \hgcmd{serve} instance, the second thing you should do 13.382 -(\emph{after} you make sure that they're using the correct URL) is 13.383 -check your firewall configuration. 13.384 - 13.385 -By default, \hgcmd{serve} listens for incoming connections on 13.386 -port~8000. If another process is already listening on the port you 13.387 -want to use, you can specify a different port to listen on using the 13.388 -\hgopt{serve}{-p} option. 13.389 - 13.390 -Normally, when \hgcmd{serve} starts, it prints no output, which can be 13.391 -a bit unnerving. If you'd like to confirm that it is indeed running 13.392 -correctly, and find out what URL you should send to your 13.393 -collaborators, start it with the \hggopt{-v} option. 13.394 - 13.395 -\section{Using the Secure Shell (ssh) protocol} 13.396 -\label{sec:collab:ssh} 13.397 - 13.398 -You can pull and push changes securely over a network connection using 13.399 -the Secure Shell (\texttt{ssh}) protocol. To use this successfully, 13.400 -you may have to do a little bit of configuration on the client or 13.401 -server sides. 13.402 - 13.403 -If you're not familiar with ssh, it's a network protocol that lets you 13.404 -securely communicate with another computer. To use it with Mercurial, 13.405 -you'll be setting up one or more user accounts on a server so that 13.406 -remote users can log in and execute commands. 13.407 - 13.408 -(If you \emph{are} familiar with ssh, you'll probably find some of the 13.409 -material that follows to be elementary in nature.) 13.410 - 13.411 -\subsection{How to read and write ssh URLs} 13.412 - 13.413 -An ssh URL tends to look like this: 13.414 -\begin{codesample2} 13.415 - ssh://bos@hg.serpentine.com:22/hg/hgbook 13.416 -\end{codesample2} 13.417 -\begin{enumerate} 13.418 -\item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh 13.419 - protocol. 13.420 -\item The ``\texttt{bos@}'' component indicates what username to log 13.421 - into the server as. You can leave this out if the remote username 13.422 - is the same as your local username. 13.423 -\item The ``\texttt{hg.serpentine.com}'' gives the hostname of the 13.424 - server to log into. 13.425 -\item The ``:22'' identifies the port number to connect to the server 13.426 - on. The default port is~22, so you only need to specify this part 13.427 - if you're \emph{not} using port~22. 13.428 -\item The remainder of the URL is the local path to the repository on 13.429 - the server. 13.430 -\end{enumerate} 13.431 - 13.432 -There's plenty of scope for confusion with the path component of ssh 13.433 -URLs, as there is no standard way for tools to interpret it. Some 13.434 -programs behave differently than others when dealing with these paths. 13.435 -This isn't an ideal situation, but it's unlikely to change. Please 13.436 -read the following paragraphs carefully. 13.437 - 13.438 -Mercurial treats the path to a repository on the server as relative to 13.439 -the remote user's home directory. For example, if user \texttt{foo} 13.440 -on the server has a home directory of \dirname{/home/foo}, then an ssh 13.441 -URL that contains a path component of \dirname{bar} 13.442 -\emph{really} refers to the directory \dirname{/home/foo/bar}. 13.443 - 13.444 -If you want to specify a path relative to another user's home 13.445 -directory, you can use a path that starts with a tilde character 13.446 -followed by the user's name (let's call them \texttt{otheruser}), like 13.447 -this. 13.448 -\begin{codesample2} 13.449 - ssh://server/~otheruser/hg/repo 13.450 -\end{codesample2} 13.451 - 13.452 -And if you really want to specify an \emph{absolute} path on the 13.453 -server, begin the path component with two slashes, as in this example. 13.454 -\begin{codesample2} 13.455 - ssh://server//absolute/path 13.456 -\end{codesample2} 13.457 - 13.458 -\subsection{Finding an ssh client for your system} 13.459 - 13.460 -Almost every Unix-like system comes with OpenSSH preinstalled. If 13.461 -you're using such a system, run \Verb|which ssh| to find out if 13.462 -the \command{ssh} command is installed (it's usually in 13.463 -\dirname{/usr/bin}). In the unlikely event that it isn't present, 13.464 -take a look at your system documentation to figure out how to install 13.465 -it. 13.466 - 13.467 -On Windows, you'll first need to download a suitable ssh 13.468 -client. There are two alternatives. 13.469 -\begin{itemize} 13.470 -\item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides 13.471 - a complete suite of ssh client commands. 13.472 -\item If you have a high tolerance for pain, you can use the Cygwin 13.473 - port of OpenSSH. 13.474 -\end{itemize} 13.475 -In either case, you'll need to edit your \hgini\ file to tell 13.476 -Mercurial where to find the actual client command. For example, if 13.477 -you're using PuTTY, you'll need to use the \command{plink} command as 13.478 -a command-line ssh client. 13.479 -\begin{codesample2} 13.480 - [ui] 13.481 - ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key" 13.482 -\end{codesample2} 13.483 - 13.484 -\begin{note} 13.485 - The path to \command{plink} shouldn't contain any whitespace 13.486 - characters, or Mercurial may not be able to run it correctly (so 13.487 - putting it in \dirname{C:\\Program Files} is probably not a good 13.488 - idea). 13.489 -\end{note} 13.490 - 13.491 -\subsection{Generating a key pair} 13.492 - 13.493 -To avoid the need to repetitively type a password every time you need 13.494 -to use your ssh client, I recommend generating a key pair. On a 13.495 -Unix-like system, the \command{ssh-keygen} command will do the trick. 13.496 -On Windows, if you're using PuTTY, the \command{puttygen} command is 13.497 -what you'll need. 13.498 - 13.499 -When you generate a key pair, it's usually \emph{highly} advisable to 13.500 -protect it with a passphrase. (The only time that you might not want 13.501 -to do this is when you're using the ssh protocol for automated tasks 13.502 -on a secure network.) 13.503 - 13.504 -Simply generating a key pair isn't enough, however. You'll need to 13.505 -add the public key to the set of authorised keys for whatever user 13.506 -you're logging in remotely as. For servers using OpenSSH (the vast 13.507 -majority), this will mean adding the public key to a list in a file 13.508 -called \sfilename{authorized\_keys} in their \sdirname{.ssh} 13.509 -directory. 13.510 - 13.511 -On a Unix-like system, your public key will have a \filename{.pub} 13.512 -extension. If you're using \command{puttygen} on Windows, you can 13.513 -save the public key to a file of your choosing, or paste it from the 13.514 -window it's displayed in straight into the 13.515 -\sfilename{authorized\_keys} file. 13.516 - 13.517 -\subsection{Using an authentication agent} 13.518 - 13.519 -An authentication agent is a daemon that stores passphrases in memory 13.520 -(so it will forget passphrases if you log out and log back in again). 13.521 -An ssh client will notice if it's running, and query it for a 13.522 -passphrase. If there's no authentication agent running, or the agent 13.523 -doesn't store the necessary passphrase, you'll have to type your 13.524 -passphrase every time Mercurial tries to communicate with a server on 13.525 -your behalf (e.g.~whenever you pull or push changes). 13.526 - 13.527 -The downside of storing passphrases in an agent is that it's possible 13.528 -for a well-prepared attacker to recover the plain text of your 13.529 -passphrases, in some cases even if your system has been power-cycled. 13.530 -You should make your own judgment as to whether this is an acceptable 13.531 -risk. It certainly saves a lot of repeated typing. 13.532 - 13.533 -On Unix-like systems, the agent is called \command{ssh-agent}, and 13.534 -it's often run automatically for you when you log in. You'll need to 13.535 -use the \command{ssh-add} command to add passphrases to the agent's 13.536 -store. On Windows, if you're using PuTTY, the \command{pageant} 13.537 -command acts as the agent. It adds an icon to your system tray that 13.538 -will let you manage stored passphrases. 13.539 - 13.540 -\subsection{Configuring the server side properly} 13.541 - 13.542 -Because ssh can be fiddly to set up if you're new to it, there's a 13.543 -variety of things that can go wrong. Add Mercurial on top, and 13.544 -there's plenty more scope for head-scratching. Most of these 13.545 -potential problems occur on the server side, not the client side. The 13.546 -good news is that once you've gotten a configuration working, it will 13.547 -usually continue to work indefinitely. 13.548 - 13.549 -Before you try using Mercurial to talk to an ssh server, it's best to 13.550 -make sure that you can use the normal \command{ssh} or \command{putty} 13.551 -command to talk to the server first. If you run into problems with 13.552 -using these commands directly, Mercurial surely won't work. Worse, it 13.553 -will obscure the underlying problem. Any time you want to debug 13.554 -ssh-related Mercurial problems, you should drop back to making sure 13.555 -that plain ssh client commands work first, \emph{before} you worry 13.556 -about whether there's a problem with Mercurial. 13.557 - 13.558 -The first thing to be sure of on the server side is that you can 13.559 -actually log in from another machine at all. If you can't use 13.560 -\command{ssh} or \command{putty} to log in, the error message you get 13.561 -may give you a few hints as to what's wrong. The most common problems 13.562 -are as follows. 13.563 -\begin{itemize} 13.564 -\item If you get a ``connection refused'' error, either there isn't an 13.565 - SSH daemon running on the server at all, or it's inaccessible due to 13.566 - firewall configuration. 13.567 -\item If you get a ``no route to host'' error, you either have an 13.568 - incorrect address for the server or a seriously locked down firewall 13.569 - that won't admit its existence at all. 13.570 -\item If you get a ``permission denied'' error, you may have mistyped 13.571 - the username on the server, or you could have mistyped your key's 13.572 - passphrase or the remote user's password. 13.573 -\end{itemize} 13.574 -In summary, if you're having trouble talking to the server's ssh 13.575 -daemon, first make sure that one is running at all. On many systems 13.576 -it will be installed, but disabled, by default. Once you're done with 13.577 -this step, you should then check that the server's firewall is 13.578 -configured to allow incoming connections on the port the ssh daemon is 13.579 -listening on (usually~22). Don't worry about more exotic 13.580 -possibilities for misconfiguration until you've checked these two 13.581 -first. 13.582 - 13.583 -If you're using an authentication agent on the client side to store 13.584 -passphrases for your keys, you ought to be able to log into the server 13.585 -without being prompted for a passphrase or a password. If you're 13.586 -prompted for a passphrase, there are a few possible culprits. 13.587 -\begin{itemize} 13.588 -\item You might have forgotten to use \command{ssh-add} or 13.589 - \command{pageant} to store the passphrase. 13.590 -\item You might have stored the passphrase for the wrong key. 13.591 -\end{itemize} 13.592 -If you're being prompted for the remote user's password, there are 13.593 -another few possible problems to check. 13.594 -\begin{itemize} 13.595 -\item Either the user's home directory or their \sdirname{.ssh} 13.596 - directory might have excessively liberal permissions. As a result, 13.597 - the ssh daemon will not trust or read their 13.598 - \sfilename{authorized\_keys} file. For example, a group-writable 13.599 - home or \sdirname{.ssh} directory will often cause this symptom. 13.600 -\item The user's \sfilename{authorized\_keys} file may have a problem. 13.601 - If anyone other than the user owns or can write to that file, the 13.602 - ssh daemon will not trust or read it. 13.603 -\end{itemize} 13.604 - 13.605 -In the ideal world, you should be able to run the following command 13.606 -successfully, and it should print exactly one line of output, the 13.607 -current date and time. 13.608 -\begin{codesample2} 13.609 - ssh myserver date 13.610 -\end{codesample2} 13.611 - 13.612 -If, on your server, you have login scripts that print banners or other 13.613 -junk even when running non-interactive commands like this, you should 13.614 -fix them before you continue, so that they only print output if 13.615 -they're run interactively. Otherwise these banners will at least 13.616 -clutter up Mercurial's output. Worse, they could potentially cause 13.617 -problems with running Mercurial commands remotely. Mercurial makes 13.618 -tries to detect and ignore banners in non-interactive \command{ssh} 13.619 -sessions, but it is not foolproof. (If you're editing your login 13.620 -scripts on your server, the usual way to see if a login script is 13.621 -running in an interactive shell is to check the return code from the 13.622 -command \Verb|tty -s|.) 13.623 - 13.624 -Once you've verified that plain old ssh is working with your server, 13.625 -the next step is to ensure that Mercurial runs on the server. The 13.626 -following command should run successfully: 13.627 -\begin{codesample2} 13.628 - ssh myserver hg version 13.629 -\end{codesample2} 13.630 -If you see an error message instead of normal \hgcmd{version} output, 13.631 -this is usually because you haven't installed Mercurial to 13.632 -\dirname{/usr/bin}. Don't worry if this is the case; you don't need 13.633 -to do that. But you should check for a few possible problems. 13.634 -\begin{itemize} 13.635 -\item Is Mercurial really installed on the server at all? I know this 13.636 - sounds trivial, but it's worth checking! 13.637 -\item Maybe your shell's search path (usually set via the \envar{PATH} 13.638 - environment variable) is simply misconfigured. 13.639 -\item Perhaps your \envar{PATH} environment variable is only being set 13.640 - to point to the location of the \command{hg} executable if the login 13.641 - session is interactive. This can happen if you're setting the path 13.642 - in the wrong shell login script. See your shell's documentation for 13.643 - details. 13.644 -\item The \envar{PYTHONPATH} environment variable may need to contain 13.645 - the path to the Mercurial Python modules. It might not be set at 13.646 - all; it could be incorrect; or it may be set only if the login is 13.647 - interactive. 13.648 -\end{itemize} 13.649 - 13.650 -If you can run \hgcmd{version} over an ssh connection, well done! 13.651 -You've got the server and client sorted out. You should now be able 13.652 -to use Mercurial to access repositories hosted by that username on 13.653 -that server. If you run into problems with Mercurial and ssh at this 13.654 -point, try using the \hggopt{--debug} option to get a clearer picture 13.655 -of what's going on. 13.656 - 13.657 -\subsection{Using compression with ssh} 13.658 - 13.659 -Mercurial does not compress data when it uses the ssh protocol, 13.660 -because the ssh protocol can transparently compress data. However, 13.661 -the default behaviour of ssh clients is \emph{not} to request 13.662 -compression. 13.663 - 13.664 -Over any network other than a fast LAN (even a wireless network), 13.665 -using compression is likely to significantly speed up Mercurial's 13.666 -network operations. For example, over a WAN, someone measured 13.667 -compression as reducing the amount of time required to clone a 13.668 -particularly large repository from~51 minutes to~17 minutes. 13.669 - 13.670 -Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C} 13.671 -option which turns on compression. You can easily edit your \hgrc\ to 13.672 -enable compression for all of Mercurial's uses of the ssh protocol. 13.673 -\begin{codesample2} 13.674 - [ui] 13.675 - ssh = ssh -C 13.676 -\end{codesample2} 13.677 - 13.678 -If you use \command{ssh}, you can configure it to always use 13.679 -compression when talking to your server. To do this, edit your 13.680 -\sfilename{.ssh/config} file (which may not yet exist), as follows. 13.681 -\begin{codesample2} 13.682 - Host hg 13.683 - Compression yes 13.684 - HostName hg.example.com 13.685 -\end{codesample2} 13.686 -This defines an alias, \texttt{hg}. When you use it on the 13.687 -\command{ssh} command line or in a Mercurial \texttt{ssh}-protocol 13.688 -URL, it will cause \command{ssh} to connect to \texttt{hg.example.com} 13.689 -and use compression. This gives you both a shorter name to type and 13.690 -compression, each of which is a good thing in its own right. 13.691 - 13.692 -\section{Serving over HTTP using CGI} 13.693 -\label{sec:collab:cgi} 13.694 - 13.695 -Depending on how ambitious you are, configuring Mercurial's CGI 13.696 -interface can take anything from a few moments to several hours. 13.697 - 13.698 -We'll begin with the simplest of examples, and work our way towards a 13.699 -more complex configuration. Even for the most basic case, you're 13.700 -almost certainly going to need to read and modify your web server's 13.701 -configuration. 13.702 - 13.703 -\begin{note} 13.704 - Configuring a web server is a complex, fiddly, and highly 13.705 - system-dependent activity. I can't possibly give you instructions 13.706 - that will cover anything like all of the cases you will encounter. 13.707 - Please use your discretion and judgment in following the sections 13.708 - below. Be prepared to make plenty of mistakes, and to spend a lot 13.709 - of time reading your server's error logs. 13.710 -\end{note} 13.711 - 13.712 -\subsection{Web server configuration checklist} 13.713 - 13.714 -Before you continue, do take a few moments to check a few aspects of 13.715 -your system's setup. 13.716 - 13.717 -\begin{enumerate} 13.718 -\item Do you have a web server installed at all? Mac OS X ships with 13.719 - Apache, but many other systems may not have a web server installed. 13.720 -\item If you have a web server installed, is it actually running? On 13.721 - most systems, even if one is present, it will be disabled by 13.722 - default. 13.723 -\item Is your server configured to allow you to run CGI programs in 13.724 - the directory where you plan to do so? Most servers default to 13.725 - explicitly disabling the ability to run CGI programs. 13.726 -\end{enumerate} 13.727 - 13.728 -If you don't have a web server installed, and don't have substantial 13.729 -experience configuring Apache, you should consider using the 13.730 -\texttt{lighttpd} web server instead of Apache. Apache has a 13.731 -well-deserved reputation for baroque and confusing configuration. 13.732 -While \texttt{lighttpd} is less capable in some ways than Apache, most 13.733 -of these capabilities are not relevant to serving Mercurial 13.734 -repositories. And \texttt{lighttpd} is undeniably \emph{much} easier 13.735 -to get started with than Apache. 13.736 - 13.737 -\subsection{Basic CGI configuration} 13.738 - 13.739 -On Unix-like systems, it's common for users to have a subdirectory 13.740 -named something like \dirname{public\_html} in their home directory, 13.741 -from which they can serve up web pages. A file named \filename{foo} 13.742 -in this directory will be accessible at a URL of the form 13.743 -\texttt{http://www.example.com/\~{}username/foo}. 13.744 - 13.745 -To get started, find the \sfilename{hgweb.cgi} script that should be 13.746 -present in your Mercurial installation. If you can't quickly find a 13.747 -local copy on your system, simply download one from the master 13.748 -Mercurial repository at 13.749 -\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}. 13.750 - 13.751 -You'll need to copy this script into your \dirname{public\_html} 13.752 -directory, and ensure that it's executable. 13.753 -\begin{codesample2} 13.754 - cp .../hgweb.cgi ~/public_html 13.755 - chmod 755 ~/public_html/hgweb.cgi 13.756 -\end{codesample2} 13.757 -The \texttt{755} argument to \command{chmod} is a little more general 13.758 -than just making the script executable: it ensures that the script is 13.759 -executable by anyone, and that ``group'' and ``other'' write 13.760 -permissions are \emph{not} set. If you were to leave those write 13.761 -permissions enabled, Apache's \texttt{suexec} subsystem would likely 13.762 -refuse to execute the script. In fact, \texttt{suexec} also insists 13.763 -that the \emph{directory} in which the script resides must not be 13.764 -writable by others. 13.765 -\begin{codesample2} 13.766 - chmod 755 ~/public_html 13.767 -\end{codesample2} 13.768 - 13.769 -\subsubsection{What could \emph{possibly} go wrong?} 13.770 -\label{sec:collab:wtf} 13.771 - 13.772 -Once you've copied the CGI script into place, go into a web browser, 13.773 -and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi}, 13.774 -\emph{but} brace yourself for instant failure. There's a high 13.775 -probability that trying to visit this URL will fail, and there are 13.776 -many possible reasons for this. In fact, you're likely to stumble 13.777 -over almost every one of the possible errors below, so please read 13.778 -carefully. The following are all of the problems I ran into on a 13.779 -system running Fedora~7, with a fresh installation of Apache, and a 13.780 -user account that I created specially to perform this exercise. 13.781 - 13.782 -Your web server may have per-user directories disabled. If you're 13.783 -using Apache, search your config file for a \texttt{UserDir} 13.784 -directive. If there's none present, per-user directories will be 13.785 -disabled. If one exists, but its value is \texttt{disabled}, then 13.786 -per-user directories will be disabled. Otherwise, the string after 13.787 -\texttt{UserDir} gives the name of the subdirectory that Apache will 13.788 -look in under your home directory, for example \dirname{public\_html}. 13.789 - 13.790 -Your file access permissions may be too restrictive. The web server 13.791 -must be able to traverse your home directory and directories under 13.792 -your \dirname{public\_html} directory, and read files under the latter 13.793 -too. Here's a quick recipe to help you to make your permissions more 13.794 -appropriate. 13.795 -\begin{codesample2} 13.796 - chmod 755 ~ 13.797 - find ~/public_html -type d -print0 | xargs -0r chmod 755 13.798 - find ~/public_html -type f -print0 | xargs -0r chmod 644 13.799 -\end{codesample2} 13.800 - 13.801 -The other possibility with permissions is that you might get a 13.802 -completely empty window when you try to load the script. In this 13.803 -case, it's likely that your access permissions are \emph{too 13.804 - permissive}. Apache's \texttt{suexec} subsystem won't execute a 13.805 -script that's group-~or world-writable, for example. 13.806 - 13.807 -Your web server may be configured to disallow execution of CGI 13.808 -programs in your per-user web directory. Here's Apache's 13.809 -default per-user configuration from my Fedora system. 13.810 -\begin{codesample2} 13.811 - <Directory /home/*/public_html> 13.812 - AllowOverride FileInfo AuthConfig Limit 13.813 - Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec 13.814 - <Limit GET POST OPTIONS> 13.815 - Order allow,deny 13.816 - Allow from all 13.817 - </Limit> 13.818 - <LimitExcept GET POST OPTIONS> 13.819 - Order deny,allow 13.820 - Deny from all 13.821 - </LimitExcept> 13.822 - </Directory> 13.823 -\end{codesample2} 13.824 -If you find a similar-looking \texttt{Directory} group in your Apache 13.825 -configuration, the directive to look at inside it is \texttt{Options}. 13.826 -Add \texttt{ExecCGI} to the end of this list if it's missing, and 13.827 -restart the web server. 13.828 - 13.829 -If you find that Apache serves you the text of the CGI script instead 13.830 -of executing it, you may need to either uncomment (if already present) 13.831 -or add a directive like this. 13.832 -\begin{codesample2} 13.833 - AddHandler cgi-script .cgi 13.834 -\end{codesample2} 13.835 - 13.836 -The next possibility is that you might be served with a colourful 13.837 -Python backtrace claiming that it can't import a 13.838 -\texttt{mercurial}-related module. This is actually progress! The 13.839 -server is now capable of executing your CGI script. This error is 13.840 -only likely to occur if you're running a private installation of 13.841 -Mercurial, instead of a system-wide version. Remember that the web 13.842 -server runs the CGI program without any of the environment variables 13.843 -that you take for granted in an interactive session. If this error 13.844 -happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the 13.845 -directions inside it to correctly set your \envar{PYTHONPATH} 13.846 -environment variable. 13.847 - 13.848 -Finally, you are \emph{certain} to by served with another colourful 13.849 -Python backtrace: this one will complain that it can't find 13.850 -\dirname{/path/to/repository}. Edit your \sfilename{hgweb.cgi} script 13.851 -and replace the \dirname{/path/to/repository} string with the complete 13.852 -path to the repository you want to serve up. 13.853 - 13.854 -At this point, when you try to reload the page, you should be 13.855 -presented with a nice HTML view of your repository's history. Whew! 13.856 - 13.857 -\subsubsection{Configuring lighttpd} 13.858 - 13.859 -To be exhaustive in my experiments, I tried configuring the 13.860 -increasingly popular \texttt{lighttpd} web server to serve the same 13.861 -repository as I described with Apache above. I had already overcome 13.862 -all of the problems I outlined with Apache, many of which are not 13.863 -server-specific. As a result, I was fairly sure that my file and 13.864 -directory permissions were good, and that my \sfilename{hgweb.cgi} 13.865 -script was properly edited. 13.866 - 13.867 -Once I had Apache running, getting \texttt{lighttpd} to serve the 13.868 -repository was a snap (in other words, even if you're trying to use 13.869 -\texttt{lighttpd}, you should read the Apache section). I first had 13.870 -to edit the \texttt{mod\_access} section of its config file to enable 13.871 -\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were 13.872 -disabled by default on my system. I then added a few lines to the end 13.873 -of the config file, to configure these modules. 13.874 -\begin{codesample2} 13.875 - userdir.path = "public_html" 13.876 - cgi.assign = ( ".cgi" => "" ) 13.877 -\end{codesample2} 13.878 -With this done, \texttt{lighttpd} ran immediately for me. If I had 13.879 -configured \texttt{lighttpd} before Apache, I'd almost certainly have 13.880 -run into many of the same system-level configuration problems as I did 13.881 -with Apache. However, I found \texttt{lighttpd} to be noticeably 13.882 -easier to configure than Apache, even though I've used Apache for over 13.883 -a decade, and this was my first exposure to \texttt{lighttpd}. 13.884 - 13.885 -\subsection{Sharing multiple repositories with one CGI script} 13.886 - 13.887 -The \sfilename{hgweb.cgi} script only lets you publish a single 13.888 -repository, which is an annoying restriction. If you want to publish 13.889 -more than one without wracking yourself with multiple copies of the 13.890 -same script, each with different names, a better choice is to use the 13.891 -\sfilename{hgwebdir.cgi} script. 13.892 - 13.893 -The procedure to configure \sfilename{hgwebdir.cgi} is only a little 13.894 -more involved than for \sfilename{hgweb.cgi}. First, you must obtain 13.895 -a copy of the script. If you don't have one handy, you can download a 13.896 -copy from the master Mercurial repository at 13.897 -\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}. 13.898 - 13.899 -You'll need to copy this script into your \dirname{public\_html} 13.900 -directory, and ensure that it's executable. 13.901 -\begin{codesample2} 13.902 - cp .../hgwebdir.cgi ~/public_html 13.903 - chmod 755 ~/public_html ~/public_html/hgwebdir.cgi 13.904 -\end{codesample2} 13.905 -With basic configuration out of the way, try to visit 13.906 -\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser. It 13.907 -should display an empty list of repositories. If you get a blank 13.908 -window or error message, try walking through the list of potential 13.909 -problems in section~\ref{sec:collab:wtf}. 13.910 - 13.911 -The \sfilename{hgwebdir.cgi} script relies on an external 13.912 -configuration file. By default, it searches for a file named 13.913 -\sfilename{hgweb.config} in the same directory as itself. You'll need 13.914 -to create this file, and make it world-readable. The format of the 13.915 -file is similar to a Windows ``ini'' file, as understood by Python's 13.916 -\texttt{ConfigParser}~\cite{web:configparser} module. 13.917 - 13.918 -The easiest way to configure \sfilename{hgwebdir.cgi} is with a 13.919 -section named \texttt{collections}. This will automatically publish 13.920 -\emph{every} repository under the directories you name. The section 13.921 -should look like this: 13.922 -\begin{codesample2} 13.923 - [collections] 13.924 - /my/root = /my/root 13.925 -\end{codesample2} 13.926 -Mercurial interprets this by looking at the directory name on the 13.927 -\emph{right} hand side of the ``\texttt{=}'' sign; finding 13.928 -repositories in that directory hierarchy; and using the text on the 13.929 -\emph{left} to strip off matching text from the names it will actually 13.930 -list in the web interface. The remaining component of a path after 13.931 -this stripping has occurred is called a ``virtual path''. 13.932 - 13.933 -Given the example above, if we have a repository whose local path is 13.934 -\dirname{/my/root/this/repo}, the CGI script will strip the leading 13.935 -\dirname{/my/root} from the name, and publish the repository with a 13.936 -virtual path of \dirname{this/repo}. If the base URL for our CGI 13.937 -script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete 13.938 -URL for that repository will be 13.939 -\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}. 13.940 - 13.941 -If we replace \dirname{/my/root} on the left hand side of this example 13.942 -with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off 13.943 -\dirname{/my} from the repository name, and will give us a virtual 13.944 -path of \dirname{root/this/repo} instead of \dirname{this/repo}. 13.945 - 13.946 -The \sfilename{hgwebdir.cgi} script will recursively search each 13.947 -directory listed in the \texttt{collections} section of its 13.948 -configuration file, but it will \texttt{not} recurse into the 13.949 -repositories it finds. 13.950 - 13.951 -The \texttt{collections} mechanism makes it easy to publish many 13.952 -repositories in a ``fire and forget'' manner. You only need to set up 13.953 -the CGI script and configuration file one time. Afterwards, you can 13.954 -publish or unpublish a repository at any time by simply moving it 13.955 -into, or out of, the directory hierarchy in which you've configured 13.956 -\sfilename{hgwebdir.cgi} to look. 13.957 - 13.958 -\subsubsection{Explicitly specifying which repositories to publish} 13.959 - 13.960 -In addition to the \texttt{collections} mechanism, the 13.961 -\sfilename{hgwebdir.cgi} script allows you to publish a specific list 13.962 -of repositories. To do so, create a \texttt{paths} section, with 13.963 -contents of the following form. 13.964 -\begin{codesample2} 13.965 - [paths] 13.966 - repo1 = /my/path/to/some/repo 13.967 - repo2 = /some/path/to/another 13.968 -\end{codesample2} 13.969 -In this case, the virtual path (the component that will appear in a 13.970 -URL) is on the left hand side of each definition, while the path to 13.971 -the repository is on the right. Notice that there does not need to be 13.972 -any relationship between the virtual path you choose and the location 13.973 -of a repository in your filesystem. 13.974 - 13.975 -If you wish, you can use both the \texttt{collections} and 13.976 -\texttt{paths} mechanisms simultaneously in a single configuration 13.977 -file. 13.978 - 13.979 -\begin{note} 13.980 - If multiple repositories have the same virtual path, 13.981 - \sfilename{hgwebdir.cgi} will not report an error. Instead, it will 13.982 - behave unpredictably. 13.983 -\end{note} 13.984 - 13.985 -\subsection{Downloading source archives} 13.986 - 13.987 -Mercurial's web interface lets users download an archive of any 13.988 -revision. This archive will contain a snapshot of the working 13.989 -directory as of that revision, but it will not contain a copy of the 13.990 -repository data. 13.991 - 13.992 -By default, this feature is not enabled. To enable it, you'll need to 13.993 -add an \rcitem{web}{allow\_archive} item to the \rcsection{web} 13.994 -section of your \hgrc. 13.995 - 13.996 -\subsection{Web configuration options} 13.997 - 13.998 -Mercurial's web interfaces (the \hgcmd{serve} command, and the 13.999 -\sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a 13.1000 -number of configuration options that you can set. These belong in a 13.1001 -section named \rcsection{web}. 13.1002 -\begin{itemize} 13.1003 -\item[\rcitem{web}{allow\_archive}] Determines which (if any) archive 13.1004 - download mechanisms Mercurial supports. If you enable this 13.1005 - feature, users of the web interface will be able to download an 13.1006 - archive of whatever revision of a repository they are viewing. 13.1007 - To enable the archive feature, this item must take the form of a 13.1008 - sequence of words drawn from the list below. 13.1009 - \begin{itemize} 13.1010 - \item[\texttt{bz2}] A \command{tar} archive, compressed using 13.1011 - \texttt{bzip2} compression. This has the best compression ratio, 13.1012 - but uses the most CPU time on the server. 13.1013 - \item[\texttt{gz}] A \command{tar} archive, compressed using 13.1014 - \texttt{gzip} compression. 13.1015 - \item[\texttt{zip}] A \command{zip} archive, compressed using LZW 13.1016 - compression. This format has the worst compression ratio, but is 13.1017 - widely used in the Windows world. 13.1018 - \end{itemize} 13.1019 - If you provide an empty list, or don't have an 13.1020 - \rcitem{web}{allow\_archive} entry at all, this feature will be 13.1021 - disabled. Here is an example of how to enable all three supported 13.1022 - formats. 13.1023 - \begin{codesample4} 13.1024 - [web] 13.1025 - allow_archive = bz2 gz zip 13.1026 - \end{codesample4} 13.1027 -\item[\rcitem{web}{allowpull}] Boolean. Determines whether the web 13.1028 - interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this 13.1029 - repository over~HTTP. If set to \texttt{no} or \texttt{false}, only 13.1030 - the ``human-oriented'' portion of the web interface is available. 13.1031 -\item[\rcitem{web}{contact}] String. A free-form (but preferably 13.1032 - brief) string identifying the person or group in charge of the 13.1033 - repository. This often contains the name and email address of a 13.1034 - person or mailing list. It often makes sense to place this entry in 13.1035 - a repository's own \sfilename{.hg/hgrc} file, but it can make sense 13.1036 - to use in a global \hgrc\ if every repository has a single 13.1037 - maintainer. 13.1038 -\item[\rcitem{web}{maxchanges}] Integer. The default maximum number 13.1039 - of changesets to display in a single page of output. 13.1040 -\item[\rcitem{web}{maxfiles}] Integer. The default maximum number 13.1041 - of modified files to display in a single page of output. 13.1042 -\item[\rcitem{web}{stripes}] Integer. If the web interface displays 13.1043 - alternating ``stripes'' to make it easier to visually align rows 13.1044 - when you are looking at a table, this number controls the number of 13.1045 - rows in each stripe. 13.1046 -\item[\rcitem{web}{style}] Controls the template Mercurial uses to 13.1047 - display the web interface. Mercurial ships with two web templates, 13.1048 - named \texttt{default} and \texttt{gitweb} (the latter is much more 13.1049 - visually attractive). You can also specify a custom template of 13.1050 - your own; see chapter~\ref{chap:template} for details. Here, you 13.1051 - can see how to enable the \texttt{gitweb} style. 13.1052 - \begin{codesample4} 13.1053 - [web] 13.1054 - style = gitweb 13.1055 - \end{codesample4} 13.1056 -\item[\rcitem{web}{templates}] Path. The directory in which to search 13.1057 - for template files. By default, Mercurial searches in the directory 13.1058 - in which it was installed. 13.1059 -\end{itemize} 13.1060 -If you are using \sfilename{hgwebdir.cgi}, you can place a few 13.1061 -configuration items in a \rcsection{web} section of the 13.1062 -\sfilename{hgweb.config} file instead of a \hgrc\ file, for 13.1063 -convenience. These items are \rcitem{web}{motd} and 13.1064 -\rcitem{web}{style}. 13.1065 - 13.1066 -\subsubsection{Options specific to an individual repository} 13.1067 - 13.1068 -A few \rcsection{web} configuration items ought to be placed in a 13.1069 -repository's local \sfilename{.hg/hgrc}, rather than a user's or 13.1070 -global \hgrc. 13.1071 -\begin{itemize} 13.1072 -\item[\rcitem{web}{description}] String. A free-form (but preferably 13.1073 - brief) string that describes the contents or purpose of the 13.1074 - repository. 13.1075 -\item[\rcitem{web}{name}] String. The name to use for the repository 13.1076 - in the web interface. This overrides the default name, which is the 13.1077 - last component of the repository's path. 13.1078 -\end{itemize} 13.1079 - 13.1080 -\subsubsection{Options specific to the \hgcmd{serve} command} 13.1081 - 13.1082 -Some of the items in the \rcsection{web} section of a \hgrc\ file are 13.1083 -only for use with the \hgcmd{serve} command. 13.1084 -\begin{itemize} 13.1085 -\item[\rcitem{web}{accesslog}] Path. The name of a file into which to 13.1086 - write an access log. By default, the \hgcmd{serve} command writes 13.1087 - this information to standard output, not to a file. Log entries are 13.1088 - written in the standard ``combined'' file format used by almost all 13.1089 - web servers. 13.1090 -\item[\rcitem{web}{address}] String. The local address on which the 13.1091 - server should listen for incoming connections. By default, the 13.1092 - server listens on all addresses. 13.1093 -\item[\rcitem{web}{errorlog}] Path. The name of a file into which to 13.1094 - write an error log. By default, the \hgcmd{serve} command writes this 13.1095 - information to standard error, not to a file. 13.1096 -\item[\rcitem{web}{ipv6}] Boolean. Whether to use the IPv6 protocol. 13.1097 - By default, IPv6 is not used. 13.1098 -\item[\rcitem{web}{port}] Integer. The TCP~port number on which the 13.1099 - server should listen. The default port number used is~8000. 13.1100 -\end{itemize} 13.1101 - 13.1102 -\subsubsection{Choosing the right \hgrc\ file to add \rcsection{web} items to} 13.1103 - 13.1104 -It is important to remember that a web server like Apache or 13.1105 -\texttt{lighttpd} will run under a user~ID that is different to yours. 13.1106 -CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will 13.1107 -usually also run under that user~ID. 13.1108 - 13.1109 -If you add \rcsection{web} items to your own personal \hgrc\ file, CGI 13.1110 -scripts won't read that \hgrc\ file. Those settings will thus only 13.1111 -affect the behaviour of the \hgcmd{serve} command when you run it. To 13.1112 -cause CGI scripts to see your settings, either create a \hgrc\ file in 13.1113 -the home directory of the user ID that runs your web server, or add 13.1114 -those settings to a system-wide \hgrc\ file. 13.1115 - 13.1116 - 13.1117 -%%% Local Variables: 13.1118 -%%% mode: latex 13.1119 -%%% TeX-master: "00book" 13.1120 -%%% End:
14.1 --- a/en/ch07-filenames.tex Thu Mar 05 21:52:23 2009 +0200 14.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 14.3 @@ -1,305 +0,0 @@ 14.4 -\chapter{File names and pattern matching} 14.5 -\label{chap:names} 14.6 - 14.7 -Mercurial provides mechanisms that let you work with file names in a 14.8 -consistent and expressive way. 14.9 - 14.10 -\section{Simple file naming} 14.11 - 14.12 -Mercurial uses a unified piece of machinery ``under the hood'' to 14.13 -handle file names. Every command behaves uniformly with respect to 14.14 -file names. The way in which commands work with file names is as 14.15 -follows. 14.16 - 14.17 -If you explicitly name real files on the command line, Mercurial works 14.18 -with exactly those files, as you would expect. 14.19 -\interaction{filenames.files} 14.20 - 14.21 -When you provide a directory name, Mercurial will interpret this as 14.22 -``operate on every file in this directory and its subdirectories''. 14.23 -Mercurial traverses the files and subdirectories in a directory in 14.24 -alphabetical order. When it encounters a subdirectory, it will 14.25 -traverse that subdirectory before continuing with the current 14.26 -directory. 14.27 -\interaction{filenames.dirs} 14.28 - 14.29 -\section{Running commands without any file names} 14.30 - 14.31 -Mercurial's commands that work with file names have useful default 14.32 -behaviours when you invoke them without providing any file names or 14.33 -patterns. What kind of behaviour you should expect depends on what 14.34 -the command does. Here are a few rules of thumb you can use to 14.35 -predict what a command is likely to do if you don't give it any names 14.36 -to work with. 14.37 -\begin{itemize} 14.38 -\item Most commands will operate on the entire working directory. 14.39 - This is what the \hgcmd{add} command does, for example. 14.40 -\item If the command has effects that are difficult or impossible to 14.41 - reverse, it will force you to explicitly provide at least one name 14.42 - or pattern (see below). This protects you from accidentally 14.43 - deleting files by running \hgcmd{remove} with no arguments, for 14.44 - example. 14.45 -\end{itemize} 14.46 - 14.47 -It's easy to work around these default behaviours if they don't suit 14.48 -you. If a command normally operates on the whole working directory, 14.49 -you can invoke it on just the current directory and its subdirectories 14.50 -by giving it the name ``\dirname{.}''. 14.51 -\interaction{filenames.wdir-subdir} 14.52 - 14.53 -Along the same lines, some commands normally print file names relative 14.54 -to the root of the repository, even if you're invoking them from a 14.55 -subdirectory. Such a command will print file names relative to your 14.56 -subdirectory if you give it explicit names. Here, we're going to run 14.57 -\hgcmd{status} from a subdirectory, and get it to operate on the 14.58 -entire working directory while printing file names relative to our 14.59 -subdirectory, by passing it the output of the \hgcmd{root} command. 14.60 -\interaction{filenames.wdir-relname} 14.61 - 14.62 -\section{Telling you what's going on} 14.63 - 14.64 -The \hgcmd{add} example in the preceding section illustrates something 14.65 -else that's helpful about Mercurial commands. If a command operates 14.66 -on a file that you didn't name explicitly on the command line, it will 14.67 -usually print the name of the file, so that you will not be surprised 14.68 -what's going on. 14.69 - 14.70 -The principle here is of \emph{least surprise}. If you've exactly 14.71 -named a file on the command line, there's no point in repeating it 14.72 -back at you. If Mercurial is acting on a file \emph{implicitly}, 14.73 -because you provided no names, or a directory, or a pattern (see 14.74 -below), it's safest to tell you what it's doing. 14.75 - 14.76 -For commands that behave this way, you can silence them using the 14.77 -\hggopt{-q} option. You can also get them to print the name of every 14.78 -file, even those you've named explicitly, using the \hggopt{-v} 14.79 -option. 14.80 - 14.81 -\section{Using patterns to identify files} 14.82 - 14.83 -In addition to working with file and directory names, Mercurial lets 14.84 -you use \emph{patterns} to identify files. Mercurial's pattern 14.85 -handling is expressive. 14.86 - 14.87 -On Unix-like systems (Linux, MacOS, etc.), the job of matching file 14.88 -names to patterns normally falls to the shell. On these systems, you 14.89 -must explicitly tell Mercurial that a name is a pattern. On Windows, 14.90 -the shell does not expand patterns, so Mercurial will automatically 14.91 -identify names that are patterns, and expand them for you. 14.92 - 14.93 -To provide a pattern in place of a regular name on the command line, 14.94 -the mechanism is simple: 14.95 -\begin{codesample2} 14.96 - syntax:patternbody 14.97 -\end{codesample2} 14.98 -That is, a pattern is identified by a short text string that says what 14.99 -kind of pattern this is, followed by a colon, followed by the actual 14.100 -pattern. 14.101 - 14.102 -Mercurial supports two kinds of pattern syntax. The most frequently 14.103 -used is called \texttt{glob}; this is the same kind of pattern 14.104 -matching used by the Unix shell, and should be familiar to Windows 14.105 -command prompt users, too. 14.106 - 14.107 -When Mercurial does automatic pattern matching on Windows, it uses 14.108 -\texttt{glob} syntax. You can thus omit the ``\texttt{glob:}'' prefix 14.109 -on Windows, but it's safe to use it, too. 14.110 - 14.111 -The \texttt{re} syntax is more powerful; it lets you specify patterns 14.112 -using regular expressions, also known as regexps. 14.113 - 14.114 -By the way, in the examples that follow, notice that I'm careful to 14.115 -wrap all of my patterns in quote characters, so that they won't get 14.116 -expanded by the shell before Mercurial sees them. 14.117 - 14.118 -\subsection{Shell-style \texttt{glob} patterns} 14.119 - 14.120 -This is an overview of the kinds of patterns you can use when you're 14.121 -matching on glob patterns. 14.122 - 14.123 -The ``\texttt{*}'' character matches any string, within a single 14.124 -directory. 14.125 -\interaction{filenames.glob.star} 14.126 - 14.127 -The ``\texttt{**}'' pattern matches any string, and crosses directory 14.128 -boundaries. It's not a standard Unix glob token, but it's accepted by 14.129 -several popular Unix shells, and is very useful. 14.130 -\interaction{filenames.glob.starstar} 14.131 - 14.132 -The ``\texttt{?}'' pattern matches any single character. 14.133 -\interaction{filenames.glob.question} 14.134 - 14.135 -The ``\texttt{[}'' character begins a \emph{character class}. This 14.136 -matches any single character within the class. The class ends with a 14.137 -``\texttt{]}'' character. A class may contain multiple \emph{range}s 14.138 -of the form ``\texttt{a-f}'', which is shorthand for 14.139 -``\texttt{abcdef}''. 14.140 -\interaction{filenames.glob.range} 14.141 -If the first character after the ``\texttt{[}'' in a character class 14.142 -is a ``\texttt{!}'', it \emph{negates} the class, making it match any 14.143 -single character not in the class. 14.144 - 14.145 -A ``\texttt{\{}'' begins a group of subpatterns, where the whole group 14.146 -matches if any subpattern in the group matches. The ``\texttt{,}'' 14.147 -character separates subpatterns, and ``\texttt{\}}'' ends the group. 14.148 -\interaction{filenames.glob.group} 14.149 - 14.150 -\subsubsection{Watch out!} 14.151 - 14.152 -Don't forget that if you want to match a pattern in any directory, you 14.153 -should not be using the ``\texttt{*}'' match-any token, as this will 14.154 -only match within one directory. Instead, use the ``\texttt{**}'' 14.155 -token. This small example illustrates the difference between the two. 14.156 -\interaction{filenames.glob.star-starstar} 14.157 - 14.158 -\subsection{Regular expression matching with \texttt{re} patterns} 14.159 - 14.160 -Mercurial accepts the same regular expression syntax as the Python 14.161 -programming language (it uses Python's regexp engine internally). 14.162 -This is based on the Perl language's regexp syntax, which is the most 14.163 -popular dialect in use (it's also used in Java, for example). 14.164 - 14.165 -I won't discuss Mercurial's regexp dialect in any detail here, as 14.166 -regexps are not often used. Perl-style regexps are in any case 14.167 -already exhaustively documented on a multitude of web sites, and in 14.168 -many books. Instead, I will focus here on a few things you should 14.169 -know if you find yourself needing to use regexps with Mercurial. 14.170 - 14.171 -A regexp is matched against an entire file name, relative to the root 14.172 -of the repository. In other words, even if you're already in 14.173 -subbdirectory \dirname{foo}, if you want to match files under this 14.174 -directory, your pattern must start with ``\texttt{foo/}''. 14.175 - 14.176 -One thing to note, if you're familiar with Perl-style regexps, is that 14.177 -Mercurial's are \emph{rooted}. That is, a regexp starts matching 14.178 -against the beginning of a string; it doesn't look for a match 14.179 -anywhere within the string. To match anywhere in a string, start 14.180 -your pattern with ``\texttt{.*}''. 14.181 - 14.182 -\section{Filtering files} 14.183 - 14.184 -Not only does Mercurial give you a variety of ways to specify files; 14.185 -it lets you further winnow those files using \emph{filters}. Commands 14.186 -that work with file names accept two filtering options. 14.187 -\begin{itemize} 14.188 -\item \hggopt{-I}, or \hggopt{--include}, lets you specify a pattern 14.189 - that file names must match in order to be processed. 14.190 -\item \hggopt{-X}, or \hggopt{--exclude}, gives you a way to 14.191 - \emph{avoid} processing files, if they match this pattern. 14.192 -\end{itemize} 14.193 -You can provide multiple \hggopt{-I} and \hggopt{-X} options on the 14.194 -command line, and intermix them as you please. Mercurial interprets 14.195 -the patterns you provide using glob syntax by default (but you can use 14.196 -regexps if you need to). 14.197 - 14.198 -You can read a \hggopt{-I} filter as ``process only the files that 14.199 -match this filter''. 14.200 -\interaction{filenames.filter.include} 14.201 -The \hggopt{-X} filter is best read as ``process only the files that 14.202 -don't match this pattern''. 14.203 -\interaction{filenames.filter.exclude} 14.204 - 14.205 -\section{Ignoring unwanted files and directories} 14.206 - 14.207 -XXX. 14.208 - 14.209 -\section{Case sensitivity} 14.210 -\label{sec:names:case} 14.211 - 14.212 -If you're working in a mixed development environment that contains 14.213 -both Linux (or other Unix) systems and Macs or Windows systems, you 14.214 -should keep in the back of your mind the knowledge that they treat the 14.215 -case (``N'' versus ``n'') of file names in incompatible ways. This is 14.216 -not very likely to affect you, and it's easy to deal with if it does, 14.217 -but it could surprise you if you don't know about it. 14.218 - 14.219 -Operating systems and filesystems differ in the way they handle the 14.220 -\emph{case} of characters in file and directory names. There are 14.221 -three common ways to handle case in names. 14.222 -\begin{itemize} 14.223 -\item Completely case insensitive. Uppercase and lowercase versions 14.224 - of a letter are treated as identical, both when creating a file and 14.225 - during subsequent accesses. This is common on older DOS-based 14.226 - systems. 14.227 -\item Case preserving, but insensitive. When a file or directory is 14.228 - created, the case of its name is stored, and can be retrieved and 14.229 - displayed by the operating system. When an existing file is being 14.230 - looked up, its case is ignored. This is the standard arrangement on 14.231 - Windows and MacOS. The names \filename{foo} and \filename{FoO} 14.232 - identify the same file. This treatment of uppercase and lowercase 14.233 - letters as interchangeable is also referred to as \emph{case folding}. 14.234 -\item Case sensitive. The case of a name is significant at all times. 14.235 - The names \filename{foo} and {FoO} identify different files. This 14.236 - is the way Linux and Unix systems normally work. 14.237 -\end{itemize} 14.238 - 14.239 -On Unix-like systems, it is possible to have any or all of the above 14.240 -ways of handling case in action at once. For example, if you use a 14.241 -USB thumb drive formatted with a FAT32 filesystem on a Linux system, 14.242 -Linux will handle names on that filesystem in a case preserving, but 14.243 -insensitive, way. 14.244 - 14.245 -\subsection{Safe, portable repository storage} 14.246 - 14.247 -Mercurial's repository storage mechanism is \emph{case safe}. It 14.248 -translates file names so that they can be safely stored on both case 14.249 -sensitive and case insensitive filesystems. This means that you can 14.250 -use normal file copying tools to transfer a Mercurial repository onto, 14.251 -for example, a USB thumb drive, and safely move that drive and 14.252 -repository back and forth between a Mac, a PC running Windows, and a 14.253 -Linux box. 14.254 - 14.255 -\subsection{Detecting case conflicts} 14.256 - 14.257 -When operating in the working directory, Mercurial honours the naming 14.258 -policy of the filesystem where the working directory is located. If 14.259 -the filesystem is case preserving, but insensitive, Mercurial will 14.260 -treat names that differ only in case as the same. 14.261 - 14.262 -An important aspect of this approach is that it is possible to commit 14.263 -a changeset on a case sensitive (typically Linux or Unix) filesystem 14.264 -that will cause trouble for users on case insensitive (usually Windows 14.265 -and MacOS) users. If a Linux user commits changes to two files, one 14.266 -named \filename{myfile.c} and the other named \filename{MyFile.C}, 14.267 -they will be stored correctly in the repository. And in the working 14.268 -directories of other Linux users, they will be correctly represented 14.269 -as separate files. 14.270 - 14.271 -If a Windows or Mac user pulls this change, they will not initially 14.272 -have a problem, because Mercurial's repository storage mechanism is 14.273 -case safe. However, once they try to \hgcmd{update} the working 14.274 -directory to that changeset, or \hgcmd{merge} with that changeset, 14.275 -Mercurial will spot the conflict between the two file names that the 14.276 -filesystem would treat as the same, and forbid the update or merge 14.277 -from occurring. 14.278 - 14.279 -\subsection{Fixing a case conflict} 14.280 - 14.281 -If you are using Windows or a Mac in a mixed environment where some of 14.282 -your collaborators are using Linux or Unix, and Mercurial reports a 14.283 -case folding conflict when you try to \hgcmd{update} or \hgcmd{merge}, 14.284 -the procedure to fix the problem is simple. 14.285 - 14.286 -Just find a nearby Linux or Unix box, clone the problem repository 14.287 -onto it, and use Mercurial's \hgcmd{rename} command to change the 14.288 -names of any offending files or directories so that they will no 14.289 -longer cause case folding conflicts. Commit this change, \hgcmd{pull} 14.290 -or \hgcmd{push} it across to your Windows or MacOS system, and 14.291 -\hgcmd{update} to the revision with the non-conflicting names. 14.292 - 14.293 -The changeset with case-conflicting names will remain in your 14.294 -project's history, and you still won't be able to \hgcmd{update} your 14.295 -working directory to that changeset on a Windows or MacOS system, but 14.296 -you can continue development unimpeded. 14.297 - 14.298 -\begin{note} 14.299 - Prior to version~0.9.3, Mercurial did not use a case safe repository 14.300 - storage mechanism, and did not detect case folding conflicts. If 14.301 - you are using an older version of Mercurial on Windows or MacOS, I 14.302 - strongly recommend that you upgrade. 14.303 -\end{note} 14.304 - 14.305 -%%% Local Variables: 14.306 -%%% mode: latex 14.307 -%%% TeX-master: "00book" 14.308 -%%% End:
15.1 --- a/en/ch08-branch.tex Thu Mar 05 21:52:23 2009 +0200 15.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 15.3 @@ -1,391 +0,0 @@ 15.4 -\chapter{Managing releases and branchy development} 15.5 -\label{chap:branch} 15.6 - 15.7 -Mercurial provides several mechanisms for you to manage a project that 15.8 -is making progress on multiple fronts at once. To understand these 15.9 -mechanisms, let's first take a brief look at a fairly normal software 15.10 -project structure. 15.11 - 15.12 -Many software projects issue periodic ``major'' releases that contain 15.13 -substantial new features. In parallel, they may issue ``minor'' 15.14 -releases. These are usually identical to the major releases off which 15.15 -they're based, but with a few bugs fixed. 15.16 - 15.17 -In this chapter, we'll start by talking about how to keep records of 15.18 -project milestones such as releases. We'll then continue on to talk 15.19 -about the flow of work between different phases of a project, and how 15.20 -Mercurial can help you to isolate and manage this work. 15.21 - 15.22 -\section{Giving a persistent name to a revision} 15.23 - 15.24 -Once you decide that you'd like to call a particular revision a 15.25 -``release'', it's a good idea to record the identity of that revision. 15.26 -This will let you reproduce that release at a later date, for whatever 15.27 -purpose you might need at the time (reproducing a bug, porting to a 15.28 -new platform, etc). 15.29 -\interaction{tag.init} 15.30 - 15.31 -Mercurial lets you give a permanent name to any revision using the 15.32 -\hgcmd{tag} command. Not surprisingly, these names are called 15.33 -``tags''. 15.34 -\interaction{tag.tag} 15.35 - 15.36 -A tag is nothing more than a ``symbolic name'' for a revision. Tags 15.37 -exist purely for your convenience, so that you have a handy permanent 15.38 -way to refer to a revision; Mercurial doesn't interpret the tag names 15.39 -you use in any way. Neither does Mercurial place any restrictions on 15.40 -the name of a tag, beyond a few that are necessary to ensure that a 15.41 -tag can be parsed unambiguously. A tag name cannot contain any of the 15.42 -following characters: 15.43 -\begin{itemize} 15.44 -\item Colon (ASCII 58, ``\texttt{:}'') 15.45 -\item Carriage return (ASCII 13, ``\Verb+\r+'') 15.46 -\item Newline (ASCII 10, ``\Verb+\n+'') 15.47 -\end{itemize} 15.48 - 15.49 -You can use the \hgcmd{tags} command to display the tags present in 15.50 -your repository. In the output, each tagged revision is identified 15.51 -first by its name, then by revision number, and finally by the unique 15.52 -hash of the revision. 15.53 -\interaction{tag.tags} 15.54 -Notice that \texttt{tip} is listed in the output of \hgcmd{tags}. The 15.55 -\texttt{tip} tag is a special ``floating'' tag, which always 15.56 -identifies the newest revision in the repository. 15.57 - 15.58 -In the output of the \hgcmd{tags} command, tags are listed in reverse 15.59 -order, by revision number. This usually means that recent tags are 15.60 -listed before older tags. It also means that \texttt{tip} is always 15.61 -going to be the first tag listed in the output of \hgcmd{tags}. 15.62 - 15.63 -When you run \hgcmd{log}, if it displays a revision that has tags 15.64 -associated with it, it will print those tags. 15.65 -\interaction{tag.log} 15.66 - 15.67 -Any time you need to provide a revision~ID to a Mercurial command, the 15.68 -command will accept a tag name in its place. Internally, Mercurial 15.69 -will translate your tag name into the corresponding revision~ID, then 15.70 -use that. 15.71 -\interaction{tag.log.v1.0} 15.72 - 15.73 -There's no limit on the number of tags you can have in a repository, 15.74 -or on the number of tags that a single revision can have. As a 15.75 -practical matter, it's not a great idea to have ``too many'' (a number 15.76 -which will vary from project to project), simply because tags are 15.77 -supposed to help you to find revisions. If you have lots of tags, the 15.78 -ease of using them to identify revisions diminishes rapidly. 15.79 - 15.80 -For example, if your project has milestones as frequent as every few 15.81 -days, it's perfectly reasonable to tag each one of those. But if you 15.82 -have a continuous build system that makes sure every revision can be 15.83 -built cleanly, you'd be introducing a lot of noise if you were to tag 15.84 -every clean build. Instead, you could tag failed builds (on the 15.85 -assumption that they're rare!), or simply not use tags to track 15.86 -buildability. 15.87 - 15.88 -If you want to remove a tag that you no longer want, use 15.89 -\hgcmdargs{tag}{--remove}. 15.90 -\interaction{tag.remove} 15.91 -You can also modify a tag at any time, so that it identifies a 15.92 -different revision, by simply issuing a new \hgcmd{tag} command. 15.93 -You'll have to use the \hgopt{tag}{-f} option to tell Mercurial that 15.94 -you \emph{really} want to update the tag. 15.95 -\interaction{tag.replace} 15.96 -There will still be a permanent record of the previous identity of the 15.97 -tag, but Mercurial will no longer use it. There's thus no penalty to 15.98 -tagging the wrong revision; all you have to do is turn around and tag 15.99 -the correct revision once you discover your error. 15.100 - 15.101 -Mercurial stores tags in a normal revision-controlled file in your 15.102 -repository. If you've created any tags, you'll find them in a file 15.103 -named \sfilename{.hgtags}. When you run the \hgcmd{tag} command, 15.104 -Mercurial modifies this file, then automatically commits the change to 15.105 -it. This means that every time you run \hgcmd{tag}, you'll see a 15.106 -corresponding changeset in the output of \hgcmd{log}. 15.107 -\interaction{tag.tip} 15.108 - 15.109 -\subsection{Handling tag conflicts during a merge} 15.110 - 15.111 -You won't often need to care about the \sfilename{.hgtags} file, but 15.112 -it sometimes makes its presence known during a merge. The format of 15.113 -the file is simple: it consists of a series of lines. Each line 15.114 -starts with a changeset hash, followed by a space, followed by the 15.115 -name of a tag. 15.116 - 15.117 -If you're resolving a conflict in the \sfilename{.hgtags} file during 15.118 -a merge, there's one twist to modifying the \sfilename{.hgtags} file: 15.119 -when Mercurial is parsing the tags in a repository, it \emph{never} 15.120 -reads the working copy of the \sfilename{.hgtags} file. Instead, it 15.121 -reads the \emph{most recently committed} revision of the file. 15.122 - 15.123 -An unfortunate consequence of this design is that you can't actually 15.124 -verify that your merged \sfilename{.hgtags} file is correct until 15.125 -\emph{after} you've committed a change. So if you find yourself 15.126 -resolving a conflict on \sfilename{.hgtags} during a merge, be sure to 15.127 -run \hgcmd{tags} after you commit. If it finds an error in the 15.128 -\sfilename{.hgtags} file, it will report the location of the error, 15.129 -which you can then fix and commit. You should then run \hgcmd{tags} 15.130 -again, just to be sure that your fix is correct. 15.131 - 15.132 -\subsection{Tags and cloning} 15.133 - 15.134 -You may have noticed that the \hgcmd{clone} command has a 15.135 -\hgopt{clone}{-r} option that lets you clone an exact copy of the 15.136 -repository as of a particular changeset. The new clone will not 15.137 -contain any project history that comes after the revision you 15.138 -specified. This has an interaction with tags that can surprise the 15.139 -unwary. 15.140 - 15.141 -Recall that a tag is stored as a revision to the \sfilename{.hgtags} 15.142 -file, so that when you create a tag, the changeset in which it's 15.143 -recorded necessarily refers to an older changeset. When you run 15.144 -\hgcmdargs{clone}{-r foo} to clone a repository as of tag 15.145 -\texttt{foo}, the new clone \emph{will not contain the history that created the tag} that you used to clone the repository. The result 15.146 -is that you'll get exactly the right subset of the project's history 15.147 -in the new repository, but \emph{not} the tag you might have expected. 15.148 - 15.149 -\subsection{When permanent tags are too much} 15.150 - 15.151 -Since Mercurial's tags are revision controlled and carried around with 15.152 -a project's history, everyone you work with will see the tags you 15.153 -create. But giving names to revisions has uses beyond simply noting 15.154 -that revision \texttt{4237e45506ee} is really \texttt{v2.0.2}. If 15.155 -you're trying to track down a subtle bug, you might want a tag to 15.156 -remind you of something like ``Anne saw the symptoms with this 15.157 -revision''. 15.158 - 15.159 -For cases like this, what you might want to use are \emph{local} tags. 15.160 -You can create a local tag with the \hgopt{tag}{-l} option to the 15.161 -\hgcmd{tag} command. This will store the tag in a file called 15.162 -\sfilename{.hg/localtags}. Unlike \sfilename{.hgtags}, 15.163 -\sfilename{.hg/localtags} is not revision controlled. Any tags you 15.164 -create using \hgopt{tag}{-l} remain strictly local to the repository 15.165 -you're currently working in. 15.166 - 15.167 -\section{The flow of changes---big picture vs. little} 15.168 - 15.169 -To return to the outline I sketched at the beginning of a chapter, 15.170 -let's think about a project that has multiple concurrent pieces of 15.171 -work under development at once. 15.172 - 15.173 -There might be a push for a new ``main'' release; a new minor bugfix 15.174 -release to the last main release; and an unexpected ``hot fix'' to an 15.175 -old release that is now in maintenance mode. 15.176 - 15.177 -The usual way people refer to these different concurrent directions of 15.178 -development is as ``branches''. However, we've already seen numerous 15.179 -times that Mercurial treats \emph{all of history} as a series of 15.180 -branches and merges. Really, what we have here is two ideas that are 15.181 -peripherally related, but which happen to share a name. 15.182 -\begin{itemize} 15.183 -\item ``Big picture'' branches represent the sweep of a project's 15.184 - evolution; people give them names, and talk about them in 15.185 - conversation. 15.186 -\item ``Little picture'' branches are artefacts of the day-to-day 15.187 - activity of developing and merging changes. They expose the 15.188 - narrative of how the code was developed. 15.189 -\end{itemize} 15.190 - 15.191 -\section{Managing big-picture branches in repositories} 15.192 - 15.193 -The easiest way to isolate a ``big picture'' branch in Mercurial is in 15.194 -a dedicated repository. If you have an existing shared 15.195 -repository---let's call it \texttt{myproject}---that reaches a ``1.0'' 15.196 -milestone, you can start to prepare for future maintenance releases on 15.197 -top of version~1.0 by tagging the revision from which you prepared 15.198 -the~1.0 release. 15.199 -\interaction{branch-repo.tag} 15.200 -You can then clone a new shared \texttt{myproject-1.0.1} repository as 15.201 -of that tag. 15.202 -\interaction{branch-repo.clone} 15.203 - 15.204 -Afterwards, if someone needs to work on a bug fix that ought to go 15.205 -into an upcoming~1.0.1 minor release, they clone the 15.206 -\texttt{myproject-1.0.1} repository, make their changes, and push them 15.207 -back. 15.208 -\interaction{branch-repo.bugfix} 15.209 -Meanwhile, development for the next major release can continue, 15.210 -isolated and unabated, in the \texttt{myproject} repository. 15.211 -\interaction{branch-repo.new} 15.212 - 15.213 -\section{Don't repeat yourself: merging across branches} 15.214 - 15.215 -In many cases, if you have a bug to fix on a maintenance branch, the 15.216 -chances are good that the bug exists on your project's main branch 15.217 -(and possibly other maintenance branches, too). It's a rare developer 15.218 -who wants to fix the same bug multiple times, so let's look at a few 15.219 -ways that Mercurial can help you to manage these bugfixes without 15.220 -duplicating your work. 15.221 - 15.222 -In the simplest instance, all you need to do is pull changes from your 15.223 -maintenance branch into your local clone of the target branch. 15.224 -\interaction{branch-repo.pull} 15.225 -You'll then need to merge the heads of the two branches, and push back 15.226 -to the main branch. 15.227 -\interaction{branch-repo.merge} 15.228 - 15.229 -\section{Naming branches within one repository} 15.230 - 15.231 -In most instances, isolating branches in repositories is the right 15.232 -approach. Its simplicity makes it easy to understand; and so it's 15.233 -hard to make mistakes. There's a one-to-one relationship between 15.234 -branches you're working in and directories on your system. This lets 15.235 -you use normal (non-Mercurial-aware) tools to work on files within a 15.236 -branch/repository. 15.237 - 15.238 -If you're more in the ``power user'' category (\emph{and} your 15.239 -collaborators are too), there is an alternative way of handling 15.240 -branches that you can consider. I've already mentioned the 15.241 -human-level distinction between ``small picture'' and ``big picture'' 15.242 -branches. While Mercurial works with multiple ``small picture'' 15.243 -branches in a repository all the time (for example after you pull 15.244 -changes in, but before you merge them), it can \emph{also} work with 15.245 -multiple ``big picture'' branches. 15.246 - 15.247 -The key to working this way is that Mercurial lets you assign a 15.248 -persistent \emph{name} to a branch. There always exists a branch 15.249 -named \texttt{default}. Even before you start naming branches 15.250 -yourself, you can find traces of the \texttt{default} branch if you 15.251 -look for them. 15.252 - 15.253 -As an example, when you run the \hgcmd{commit} command, and it pops up 15.254 -your editor so that you can enter a commit message, look for a line 15.255 -that contains the text ``\texttt{HG: branch default}'' at the bottom. 15.256 -This is telling you that your commit will occur on the branch named 15.257 -\texttt{default}. 15.258 - 15.259 -To start working with named branches, use the \hgcmd{branches} 15.260 -command. This command lists the named branches already present in 15.261 -your repository, telling you which changeset is the tip of each. 15.262 -\interaction{branch-named.branches} 15.263 -Since you haven't created any named branches yet, the only one that 15.264 -exists is \texttt{default}. 15.265 - 15.266 -To find out what the ``current'' branch is, run the \hgcmd{branch} 15.267 -command, giving it no arguments. This tells you what branch the 15.268 -parent of the current changeset is on. 15.269 -\interaction{branch-named.branch} 15.270 - 15.271 -To create a new branch, run the \hgcmd{branch} command again. This 15.272 -time, give it one argument: the name of the branch you want to create. 15.273 -\interaction{branch-named.create} 15.274 - 15.275 -After you've created a branch, you might wonder what effect the 15.276 -\hgcmd{branch} command has had. What do the \hgcmd{status} and 15.277 -\hgcmd{tip} commands report? 15.278 -\interaction{branch-named.status} 15.279 -Nothing has changed in the working directory, and there's been no new 15.280 -history created. As this suggests, running the \hgcmd{branch} command 15.281 -has no permanent effect; it only tells Mercurial what branch name to 15.282 -use the \emph{next} time you commit a changeset. 15.283 - 15.284 -When you commit a change, Mercurial records the name of the branch on 15.285 -which you committed. Once you've switched from the \texttt{default} 15.286 -branch to another and committed, you'll see the name of the new branch 15.287 -show up in the output of \hgcmd{log}, \hgcmd{tip}, and other commands 15.288 -that display the same kind of output. 15.289 -\interaction{branch-named.commit} 15.290 -The \hgcmd{log}-like commands will print the branch name of every 15.291 -changeset that's not on the \texttt{default} branch. As a result, if 15.292 -you never use named branches, you'll never see this information. 15.293 - 15.294 -Once you've named a branch and committed a change with that name, 15.295 -every subsequent commit that descends from that change will inherit 15.296 -the same branch name. You can change the name of a branch at any 15.297 -time, using the \hgcmd{branch} command. 15.298 -\interaction{branch-named.rebranch} 15.299 -In practice, this is something you won't do very often, as branch 15.300 -names tend to have fairly long lifetimes. (This isn't a rule, just an 15.301 -observation.) 15.302 - 15.303 -\section{Dealing with multiple named branches in a repository} 15.304 - 15.305 -If you have more than one named branch in a repository, Mercurial will 15.306 -remember the branch that your working directory on when you start a 15.307 -command like \hgcmd{update} or \hgcmdargs{pull}{-u}. It will update 15.308 -the working directory to the tip of this branch, no matter what the 15.309 -``repo-wide'' tip is. To update to a revision that's on a different 15.310 -named branch, you may need to use the \hgopt{update}{-C} option to 15.311 -\hgcmd{update}. 15.312 - 15.313 -This behaviour is a little subtle, so let's see it in action. First, 15.314 -let's remind ourselves what branch we're currently on, and what 15.315 -branches are in our repository. 15.316 -\interaction{branch-named.parents} 15.317 -We're on the \texttt{bar} branch, but there also exists an older 15.318 -\hgcmd{foo} branch. 15.319 - 15.320 -We can \hgcmd{update} back and forth between the tips of the 15.321 -\texttt{foo} and \texttt{bar} branches without needing to use the 15.322 -\hgopt{update}{-C} option, because this only involves going backwards 15.323 -and forwards linearly through our change history. 15.324 -\interaction{branch-named.update-switchy} 15.325 - 15.326 -If we go back to the \texttt{foo} branch and then run \hgcmd{update}, 15.327 -it will keep us on \texttt{foo}, not move us to the tip of 15.328 -\texttt{bar}. 15.329 -\interaction{branch-named.update-nothing} 15.330 - 15.331 -Committing a new change on the \texttt{foo} branch introduces a new 15.332 -head. 15.333 -\interaction{branch-named.foo-commit} 15.334 - 15.335 -\section{Branch names and merging} 15.336 - 15.337 -As you've probably noticed, merges in Mercurial are not symmetrical. 15.338 -Let's say our repository has two heads, 17 and 23. If I 15.339 -\hgcmd{update} to 17 and then \hgcmd{merge} with 23, Mercurial records 15.340 -17 as the first parent of the merge, and 23 as the second. Whereas if 15.341 -I \hgcmd{update} to 23 and then \hgcmd{merge} with 17, it records 23 15.342 -as the first parent, and 17 as the second. 15.343 - 15.344 -This affects Mercurial's choice of branch name when you merge. After 15.345 -a merge, Mercurial will retain the branch name of the first parent 15.346 -when you commit the result of the merge. If your first parent's 15.347 -branch name is \texttt{foo}, and you merge with \texttt{bar}, the 15.348 -branch name will still be \texttt{foo} after you merge. 15.349 - 15.350 -It's not unusual for a repository to contain multiple heads, each with 15.351 -the same branch name. Let's say I'm working on the \texttt{foo} 15.352 -branch, and so are you. We commit different changes; I pull your 15.353 -changes; I now have two heads, each claiming to be on the \texttt{foo} 15.354 -branch. The result of a merge will be a single head on the 15.355 -\texttt{foo} branch, as you might hope. 15.356 - 15.357 -But if I'm working on the \texttt{bar} branch, and I merge work from 15.358 -the \texttt{foo} branch, the result will remain on the \texttt{bar} 15.359 -branch. 15.360 -\interaction{branch-named.merge} 15.361 - 15.362 -To give a more concrete example, if I'm working on the 15.363 -\texttt{bleeding-edge} branch, and I want to bring in the latest fixes 15.364 -from the \texttt{stable} branch, Mercurial will choose the ``right'' 15.365 -(\texttt{bleeding-edge}) branch name when I pull and merge from 15.366 -\texttt{stable}. 15.367 - 15.368 -\section{Branch naming is generally useful} 15.369 - 15.370 -You shouldn't think of named branches as applicable only to situations 15.371 -where you have multiple long-lived branches cohabiting in a single 15.372 -repository. They're very useful even in the one-branch-per-repository 15.373 -case. 15.374 - 15.375 -In the simplest case, giving a name to each branch gives you a 15.376 -permanent record of which branch a changeset originated on. This 15.377 -gives you more context when you're trying to follow the history of a 15.378 -long-lived branchy project. 15.379 - 15.380 -If you're working with shared repositories, you can set up a 15.381 -\hook{pretxnchangegroup} hook on each that will block incoming changes 15.382 -that have the ``wrong'' branch name. This provides a simple, but 15.383 -effective, defence against people accidentally pushing changes from a 15.384 -``bleeding edge'' branch to a ``stable'' branch. Such a hook might 15.385 -look like this inside the shared repo's \hgrc. 15.386 -\begin{codesample2} 15.387 - [hooks] 15.388 - pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch 15.389 -\end{codesample2} 15.390 - 15.391 -%%% Local Variables: 15.392 -%%% mode: latex 15.393 -%%% TeX-master: "00book" 15.394 -%%% End:
16.1 --- a/en/ch09-undo.tex Thu Mar 05 21:52:23 2009 +0200 16.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 16.3 @@ -1,767 +0,0 @@ 16.4 -\chapter{Finding and fixing your mistakes} 16.5 -\label{chap:undo} 16.6 - 16.7 -To err might be human, but to really handle the consequences well 16.8 -takes a top-notch revision control system. In this chapter, we'll 16.9 -discuss some of the techniques you can use when you find that a 16.10 -problem has crept into your project. Mercurial has some highly 16.11 -capable features that will help you to isolate the sources of 16.12 -problems, and to handle them appropriately. 16.13 - 16.14 -\section{Erasing local history} 16.15 - 16.16 -\subsection{The accidental commit} 16.17 - 16.18 -I have the occasional but persistent problem of typing rather more 16.19 -quickly than I can think, which sometimes results in me committing a 16.20 -changeset that is either incomplete or plain wrong. In my case, the 16.21 -usual kind of incomplete changeset is one in which I've created a new 16.22 -source file, but forgotten to \hgcmd{add} it. A ``plain wrong'' 16.23 -changeset is not as common, but no less annoying. 16.24 - 16.25 -\subsection{Rolling back a transaction} 16.26 -\label{sec:undo:rollback} 16.27 - 16.28 -In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats 16.29 -each modification of a repository as a \emph{transaction}. Every time 16.30 -you commit a changeset or pull changes from another repository, 16.31 -Mercurial remembers what you did. You can undo, or \emph{roll back}, 16.32 -exactly one of these actions using the \hgcmd{rollback} command. (See 16.33 -section~\ref{sec:undo:rollback-after-push} for an important caveat 16.34 -about the use of this command.) 16.35 - 16.36 -Here's a mistake that I often find myself making: committing a change 16.37 -in which I've created a new file, but forgotten to \hgcmd{add} it. 16.38 -\interaction{rollback.commit} 16.39 -Looking at the output of \hgcmd{status} after the commit immediately 16.40 -confirms the error. 16.41 -\interaction{rollback.status} 16.42 -The commit captured the changes to the file \filename{a}, but not the 16.43 -new file \filename{b}. If I were to push this changeset to a 16.44 -repository that I shared with a colleague, the chances are high that 16.45 -something in \filename{a} would refer to \filename{b}, which would not 16.46 -be present in their repository when they pulled my changes. I would 16.47 -thus become the object of some indignation. 16.48 - 16.49 -However, luck is with me---I've caught my error before I pushed the 16.50 -changeset. I use the \hgcmd{rollback} command, and Mercurial makes 16.51 -that last changeset vanish. 16.52 -\interaction{rollback.rollback} 16.53 -Notice that the changeset is no longer present in the repository's 16.54 -history, and the working directory once again thinks that the file 16.55 -\filename{a} is modified. The commit and rollback have left the 16.56 -working directory exactly as it was prior to the commit; the changeset 16.57 -has been completely erased. I can now safely \hgcmd{add} the file 16.58 -\filename{b}, and rerun my commit. 16.59 -\interaction{rollback.add} 16.60 - 16.61 -\subsection{The erroneous pull} 16.62 - 16.63 -It's common practice with Mercurial to maintain separate development 16.64 -branches of a project in different repositories. Your development 16.65 -team might have one shared repository for your project's ``0.9'' 16.66 -release, and another, containing different changes, for the ``1.0'' 16.67 -release. 16.68 - 16.69 -Given this, you can imagine that the consequences could be messy if 16.70 -you had a local ``0.9'' repository, and accidentally pulled changes 16.71 -from the shared ``1.0'' repository into it. At worst, you could be 16.72 -paying insufficient attention, and push those changes into the shared 16.73 -``0.9'' tree, confusing your entire team (but don't worry, we'll 16.74 -return to this horror scenario later). However, it's more likely that 16.75 -you'll notice immediately, because Mercurial will display the URL it's 16.76 -pulling from, or you will see it pull a suspiciously large number of 16.77 -changes into the repository. 16.78 - 16.79 -The \hgcmd{rollback} command will work nicely to expunge all of the 16.80 -changesets that you just pulled. Mercurial groups all changes from 16.81 -one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is 16.82 -all you need to undo this mistake. 16.83 - 16.84 -\subsection{Rolling back is useless once you've pushed} 16.85 -\label{sec:undo:rollback-after-push} 16.86 - 16.87 -The value of the \hgcmd{rollback} command drops to zero once you've 16.88 -pushed your changes to another repository. Rolling back a change 16.89 -makes it disappear entirely, but \emph{only} in the repository in 16.90 -which you perform the \hgcmd{rollback}. Because a rollback eliminates 16.91 -history, there's no way for the disappearance of a change to propagate 16.92 -between repositories. 16.93 - 16.94 -If you've pushed a change to another repository---particularly if it's 16.95 -a shared repository---it has essentially ``escaped into the wild,'' 16.96 -and you'll have to recover from your mistake in a different way. What 16.97 -will happen if you push a changeset somewhere, then roll it back, then 16.98 -pull from the repository you pushed to, is that the changeset will 16.99 -reappear in your repository. 16.100 - 16.101 -(If you absolutely know for sure that the change you want to roll back 16.102 -is the most recent change in the repository that you pushed to, 16.103 -\emph{and} you know that nobody else could have pulled it from that 16.104 -repository, you can roll back the changeset there, too, but you really 16.105 -should really not rely on this working reliably. If you do this, 16.106 -sooner or later a change really will make it into a repository that 16.107 -you don't directly control (or have forgotten about), and come back to 16.108 -bite you.) 16.109 - 16.110 -\subsection{You can only roll back once} 16.111 - 16.112 -Mercurial stores exactly one transaction in its transaction log; that 16.113 -transaction is the most recent one that occurred in the repository. 16.114 -This means that you can only roll back one transaction. If you expect 16.115 -to be able to roll back one transaction, then its predecessor, this is 16.116 -not the behaviour you will get. 16.117 -\interaction{rollback.twice} 16.118 -Once you've rolled back one transaction in a repository, you can't 16.119 -roll back again in that repository until you perform another commit or 16.120 -pull. 16.121 - 16.122 -\section{Reverting the mistaken change} 16.123 - 16.124 -If you make a modification to a file, and decide that you really 16.125 -didn't want to change the file at all, and you haven't yet committed 16.126 -your changes, the \hgcmd{revert} command is the one you'll need. It 16.127 -looks at the changeset that's the parent of the working directory, and 16.128 -restores the contents of the file to their state as of that changeset. 16.129 -(That's a long-winded way of saying that, in the normal case, it 16.130 -undoes your modifications.) 16.131 - 16.132 -Let's illustrate how the \hgcmd{revert} command works with yet another 16.133 -small example. We'll begin by modifying a file that Mercurial is 16.134 -already tracking. 16.135 -\interaction{daily.revert.modify} 16.136 -If we don't want that change, we can simply \hgcmd{revert} the file. 16.137 -\interaction{daily.revert.unmodify} 16.138 -The \hgcmd{revert} command provides us with an extra degree of safety 16.139 -by saving our modified file with a \filename{.orig} extension. 16.140 -\interaction{daily.revert.status} 16.141 - 16.142 -Here is a summary of the cases that the \hgcmd{revert} command can 16.143 -deal with. We will describe each of these in more detail in the 16.144 -section that follows. 16.145 -\begin{itemize} 16.146 -\item If you modify a file, it will restore the file to its unmodified 16.147 - state. 16.148 -\item If you \hgcmd{add} a file, it will undo the ``added'' state of 16.149 - the file, but leave the file itself untouched. 16.150 -\item If you delete a file without telling Mercurial, it will restore 16.151 - the file to its unmodified contents. 16.152 -\item If you use the \hgcmd{remove} command to remove a file, it will 16.153 - undo the ``removed'' state of the file, and restore the file to its 16.154 - unmodified contents. 16.155 -\end{itemize} 16.156 - 16.157 -\subsection{File management errors} 16.158 -\label{sec:undo:mgmt} 16.159 - 16.160 -The \hgcmd{revert} command is useful for more than just modified 16.161 -files. It lets you reverse the results of all of Mercurial's file 16.162 -management commands---\hgcmd{add}, \hgcmd{remove}, and so on. 16.163 - 16.164 -If you \hgcmd{add} a file, then decide that in fact you don't want 16.165 -Mercurial to track it, use \hgcmd{revert} to undo the add. Don't 16.166 -worry; Mercurial will not modify the file in any way. It will just 16.167 -``unmark'' the file. 16.168 -\interaction{daily.revert.add} 16.169 - 16.170 -Similarly, if you ask Mercurial to \hgcmd{remove} a file, you can use 16.171 -\hgcmd{revert} to restore it to the contents it had as of the parent 16.172 -of the working directory. 16.173 -\interaction{daily.revert.remove} 16.174 -This works just as well for a file that you deleted by hand, without 16.175 -telling Mercurial (recall that in Mercurial terminology, this kind of 16.176 -file is called ``missing''). 16.177 -\interaction{daily.revert.missing} 16.178 - 16.179 -If you revert a \hgcmd{copy}, the copied-to file remains in your 16.180 -working directory afterwards, untracked. Since a copy doesn't affect 16.181 -the copied-from file in any way, Mercurial doesn't do anything with 16.182 -the copied-from file. 16.183 -\interaction{daily.revert.copy} 16.184 - 16.185 -\subsubsection{A slightly special case: reverting a rename} 16.186 - 16.187 -If you \hgcmd{rename} a file, there is one small detail that 16.188 -you should remember. When you \hgcmd{revert} a rename, it's not 16.189 -enough to provide the name of the renamed-to file, as you can see 16.190 -here. 16.191 -\interaction{daily.revert.rename} 16.192 -As you can see from the output of \hgcmd{status}, the renamed-to file 16.193 -is no longer identified as added, but the renamed-\emph{from} file is 16.194 -still removed! This is counter-intuitive (at least to me), but at 16.195 -least it's easy to deal with. 16.196 -\interaction{daily.revert.rename-orig} 16.197 -So remember, to revert a \hgcmd{rename}, you must provide \emph{both} 16.198 -the source and destination names. 16.199 - 16.200 -% TODO: the output doesn't look like it will be removed! 16.201 - 16.202 -(By the way, if you rename a file, then modify the renamed-to file, 16.203 -then revert both components of the rename, when Mercurial restores the 16.204 -file that was removed as part of the rename, it will be unmodified. 16.205 -If you need the modifications in the renamed-to file to show up in the 16.206 -renamed-from file, don't forget to copy them over.) 16.207 - 16.208 -These fiddly aspects of reverting a rename arguably constitute a small 16.209 -bug in Mercurial. 16.210 - 16.211 -\section{Dealing with committed changes} 16.212 - 16.213 -Consider a case where you have committed a change $a$, and another 16.214 -change $b$ on top of it; you then realise that change $a$ was 16.215 -incorrect. Mercurial lets you ``back out'' an entire changeset 16.216 -automatically, and building blocks that let you reverse part of a 16.217 -changeset by hand. 16.218 - 16.219 -Before you read this section, here's something to keep in mind: the 16.220 -\hgcmd{backout} command undoes changes by \emph{adding} history, not 16.221 -by modifying or erasing it. It's the right tool to use if you're 16.222 -fixing bugs, but not if you're trying to undo some change that has 16.223 -catastrophic consequences. To deal with those, see 16.224 -section~\ref{sec:undo:aaaiiieee}. 16.225 - 16.226 -\subsection{Backing out a changeset} 16.227 - 16.228 -The \hgcmd{backout} command lets you ``undo'' the effects of an entire 16.229 -changeset in an automated fashion. Because Mercurial's history is 16.230 -immutable, this command \emph{does not} get rid of the changeset you 16.231 -want to undo. Instead, it creates a new changeset that 16.232 -\emph{reverses} the effect of the to-be-undone changeset. 16.233 - 16.234 -The operation of the \hgcmd{backout} command is a little intricate, so 16.235 -let's illustrate it with some examples. First, we'll create a 16.236 -repository with some simple changes. 16.237 -\interaction{backout.init} 16.238 - 16.239 -The \hgcmd{backout} command takes a single changeset ID as its 16.240 -argument; this is the changeset to back out. Normally, 16.241 -\hgcmd{backout} will drop you into a text editor to write a commit 16.242 -message, so you can record why you're backing the change out. In this 16.243 -example, we provide a commit message on the command line using the 16.244 -\hgopt{backout}{-m} option. 16.245 - 16.246 -\subsection{Backing out the tip changeset} 16.247 - 16.248 -We're going to start by backing out the last changeset we committed. 16.249 -\interaction{backout.simple} 16.250 -You can see that the second line from \filename{myfile} is no longer 16.251 -present. Taking a look at the output of \hgcmd{log} gives us an idea 16.252 -of what the \hgcmd{backout} command has done. 16.253 -\interaction{backout.simple.log} 16.254 -Notice that the new changeset that \hgcmd{backout} has created is a 16.255 -child of the changeset we backed out. It's easier to see this in 16.256 -figure~\ref{fig:undo:backout}, which presents a graphical view of the 16.257 -change history. As you can see, the history is nice and linear. 16.258 - 16.259 -\begin{figure}[htb] 16.260 - \centering 16.261 - \grafix{undo-simple} 16.262 - \caption{Backing out a change using the \hgcmd{backout} command} 16.263 - \label{fig:undo:backout} 16.264 -\end{figure} 16.265 - 16.266 -\subsection{Backing out a non-tip change} 16.267 - 16.268 -If you want to back out a change other than the last one you 16.269 -committed, pass the \hgopt{backout}{--merge} option to the 16.270 -\hgcmd{backout} command. 16.271 -\interaction{backout.non-tip.clone} 16.272 -This makes backing out any changeset a ``one-shot'' operation that's 16.273 -usually simple and fast. 16.274 -\interaction{backout.non-tip.backout} 16.275 - 16.276 -If you take a look at the contents of \filename{myfile} after the 16.277 -backout finishes, you'll see that the first and third changes are 16.278 -present, but not the second. 16.279 -\interaction{backout.non-tip.cat} 16.280 - 16.281 -As the graphical history in figure~\ref{fig:undo:backout-non-tip} 16.282 -illustrates, Mercurial actually commits \emph{two} changes in this 16.283 -kind of situation (the box-shaped nodes are the ones that Mercurial 16.284 -commits automatically). Before Mercurial begins the backout process, 16.285 -it first remembers what the current parent of the working directory 16.286 -is. It then backs out the target changeset, and commits that as a 16.287 -changeset. Finally, it merges back to the previous parent of the 16.288 -working directory, and commits the result of the merge. 16.289 - 16.290 -% TODO: to me it looks like mercurial doesn't commit the second merge automatically! 16.291 - 16.292 -\begin{figure}[htb] 16.293 - \centering 16.294 - \grafix{undo-non-tip} 16.295 - \caption{Automated backout of a non-tip change using the \hgcmd{backout} command} 16.296 - \label{fig:undo:backout-non-tip} 16.297 -\end{figure} 16.298 - 16.299 -The result is that you end up ``back where you were'', only with some 16.300 -extra history that undoes the effect of the changeset you wanted to 16.301 -back out. 16.302 - 16.303 -\subsubsection{Always use the \hgopt{backout}{--merge} option} 16.304 - 16.305 -In fact, since the \hgopt{backout}{--merge} option will do the ``right 16.306 -thing'' whether or not the changeset you're backing out is the tip 16.307 -(i.e.~it won't try to merge if it's backing out the tip, since there's 16.308 -no need), you should \emph{always} use this option when you run the 16.309 -\hgcmd{backout} command. 16.310 - 16.311 -\subsection{Gaining more control of the backout process} 16.312 - 16.313 -While I've recommended that you always use the 16.314 -\hgopt{backout}{--merge} option when backing out a change, the 16.315 -\hgcmd{backout} command lets you decide how to merge a backout 16.316 -changeset. Taking control of the backout process by hand is something 16.317 -you will rarely need to do, but it can be useful to understand what 16.318 -the \hgcmd{backout} command is doing for you automatically. To 16.319 -illustrate this, let's clone our first repository, but omit the 16.320 -backout change that it contains. 16.321 - 16.322 -\interaction{backout.manual.clone} 16.323 -As with our earlier example, We'll commit a third changeset, then back 16.324 -out its parent, and see what happens. 16.325 -\interaction{backout.manual.backout} 16.326 -Our new changeset is again a descendant of the changeset we backout 16.327 -out; it's thus a new head, \emph{not} a descendant of the changeset 16.328 -that was the tip. The \hgcmd{backout} command was quite explicit in 16.329 -telling us this. 16.330 -\interaction{backout.manual.log} 16.331 - 16.332 -Again, it's easier to see what has happened by looking at a graph of 16.333 -the revision history, in figure~\ref{fig:undo:backout-manual}. This 16.334 -makes it clear that when we use \hgcmd{backout} to back out a change 16.335 -other than the tip, Mercurial adds a new head to the repository (the 16.336 -change it committed is box-shaped). 16.337 - 16.338 -\begin{figure}[htb] 16.339 - \centering 16.340 - \grafix{undo-manual} 16.341 - \caption{Backing out a change using the \hgcmd{backout} command} 16.342 - \label{fig:undo:backout-manual} 16.343 -\end{figure} 16.344 - 16.345 -After the \hgcmd{backout} command has completed, it leaves the new 16.346 -``backout'' changeset as the parent of the working directory. 16.347 -\interaction{backout.manual.parents} 16.348 -Now we have two isolated sets of changes. 16.349 -\interaction{backout.manual.heads} 16.350 - 16.351 -Let's think about what we expect to see as the contents of 16.352 -\filename{myfile} now. The first change should be present, because 16.353 -we've never backed it out. The second change should be missing, as 16.354 -that's the change we backed out. Since the history graph shows the 16.355 -third change as a separate head, we \emph{don't} expect to see the 16.356 -third change present in \filename{myfile}. 16.357 -\interaction{backout.manual.cat} 16.358 -To get the third change back into the file, we just do a normal merge 16.359 -of our two heads. 16.360 -\interaction{backout.manual.merge} 16.361 -Afterwards, the graphical history of our repository looks like 16.362 -figure~\ref{fig:undo:backout-manual-merge}. 16.363 - 16.364 -\begin{figure}[htb] 16.365 - \centering 16.366 - \grafix{undo-manual-merge} 16.367 - \caption{Manually merging a backout change} 16.368 - \label{fig:undo:backout-manual-merge} 16.369 -\end{figure} 16.370 - 16.371 -\subsection{Why \hgcmd{backout} works as it does} 16.372 - 16.373 -Here's a brief description of how the \hgcmd{backout} command works. 16.374 -\begin{enumerate} 16.375 -\item It ensures that the working directory is ``clean'', i.e.~that 16.376 - the output of \hgcmd{status} would be empty. 16.377 -\item It remembers the current parent of the working directory. Let's 16.378 - call this changeset \texttt{orig} 16.379 -\item It does the equivalent of a \hgcmd{update} to sync the working 16.380 - directory to the changeset you want to back out. Let's call this 16.381 - changeset \texttt{backout} 16.382 -\item It finds the parent of that changeset. Let's call that 16.383 - changeset \texttt{parent}. 16.384 -\item For each file that the \texttt{backout} changeset affected, it 16.385 - does the equivalent of a \hgcmdargs{revert}{-r parent} on that file, 16.386 - to restore it to the contents it had before that changeset was 16.387 - committed. 16.388 -\item It commits the result as a new changeset. This changeset has 16.389 - \texttt{backout} as its parent. 16.390 -\item If you specify \hgopt{backout}{--merge} on the command line, it 16.391 - merges with \texttt{orig}, and commits the result of the merge. 16.392 -\end{enumerate} 16.393 - 16.394 -An alternative way to implement the \hgcmd{backout} command would be 16.395 -to \hgcmd{export} the to-be-backed-out changeset as a diff, then use 16.396 -the \cmdopt{patch}{--reverse} option to the \command{patch} command to 16.397 -reverse the effect of the change without fiddling with the working 16.398 -directory. This sounds much simpler, but it would not work nearly as 16.399 -well. 16.400 - 16.401 -The reason that \hgcmd{backout} does an update, a commit, a merge, and 16.402 -another commit is to give the merge machinery the best chance to do a 16.403 -good job when dealing with all the changes \emph{between} the change 16.404 -you're backing out and the current tip. 16.405 - 16.406 -If you're backing out a changeset that's~100 revisions back in your 16.407 -project's history, the chances that the \command{patch} command will 16.408 -be able to apply a reverse diff cleanly are not good, because 16.409 -intervening changes are likely to have ``broken the context'' that 16.410 -\command{patch} uses to determine whether it can apply a patch (if 16.411 -this sounds like gibberish, see \ref{sec:mq:patch} for a 16.412 -discussion of the \command{patch} command). Also, Mercurial's merge 16.413 -machinery will handle files and directories being renamed, permission 16.414 -changes, and modifications to binary files, none of which 16.415 -\command{patch} can deal with. 16.416 - 16.417 -\section{Changes that should never have been} 16.418 -\label{sec:undo:aaaiiieee} 16.419 - 16.420 -Most of the time, the \hgcmd{backout} command is exactly what you need 16.421 -if you want to undo the effects of a change. It leaves a permanent 16.422 -record of exactly what you did, both when committing the original 16.423 -changeset and when you cleaned up after it. 16.424 - 16.425 -On rare occasions, though, you may find that you've committed a change 16.426 -that really should not be present in the repository at all. For 16.427 -example, it would be very unusual, and usually considered a mistake, 16.428 -to commit a software project's object files as well as its source 16.429 -files. Object files have almost no intrinsic value, and they're 16.430 -\emph{big}, so they increase the size of the repository and the amount 16.431 -of time it takes to clone or pull changes. 16.432 - 16.433 -Before I discuss the options that you have if you commit a ``brown 16.434 -paper bag'' change (the kind that's so bad that you want to pull a 16.435 -brown paper bag over your head), let me first discuss some approaches 16.436 -that probably won't work. 16.437 - 16.438 -Since Mercurial treats history as accumulative---every change builds 16.439 -on top of all changes that preceded it---you generally can't just make 16.440 -disastrous changes disappear. The one exception is when you've just 16.441 -committed a change, and it hasn't been pushed or pulled into another 16.442 -repository. That's when you can safely use the \hgcmd{rollback} 16.443 -command, as I detailed in section~\ref{sec:undo:rollback}. 16.444 - 16.445 -After you've pushed a bad change to another repository, you 16.446 -\emph{could} still use \hgcmd{rollback} to make your local copy of the 16.447 -change disappear, but it won't have the consequences you want. The 16.448 -change will still be present in the remote repository, so it will 16.449 -reappear in your local repository the next time you pull. 16.450 - 16.451 -If a situation like this arises, and you know which repositories your 16.452 -bad change has propagated into, you can \emph{try} to get rid of the 16.453 -changeefrom \emph{every} one of those repositories. This is, of 16.454 -course, not a satisfactory solution: if you miss even a single 16.455 -repository while you're expunging, the change is still ``in the 16.456 -wild'', and could propagate further. 16.457 - 16.458 -If you've committed one or more changes \emph{after} the change that 16.459 -you'd like to see disappear, your options are further reduced. 16.460 -Mercurial doesn't provide a way to ``punch a hole'' in history, 16.461 -leaving changesets intact. 16.462 - 16.463 -XXX This needs filling out. The \texttt{hg-replay} script in the 16.464 -\texttt{examples} directory works, but doesn't handle merge 16.465 -changesets. Kind of an important omission. 16.466 - 16.467 -\subsection{Protect yourself from ``escaped'' changes} 16.468 - 16.469 -If you've committed some changes to your local repository and they've 16.470 -been pushed or pulled somewhere else, this isn't necessarily a 16.471 -disaster. You can protect yourself ahead of time against some classes 16.472 -of bad changeset. This is particularly easy if your team usually 16.473 -pulls changes from a central repository. 16.474 - 16.475 -By configuring some hooks on that repository to validate incoming 16.476 -changesets (see chapter~\ref{chap:hook}), you can automatically 16.477 -prevent some kinds of bad changeset from being pushed to the central 16.478 -repository at all. With such a configuration in place, some kinds of 16.479 -bad changeset will naturally tend to ``die out'' because they can't 16.480 -propagate into the central repository. Better yet, this happens 16.481 -without any need for explicit intervention. 16.482 - 16.483 -For instance, an incoming change hook that verifies that a changeset 16.484 -will actually compile can prevent people from inadvertantly ``breaking 16.485 -the build''. 16.486 - 16.487 -\section{Finding the source of a bug} 16.488 -\label{sec:undo:bisect} 16.489 - 16.490 -While it's all very well to be able to back out a changeset that 16.491 -introduced a bug, this requires that you know which changeset to back 16.492 -out. Mercurial provides an invaluable command, called 16.493 -\hgcmd{bisect}, that helps you to automate this process and accomplish 16.494 -it very efficiently. 16.495 - 16.496 -The idea behind the \hgcmd{bisect} command is that a changeset has 16.497 -introduced some change of behaviour that you can identify with a 16.498 -simple binary test. You don't know which piece of code introduced the 16.499 -change, but you know how to test for the presence of the bug. The 16.500 -\hgcmd{bisect} command uses your test to direct its search for the 16.501 -changeset that introduced the code that caused the bug. 16.502 - 16.503 -Here are a few scenarios to help you understand how you might apply 16.504 -this command. 16.505 -\begin{itemize} 16.506 -\item The most recent version of your software has a bug that you 16.507 - remember wasn't present a few weeks ago, but you don't know when it 16.508 - was introduced. Here, your binary test checks for the presence of 16.509 - that bug. 16.510 -\item You fixed a bug in a rush, and now it's time to close the entry 16.511 - in your team's bug database. The bug database requires a changeset 16.512 - ID when you close an entry, but you don't remember which changeset 16.513 - you fixed the bug in. Once again, your binary test checks for the 16.514 - presence of the bug. 16.515 -\item Your software works correctly, but runs~15\% slower than the 16.516 - last time you measured it. You want to know which changeset 16.517 - introduced the performance regression. In this case, your binary 16.518 - test measures the performance of your software, to see whether it's 16.519 - ``fast'' or ``slow''. 16.520 -\item The sizes of the components of your project that you ship 16.521 - exploded recently, and you suspect that something changed in the way 16.522 - you build your project. 16.523 -\end{itemize} 16.524 - 16.525 -From these examples, it should be clear that the \hgcmd{bisect} 16.526 -command is not useful only for finding the sources of bugs. You can 16.527 -use it to find any ``emergent property'' of a repository (anything 16.528 -that you can't find from a simple text search of the files in the 16.529 -tree) for which you can write a binary test. 16.530 - 16.531 -We'll introduce a little bit of terminology here, just to make it 16.532 -clear which parts of the search process are your responsibility, and 16.533 -which are Mercurial's. A \emph{test} is something that \emph{you} run 16.534 -when \hgcmd{bisect} chooses a changeset. A \emph{probe} is what 16.535 -\hgcmd{bisect} runs to tell whether a revision is good. Finally, 16.536 -we'll use the word ``bisect'', as both a noun and a verb, to stand in 16.537 -for the phrase ``search using the \hgcmd{bisect} command. 16.538 - 16.539 -One simple way to automate the searching process would be simply to 16.540 -probe every changeset. However, this scales poorly. If it took ten 16.541 -minutes to test a single changeset, and you had 10,000 changesets in 16.542 -your repository, the exhaustive approach would take on average~35 16.543 -\emph{days} to find the changeset that introduced a bug. Even if you 16.544 -knew that the bug was introduced by one of the last 500 changesets, 16.545 -and limited your search to those, you'd still be looking at over 40 16.546 -hours to find the changeset that introduced your bug. 16.547 - 16.548 -What the \hgcmd{bisect} command does is use its knowledge of the 16.549 -``shape'' of your project's revision history to perform a search in 16.550 -time proportional to the \emph{logarithm} of the number of changesets 16.551 -to check (the kind of search it performs is called a dichotomic 16.552 -search). With this approach, searching through 10,000 changesets will 16.553 -take less than three hours, even at ten minutes per test (the search 16.554 -will require about 14 tests). Limit your search to the last hundred 16.555 -changesets, and it will take only about an hour (roughly seven tests). 16.556 - 16.557 -The \hgcmd{bisect} command is aware of the ``branchy'' nature of a 16.558 -Mercurial project's revision history, so it has no problems dealing 16.559 -with branches, merges, or multiple heads in a repository. It can 16.560 -prune entire branches of history with a single probe, which is how it 16.561 -operates so efficiently. 16.562 - 16.563 -\subsection{Using the \hgcmd{bisect} command} 16.564 - 16.565 -Here's an example of \hgcmd{bisect} in action. 16.566 - 16.567 -\begin{note} 16.568 - In versions 0.9.5 and earlier of Mercurial, \hgcmd{bisect} was not a 16.569 - core command: it was distributed with Mercurial as an extension. 16.570 - This section describes the built-in command, not the old extension. 16.571 -\end{note} 16.572 - 16.573 -Now let's create a repository, so that we can try out the 16.574 -\hgcmd{bisect} command in isolation. 16.575 -\interaction{bisect.init} 16.576 -We'll simulate a project that has a bug in it in a simple-minded way: 16.577 -create trivial changes in a loop, and nominate one specific change 16.578 -that will have the ``bug''. This loop creates 35 changesets, each 16.579 -adding a single file to the repository. We'll represent our ``bug'' 16.580 -with a file that contains the text ``i have a gub''. 16.581 -\interaction{bisect.commits} 16.582 - 16.583 -The next thing that we'd like to do is figure out how to use the 16.584 -\hgcmd{bisect} command. We can use Mercurial's normal built-in help 16.585 -mechanism for this. 16.586 -\interaction{bisect.help} 16.587 - 16.588 -The \hgcmd{bisect} command works in steps. Each step proceeds as follows. 16.589 -\begin{enumerate} 16.590 -\item You run your binary test. 16.591 - \begin{itemize} 16.592 - \item If the test succeeded, you tell \hgcmd{bisect} by running the 16.593 - \hgcmdargs{bisect}{good} command. 16.594 - \item If it failed, run the \hgcmdargs{bisect}{--bad} command. 16.595 - \end{itemize} 16.596 -\item The command uses your information to decide which changeset to 16.597 - test next. 16.598 -\item It updates the working directory to that changeset, and the 16.599 - process begins again. 16.600 -\end{enumerate} 16.601 -The process ends when \hgcmd{bisect} identifies a unique changeset 16.602 -that marks the point where your test transitioned from ``succeeding'' 16.603 -to ``failing''. 16.604 - 16.605 -To start the search, we must run the \hgcmdargs{bisect}{--reset} command. 16.606 -\interaction{bisect.search.init} 16.607 - 16.608 -In our case, the binary test we use is simple: we check to see if any 16.609 -file in the repository contains the string ``i have a gub''. If it 16.610 -does, this changeset contains the change that ``caused the bug''. By 16.611 -convention, a changeset that has the property we're searching for is 16.612 -``bad'', while one that doesn't is ``good''. 16.613 - 16.614 -Most of the time, the revision to which the working directory is 16.615 -synced (usually the tip) already exhibits the problem introduced by 16.616 -the buggy change, so we'll mark it as ``bad''. 16.617 -\interaction{bisect.search.bad-init} 16.618 - 16.619 -Our next task is to nominate a changeset that we know \emph{doesn't} 16.620 -have the bug; the \hgcmd{bisect} command will ``bracket'' its search 16.621 -between the first pair of good and bad changesets. In our case, we 16.622 -know that revision~10 didn't have the bug. (I'll have more words 16.623 -about choosing the first ``good'' changeset later.) 16.624 -\interaction{bisect.search.good-init} 16.625 - 16.626 -Notice that this command printed some output. 16.627 -\begin{itemize} 16.628 -\item It told us how many changesets it must consider before it can 16.629 - identify the one that introduced the bug, and how many tests that 16.630 - will require. 16.631 -\item It updated the working directory to the next changeset to test, 16.632 - and told us which changeset it's testing. 16.633 -\end{itemize} 16.634 - 16.635 -We now run our test in the working directory. We use the 16.636 -\command{grep} command to see if our ``bad'' file is present in the 16.637 -working directory. If it is, this revision is bad; if not, this 16.638 -revision is good. 16.639 -\interaction{bisect.search.step1} 16.640 - 16.641 -This test looks like a perfect candidate for automation, so let's turn 16.642 -it into a shell function. 16.643 -\interaction{bisect.search.mytest} 16.644 -We can now run an entire test step with a single command, 16.645 -\texttt{mytest}. 16.646 -\interaction{bisect.search.step2} 16.647 -A few more invocations of our canned test step command, and we're 16.648 -done. 16.649 -\interaction{bisect.search.rest} 16.650 - 16.651 -Even though we had~40 changesets to search through, the \hgcmd{bisect} 16.652 -command let us find the changeset that introduced our ``bug'' with 16.653 -only five tests. Because the number of tests that the \hgcmd{bisect} 16.654 -command performs grows logarithmically with the number of changesets to 16.655 -search, the advantage that it has over the ``brute force'' search 16.656 -approach increases with every changeset you add. 16.657 - 16.658 -\subsection{Cleaning up after your search} 16.659 - 16.660 -When you're finished using the \hgcmd{bisect} command in a 16.661 -repository, you can use the \hgcmdargs{bisect}{reset} command to drop 16.662 -the information it was using to drive your search. The command 16.663 -doesn't use much space, so it doesn't matter if you forget to run this 16.664 -command. However, \hgcmd{bisect} won't let you start a new search in 16.665 -that repository until you do a \hgcmdargs{bisect}{reset}. 16.666 -\interaction{bisect.search.reset} 16.667 - 16.668 -\section{Tips for finding bugs effectively} 16.669 - 16.670 -\subsection{Give consistent input} 16.671 - 16.672 -The \hgcmd{bisect} command requires that you correctly report the 16.673 -result of every test you perform. If you tell it that a test failed 16.674 -when it really succeeded, it \emph{might} be able to detect the 16.675 -inconsistency. If it can identify an inconsistency in your reports, 16.676 -it will tell you that a particular changeset is both good and bad. 16.677 -However, it can't do this perfectly; it's about as likely to report 16.678 -the wrong changeset as the source of the bug. 16.679 - 16.680 -\subsection{Automate as much as possible} 16.681 - 16.682 -When I started using the \hgcmd{bisect} command, I tried a few times 16.683 -to run my tests by hand, on the command line. This is an approach 16.684 -that I, at least, am not suited to. After a few tries, I found that I 16.685 -was making enough mistakes that I was having to restart my searches 16.686 -several times before finally getting correct results. 16.687 - 16.688 -My initial problems with driving the \hgcmd{bisect} command by hand 16.689 -occurred even with simple searches on small repositories; if the 16.690 -problem you're looking for is more subtle, or the number of tests that 16.691 -\hgcmd{bisect} must perform increases, the likelihood of operator 16.692 -error ruining the search is much higher. Once I started automating my 16.693 -tests, I had much better results. 16.694 - 16.695 -The key to automated testing is twofold: 16.696 -\begin{itemize} 16.697 -\item always test for the same symptom, and 16.698 -\item always feed consistent input to the \hgcmd{bisect} command. 16.699 -\end{itemize} 16.700 -In my tutorial example above, the \command{grep} command tests for the 16.701 -symptom, and the \texttt{if} statement takes the result of this check 16.702 -and ensures that we always feed the same input to the \hgcmd{bisect} 16.703 -command. The \texttt{mytest} function marries these together in a 16.704 -reproducible way, so that every test is uniform and consistent. 16.705 - 16.706 -\subsection{Check your results} 16.707 - 16.708 -Because the output of a \hgcmd{bisect} search is only as good as the 16.709 -input you give it, don't take the changeset it reports as the 16.710 -absolute truth. A simple way to cross-check its report is to manually 16.711 -run your test at each of the following changesets: 16.712 -\begin{itemize} 16.713 -\item The changeset that it reports as the first bad revision. Your 16.714 - test should still report this as bad. 16.715 -\item The parent of that changeset (either parent, if it's a merge). 16.716 - Your test should report this changeset as good. 16.717 -\item A child of that changeset. Your test should report this 16.718 - changeset as bad. 16.719 -\end{itemize} 16.720 - 16.721 -\subsection{Beware interference between bugs} 16.722 - 16.723 -It's possible that your search for one bug could be disrupted by the 16.724 -presence of another. For example, let's say your software crashes at 16.725 -revision 100, and worked correctly at revision 50. Unknown to you, 16.726 -someone else introduced a different crashing bug at revision 60, and 16.727 -fixed it at revision 80. This could distort your results in one of 16.728 -several ways. 16.729 - 16.730 -It is possible that this other bug completely ``masks'' yours, which 16.731 -is to say that it occurs before your bug has a chance to manifest 16.732 -itself. If you can't avoid that other bug (for example, it prevents 16.733 -your project from building), and so can't tell whether your bug is 16.734 -present in a particular changeset, the \hgcmd{bisect} command cannot 16.735 -help you directly. Instead, you can mark a changeset as untested by 16.736 -running \hgcmdargs{bisect}{--skip}. 16.737 - 16.738 -A different problem could arise if your test for a bug's presence is 16.739 -not specific enough. If you check for ``my program crashes'', then 16.740 -both your crashing bug and an unrelated crashing bug that masks it 16.741 -will look like the same thing, and mislead \hgcmd{bisect}. 16.742 - 16.743 -Another useful situation in which to use \hgcmdargs{bisect}{--skip} is 16.744 -if you can't test a revision because your project was in a broken and 16.745 -hence untestable state at that revision, perhaps because someone 16.746 -checked in a change that prevented the project from building. 16.747 - 16.748 -\subsection{Bracket your search lazily} 16.749 - 16.750 -Choosing the first ``good'' and ``bad'' changesets that will mark the 16.751 -end points of your search is often easy, but it bears a little 16.752 -discussion nevertheless. From the perspective of \hgcmd{bisect}, the 16.753 -``newest'' changeset is conventionally ``bad'', and the older 16.754 -changeset is ``good''. 16.755 - 16.756 -If you're having trouble remembering when a suitable ``good'' change 16.757 -was, so that you can tell \hgcmd{bisect}, you could do worse than 16.758 -testing changesets at random. Just remember to eliminate contenders 16.759 -that can't possibly exhibit the bug (perhaps because the feature with 16.760 -the bug isn't present yet) and those where another problem masks the 16.761 -bug (as I discussed above). 16.762 - 16.763 -Even if you end up ``early'' by thousands of changesets or months of 16.764 -history, you will only add a handful of tests to the total number that 16.765 -\hgcmd{bisect} must perform, thanks to its logarithmic behaviour. 16.766 - 16.767 -%%% Local Variables: 16.768 -%%% mode: latex 16.769 -%%% TeX-master: "00book" 16.770 -%%% End:
17.1 --- a/en/ch10-hook.tex Thu Mar 05 21:52:23 2009 +0200 17.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 17.3 @@ -1,1413 +0,0 @@ 17.4 -\chapter{Handling repository events with hooks} 17.5 -\label{chap:hook} 17.6 - 17.7 -Mercurial offers a powerful mechanism to let you perform automated 17.8 -actions in response to events that occur in a repository. In some 17.9 -cases, you can even control Mercurial's response to those events. 17.10 - 17.11 -The name Mercurial uses for one of these actions is a \emph{hook}. 17.12 -Hooks are called ``triggers'' in some revision control systems, but 17.13 -the two names refer to the same idea. 17.14 - 17.15 -\section{An overview of hooks in Mercurial} 17.16 - 17.17 -Here is a brief list of the hooks that Mercurial supports. We will 17.18 -revisit each of these hooks in more detail later, in 17.19 -section~\ref{sec:hook:ref}. 17.20 - 17.21 -\begin{itemize} 17.22 -\item[\small\hook{changegroup}] This is run after a group of 17.23 - changesets has been brought into the repository from elsewhere. 17.24 -\item[\small\hook{commit}] This is run after a new changeset has been 17.25 - created in the local repository. 17.26 -\item[\small\hook{incoming}] This is run once for each new changeset 17.27 - that is brought into the repository from elsewhere. Notice the 17.28 - difference from \hook{changegroup}, which is run once per 17.29 - \emph{group} of changesets brought in. 17.30 -\item[\small\hook{outgoing}] This is run after a group of changesets 17.31 - has been transmitted from this repository. 17.32 -\item[\small\hook{prechangegroup}] This is run before starting to 17.33 - bring a group of changesets into the repository. 17.34 -\item[\small\hook{precommit}] Controlling. This is run before starting 17.35 - a commit. 17.36 -\item[\small\hook{preoutgoing}] Controlling. This is run before 17.37 - starting to transmit a group of changesets from this repository. 17.38 -\item[\small\hook{pretag}] Controlling. This is run before creating a tag. 17.39 -\item[\small\hook{pretxnchangegroup}] Controlling. This is run after a 17.40 - group of changesets has been brought into the local repository from 17.41 - another, but before the transaction completes that will make the 17.42 - changes permanent in the repository. 17.43 -\item[\small\hook{pretxncommit}] Controlling. This is run after a new 17.44 - changeset has been created in the local repository, but before the 17.45 - transaction completes that will make it permanent. 17.46 -\item[\small\hook{preupdate}] Controlling. This is run before starting 17.47 - an update or merge of the working directory. 17.48 -\item[\small\hook{tag}] This is run after a tag is created. 17.49 -\item[\small\hook{update}] This is run after an update or merge of the 17.50 - working directory has finished. 17.51 -\end{itemize} 17.52 -Each of the hooks whose description begins with the word 17.53 -``Controlling'' has the ability to determine whether an activity can 17.54 -proceed. If the hook succeeds, the activity may proceed; if it fails, 17.55 -the activity is either not permitted or undone, depending on the hook. 17.56 - 17.57 -\section{Hooks and security} 17.58 - 17.59 -\subsection{Hooks are run with your privileges} 17.60 - 17.61 -When you run a Mercurial command in a repository, and the command 17.62 -causes a hook to run, that hook runs on \emph{your} system, under 17.63 -\emph{your} user account, with \emph{your} privilege level. Since 17.64 -hooks are arbitrary pieces of executable code, you should treat them 17.65 -with an appropriate level of suspicion. Do not install a hook unless 17.66 -you are confident that you know who created it and what it does. 17.67 - 17.68 -In some cases, you may be exposed to hooks that you did not install 17.69 -yourself. If you work with Mercurial on an unfamiliar system, 17.70 -Mercurial will run hooks defined in that system's global \hgrc\ file. 17.71 - 17.72 -If you are working with a repository owned by another user, Mercurial 17.73 -can run hooks defined in that user's repository, but it will still run 17.74 -them as ``you''. For example, if you \hgcmd{pull} from that 17.75 -repository, and its \sfilename{.hg/hgrc} defines a local 17.76 -\hook{outgoing} hook, that hook will run under your user account, even 17.77 -though you don't own that repository. 17.78 - 17.79 -\begin{note} 17.80 - This only applies if you are pulling from a repository on a local or 17.81 - network filesystem. If you're pulling over http or ssh, any 17.82 - \hook{outgoing} hook will run under whatever account is executing 17.83 - the server process, on the server. 17.84 -\end{note} 17.85 - 17.86 -XXX To see what hooks are defined in a repository, use the 17.87 -\hgcmdargs{config}{hooks} command. If you are working in one 17.88 -repository, but talking to another that you do not own (e.g.~using 17.89 -\hgcmd{pull} or \hgcmd{incoming}), remember that it is the other 17.90 -repository's hooks you should be checking, not your own. 17.91 - 17.92 -\subsection{Hooks do not propagate} 17.93 - 17.94 -In Mercurial, hooks are not revision controlled, and do not propagate 17.95 -when you clone, or pull from, a repository. The reason for this is 17.96 -simple: a hook is a completely arbitrary piece of executable code. It 17.97 -runs under your user identity, with your privilege level, on your 17.98 -machine. 17.99 - 17.100 -It would be extremely reckless for any distributed revision control 17.101 -system to implement revision-controlled hooks, as this would offer an 17.102 -easily exploitable way to subvert the accounts of users of the 17.103 -revision control system. 17.104 - 17.105 -Since Mercurial does not propagate hooks, if you are collaborating 17.106 -with other people on a common project, you should not assume that they 17.107 -are using the same Mercurial hooks as you are, or that theirs are 17.108 -correctly configured. You should document the hooks you expect people 17.109 -to use. 17.110 - 17.111 -In a corporate intranet, this is somewhat easier to control, as you 17.112 -can for example provide a ``standard'' installation of Mercurial on an 17.113 -NFS filesystem, and use a site-wide \hgrc\ file to define hooks that 17.114 -all users will see. However, this too has its limits; see below. 17.115 - 17.116 -\subsection{Hooks can be overridden} 17.117 - 17.118 -Mercurial allows you to override a hook definition by redefining the 17.119 -hook. You can disable it by setting its value to the empty string, or 17.120 -change its behaviour as you wish. 17.121 - 17.122 -If you deploy a system-~or site-wide \hgrc\ file that defines some 17.123 -hooks, you should thus understand that your users can disable or 17.124 -override those hooks. 17.125 - 17.126 -\subsection{Ensuring that critical hooks are run} 17.127 - 17.128 -Sometimes you may want to enforce a policy that you do not want others 17.129 -to be able to work around. For example, you may have a requirement 17.130 -that every changeset must pass a rigorous set of tests. Defining this 17.131 -requirement via a hook in a site-wide \hgrc\ won't work for remote 17.132 -users on laptops, and of course local users can subvert it at will by 17.133 -overriding the hook. 17.134 - 17.135 -Instead, you can set up your policies for use of Mercurial so that 17.136 -people are expected to propagate changes through a well-known 17.137 -``canonical'' server that you have locked down and configured 17.138 -appropriately. 17.139 - 17.140 -One way to do this is via a combination of social engineering and 17.141 -technology. Set up a restricted-access account; users can push 17.142 -changes over the network to repositories managed by this account, but 17.143 -they cannot log into the account and run normal shell commands. In 17.144 -this scenario, a user can commit a changeset that contains any old 17.145 -garbage they want. 17.146 - 17.147 -When someone pushes a changeset to the server that everyone pulls 17.148 -from, the server will test the changeset before it accepts it as 17.149 -permanent, and reject it if it fails to pass the test suite. If 17.150 -people only pull changes from this filtering server, it will serve to 17.151 -ensure that all changes that people pull have been automatically 17.152 -vetted. 17.153 - 17.154 -\section{Care with \texttt{pretxn} hooks in a shared-access repository} 17.155 - 17.156 -If you want to use hooks to do some automated work in a repository 17.157 -that a number of people have shared access to, you need to be careful 17.158 -in how you do this. 17.159 - 17.160 -Mercurial only locks a repository when it is writing to the 17.161 -repository, and only the parts of Mercurial that write to the 17.162 -repository pay attention to locks. Write locks are necessary to 17.163 -prevent multiple simultaneous writers from scribbling on each other's 17.164 -work, corrupting the repository. 17.165 - 17.166 -Because Mercurial is careful with the order in which it reads and 17.167 -writes data, it does not need to acquire a lock when it wants to read 17.168 -data from the repository. The parts of Mercurial that read from the 17.169 -repository never pay attention to locks. This lockless reading scheme 17.170 -greatly increases performance and concurrency. 17.171 - 17.172 -With great performance comes a trade-off, though, one which has the 17.173 -potential to cause you trouble unless you're aware of it. To describe 17.174 -this requires a little detail about how Mercurial adds changesets to a 17.175 -repository and reads those changes. 17.176 - 17.177 -When Mercurial \emph{writes} metadata, it writes it straight into the 17.178 -destination file. It writes file data first, then manifest data 17.179 -(which contains pointers to the new file data), then changelog data 17.180 -(which contains pointers to the new manifest data). Before the first 17.181 -write to each file, it stores a record of where the end of the file 17.182 -was in its transaction log. If the transaction must be rolled back, 17.183 -Mercurial simply truncates each file back to the size it was before the 17.184 -transaction began. 17.185 - 17.186 -When Mercurial \emph{reads} metadata, it reads the changelog first, 17.187 -then everything else. Since a reader will only access parts of the 17.188 -manifest or file metadata that it can see in the changelog, it can 17.189 -never see partially written data. 17.190 - 17.191 -Some controlling hooks (\hook{pretxncommit} and 17.192 -\hook{pretxnchangegroup}) run when a transaction is almost complete. 17.193 -All of the metadata has been written, but Mercurial can still roll the 17.194 -transaction back and cause the newly-written data to disappear. 17.195 - 17.196 -If one of these hooks runs for long, it opens a window of time during 17.197 -which a reader can see the metadata for changesets that are not yet 17.198 -permanent, and should not be thought of as ``really there''. The 17.199 -longer the hook runs, the longer that window is open. 17.200 - 17.201 -\subsection{The problem illustrated} 17.202 - 17.203 -In principle, a good use for the \hook{pretxnchangegroup} hook would 17.204 -be to automatically build and test incoming changes before they are 17.205 -accepted into a central repository. This could let you guarantee that 17.206 -nobody can push changes to this repository that ``break the build''. 17.207 -But if a client can pull changes while they're being tested, the 17.208 -usefulness of the test is zero; an unsuspecting someone can pull 17.209 -untested changes, potentially breaking their build. 17.210 - 17.211 -The safest technological answer to this challenge is to set up such a 17.212 -``gatekeeper'' repository as \emph{unidirectional}. Let it take 17.213 -changes pushed in from the outside, but do not allow anyone to pull 17.214 -changes from it (use the \hook{preoutgoing} hook to lock it down). 17.215 -Configure a \hook{changegroup} hook so that if a build or test 17.216 -succeeds, the hook will push the new changes out to another repository 17.217 -that people \emph{can} pull from. 17.218 - 17.219 -In practice, putting a centralised bottleneck like this in place is 17.220 -not often a good idea, and transaction visibility has nothing to do 17.221 -with the problem. As the size of a project---and the time it takes to 17.222 -build and test---grows, you rapidly run into a wall with this ``try 17.223 -before you buy'' approach, where you have more changesets to test than 17.224 -time in which to deal with them. The inevitable result is frustration 17.225 -on the part of all involved. 17.226 - 17.227 -An approach that scales better is to get people to build and test 17.228 -before they push, then run automated builds and tests centrally 17.229 -\emph{after} a push, to be sure all is well. The advantage of this 17.230 -approach is that it does not impose a limit on the rate at which the 17.231 -repository can accept changes. 17.232 - 17.233 -\section{A short tutorial on using hooks} 17.234 -\label{sec:hook:simple} 17.235 - 17.236 -It is easy to write a Mercurial hook. Let's start with a hook that 17.237 -runs when you finish a \hgcmd{commit}, and simply prints the hash of 17.238 -the changeset you just created. The hook is called \hook{commit}. 17.239 - 17.240 -\begin{figure}[ht] 17.241 - \interaction{hook.simple.init} 17.242 - \caption{A simple hook that runs when a changeset is committed} 17.243 - \label{ex:hook:init} 17.244 -\end{figure} 17.245 - 17.246 -All hooks follow the pattern in example~\ref{ex:hook:init}. You add 17.247 -an entry to the \rcsection{hooks} section of your \hgrc. On the left 17.248 -is the name of the event to trigger on; on the right is the action to 17.249 -take. As you can see, you can run an arbitrary shell command in a 17.250 -hook. Mercurial passes extra information to the hook using 17.251 -environment variables (look for \envar{HG\_NODE} in the example). 17.252 - 17.253 -\subsection{Performing multiple actions per event} 17.254 - 17.255 -Quite often, you will want to define more than one hook for a 17.256 -particular kind of event, as shown in example~\ref{ex:hook:ext}. 17.257 -Mercurial lets you do this by adding an \emph{extension} to the end of 17.258 -a hook's name. You extend a hook's name by giving the name of the 17.259 -hook, followed by a full stop (the ``\texttt{.}'' character), followed 17.260 -by some more text of your choosing. For example, Mercurial will run 17.261 -both \texttt{commit.foo} and \texttt{commit.bar} when the 17.262 -\texttt{commit} event occurs. 17.263 - 17.264 -\begin{figure}[ht] 17.265 - \interaction{hook.simple.ext} 17.266 - \caption{Defining a second \hook{commit} hook} 17.267 - \label{ex:hook:ext} 17.268 -\end{figure} 17.269 - 17.270 -To give a well-defined order of execution when there are multiple 17.271 -hooks defined for an event, Mercurial sorts hooks by extension, and 17.272 -executes the hook commands in this sorted order. In the above 17.273 -example, it will execute \texttt{commit.bar} before 17.274 -\texttt{commit.foo}, and \texttt{commit} before both. 17.275 - 17.276 -It is a good idea to use a somewhat descriptive extension when you 17.277 -define a new hook. This will help you to remember what the hook was 17.278 -for. If the hook fails, you'll get an error message that contains the 17.279 -hook name and extension, so using a descriptive extension could give 17.280 -you an immediate hint as to why the hook failed (see 17.281 -section~\ref{sec:hook:perm} for an example). 17.282 - 17.283 -\subsection{Controlling whether an activity can proceed} 17.284 -\label{sec:hook:perm} 17.285 - 17.286 -In our earlier examples, we used the \hook{commit} hook, which is 17.287 -run after a commit has completed. This is one of several Mercurial 17.288 -hooks that run after an activity finishes. Such hooks have no way of 17.289 -influencing the activity itself. 17.290 - 17.291 -Mercurial defines a number of events that occur before an activity 17.292 -starts; or after it starts, but before it finishes. Hooks that 17.293 -trigger on these events have the added ability to choose whether the 17.294 -activity can continue, or will abort. 17.295 - 17.296 -The \hook{pretxncommit} hook runs after a commit has all but 17.297 -completed. In other words, the metadata representing the changeset 17.298 -has been written out to disk, but the transaction has not yet been 17.299 -allowed to complete. The \hook{pretxncommit} hook has the ability to 17.300 -decide whether the transaction can complete, or must be rolled back. 17.301 - 17.302 -If the \hook{pretxncommit} hook exits with a status code of zero, the 17.303 -transaction is allowed to complete; the commit finishes; and the 17.304 -\hook{commit} hook is run. If the \hook{pretxncommit} hook exits with 17.305 -a non-zero status code, the transaction is rolled back; the metadata 17.306 -representing the changeset is erased; and the \hook{commit} hook is 17.307 -not run. 17.308 - 17.309 -\begin{figure}[ht] 17.310 - \interaction{hook.simple.pretxncommit} 17.311 - \caption{Using the \hook{pretxncommit} hook to control commits} 17.312 - \label{ex:hook:pretxncommit} 17.313 -\end{figure} 17.314 - 17.315 -The hook in example~\ref{ex:hook:pretxncommit} checks that a commit 17.316 -comment contains a bug ID. If it does, the commit can complete. If 17.317 -not, the commit is rolled back. 17.318 - 17.319 -\section{Writing your own hooks} 17.320 - 17.321 -When you are writing a hook, you might find it useful to run Mercurial 17.322 -either with the \hggopt{-v} option, or the \rcitem{ui}{verbose} config 17.323 -item set to ``true''. When you do so, Mercurial will print a message 17.324 -before it calls each hook. 17.325 - 17.326 -\subsection{Choosing how your hook should run} 17.327 -\label{sec:hook:lang} 17.328 - 17.329 -You can write a hook either as a normal program---typically a shell 17.330 -script---or as a Python function that is executed within the Mercurial 17.331 -process. 17.332 - 17.333 -Writing a hook as an external program has the advantage that it 17.334 -requires no knowledge of Mercurial's internals. You can call normal 17.335 -Mercurial commands to get any added information you need. The 17.336 -trade-off is that external hooks are slower than in-process hooks. 17.337 - 17.338 -An in-process Python hook has complete access to the Mercurial API, 17.339 -and does not ``shell out'' to another process, so it is inherently 17.340 -faster than an external hook. It is also easier to obtain much of the 17.341 -information that a hook requires by using the Mercurial API than by 17.342 -running Mercurial commands. 17.343 - 17.344 -If you are comfortable with Python, or require high performance, 17.345 -writing your hooks in Python may be a good choice. However, when you 17.346 -have a straightforward hook to write and you don't need to care about 17.347 -performance (probably the majority of hooks), a shell script is 17.348 -perfectly fine. 17.349 - 17.350 -\subsection{Hook parameters} 17.351 -\label{sec:hook:param} 17.352 - 17.353 -Mercurial calls each hook with a set of well-defined parameters. In 17.354 -Python, a parameter is passed as a keyword argument to your hook 17.355 -function. For an external program, a parameter is passed as an 17.356 -environment variable. 17.357 - 17.358 -Whether your hook is written in Python or as a shell script, the 17.359 -hook-specific parameter names and values will be the same. A boolean 17.360 -parameter will be represented as a boolean value in Python, but as the 17.361 -number 1 (for ``true'') or 0 (for ``false'') as an environment 17.362 -variable for an external hook. If a hook parameter is named 17.363 -\texttt{foo}, the keyword argument for a Python hook will also be 17.364 -named \texttt{foo}, while the environment variable for an external 17.365 -hook will be named \texttt{HG\_FOO}. 17.366 - 17.367 -\subsection{Hook return values and activity control} 17.368 - 17.369 -A hook that executes successfully must exit with a status of zero if 17.370 -external, or return boolean ``false'' if in-process. Failure is 17.371 -indicated with a non-zero exit status from an external hook, or an 17.372 -in-process hook returning boolean ``true''. If an in-process hook 17.373 -raises an exception, the hook is considered to have failed. 17.374 - 17.375 -For a hook that controls whether an activity can proceed, zero/false 17.376 -means ``allow'', while non-zero/true/exception means ``deny''. 17.377 - 17.378 -\subsection{Writing an external hook} 17.379 - 17.380 -When you define an external hook in your \hgrc\ and the hook is run, 17.381 -its value is passed to your shell, which interprets it. This means 17.382 -that you can use normal shell constructs in the body of the hook. 17.383 - 17.384 -An executable hook is always run with its current directory set to a 17.385 -repository's root directory. 17.386 - 17.387 -Each hook parameter is passed in as an environment variable; the name 17.388 -is upper-cased, and prefixed with the string ``\texttt{HG\_}''. 17.389 - 17.390 -With the exception of hook parameters, Mercurial does not set or 17.391 -modify any environment variables when running a hook. This is useful 17.392 -to remember if you are writing a site-wide hook that may be run by a 17.393 -number of different users with differing environment variables set. 17.394 -In multi-user situations, you should not rely on environment variables 17.395 -being set to the values you have in your environment when testing the 17.396 -hook. 17.397 - 17.398 -\subsection{Telling Mercurial to use an in-process hook} 17.399 - 17.400 -The \hgrc\ syntax for defining an in-process hook is slightly 17.401 -different than for an executable hook. The value of the hook must 17.402 -start with the text ``\texttt{python:}'', and continue with the 17.403 -fully-qualified name of a callable object to use as the hook's value. 17.404 - 17.405 -The module in which a hook lives is automatically imported when a hook 17.406 -is run. So long as you have the module name and \envar{PYTHONPATH} 17.407 -right, it should ``just work''. 17.408 - 17.409 -The following \hgrc\ example snippet illustrates the syntax and 17.410 -meaning of the notions we just described. 17.411 -\begin{codesample2} 17.412 - [hooks] 17.413 - commit.example = python:mymodule.submodule.myhook 17.414 -\end{codesample2} 17.415 -When Mercurial runs the \texttt{commit.example} hook, it imports 17.416 -\texttt{mymodule.submodule}, looks for the callable object named 17.417 -\texttt{myhook}, and calls it. 17.418 - 17.419 -\subsection{Writing an in-process hook} 17.420 - 17.421 -The simplest in-process hook does nothing, but illustrates the basic 17.422 -shape of the hook API: 17.423 -\begin{codesample2} 17.424 - def myhook(ui, repo, **kwargs): 17.425 - pass 17.426 -\end{codesample2} 17.427 -The first argument to a Python hook is always a 17.428 -\pymodclass{mercurial.ui}{ui} object. The second is a repository object; 17.429 -at the moment, it is always an instance of 17.430 -\pymodclass{mercurial.localrepo}{localrepository}. Following these two 17.431 -arguments are other keyword arguments. Which ones are passed in 17.432 -depends on the hook being called, but a hook can ignore arguments it 17.433 -doesn't care about by dropping them into a keyword argument dict, as 17.434 -with \texttt{**kwargs} above. 17.435 - 17.436 -\section{Some hook examples} 17.437 - 17.438 -\subsection{Writing meaningful commit messages} 17.439 - 17.440 -It's hard to imagine a useful commit message being very short. The 17.441 -simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.go} 17.442 -will prevent you from committing a changeset with a message that is 17.443 -less than ten bytes long. 17.444 - 17.445 -\begin{figure}[ht] 17.446 - \interaction{hook.msglen.go} 17.447 - \caption{A hook that forbids overly short commit messages} 17.448 - \label{ex:hook:msglen.go} 17.449 -\end{figure} 17.450 - 17.451 -\subsection{Checking for trailing whitespace} 17.452 - 17.453 -An interesting use of a commit-related hook is to help you to write 17.454 -cleaner code. A simple example of ``cleaner code'' is the dictum that 17.455 -a change should not add any new lines of text that contain ``trailing 17.456 -whitespace''. Trailing whitespace is a series of space and tab 17.457 -characters at the end of a line of text. In most cases, trailing 17.458 -whitespace is unnecessary, invisible noise, but it is occasionally 17.459 -problematic, and people often prefer to get rid of it. 17.460 - 17.461 -You can use either the \hook{precommit} or \hook{pretxncommit} hook to 17.462 -tell whether you have a trailing whitespace problem. If you use the 17.463 -\hook{precommit} hook, the hook will not know which files you are 17.464 -committing, so it will have to check every modified file in the 17.465 -repository for trailing white space. If you want to commit a change 17.466 -to just the file \filename{foo}, but the file \filename{bar} contains 17.467 -trailing whitespace, doing a check in the \hook{precommit} hook will 17.468 -prevent you from committing \filename{foo} due to the problem with 17.469 -\filename{bar}. This doesn't seem right. 17.470 - 17.471 -Should you choose the \hook{pretxncommit} hook, the check won't occur 17.472 -until just before the transaction for the commit completes. This will 17.473 -allow you to check for problems only the exact files that are being 17.474 -committed. However, if you entered the commit message interactively 17.475 -and the hook fails, the transaction will roll back; you'll have to 17.476 -re-enter the commit message after you fix the trailing whitespace and 17.477 -run \hgcmd{commit} again. 17.478 - 17.479 -\begin{figure}[ht] 17.480 - \interaction{hook.ws.simple} 17.481 - \caption{A simple hook that checks for trailing whitespace} 17.482 - \label{ex:hook:ws.simple} 17.483 -\end{figure} 17.484 - 17.485 -Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit} 17.486 -hook that checks for trailing whitespace. This hook is short, but not 17.487 -very helpful. It exits with an error status if a change adds a line 17.488 -with trailing whitespace to any file, but does not print any 17.489 -information that might help us to identify the offending file or 17.490 -line. It also has the nice property of not paying attention to 17.491 -unmodified lines; only lines that introduce new trailing whitespace 17.492 -cause problems. 17.493 - 17.494 -\begin{figure}[ht] 17.495 - \interaction{hook.ws.better} 17.496 - \caption{A better trailing whitespace hook} 17.497 - \label{ex:hook:ws.better} 17.498 -\end{figure} 17.499 - 17.500 -The example of figure~\ref{ex:hook:ws.better} is much more complex, 17.501 -but also more useful. It parses a unified diff to see if any lines 17.502 -add trailing whitespace, and prints the name of the file and the line 17.503 -number of each such occurrence. Even better, if the change adds 17.504 -trailing whitespace, this hook saves the commit comment and prints the 17.505 -name of the save file before exiting and telling Mercurial to roll the 17.506 -transaction back, so you can use 17.507 -\hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the 17.508 -saved commit message once you've corrected the problem. 17.509 - 17.510 -As a final aside, note in figure~\ref{ex:hook:ws.better} the use of 17.511 -\command{perl}'s in-place editing feature to get rid of trailing 17.512 -whitespace from a file. This is concise and useful enough that I will 17.513 -reproduce it here. 17.514 -\begin{codesample2} 17.515 - perl -pi -e 's,\textbackslash{}s+\$,,' filename 17.516 -\end{codesample2} 17.517 - 17.518 -\section{Bundled hooks} 17.519 - 17.520 -Mercurial ships with several bundled hooks. You can find them in the 17.521 -\dirname{hgext} directory of a Mercurial source tree. If you are 17.522 -using a Mercurial binary package, the hooks will be located in the 17.523 -\dirname{hgext} directory of wherever your package installer put 17.524 -Mercurial. 17.525 - 17.526 -\subsection{\hgext{acl}---access control for parts of a repository} 17.527 - 17.528 -The \hgext{acl} extension lets you control which remote users are 17.529 -allowed to push changesets to a networked server. You can protect any 17.530 -portion of a repository (including the entire repo), so that a 17.531 -specific remote user can push changes that do not affect the protected 17.532 -portion. 17.533 - 17.534 -This extension implements access control based on the identity of the 17.535 -user performing a push, \emph{not} on who committed the changesets 17.536 -they're pushing. It makes sense to use this hook only if you have a 17.537 -locked-down server environment that authenticates remote users, and 17.538 -you want to be sure that only specific users are allowed to push 17.539 -changes to that server. 17.540 - 17.541 -\subsubsection{Configuring the \hook{acl} hook} 17.542 - 17.543 -In order to manage incoming changesets, the \hgext{acl} hook must be 17.544 -used as a \hook{pretxnchangegroup} hook. This lets it see which files 17.545 -are modified by each incoming changeset, and roll back a group of 17.546 -changesets if they modify ``forbidden'' files. Example: 17.547 -\begin{codesample2} 17.548 - [hooks] 17.549 - pretxnchangegroup.acl = python:hgext.acl.hook 17.550 -\end{codesample2} 17.551 - 17.552 -The \hgext{acl} extension is configured using three sections. 17.553 - 17.554 -The \rcsection{acl} section has only one entry, \rcitem{acl}{sources}, 17.555 -which lists the sources of incoming changesets that the hook should 17.556 -pay attention to. You don't normally need to configure this section. 17.557 -\begin{itemize} 17.558 -\item[\rcitem{acl}{serve}] Control incoming changesets that are arriving 17.559 - from a remote repository over http or ssh. This is the default 17.560 - value of \rcitem{acl}{sources}, and usually the only setting you'll 17.561 - need for this configuration item. 17.562 -\item[\rcitem{acl}{pull}] Control incoming changesets that are 17.563 - arriving via a pull from a local repository. 17.564 -\item[\rcitem{acl}{push}] Control incoming changesets that are 17.565 - arriving via a push from a local repository. 17.566 -\item[\rcitem{acl}{bundle}] Control incoming changesets that are 17.567 - arriving from another repository via a bundle. 17.568 -\end{itemize} 17.569 - 17.570 -The \rcsection{acl.allow} section controls the users that are allowed to 17.571 -add changesets to the repository. If this section is not present, all 17.572 -users that are not explicitly denied are allowed. If this section is 17.573 -present, all users that are not explicitly allowed are denied (so an 17.574 -empty section means that all users are denied). 17.575 - 17.576 -The \rcsection{acl.deny} section determines which users are denied 17.577 -from adding changesets to the repository. If this section is not 17.578 -present or is empty, no users are denied. 17.579 - 17.580 -The syntaxes for the \rcsection{acl.allow} and \rcsection{acl.deny} 17.581 -sections are identical. On the left of each entry is a glob pattern 17.582 -that matches files or directories, relative to the root of the 17.583 -repository; on the right, a user name. 17.584 - 17.585 -In the following example, the user \texttt{docwriter} can only push 17.586 -changes to the \dirname{docs} subtree of the repository, while 17.587 -\texttt{intern} can push changes to any file or directory except 17.588 -\dirname{source/sensitive}. 17.589 -\begin{codesample2} 17.590 - [acl.allow] 17.591 - docs/** = docwriter 17.592 - 17.593 - [acl.deny] 17.594 - source/sensitive/** = intern 17.595 -\end{codesample2} 17.596 - 17.597 -\subsubsection{Testing and troubleshooting} 17.598 - 17.599 -If you want to test the \hgext{acl} hook, run it with Mercurial's 17.600 -debugging output enabled. Since you'll probably be running it on a 17.601 -server where it's not convenient (or sometimes possible) to pass in 17.602 -the \hggopt{--debug} option, don't forget that you can enable 17.603 -debugging output in your \hgrc: 17.604 -\begin{codesample2} 17.605 - [ui] 17.606 - debug = true 17.607 -\end{codesample2} 17.608 -With this enabled, the \hgext{acl} hook will print enough information 17.609 -to let you figure out why it is allowing or forbidding pushes from 17.610 -specific users. 17.611 - 17.612 -\subsection{\hgext{bugzilla}---integration with Bugzilla} 17.613 - 17.614 -The \hgext{bugzilla} extension adds a comment to a Bugzilla bug 17.615 -whenever it finds a reference to that bug ID in a commit comment. You 17.616 -can install this hook on a shared server, so that any time a remote 17.617 -user pushes changes to this server, the hook gets run. 17.618 - 17.619 -It adds a comment to the bug that looks like this (you can configure 17.620 -the contents of the comment---see below): 17.621 -\begin{codesample2} 17.622 - Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in 17.623 - the frobnitz repository, refers to this bug. 17.624 - 17.625 - For complete details, see 17.626 - http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a 17.627 - 17.628 - Changeset description: 17.629 - Fix bug 10483 by guarding against some NULL pointers 17.630 -\end{codesample2} 17.631 -The value of this hook is that it automates the process of updating a 17.632 -bug any time a changeset refers to it. If you configure the hook 17.633 -properly, it makes it easy for people to browse straight from a 17.634 -Bugzilla bug to a changeset that refers to that bug. 17.635 - 17.636 -You can use the code in this hook as a starting point for some more 17.637 -exotic Bugzilla integration recipes. Here are a few possibilities: 17.638 -\begin{itemize} 17.639 -\item Require that every changeset pushed to the server have a valid 17.640 - bug~ID in its commit comment. In this case, you'd want to configure 17.641 - the hook as a \hook{pretxncommit} hook. This would allow the hook 17.642 - to reject changes that didn't contain bug IDs. 17.643 -\item Allow incoming changesets to automatically modify the 17.644 - \emph{state} of a bug, as well as simply adding a comment. For 17.645 - example, the hook could recognise the string ``fixed bug 31337'' as 17.646 - indicating that it should update the state of bug 31337 to 17.647 - ``requires testing''. 17.648 -\end{itemize} 17.649 - 17.650 -\subsubsection{Configuring the \hook{bugzilla} hook} 17.651 -\label{sec:hook:bugzilla:config} 17.652 - 17.653 -You should configure this hook in your server's \hgrc\ as an 17.654 -\hook{incoming} hook, for example as follows: 17.655 -\begin{codesample2} 17.656 - [hooks] 17.657 - incoming.bugzilla = python:hgext.bugzilla.hook 17.658 -\end{codesample2} 17.659 - 17.660 -Because of the specialised nature of this hook, and because Bugzilla 17.661 -was not written with this kind of integration in mind, configuring 17.662 -this hook is a somewhat involved process. 17.663 - 17.664 -Before you begin, you must install the MySQL bindings for Python on 17.665 -the host(s) where you'll be running the hook. If this is not 17.666 -available as a binary package for your system, you can download it 17.667 -from~\cite{web:mysql-python}. 17.668 - 17.669 -Configuration information for this hook lives in the 17.670 -\rcsection{bugzilla} section of your \hgrc. 17.671 -\begin{itemize} 17.672 -\item[\rcitem{bugzilla}{version}] The version of Bugzilla installed on 17.673 - the server. The database schema that Bugzilla uses changes 17.674 - occasionally, so this hook has to know exactly which schema to use. 17.675 - At the moment, the only version supported is \texttt{2.16}. 17.676 -\item[\rcitem{bugzilla}{host}] The hostname of the MySQL server that 17.677 - stores your Bugzilla data. The database must be configured to allow 17.678 - connections from whatever host you are running the \hook{bugzilla} 17.679 - hook on. 17.680 -\item[\rcitem{bugzilla}{user}] The username with which to connect to 17.681 - the MySQL server. The database must be configured to allow this 17.682 - user to connect from whatever host you are running the 17.683 - \hook{bugzilla} hook on. This user must be able to access and 17.684 - modify Bugzilla tables. The default value of this item is 17.685 - \texttt{bugs}, which is the standard name of the Bugzilla user in a 17.686 - MySQL database. 17.687 -\item[\rcitem{bugzilla}{password}] The MySQL password for the user you 17.688 - configured above. This is stored as plain text, so you should make 17.689 - sure that unauthorised users cannot read the \hgrc\ file where you 17.690 - store this information. 17.691 -\item[\rcitem{bugzilla}{db}] The name of the Bugzilla database on the 17.692 - MySQL server. The default value of this item is \texttt{bugs}, 17.693 - which is the standard name of the MySQL database where Bugzilla 17.694 - stores its data. 17.695 -\item[\rcitem{bugzilla}{notify}] If you want Bugzilla to send out a 17.696 - notification email to subscribers after this hook has added a 17.697 - comment to a bug, you will need this hook to run a command whenever 17.698 - it updates the database. The command to run depends on where you 17.699 - have installed Bugzilla, but it will typically look something like 17.700 - this, if you have Bugzilla installed in 17.701 - \dirname{/var/www/html/bugzilla}: 17.702 - \begin{codesample4} 17.703 - cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com 17.704 - \end{codesample4} 17.705 - The Bugzilla \texttt{processmail} program expects to be given a 17.706 - bug~ID (the hook replaces ``\texttt{\%s}'' with the bug~ID) and an 17.707 - email address. It also expects to be able to write to some files in 17.708 - the directory that it runs in. If Bugzilla and this hook are not 17.709 - installed on the same machine, you will need to find a way to run 17.710 - \texttt{processmail} on the server where Bugzilla is installed. 17.711 -\end{itemize} 17.712 - 17.713 -\subsubsection{Mapping committer names to Bugzilla user names} 17.714 - 17.715 -By default, the \hgext{bugzilla} hook tries to use the email address 17.716 -of a changeset's committer as the Bugzilla user name with which to 17.717 -update a bug. If this does not suit your needs, you can map committer 17.718 -email addresses to Bugzilla user names using a \rcsection{usermap} 17.719 -section. 17.720 - 17.721 -Each item in the \rcsection{usermap} section contains an email address 17.722 -on the left, and a Bugzilla user name on the right. 17.723 -\begin{codesample2} 17.724 - [usermap] 17.725 - jane.user@example.com = jane 17.726 -\end{codesample2} 17.727 -You can either keep the \rcsection{usermap} data in a normal \hgrc, or 17.728 -tell the \hgext{bugzilla} hook to read the information from an 17.729 -external \filename{usermap} file. In the latter case, you can store 17.730 -\filename{usermap} data by itself in (for example) a user-modifiable 17.731 -repository. This makes it possible to let your users maintain their 17.732 -own \rcitem{bugzilla}{usermap} entries. The main \hgrc\ file might 17.733 -look like this: 17.734 -\begin{codesample2} 17.735 - # regular hgrc file refers to external usermap file 17.736 - [bugzilla] 17.737 - usermap = /home/hg/repos/userdata/bugzilla-usermap.conf 17.738 -\end{codesample2} 17.739 -While the \filename{usermap} file that it refers to might look like 17.740 -this: 17.741 -\begin{codesample2} 17.742 - # bugzilla-usermap.conf - inside a hg repository 17.743 - [usermap] 17.744 - stephanie@example.com = steph 17.745 -\end{codesample2} 17.746 - 17.747 -\subsubsection{Configuring the text that gets added to a bug} 17.748 - 17.749 -You can configure the text that this hook adds as a comment; you 17.750 -specify it in the form of a Mercurial template. Several \hgrc\ 17.751 -entries (still in the \rcsection{bugzilla} section) control this 17.752 -behaviour. 17.753 -\begin{itemize} 17.754 -\item[\texttt{strip}] The number of leading path elements to strip 17.755 - from a repository's path name to construct a partial path for a URL. 17.756 - For example, if the repositories on your server live under 17.757 - \dirname{/home/hg/repos}, and you have a repository whose path is 17.758 - \dirname{/home/hg/repos/app/tests}, then setting \texttt{strip} to 17.759 - \texttt{4} will give a partial path of \dirname{app/tests}. The 17.760 - hook will make this partial path available when expanding a 17.761 - template, as \texttt{webroot}. 17.762 -\item[\texttt{template}] The text of the template to use. In addition 17.763 - to the usual changeset-related variables, this template can use 17.764 - \texttt{hgweb} (the value of the \texttt{hgweb} configuration item 17.765 - above) and \texttt{webroot} (the path constructed using 17.766 - \texttt{strip} above). 17.767 -\end{itemize} 17.768 - 17.769 -In addition, you can add a \rcitem{web}{baseurl} item to the 17.770 -\rcsection{web} section of your \hgrc. The \hgext{bugzilla} hook will 17.771 -make this available when expanding a template, as the base string to 17.772 -use when constructing a URL that will let users browse from a Bugzilla 17.773 -comment to view a changeset. Example: 17.774 -\begin{codesample2} 17.775 - [web] 17.776 - baseurl = http://hg.domain.com/ 17.777 -\end{codesample2} 17.778 - 17.779 -Here is an example set of \hgext{bugzilla} hook config information. 17.780 -\begin{codesample2} 17.781 - [bugzilla] 17.782 - host = bugzilla.example.com 17.783 - password = mypassword 17.784 - version = 2.16 17.785 - # server-side repos live in /home/hg/repos, so strip 4 leading 17.786 - # separators 17.787 - strip = 4 17.788 - hgweb = http://hg.example.com/ 17.789 - usermap = /home/hg/repos/notify/bugzilla.conf 17.790 - template = Changeset \{node|short\}, made by \{author\} in the \{webroot\} 17.791 - repo, refers to this bug.\\nFor complete details, see 17.792 - \{hgweb\}\{webroot\}?cmd=changeset;node=\{node|short\}\\nChangeset 17.793 - description:\\n\\t\{desc|tabindent\} 17.794 -\end{codesample2} 17.795 - 17.796 -\subsubsection{Testing and troubleshooting} 17.797 - 17.798 -The most common problems with configuring the \hgext{bugzilla} hook 17.799 -relate to running Bugzilla's \filename{processmail} script and mapping 17.800 -committer names to user names. 17.801 - 17.802 -Recall from section~\ref{sec:hook:bugzilla:config} above that the user 17.803 -that runs the Mercurial process on the server is also the one that 17.804 -will run the \filename{processmail} script. The 17.805 -\filename{processmail} script sometimes causes Bugzilla to write to 17.806 -files in its configuration directory, and Bugzilla's configuration 17.807 -files are usually owned by the user that your web server runs under. 17.808 - 17.809 -You can cause \filename{processmail} to be run with the suitable 17.810 -user's identity using the \command{sudo} command. Here is an example 17.811 -entry for a \filename{sudoers} file. 17.812 -\begin{codesample2} 17.813 - hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s 17.814 -\end{codesample2} 17.815 -This allows the \texttt{hg\_user} user to run a 17.816 -\filename{processmail-wrapper} program under the identity of 17.817 -\texttt{httpd\_user}. 17.818 - 17.819 -This indirection through a wrapper script is necessary, because 17.820 -\filename{processmail} expects to be run with its current directory 17.821 -set to wherever you installed Bugzilla; you can't specify that kind of 17.822 -constraint in a \filename{sudoers} file. The contents of the wrapper 17.823 -script are simple: 17.824 -\begin{codesample2} 17.825 - #!/bin/sh 17.826 - cd `dirname $0` && ./processmail "$1" nobody@example.com 17.827 -\end{codesample2} 17.828 -It doesn't seem to matter what email address you pass to 17.829 -\filename{processmail}. 17.830 - 17.831 -If your \rcsection{usermap} is not set up correctly, users will see an 17.832 -error message from the \hgext{bugzilla} hook when they push changes 17.833 -to the server. The error message will look like this: 17.834 -\begin{codesample2} 17.835 - cannot find bugzilla user id for john.q.public@example.com 17.836 -\end{codesample2} 17.837 -What this means is that the committer's address, 17.838 -\texttt{john.q.public@example.com}, is not a valid Bugzilla user name, 17.839 -nor does it have an entry in your \rcsection{usermap} that maps it to 17.840 -a valid Bugzilla user name. 17.841 - 17.842 -\subsection{\hgext{notify}---send email notifications} 17.843 - 17.844 -Although Mercurial's built-in web server provides RSS feeds of changes 17.845 -in every repository, many people prefer to receive change 17.846 -notifications via email. The \hgext{notify} hook lets you send out 17.847 -notifications to a set of email addresses whenever changesets arrive 17.848 -that those subscribers are interested in. 17.849 - 17.850 -As with the \hgext{bugzilla} hook, the \hgext{notify} hook is 17.851 -template-driven, so you can customise the contents of the notification 17.852 -messages that it sends. 17.853 - 17.854 -By default, the \hgext{notify} hook includes a diff of every changeset 17.855 -that it sends out; you can limit the size of the diff, or turn this 17.856 -feature off entirely. It is useful for letting subscribers review 17.857 -changes immediately, rather than clicking to follow a URL. 17.858 - 17.859 -\subsubsection{Configuring the \hgext{notify} hook} 17.860 - 17.861 -You can set up the \hgext{notify} hook to send one email message per 17.862 -incoming changeset, or one per incoming group of changesets (all those 17.863 -that arrived in a single pull or push). 17.864 -\begin{codesample2} 17.865 - [hooks] 17.866 - # send one email per group of changes 17.867 - changegroup.notify = python:hgext.notify.hook 17.868 - # send one email per change 17.869 - incoming.notify = python:hgext.notify.hook 17.870 -\end{codesample2} 17.871 - 17.872 -Configuration information for this hook lives in the 17.873 -\rcsection{notify} section of a \hgrc\ file. 17.874 -\begin{itemize} 17.875 -\item[\rcitem{notify}{test}] By default, this hook does not send out 17.876 - email at all; instead, it prints the message that it \emph{would} 17.877 - send. Set this item to \texttt{false} to allow email to be sent. 17.878 - The reason that sending of email is turned off by default is that it 17.879 - takes several tries to configure this extension exactly as you would 17.880 - like, and it would be bad form to spam subscribers with a number of 17.881 - ``broken'' notifications while you debug your configuration. 17.882 -\item[\rcitem{notify}{config}] The path to a configuration file that 17.883 - contains subscription information. This is kept separate from the 17.884 - main \hgrc\ so that you can maintain it in a repository of its own. 17.885 - People can then clone that repository, update their subscriptions, 17.886 - and push the changes back to your server. 17.887 -\item[\rcitem{notify}{strip}] The number of leading path separator 17.888 - characters to strip from a repository's path, when deciding whether 17.889 - a repository has subscribers. For example, if the repositories on 17.890 - your server live in \dirname{/home/hg/repos}, and \hgext{notify} is 17.891 - considering a repository named \dirname{/home/hg/repos/shared/test}, 17.892 - setting \rcitem{notify}{strip} to \texttt{4} will cause 17.893 - \hgext{notify} to trim the path it considers down to 17.894 - \dirname{shared/test}, and it will match subscribers against that. 17.895 -\item[\rcitem{notify}{template}] The template text to use when sending 17.896 - messages. This specifies both the contents of the message header 17.897 - and its body. 17.898 -\item[\rcitem{notify}{maxdiff}] The maximum number of lines of diff 17.899 - data to append to the end of a message. If a diff is longer than 17.900 - this, it is truncated. By default, this is set to 300. Set this to 17.901 - \texttt{0} to omit diffs from notification emails. 17.902 -\item[\rcitem{notify}{sources}] A list of sources of changesets to 17.903 - consider. This lets you limit \hgext{notify} to only sending out 17.904 - email about changes that remote users pushed into this repository 17.905 - via a server, for example. See section~\ref{sec:hook:sources} for 17.906 - the sources you can specify here. 17.907 -\end{itemize} 17.908 - 17.909 -If you set the \rcitem{web}{baseurl} item in the \rcsection{web} 17.910 -section, you can use it in a template; it will be available as 17.911 -\texttt{webroot}. 17.912 - 17.913 -Here is an example set of \hgext{notify} configuration information. 17.914 -\begin{codesample2} 17.915 - [notify] 17.916 - # really send email 17.917 - test = false 17.918 - # subscriber data lives in the notify repo 17.919 - config = /home/hg/repos/notify/notify.conf 17.920 - # repos live in /home/hg/repos on server, so strip 4 "/" chars 17.921 - strip = 4 17.922 - template = X-Hg-Repo: \{webroot\} 17.923 - Subject: \{webroot\}: \{desc|firstline|strip\} 17.924 - From: \{author\} 17.925 - 17.926 - changeset \{node|short\} in \{root\} 17.927 - details: \{baseurl\}\{webroot\}?cmd=changeset;node=\{node|short\} 17.928 - description: 17.929 - \{desc|tabindent|strip\} 17.930 - 17.931 - [web] 17.932 - baseurl = http://hg.example.com/ 17.933 -\end{codesample2} 17.934 - 17.935 -This will produce a message that looks like the following: 17.936 -\begin{codesample2} 17.937 - X-Hg-Repo: tests/slave 17.938 - Subject: tests/slave: Handle error case when slave has no buffers 17.939 - Date: Wed, 2 Aug 2006 15:25:46 -0700 (PDT) 17.940 - 17.941 - changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave 17.942 - details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5 17.943 - description: 17.944 - Handle error case when slave has no buffers 17.945 - diffs (54 lines): 17.946 - 17.947 - diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h 17.948 - --- a/include/tests.h Wed Aug 02 15:19:52 2006 -0700 17.949 - +++ b/include/tests.h Wed Aug 02 15:25:26 2006 -0700 17.950 - @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h) 17.951 - [...snip...] 17.952 -\end{codesample2} 17.953 - 17.954 -\subsubsection{Testing and troubleshooting} 17.955 - 17.956 -Do not forget that by default, the \hgext{notify} extension \emph{will 17.957 - not send any mail} until you explicitly configure it to do so, by 17.958 -setting \rcitem{notify}{test} to \texttt{false}. Until you do that, 17.959 -it simply prints the message it \emph{would} send. 17.960 - 17.961 -\section{Information for writers of hooks} 17.962 -\label{sec:hook:ref} 17.963 - 17.964 -\subsection{In-process hook execution} 17.965 - 17.966 -An in-process hook is called with arguments of the following form: 17.967 -\begin{codesample2} 17.968 - def myhook(ui, repo, **kwargs): 17.969 - pass 17.970 -\end{codesample2} 17.971 -The \texttt{ui} parameter is a \pymodclass{mercurial.ui}{ui} object. 17.972 -The \texttt{repo} parameter is a 17.973 -\pymodclass{mercurial.localrepo}{localrepository} object. The 17.974 -names and values of the \texttt{**kwargs} parameters depend on the 17.975 -hook being invoked, with the following common features: 17.976 -\begin{itemize} 17.977 -\item If a parameter is named \texttt{node} or 17.978 - \texttt{parent\emph{N}}, it will contain a hexadecimal changeset ID. 17.979 - The empty string is used to represent ``null changeset ID'' instead 17.980 - of a string of zeroes. 17.981 -\item If a parameter is named \texttt{url}, it will contain the URL of 17.982 - a remote repository, if that can be determined. 17.983 -\item Boolean-valued parameters are represented as Python 17.984 - \texttt{bool} objects. 17.985 -\end{itemize} 17.986 - 17.987 -An in-process hook is called without a change to the process's working 17.988 -directory (unlike external hooks, which are run in the root of the 17.989 -repository). It must not change the process's working directory, or 17.990 -it will cause any calls it makes into the Mercurial API to fail. 17.991 - 17.992 -If a hook returns a boolean ``false'' value, it is considered to have 17.993 -succeeded. If it returns a boolean ``true'' value or raises an 17.994 -exception, it is considered to have failed. A useful way to think of 17.995 -the calling convention is ``tell me if you fail''. 17.996 - 17.997 -Note that changeset IDs are passed into Python hooks as hexadecimal 17.998 -strings, not the binary hashes that Mercurial's APIs normally use. To 17.999 -convert a hash from hex to binary, use the 17.1000 -\pymodfunc{mercurial.node}{bin} function. 17.1001 - 17.1002 -\subsection{External hook execution} 17.1003 - 17.1004 -An external hook is passed to the shell of the user running Mercurial. 17.1005 -Features of that shell, such as variable substitution and command 17.1006 -redirection, are available. The hook is run in the root directory of 17.1007 -the repository (unlike in-process hooks, which are run in the same 17.1008 -directory that Mercurial was run in). 17.1009 - 17.1010 -Hook parameters are passed to the hook as environment variables. Each 17.1011 -environment variable's name is converted in upper case and prefixed 17.1012 -with the string ``\texttt{HG\_}''. For example, if the name of a 17.1013 -parameter is ``\texttt{node}'', the name of the environment variable 17.1014 -representing that parameter will be ``\texttt{HG\_NODE}''. 17.1015 - 17.1016 -A boolean parameter is represented as the string ``\texttt{1}'' for 17.1017 -``true'', ``\texttt{0}'' for ``false''. If an environment variable is 17.1018 -named \envar{HG\_NODE}, \envar{HG\_PARENT1} or \envar{HG\_PARENT2}, it 17.1019 -contains a changeset ID represented as a hexadecimal string. The 17.1020 -empty string is used to represent ``null changeset ID'' instead of a 17.1021 -string of zeroes. If an environment variable is named 17.1022 -\envar{HG\_URL}, it will contain the URL of a remote repository, if 17.1023 -that can be determined. 17.1024 - 17.1025 -If a hook exits with a status of zero, it is considered to have 17.1026 -succeeded. If it exits with a non-zero status, it is considered to 17.1027 -have failed. 17.1028 - 17.1029 -\subsection{Finding out where changesets come from} 17.1030 - 17.1031 -A hook that involves the transfer of changesets between a local 17.1032 -repository and another may be able to find out information about the 17.1033 -``far side''. Mercurial knows \emph{how} changes are being 17.1034 -transferred, and in many cases \emph{where} they are being transferred 17.1035 -to or from. 17.1036 - 17.1037 -\subsubsection{Sources of changesets} 17.1038 -\label{sec:hook:sources} 17.1039 - 17.1040 -Mercurial will tell a hook what means are, or were, used to transfer 17.1041 -changesets between repositories. This is provided by Mercurial in a 17.1042 -Python parameter named \texttt{source}, or an environment variable named 17.1043 -\envar{HG\_SOURCE}. 17.1044 - 17.1045 -\begin{itemize} 17.1046 -\item[\texttt{serve}] Changesets are transferred to or from a remote 17.1047 - repository over http or ssh. 17.1048 -\item[\texttt{pull}] Changesets are being transferred via a pull from 17.1049 - one repository into another. 17.1050 -\item[\texttt{push}] Changesets are being transferred via a push from 17.1051 - one repository into another. 17.1052 -\item[\texttt{bundle}] Changesets are being transferred to or from a 17.1053 - bundle. 17.1054 -\end{itemize} 17.1055 - 17.1056 -\subsubsection{Where changes are going---remote repository URLs} 17.1057 -\label{sec:hook:url} 17.1058 - 17.1059 -When possible, Mercurial will tell a hook the location of the ``far 17.1060 -side'' of an activity that transfers changeset data between 17.1061 -repositories. This is provided by Mercurial in a Python parameter 17.1062 -named \texttt{url}, or an environment variable named \envar{HG\_URL}. 17.1063 - 17.1064 -This information is not always known. If a hook is invoked in a 17.1065 -repository that is being served via http or ssh, Mercurial cannot tell 17.1066 -where the remote repository is, but it may know where the client is 17.1067 -connecting from. In such cases, the URL will take one of the 17.1068 -following forms: 17.1069 -\begin{itemize} 17.1070 -\item \texttt{remote:ssh:\emph{ip-address}}---remote ssh client, at 17.1071 - the given IP address. 17.1072 -\item \texttt{remote:http:\emph{ip-address}}---remote http client, at 17.1073 - the given IP address. If the client is using SSL, this will be of 17.1074 - the form \texttt{remote:https:\emph{ip-address}}. 17.1075 -\item Empty---no information could be discovered about the remote 17.1076 - client. 17.1077 -\end{itemize} 17.1078 - 17.1079 -\section{Hook reference} 17.1080 - 17.1081 -\subsection{\hook{changegroup}---after remote changesets added} 17.1082 -\label{sec:hook:changegroup} 17.1083 - 17.1084 -This hook is run after a group of pre-existing changesets has been 17.1085 -added to the repository, for example via a \hgcmd{pull} or 17.1086 -\hgcmd{unbundle}. This hook is run once per operation that added one 17.1087 -or more changesets. This is in contrast to the \hook{incoming} hook, 17.1088 -which is run once per changeset, regardless of whether the changesets 17.1089 -arrive in a group. 17.1090 - 17.1091 -Some possible uses for this hook include kicking off an automated 17.1092 -build or test of the added changesets, updating a bug database, or 17.1093 -notifying subscribers that a repository contains new changes. 17.1094 - 17.1095 -Parameters to this hook: 17.1096 -\begin{itemize} 17.1097 -\item[\texttt{node}] A changeset ID. The changeset ID of the first 17.1098 - changeset in the group that was added. All changesets between this 17.1099 - and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by 17.1100 - a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}. 17.1101 -\item[\texttt{source}] A string. The source of these changes. See 17.1102 - section~\ref{sec:hook:sources} for details. 17.1103 -\item[\texttt{url}] A URL. The location of the remote repository, if 17.1104 - known. See section~\ref{sec:hook:url} for more information. 17.1105 -\end{itemize} 17.1106 - 17.1107 -See also: \hook{incoming} (section~\ref{sec:hook:incoming}), 17.1108 -\hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}), 17.1109 -\hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup}) 17.1110 - 17.1111 -\subsection{\hook{commit}---after a new changeset is created} 17.1112 -\label{sec:hook:commit} 17.1113 - 17.1114 -This hook is run after a new changeset has been created. 17.1115 - 17.1116 -Parameters to this hook: 17.1117 -\begin{itemize} 17.1118 -\item[\texttt{node}] A changeset ID. The changeset ID of the newly 17.1119 - committed changeset. 17.1120 -\item[\texttt{parent1}] A changeset ID. The changeset ID of the first 17.1121 - parent of the newly committed changeset. 17.1122 -\item[\texttt{parent2}] A changeset ID. The changeset ID of the second 17.1123 - parent of the newly committed changeset. 17.1124 -\end{itemize} 17.1125 - 17.1126 -See also: \hook{precommit} (section~\ref{sec:hook:precommit}), 17.1127 -\hook{pretxncommit} (section~\ref{sec:hook:pretxncommit}) 17.1128 - 17.1129 -\subsection{\hook{incoming}---after one remote changeset is added} 17.1130 -\label{sec:hook:incoming} 17.1131 - 17.1132 -This hook is run after a pre-existing changeset has been added to the 17.1133 -repository, for example via a \hgcmd{push}. If a group of changesets 17.1134 -was added in a single operation, this hook is called once for each 17.1135 -added changeset. 17.1136 - 17.1137 -You can use this hook for the same purposes as the \hook{changegroup} 17.1138 -hook (section~\ref{sec:hook:changegroup}); it's simply more convenient 17.1139 -sometimes to run a hook once per group of changesets, while other 17.1140 -times it's handier once per changeset. 17.1141 - 17.1142 -Parameters to this hook: 17.1143 -\begin{itemize} 17.1144 -\item[\texttt{node}] A changeset ID. The ID of the newly added 17.1145 - changeset. 17.1146 -\item[\texttt{source}] A string. The source of these changes. See 17.1147 - section~\ref{sec:hook:sources} for details. 17.1148 -\item[\texttt{url}] A URL. The location of the remote repository, if 17.1149 - known. See section~\ref{sec:hook:url} for more information. 17.1150 -\end{itemize} 17.1151 - 17.1152 -See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}) \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}), \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup}) 17.1153 - 17.1154 -\subsection{\hook{outgoing}---after changesets are propagated} 17.1155 -\label{sec:hook:outgoing} 17.1156 - 17.1157 -This hook is run after a group of changesets has been propagated out 17.1158 -of this repository, for example by a \hgcmd{push} or \hgcmd{bundle} 17.1159 -command. 17.1160 - 17.1161 -One possible use for this hook is to notify administrators that 17.1162 -changes have been pulled. 17.1163 - 17.1164 -Parameters to this hook: 17.1165 -\begin{itemize} 17.1166 -\item[\texttt{node}] A changeset ID. The changeset ID of the first 17.1167 - changeset of the group that was sent. 17.1168 -\item[\texttt{source}] A string. The source of the of the operation 17.1169 - (see section~\ref{sec:hook:sources}). If a remote client pulled 17.1170 - changes from this repository, \texttt{source} will be 17.1171 - \texttt{serve}. If the client that obtained changes from this 17.1172 - repository was local, \texttt{source} will be \texttt{bundle}, 17.1173 - \texttt{pull}, or \texttt{push}, depending on the operation the 17.1174 - client performed. 17.1175 -\item[\texttt{url}] A URL. The location of the remote repository, if 17.1176 - known. See section~\ref{sec:hook:url} for more information. 17.1177 -\end{itemize} 17.1178 - 17.1179 -See also: \hook{preoutgoing} (section~\ref{sec:hook:preoutgoing}) 17.1180 - 17.1181 -\subsection{\hook{prechangegroup}---before starting to add remote changesets} 17.1182 -\label{sec:hook:prechangegroup} 17.1183 - 17.1184 -This controlling hook is run before Mercurial begins to add a group of 17.1185 -changesets from another repository. 17.1186 - 17.1187 -This hook does not have any information about the changesets to be 17.1188 -added, because it is run before transmission of those changesets is 17.1189 -allowed to begin. If this hook fails, the changesets will not be 17.1190 -transmitted. 17.1191 - 17.1192 -One use for this hook is to prevent external changes from being added 17.1193 -to a repository. For example, you could use this to ``freeze'' a 17.1194 -server-hosted branch temporarily or permanently so that users cannot 17.1195 -push to it, while still allowing a local administrator to modify the 17.1196 -repository. 17.1197 - 17.1198 -Parameters to this hook: 17.1199 -\begin{itemize} 17.1200 -\item[\texttt{source}] A string. The source of these changes. See 17.1201 - section~\ref{sec:hook:sources} for details. 17.1202 -\item[\texttt{url}] A URL. The location of the remote repository, if 17.1203 - known. See section~\ref{sec:hook:url} for more information. 17.1204 -\end{itemize} 17.1205 - 17.1206 -See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}), 17.1207 -\hook{incoming} (section~\ref{sec:hook:incoming}), , 17.1208 -\hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup}) 17.1209 - 17.1210 -\subsection{\hook{precommit}---before starting to commit a changeset} 17.1211 -\label{sec:hook:precommit} 17.1212 - 17.1213 -This hook is run before Mercurial begins to commit a new changeset. 17.1214 -It is run before Mercurial has any of the metadata for the commit, 17.1215 -such as the files to be committed, the commit message, or the commit 17.1216 -date. 17.1217 - 17.1218 -One use for this hook is to disable the ability to commit new 17.1219 -changesets, while still allowing incoming changesets. Another is to 17.1220 -run a build or test, and only allow the commit to begin if the build 17.1221 -or test succeeds. 17.1222 - 17.1223 -Parameters to this hook: 17.1224 -\begin{itemize} 17.1225 -\item[\texttt{parent1}] A changeset ID. The changeset ID of the first 17.1226 - parent of the working directory. 17.1227 -\item[\texttt{parent2}] A changeset ID. The changeset ID of the second 17.1228 - parent of the working directory. 17.1229 -\end{itemize} 17.1230 -If the commit proceeds, the parents of the working directory will 17.1231 -become the parents of the new changeset. 17.1232 - 17.1233 -See also: \hook{commit} (section~\ref{sec:hook:commit}), 17.1234 -\hook{pretxncommit} (section~\ref{sec:hook:pretxncommit}) 17.1235 - 17.1236 -\subsection{\hook{preoutgoing}---before starting to propagate changesets} 17.1237 -\label{sec:hook:preoutgoing} 17.1238 - 17.1239 -This hook is invoked before Mercurial knows the identities of the 17.1240 -changesets to be transmitted. 17.1241 - 17.1242 -One use for this hook is to prevent changes from being transmitted to 17.1243 -another repository. 17.1244 - 17.1245 -Parameters to this hook: 17.1246 -\begin{itemize} 17.1247 -\item[\texttt{source}] A string. The source of the operation that is 17.1248 - attempting to obtain changes from this repository (see 17.1249 - section~\ref{sec:hook:sources}). See the documentation for the 17.1250 - \texttt{source} parameter to the \hook{outgoing} hook, in 17.1251 - section~\ref{sec:hook:outgoing}, for possible values of this 17.1252 - parameter. 17.1253 -\item[\texttt{url}] A URL. The location of the remote repository, if 17.1254 - known. See section~\ref{sec:hook:url} for more information. 17.1255 -\end{itemize} 17.1256 - 17.1257 -See also: \hook{outgoing} (section~\ref{sec:hook:outgoing}) 17.1258 - 17.1259 -\subsection{\hook{pretag}---before tagging a changeset} 17.1260 -\label{sec:hook:pretag} 17.1261 - 17.1262 -This controlling hook is run before a tag is created. If the hook 17.1263 -succeeds, creation of the tag proceeds. If the hook fails, the tag is 17.1264 -not created. 17.1265 - 17.1266 -Parameters to this hook: 17.1267 -\begin{itemize} 17.1268 -\item[\texttt{local}] A boolean. Whether the tag is local to this 17.1269 - repository instance (i.e.~stored in \sfilename{.hg/localtags}) or 17.1270 - managed by Mercurial (stored in \sfilename{.hgtags}). 17.1271 -\item[\texttt{node}] A changeset ID. The ID of the changeset to be tagged. 17.1272 -\item[\texttt{tag}] A string. The name of the tag to be created. 17.1273 -\end{itemize} 17.1274 - 17.1275 -If the tag to be created is revision-controlled, the \hook{precommit} 17.1276 -and \hook{pretxncommit} hooks (sections~\ref{sec:hook:commit} 17.1277 -and~\ref{sec:hook:pretxncommit}) will also be run. 17.1278 - 17.1279 -See also: \hook{tag} (section~\ref{sec:hook:tag}) 17.1280 - 17.1281 -\subsection{\hook{pretxnchangegroup}---before completing addition of 17.1282 - remote changesets} 17.1283 -\label{sec:hook:pretxnchangegroup} 17.1284 - 17.1285 -This controlling hook is run before a transaction---that manages the 17.1286 -addition of a group of new changesets from outside the 17.1287 -repository---completes. If the hook succeeds, the transaction 17.1288 -completes, and all of the changesets become permanent within this 17.1289 -repository. If the hook fails, the transaction is rolled back, and 17.1290 -the data for the changesets is erased. 17.1291 - 17.1292 -This hook can access the metadata associated with the almost-added 17.1293 -changesets, but it should not do anything permanent with this data. 17.1294 -It must also not modify the working directory. 17.1295 - 17.1296 -While this hook is running, if other Mercurial processes access this 17.1297 -repository, they will be able to see the almost-added changesets as if 17.1298 -they are permanent. This may lead to race conditions if you do not 17.1299 -take steps to avoid them. 17.1300 - 17.1301 -This hook can be used to automatically vet a group of changesets. If 17.1302 -the hook fails, all of the changesets are ``rejected'' when the 17.1303 -transaction rolls back. 17.1304 - 17.1305 -Parameters to this hook: 17.1306 -\begin{itemize} 17.1307 -\item[\texttt{node}] A changeset ID. The changeset ID of the first 17.1308 - changeset in the group that was added. All changesets between this 17.1309 - and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by 17.1310 - a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}. 17.1311 -\item[\texttt{source}] A string. The source of these changes. See 17.1312 - section~\ref{sec:hook:sources} for details. 17.1313 -\item[\texttt{url}] A URL. The location of the remote repository, if 17.1314 - known. See section~\ref{sec:hook:url} for more information. 17.1315 -\end{itemize} 17.1316 - 17.1317 -See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}), 17.1318 -\hook{incoming} (section~\ref{sec:hook:incoming}), 17.1319 -\hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}) 17.1320 - 17.1321 -\subsection{\hook{pretxncommit}---before completing commit of new changeset} 17.1322 -\label{sec:hook:pretxncommit} 17.1323 - 17.1324 -This controlling hook is run before a transaction---that manages a new 17.1325 -commit---completes. If the hook succeeds, the transaction completes 17.1326 -and the changeset becomes permanent within this repository. If the 17.1327 -hook fails, the transaction is rolled back, and the commit data is 17.1328 -erased. 17.1329 - 17.1330 -This hook can access the metadata associated with the almost-new 17.1331 -changeset, but it should not do anything permanent with this data. It 17.1332 -must also not modify the working directory. 17.1333 - 17.1334 -While this hook is running, if other Mercurial processes access this 17.1335 -repository, they will be able to see the almost-new changeset as if it 17.1336 -is permanent. This may lead to race conditions if you do not take 17.1337 -steps to avoid them. 17.1338 - 17.1339 -Parameters to this hook: 17.1340 -\begin{itemize} 17.1341 -\item[\texttt{node}] A changeset ID. The changeset ID of the newly 17.1342 - committed changeset. 17.1343 -\item[\texttt{parent1}] A changeset ID. The changeset ID of the first 17.1344 - parent of the newly committed changeset. 17.1345 -\item[\texttt{parent2}] A changeset ID. The changeset ID of the second 17.1346 - parent of the newly committed changeset. 17.1347 -\end{itemize} 17.1348 - 17.1349 -See also: \hook{precommit} (section~\ref{sec:hook:precommit}) 17.1350 - 17.1351 -\subsection{\hook{preupdate}---before updating or merging working directory} 17.1352 -\label{sec:hook:preupdate} 17.1353 - 17.1354 -This controlling hook is run before an update or merge of the working 17.1355 -directory begins. It is run only if Mercurial's normal pre-update 17.1356 -checks determine that the update or merge can proceed. If the hook 17.1357 -succeeds, the update or merge may proceed; if it fails, the update or 17.1358 -merge does not start. 17.1359 - 17.1360 -Parameters to this hook: 17.1361 -\begin{itemize} 17.1362 -\item[\texttt{parent1}] A changeset ID. The ID of the parent that the 17.1363 - working directory is to be updated to. If the working directory is 17.1364 - being merged, it will not change this parent. 17.1365 -\item[\texttt{parent2}] A changeset ID. Only set if the working 17.1366 - directory is being merged. The ID of the revision that the working 17.1367 - directory is being merged with. 17.1368 -\end{itemize} 17.1369 - 17.1370 -See also: \hook{update} (section~\ref{sec:hook:update}) 17.1371 - 17.1372 -\subsection{\hook{tag}---after tagging a changeset} 17.1373 -\label{sec:hook:tag} 17.1374 - 17.1375 -This hook is run after a tag has been created. 17.1376 - 17.1377 -Parameters to this hook: 17.1378 -\begin{itemize} 17.1379 -\item[\texttt{local}] A boolean. Whether the new tag is local to this 17.1380 - repository instance (i.e.~stored in \sfilename{.hg/localtags}) or 17.1381 - managed by Mercurial (stored in \sfilename{.hgtags}). 17.1382 -\item[\texttt{node}] A changeset ID. The ID of the changeset that was 17.1383 - tagged. 17.1384 -\item[\texttt{tag}] A string. The name of the tag that was created. 17.1385 -\end{itemize} 17.1386 - 17.1387 -If the created tag is revision-controlled, the \hook{commit} hook 17.1388 -(section~\ref{sec:hook:commit}) is run before this hook. 17.1389 - 17.1390 -See also: \hook{pretag} (section~\ref{sec:hook:pretag}) 17.1391 - 17.1392 -\subsection{\hook{update}---after updating or merging working directory} 17.1393 -\label{sec:hook:update} 17.1394 - 17.1395 -This hook is run after an update or merge of the working directory 17.1396 -completes. Since a merge can fail (if the external \command{hgmerge} 17.1397 -command fails to resolve conflicts in a file), this hook communicates 17.1398 -whether the update or merge completed cleanly. 17.1399 - 17.1400 -\begin{itemize} 17.1401 -\item[\texttt{error}] A boolean. Indicates whether the update or 17.1402 - merge completed successfully. 17.1403 -\item[\texttt{parent1}] A changeset ID. The ID of the parent that the 17.1404 - working directory was updated to. If the working directory was 17.1405 - merged, it will not have changed this parent. 17.1406 -\item[\texttt{parent2}] A changeset ID. Only set if the working 17.1407 - directory was merged. The ID of the revision that the working 17.1408 - directory was merged with. 17.1409 -\end{itemize} 17.1410 - 17.1411 -See also: \hook{preupdate} (section~\ref{sec:hook:preupdate}) 17.1412 - 17.1413 -%%% Local Variables: 17.1414 -%%% mode: latex 17.1415 -%%% TeX-master: "00book" 17.1416 -%%% End:
18.1 --- a/en/ch11-template.tex Thu Mar 05 21:52:23 2009 +0200 18.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 18.3 @@ -1,475 +0,0 @@ 18.4 -\chapter{Customising the output of Mercurial} 18.5 -\label{chap:template} 18.6 - 18.7 -Mercurial provides a powerful mechanism to let you control how it 18.8 -displays information. The mechanism is based on templates. You can 18.9 -use templates to generate specific output for a single command, or to 18.10 -customise the entire appearance of the built-in web interface. 18.11 - 18.12 -\section{Using precanned output styles} 18.13 -\label{sec:style} 18.14 - 18.15 -Packaged with Mercurial are some output styles that you can use 18.16 -immediately. A style is simply a precanned template that someone 18.17 -wrote and installed somewhere that Mercurial can find. 18.18 - 18.19 -Before we take a look at Mercurial's bundled styles, let's review its 18.20 -normal output. 18.21 - 18.22 -\interaction{template.simple.normal} 18.23 - 18.24 -This is somewhat informative, but it takes up a lot of space---five 18.25 -lines of output per changeset. The \texttt{compact} style reduces 18.26 -this to three lines, presented in a sparse manner. 18.27 - 18.28 -\interaction{template.simple.compact} 18.29 - 18.30 -The \texttt{changelog} style hints at the expressive power of 18.31 -Mercurial's templating engine. This style attempts to follow the GNU 18.32 -Project's changelog guidelines\cite{web:changelog}. 18.33 - 18.34 -\interaction{template.simple.changelog} 18.35 - 18.36 -You will not be shocked to learn that Mercurial's default output style 18.37 -is named \texttt{default}. 18.38 - 18.39 -\subsection{Setting a default style} 18.40 - 18.41 -You can modify the output style that Mercurial will use for every 18.42 -command by editing your \hgrc\ file, naming the style you would 18.43 -prefer to use. 18.44 - 18.45 -\begin{codesample2} 18.46 - [ui] 18.47 - style = compact 18.48 -\end{codesample2} 18.49 - 18.50 -If you write a style of your own, you can use it by either providing 18.51 -the path to your style file, or copying your style file into a 18.52 -location where Mercurial can find it (typically the \texttt{templates} 18.53 -subdirectory of your Mercurial install directory). 18.54 - 18.55 -\section{Commands that support styles and templates} 18.56 - 18.57 -All of Mercurial's ``\texttt{log}-like'' commands let you use styles 18.58 -and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and 18.59 -\hgcmd{tip}. 18.60 - 18.61 -As I write this manual, these are so far the only commands that 18.62 -support styles and templates. Since these are the most important 18.63 -commands that need customisable output, there has been little pressure 18.64 -from the Mercurial user community to add style and template support to 18.65 -other commands. 18.66 - 18.67 -\section{The basics of templating} 18.68 - 18.69 -At its simplest, a Mercurial template is a piece of text. Some of the 18.70 -text never changes, while other parts are \emph{expanded}, or replaced 18.71 -with new text, when necessary. 18.72 - 18.73 -Before we continue, let's look again at a simple example of 18.74 -Mercurial's normal output. 18.75 - 18.76 -\interaction{template.simple.normal} 18.77 - 18.78 -Now, let's run the same command, but using a template to change its 18.79 -output. 18.80 - 18.81 -\interaction{template.simple.simplest} 18.82 - 18.83 -The example above illustrates the simplest possible template; it's 18.84 -just a piece of static text, printed once for each changeset. The 18.85 -\hgopt{log}{--template} option to the \hgcmd{log} command tells 18.86 -Mercurial to use the given text as the template when printing each 18.87 -changeset. 18.88 - 18.89 -Notice that the template string above ends with the text 18.90 -``\Verb+\n+''. This is an \emph{escape sequence}, telling Mercurial 18.91 -to print a newline at the end of each template item. If you omit this 18.92 -newline, Mercurial will run each piece of output together. See 18.93 -section~\ref{sec:template:escape} for more details of escape sequences. 18.94 - 18.95 -A template that prints a fixed string of text all the time isn't very 18.96 -useful; let's try something a bit more complex. 18.97 - 18.98 -\interaction{template.simple.simplesub} 18.99 - 18.100 -As you can see, the string ``\Verb+{desc}+'' in the template has been 18.101 -replaced in the output with the description of each changeset. Every 18.102 -time Mercurial finds text enclosed in curly braces (``\texttt{\{}'' 18.103 -and ``\texttt{\}}''), it will try to replace the braces and text with 18.104 -the expansion of whatever is inside. To print a literal curly brace, 18.105 -you must escape it, as described in section~\ref{sec:template:escape}. 18.106 - 18.107 -\section{Common template keywords} 18.108 -\label{sec:template:keyword} 18.109 - 18.110 -You can start writing simple templates immediately using the keywords 18.111 -below. 18.112 - 18.113 -\begin{itemize} 18.114 -\item[\tplkword{author}] String. The unmodified author of the changeset. 18.115 -\item[\tplkword{branches}] String. The name of the branch on which 18.116 - the changeset was committed. Will be empty if the branch name was 18.117 - \texttt{default}. 18.118 -\item[\tplkword{date}] Date information. The date when the changeset 18.119 - was committed. This is \emph{not} human-readable; you must pass it 18.120 - through a filter that will render it appropriately. See 18.121 - section~\ref{sec:template:filter} for more information on filters. 18.122 - The date is expressed as a pair of numbers. The first number is a 18.123 - Unix UTC timestamp (seconds since January 1, 1970); the second is 18.124 - the offset of the committer's timezone from UTC, in seconds. 18.125 -\item[\tplkword{desc}] String. The text of the changeset description. 18.126 -\item[\tplkword{files}] List of strings. All files modified, added, or 18.127 - removed by this changeset. 18.128 -\item[\tplkword{file\_adds}] List of strings. Files added by this 18.129 - changeset. 18.130 -\item[\tplkword{file\_dels}] List of strings. Files removed by this 18.131 - changeset. 18.132 -\item[\tplkword{node}] String. The changeset identification hash, as a 18.133 - 40-character hexadecimal string. 18.134 -\item[\tplkword{parents}] List of strings. The parents of the 18.135 - changeset. 18.136 -\item[\tplkword{rev}] Integer. The repository-local changeset revision 18.137 - number. 18.138 -\item[\tplkword{tags}] List of strings. Any tags associated with the 18.139 - changeset. 18.140 -\end{itemize} 18.141 - 18.142 -A few simple experiments will show us what to expect when we use these 18.143 -keywords; you can see the results in 18.144 -figure~\ref{fig:template:keywords}. 18.145 - 18.146 -\begin{figure} 18.147 - \interaction{template.simple.keywords} 18.148 - \caption{Template keywords in use} 18.149 - \label{fig:template:keywords} 18.150 -\end{figure} 18.151 - 18.152 -As we noted above, the date keyword does not produce human-readable 18.153 -output, so we must treat it specially. This involves using a 18.154 -\emph{filter}, about which more in section~\ref{sec:template:filter}. 18.155 - 18.156 -\interaction{template.simple.datekeyword} 18.157 - 18.158 -\section{Escape sequences} 18.159 -\label{sec:template:escape} 18.160 - 18.161 -Mercurial's templating engine recognises the most commonly used escape 18.162 -sequences in strings. When it sees a backslash (``\Verb+\+'') 18.163 -character, it looks at the following character and substitutes the two 18.164 -characters with a single replacement, as described below. 18.165 - 18.166 -\begin{itemize} 18.167 -\item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'', 18.168 - ASCII~134. 18.169 -\item[\Verb+\textbackslash n+] Newline, ASCII~12. 18.170 -\item[\Verb+\textbackslash r+] Carriage return, ASCII~15. 18.171 -\item[\Verb+\textbackslash t+] Tab, ASCII~11. 18.172 -\item[\Verb+\textbackslash v+] Vertical tab, ASCII~13. 18.173 -\item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173. 18.174 -\item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175. 18.175 -\end{itemize} 18.176 - 18.177 -As indicated above, if you want the expansion of a template to contain 18.178 -a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you 18.179 -must escape it. 18.180 - 18.181 -\section{Filtering keywords to change their results} 18.182 -\label{sec:template:filter} 18.183 - 18.184 -Some of the results of template expansion are not immediately easy to 18.185 -use. Mercurial lets you specify an optional chain of \emph{filters} 18.186 -to modify the result of expanding a keyword. You have already seen a 18.187 -common filter, \tplkwfilt{date}{isodate}, in action above, to make a 18.188 -date readable. 18.189 - 18.190 -Below is a list of the most commonly used filters that Mercurial 18.191 -supports. While some filters can be applied to any text, others can 18.192 -only be used in specific circumstances. The name of each filter is 18.193 -followed first by an indication of where it can be used, then a 18.194 -description of its effect. 18.195 - 18.196 -\begin{itemize} 18.197 -\item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+'' 18.198 - tag before the end of every line except the last. For example, 18.199 - ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''. 18.200 -\item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the 18.201 - age of the date, relative to the current time. Yields a string like 18.202 - ``\Verb+10 minutes+''. 18.203 -\item[\tplfilter{basename}] Any text, but most useful for the 18.204 - \tplkword{files} keyword and its relatives. Treat the text as a 18.205 - path, and return the basename. For example, ``\Verb+foo/bar/baz+'' 18.206 - becomes ``\Verb+baz+''. 18.207 -\item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date 18.208 - in a similar format to the Unix \tplkword{date} command, but with 18.209 - timezone included. Yields a string like 18.210 - ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''. 18.211 -\item[\tplkwfilt{author}{domain}] Any text, but most useful for the 18.212 - \tplkword{author} keyword. Finds the first string that looks like 18.213 - an email address, and extract just the domain component. For 18.214 - example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes 18.215 - ``\Verb+serpentine.com+''. 18.216 -\item[\tplkwfilt{author}{email}] Any text, but most useful for the 18.217 - \tplkword{author} keyword. Extract the first string that looks like 18.218 - an email address. For example, 18.219 - ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes 18.220 - ``\Verb+bos@serpentine.com+''. 18.221 -\item[\tplfilter{escape}] Any text. Replace the special XML/XHTML 18.222 - characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with 18.223 - XML entities. 18.224 -\item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68 18.225 - columns. This is useful before you pass text through the 18.226 - \tplfilter{tabindent} filter, and still want it to fit in an 18.227 - 80-column fixed-font window. 18.228 -\item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76 18.229 - columns. 18.230 -\item[\tplfilter{firstline}] Any text. Yield the first line of text, 18.231 - without any trailing newlines. 18.232 -\item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the 18.233 - date as a pair of readable numbers. Yields a string like 18.234 - ``\Verb+1157407993 25200+''. 18.235 -\item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the 18.236 - date as a text string in ISO~8601 format. Yields a string like 18.237 - ``\Verb+2006-09-04 15:13:13 -0700+''. 18.238 -\item[\tplfilter{obfuscate}] Any text, but most useful for the 18.239 - \tplkword{author} keyword. Yield the input text rendered as a 18.240 - sequence of XML entities. This helps to defeat some particularly 18.241 - stupid screen-scraping email harvesting spambots. 18.242 -\item[\tplkwfilt{author}{person}] Any text, but most useful for the 18.243 - \tplkword{author} keyword. Yield the text before an email address. 18.244 - For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' 18.245 - becomes ``\Verb+Bryan O'Sullivan+''. 18.246 -\item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a 18.247 - date using the same format used in email headers. Yields a string 18.248 - like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''. 18.249 -\item[\tplkwfilt{node}{short}] Changeset hash. Yield the short form 18.250 - of a changeset hash, i.e.~a 12-character hexadecimal string. 18.251 -\item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render 18.252 - the year, month, and day of the date. Yields a string like 18.253 - ``\Verb+2006-09-04+''. 18.254 -\item[\tplfilter{strip}] Any text. Strip all leading and trailing 18.255 - whitespace from the string. 18.256 -\item[\tplfilter{tabindent}] Any text. Yield the text, with every line 18.257 - except the first starting with a tab character. 18.258 -\item[\tplfilter{urlescape}] Any text. Escape all characters that are 18.259 - considered ``special'' by URL parsers. For example, \Verb+foo bar+ 18.260 - becomes \Verb+foo%20bar+. 18.261 -\item[\tplkwfilt{author}{user}] Any text, but most useful for the 18.262 - \tplkword{author} keyword. Return the ``user'' portion of an email 18.263 - address. For example, 18.264 - ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes 18.265 - ``\Verb+bos+''. 18.266 -\end{itemize} 18.267 - 18.268 -\begin{figure} 18.269 - \interaction{template.simple.manyfilters} 18.270 - \caption{Template filters in action} 18.271 - \label{fig:template:filters} 18.272 -\end{figure} 18.273 - 18.274 -\begin{note} 18.275 - If you try to apply a filter to a piece of data that it cannot 18.276 - process, Mercurial will fail and print a Python exception. For 18.277 - example, trying to run the output of the \tplkword{desc} keyword 18.278 - into the \tplkwfilt{date}{isodate} filter is not a good idea. 18.279 -\end{note} 18.280 - 18.281 -\subsection{Combining filters} 18.282 - 18.283 -It is easy to combine filters to yield output in the form you would 18.284 -like. The following chain of filters tidies up a description, then 18.285 -makes sure that it fits cleanly into 68 columns, then indents it by a 18.286 -further 8~characters (at least on Unix-like systems, where a tab is 18.287 -conventionally 8~characters wide). 18.288 - 18.289 -\interaction{template.simple.combine} 18.290 - 18.291 -Note the use of ``\Verb+\t+'' (a tab character) in the template to 18.292 -force the first line to be indented; this is necessary since 18.293 -\tplkword{tabindent} indents all lines \emph{except} the first. 18.294 - 18.295 -Keep in mind that the order of filters in a chain is significant. The 18.296 -first filter is applied to the result of the keyword; the second to 18.297 -the result of the first filter; and so on. For example, using 18.298 -\Verb+fill68|tabindent+ gives very different results from 18.299 -\Verb+tabindent|fill68+. 18.300 - 18.301 - 18.302 -\section{From templates to styles} 18.303 - 18.304 -A command line template provides a quick and simple way to format some 18.305 -output. Templates can become verbose, though, and it's useful to be 18.306 -able to give a template a name. A style file is a template with a 18.307 -name, stored in a file. 18.308 - 18.309 -More than that, using a style file unlocks the power of Mercurial's 18.310 -templating engine in ways that are not possible using the command line 18.311 -\hgopt{log}{--template} option. 18.312 - 18.313 -\subsection{The simplest of style files} 18.314 - 18.315 -Our simple style file contains just one line: 18.316 - 18.317 -\interaction{template.simple.rev} 18.318 - 18.319 -This tells Mercurial, ``if you're printing a changeset, use the text 18.320 -on the right as the template''. 18.321 - 18.322 -\subsection{Style file syntax} 18.323 - 18.324 -The syntax rules for a style file are simple. 18.325 - 18.326 -\begin{itemize} 18.327 -\item The file is processed one line at a time. 18.328 - 18.329 -\item Leading and trailing white space are ignored. 18.330 - 18.331 -\item Empty lines are skipped. 18.332 - 18.333 -\item If a line starts with either of the characters ``\texttt{\#}'' or 18.334 - ``\texttt{;}'', the entire line is treated as a comment, and skipped 18.335 - as if empty. 18.336 - 18.337 -\item A line starts with a keyword. This must start with an 18.338 - alphabetic character or underscore, and can subsequently contain any 18.339 - alphanumeric character or underscore. (In regexp notation, a 18.340 - keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.) 18.341 - 18.342 -\item The next element must be an ``\texttt{=}'' character, which can 18.343 - be preceded or followed by an arbitrary amount of white space. 18.344 - 18.345 -\item If the rest of the line starts and ends with matching quote 18.346 - characters (either single or double quote), it is treated as a 18.347 - template body. 18.348 - 18.349 -\item If the rest of the line \emph{does not} start with a quote 18.350 - character, it is treated as the name of a file; the contents of this 18.351 - file will be read and used as a template body. 18.352 -\end{itemize} 18.353 - 18.354 -\section{Style files by example} 18.355 - 18.356 -To illustrate how to write a style file, we will construct a few by 18.357 -example. Rather than provide a complete style file and walk through 18.358 -it, we'll mirror the usual process of developing a style file by 18.359 -starting with something very simple, and walking through a series of 18.360 -successively more complete examples. 18.361 - 18.362 -\subsection{Identifying mistakes in style files} 18.363 - 18.364 -If Mercurial encounters a problem in a style file you are working on, 18.365 -it prints a terse error message that, once you figure out what it 18.366 -means, is actually quite useful. 18.367 - 18.368 -\interaction{template.svnstyle.syntax.input} 18.369 - 18.370 -Notice that \filename{broken.style} attempts to define a 18.371 -\texttt{changeset} keyword, but forgets to give any content for it. 18.372 -When instructed to use this style file, Mercurial promptly complains. 18.373 - 18.374 -\interaction{template.svnstyle.syntax.error} 18.375 - 18.376 -This error message looks intimidating, but it is not too hard to 18.377 -follow. 18.378 - 18.379 -\begin{itemize} 18.380 -\item The first component is simply Mercurial's way of saying ``I am 18.381 - giving up''. 18.382 - \begin{codesample4} 18.383 - \textbf{abort:} broken.style:1: parse error 18.384 - \end{codesample4} 18.385 - 18.386 -\item Next comes the name of the style file that contains the error. 18.387 - \begin{codesample4} 18.388 - abort: \textbf{broken.style}:1: parse error 18.389 - \end{codesample4} 18.390 - 18.391 -\item Following the file name is the line number where the error was 18.392 - encountered. 18.393 - \begin{codesample4} 18.394 - abort: broken.style:\textbf{1}: parse error 18.395 - \end{codesample4} 18.396 - 18.397 -\item Finally, a description of what went wrong. 18.398 - \begin{codesample4} 18.399 - abort: broken.style:1: \textbf{parse error} 18.400 - \end{codesample4} 18.401 - The description of the problem is not always clear (as in this 18.402 - case), but even when it is cryptic, it is almost always trivial to 18.403 - visually inspect the offending line in the style file and see what 18.404 - is wrong. 18.405 -\end{itemize} 18.406 - 18.407 -\subsection{Uniquely identifying a repository} 18.408 - 18.409 -If you would like to be able to identify a Mercurial repository 18.410 -``fairly uniquely'' using a short string as an identifier, you can 18.411 -use the first revision in the repository. 18.412 -\interaction{template.svnstyle.id} 18.413 -This is not guaranteed to be unique, but it is nevertheless useful in 18.414 -many cases. 18.415 -\begin{itemize} 18.416 -\item It will not work in a completely empty repository, because such 18.417 - a repository does not have a revision~zero. 18.418 -\item Neither will it work in the (extremely rare) case where a 18.419 - repository is a merge of two or more formerly independent 18.420 - repositories, and you still have those repositories around. 18.421 -\end{itemize} 18.422 -Here are some uses to which you could put this identifier: 18.423 -\begin{itemize} 18.424 -\item As a key into a table for a database that manages repositories 18.425 - on a server. 18.426 -\item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple. 18.427 - Save this information away when you run an automated build or other 18.428 - activity, so that you can ``replay'' the build later if necessary. 18.429 -\end{itemize} 18.430 - 18.431 -\subsection{Mimicking Subversion's output} 18.432 - 18.433 -Let's try to emulate the default output format used by another 18.434 -revision control tool, Subversion. 18.435 -\interaction{template.svnstyle.short} 18.436 - 18.437 -Since Subversion's output style is fairly simple, it is easy to 18.438 -copy-and-paste a hunk of its output into a file, and replace the text 18.439 -produced above by Subversion with the template values we'd like to see 18.440 -expanded. 18.441 -\interaction{template.svnstyle.template} 18.442 - 18.443 -There are a few small ways in which this template deviates from the 18.444 -output produced by Subversion. 18.445 -\begin{itemize} 18.446 -\item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep 18.447 - 2006}'' in the example output above) in parentheses. Mercurial's 18.448 - templating engine does not provide a way to display a date in this 18.449 - format without also printing the time and time zone. 18.450 -\item We emulate Subversion's printing of ``separator'' lines full of 18.451 - ``\texttt{-}'' characters by ending the template with such a line. 18.452 - We use the templating engine's \tplkword{header} keyword to print a 18.453 - separator line as the first line of output (see below), thus 18.454 - achieving similar output to Subversion. 18.455 -\item Subversion's output includes a count in the header of the number 18.456 - of lines in the commit message. We cannot replicate this in 18.457 - Mercurial; the templating engine does not currently provide a filter 18.458 - that counts the number of lines the template generates. 18.459 -\end{itemize} 18.460 -It took me no more than a minute or two of work to replace literal 18.461 -text from an example of Subversion's output with some keywords and 18.462 -filters to give the template above. The style file simply refers to 18.463 -the template. 18.464 -\interaction{template.svnstyle.style} 18.465 - 18.466 -We could have included the text of the template file directly in the 18.467 -style file by enclosing it in quotes and replacing the newlines with 18.468 -``\verb!\n!'' sequences, but it would have made the style file too 18.469 -difficult to read. Readability is a good guide when you're trying to 18.470 -decide whether some text belongs in a style file, or in a template 18.471 -file that the style file points to. If the style file will look too 18.472 -big or cluttered if you insert a literal piece of text, drop it into a 18.473 -template instead. 18.474 - 18.475 -%%% Local Variables: 18.476 -%%% mode: latex 18.477 -%%% TeX-master: "00book" 18.478 -%%% End:
19.1 --- a/en/ch12-mq.tex Thu Mar 05 21:52:23 2009 +0200 19.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 19.3 @@ -1,1043 +0,0 @@ 19.4 -\chapter{Managing change with Mercurial Queues} 19.5 -\label{chap:mq} 19.6 - 19.7 -\section{The patch management problem} 19.8 -\label{sec:mq:patch-mgmt} 19.9 - 19.10 -Here is a common scenario: you need to install a software package from 19.11 -source, but you find a bug that you must fix in the source before you 19.12 -can start using the package. You make your changes, forget about the 19.13 -package for a while, and a few months later you need to upgrade to a 19.14 -newer version of the package. If the newer version of the package 19.15 -still has the bug, you must extract your fix from the older source 19.16 -tree and apply it against the newer version. This is a tedious task, 19.17 -and it's easy to make mistakes. 19.18 - 19.19 -This is a simple case of the ``patch management'' problem. You have 19.20 -an ``upstream'' source tree that you can't change; you need to make 19.21 -some local changes on top of the upstream tree; and you'd like to be 19.22 -able to keep those changes separate, so that you can apply them to 19.23 -newer versions of the upstream source. 19.24 - 19.25 -The patch management problem arises in many situations. Probably the 19.26 -most visible is that a user of an open source software project will 19.27 -contribute a bug fix or new feature to the project's maintainers in the 19.28 -form of a patch. 19.29 - 19.30 -Distributors of operating systems that include open source software 19.31 -often need to make changes to the packages they distribute so that 19.32 -they will build properly in their environments. 19.33 - 19.34 -When you have few changes to maintain, it is easy to manage a single 19.35 -patch using the standard \command{diff} and \command{patch} programs 19.36 -(see section~\ref{sec:mq:patch} for a discussion of these tools). 19.37 -Once the number of changes grows, it starts to make sense to maintain 19.38 -patches as discrete ``chunks of work,'' so that for example a single 19.39 -patch will contain only one bug fix (the patch might modify several 19.40 -files, but it's doing ``only one thing''), and you may have a number 19.41 -of such patches for different bugs you need fixed and local changes 19.42 -you require. In this situation, if you submit a bug fix patch to the 19.43 -upstream maintainers of a package and they include your fix in a 19.44 -subsequent release, you can simply drop that single patch when you're 19.45 -updating to the newer release. 19.46 - 19.47 -Maintaining a single patch against an upstream tree is a little 19.48 -tedious and error-prone, but not difficult. However, the complexity 19.49 -of the problem grows rapidly as the number of patches you have to 19.50 -maintain increases. With more than a tiny number of patches in hand, 19.51 -understanding which ones you have applied and maintaining them moves 19.52 -from messy to overwhelming. 19.53 - 19.54 -Fortunately, Mercurial includes a powerful extension, Mercurial Queues 19.55 -(or simply ``MQ''), that massively simplifies the patch management 19.56 -problem. 19.57 - 19.58 -\section{The prehistory of Mercurial Queues} 19.59 -\label{sec:mq:history} 19.60 - 19.61 -During the late 1990s, several Linux kernel developers started to 19.62 -maintain ``patch series'' that modified the behaviour of the Linux 19.63 -kernel. Some of these series were focused on stability, some on 19.64 -feature coverage, and others were more speculative. 19.65 - 19.66 -The sizes of these patch series grew rapidly. In 2002, Andrew Morton 19.67 -published some shell scripts he had been using to automate the task of 19.68 -managing his patch queues. Andrew was successfully using these 19.69 -scripts to manage hundreds (sometimes thousands) of patches on top of 19.70 -the Linux kernel. 19.71 - 19.72 -\subsection{A patchwork quilt} 19.73 -\label{sec:mq:quilt} 19.74 - 19.75 -In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the 19.76 -approach of Andrew's scripts and published a tool called ``patchwork 19.77 -quilt''~\cite{web:quilt}, or simply ``quilt'' 19.78 -(see~\cite{gruenbacher:2005} for a paper describing it). Because 19.79 -quilt substantially automated patch management, it rapidly gained a 19.80 -large following among open source software developers. 19.81 - 19.82 -Quilt manages a \emph{stack of patches} on top of a directory tree. 19.83 -To begin, you tell quilt to manage a directory tree, and tell it which 19.84 -files you want to manage; it stores away the names and contents of 19.85 -those files. To fix a bug, you create a new patch (using a single 19.86 -command), edit the files you need to fix, then ``refresh'' the patch. 19.87 - 19.88 -The refresh step causes quilt to scan the directory tree; it updates 19.89 -the patch with all of the changes you have made. You can create 19.90 -another patch on top of the first, which will track the changes 19.91 -required to modify the tree from ``tree with one patch applied'' to 19.92 -``tree with two patches applied''. 19.93 - 19.94 -You can \emph{change} which patches are applied to the tree. If you 19.95 -``pop'' a patch, the changes made by that patch will vanish from the 19.96 -directory tree. Quilt remembers which patches you have popped, 19.97 -though, so you can ``push'' a popped patch again, and the directory 19.98 -tree will be restored to contain the modifications in the patch. Most 19.99 -importantly, you can run the ``refresh'' command at any time, and the 19.100 -topmost applied patch will be updated. This means that you can, at 19.101 -any time, change both which patches are applied and what 19.102 -modifications those patches make. 19.103 - 19.104 -Quilt knows nothing about revision control tools, so it works equally 19.105 -well on top of an unpacked tarball or a Subversion working copy. 19.106 - 19.107 -\subsection{From patchwork quilt to Mercurial Queues} 19.108 -\label{sec:mq:quilt-mq} 19.109 - 19.110 -In mid-2005, Chris Mason took the features of quilt and wrote an 19.111 -extension that he called Mercurial Queues, which added quilt-like 19.112 -behaviour to Mercurial. 19.113 - 19.114 -The key difference between quilt and MQ is that quilt knows nothing 19.115 -about revision control systems, while MQ is \emph{integrated} into 19.116 -Mercurial. Each patch that you push is represented as a Mercurial 19.117 -changeset. Pop a patch, and the changeset goes away. 19.118 - 19.119 -Because quilt does not care about revision control tools, it is still 19.120 -a tremendously useful piece of software to know about for situations 19.121 -where you cannot use Mercurial and MQ. 19.122 - 19.123 -\section{The huge advantage of MQ} 19.124 - 19.125 -I cannot overstate the value that MQ offers through the unification of 19.126 -patches and revision control. 19.127 - 19.128 -A major reason that patches have persisted in the free software and 19.129 -open source world---in spite of the availability of increasingly 19.130 -capable revision control tools over the years---is the \emph{agility} 19.131 -they offer. 19.132 - 19.133 -Traditional revision control tools make a permanent, irreversible 19.134 -record of everything that you do. While this has great value, it's 19.135 -also somewhat stifling. If you want to perform a wild-eyed 19.136 -experiment, you have to be careful in how you go about it, or you risk 19.137 -leaving unneeded---or worse, misleading or destabilising---traces of 19.138 -your missteps and errors in the permanent revision record. 19.139 - 19.140 -By contrast, MQ's marriage of distributed revision control with 19.141 -patches makes it much easier to isolate your work. Your patches live 19.142 -on top of normal revision history, and you can make them disappear or 19.143 -reappear at will. If you don't like a patch, you can drop it. If a 19.144 -patch isn't quite as you want it to be, simply fix it---as many times 19.145 -as you need to, until you have refined it into the form you desire. 19.146 - 19.147 -As an example, the integration of patches with revision control makes 19.148 -understanding patches and debugging their effects---and their 19.149 -interplay with the code they're based on---\emph{enormously} easier. 19.150 -Since every applied patch has an associated changeset, you can use 19.151 -\hgcmdargs{log}{\emph{filename}} to see which changesets and patches 19.152 -affected a file. You can use the \hgext{bisect} command to 19.153 -binary-search through all changesets and applied patches to see where 19.154 -a bug got introduced or fixed. You can use the \hgcmd{annotate} 19.155 -command to see which changeset or patch modified a particular line of 19.156 -a source file. And so on. 19.157 - 19.158 -\section{Understanding patches} 19.159 -\label{sec:mq:patch} 19.160 - 19.161 -Because MQ doesn't hide its patch-oriented nature, it is helpful to 19.162 -understand what patches are, and a little about the tools that work 19.163 -with them. 19.164 - 19.165 -The traditional Unix \command{diff} command compares two files, and 19.166 -prints a list of differences between them. The \command{patch} command 19.167 -understands these differences as \emph{modifications} to make to a 19.168 -file. Take a look at figure~\ref{ex:mq:diff} for a simple example of 19.169 -these commands in action. 19.170 - 19.171 -\begin{figure}[ht] 19.172 - \interaction{mq.dodiff.diff} 19.173 - \caption{Simple uses of the \command{diff} and \command{patch} commands} 19.174 - \label{ex:mq:diff} 19.175 -\end{figure} 19.176 - 19.177 -The type of file that \command{diff} generates (and \command{patch} 19.178 -takes as input) is called a ``patch'' or a ``diff''; there is no 19.179 -difference between a patch and a diff. (We'll use the term ``patch'', 19.180 -since it's more commonly used.) 19.181 - 19.182 -A patch file can start with arbitrary text; the \command{patch} 19.183 -command ignores this text, but MQ uses it as the commit message when 19.184 -creating changesets. To find the beginning of the patch content, 19.185 -\command{patch} searches for the first line that starts with the 19.186 -string ``\texttt{diff~-}''. 19.187 - 19.188 -MQ works with \emph{unified} diffs (\command{patch} can accept several 19.189 -other diff formats, but MQ doesn't). A unified diff contains two 19.190 -kinds of header. The \emph{file header} describes the file being 19.191 -modified; it contains the name of the file to modify. When 19.192 -\command{patch} sees a new file header, it looks for a file with that 19.193 -name to start modifying. 19.194 - 19.195 -After the file header comes a series of \emph{hunks}. Each hunk 19.196 -starts with a header; this identifies the range of line numbers within 19.197 -the file that the hunk should modify. Following the header, a hunk 19.198 -starts and ends with a few (usually three) lines of text from the 19.199 -unmodified file; these are called the \emph{context} for the hunk. If 19.200 -there's only a small amount of context between successive hunks, 19.201 -\command{diff} doesn't print a new hunk header; it just runs the hunks 19.202 -together, with a few lines of context between modifications. 19.203 - 19.204 -Each line of context begins with a space character. Within the hunk, 19.205 -a line that begins with ``\texttt{-}'' means ``remove this line,'' 19.206 -while a line that begins with ``\texttt{+}'' means ``insert this 19.207 -line.'' For example, a line that is modified is represented by one 19.208 -deletion and one insertion. 19.209 - 19.210 -We will return to some of the more subtle aspects of patches later (in 19.211 -section~\ref{sec:mq:adv-patch}), but you should have enough information 19.212 -now to use MQ. 19.213 - 19.214 -\section{Getting started with Mercurial Queues} 19.215 -\label{sec:mq:start} 19.216 - 19.217 -Because MQ is implemented as an extension, you must explicitly enable 19.218 -before you can use it. (You don't need to download anything; MQ ships 19.219 -with the standard Mercurial distribution.) To enable MQ, edit your 19.220 -\tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}. 19.221 - 19.222 -\begin{figure}[ht] 19.223 - \begin{codesample4} 19.224 - [extensions] 19.225 - hgext.mq = 19.226 - \end{codesample4} 19.227 - \label{ex:mq:config} 19.228 - \caption{Contents to add to \tildefile{.hgrc} to enable the MQ extension} 19.229 -\end{figure} 19.230 - 19.231 -Once the extension is enabled, it will make a number of new commands 19.232 -available. To verify that the extension is working, you can use 19.233 -\hgcmd{help} to see if the \hgxcmd{mq}{qinit} command is now available; see 19.234 -the example in figure~\ref{ex:mq:enabled}. 19.235 - 19.236 -\begin{figure}[ht] 19.237 - \interaction{mq.qinit-help.help} 19.238 - \caption{How to verify that MQ is enabled} 19.239 - \label{ex:mq:enabled} 19.240 -\end{figure} 19.241 - 19.242 -You can use MQ with \emph{any} Mercurial repository, and its commands 19.243 -only operate within that repository. To get started, simply prepare 19.244 -the repository using the \hgxcmd{mq}{qinit} command (see 19.245 -figure~\ref{ex:mq:qinit}). This command creates an empty directory 19.246 -called \sdirname{.hg/patches}, where MQ will keep its metadata. As 19.247 -with many Mercurial commands, the \hgxcmd{mq}{qinit} command prints nothing 19.248 -if it succeeds. 19.249 - 19.250 -\begin{figure}[ht] 19.251 - \interaction{mq.tutorial.qinit} 19.252 - \caption{Preparing a repository for use with MQ} 19.253 - \label{ex:mq:qinit} 19.254 -\end{figure} 19.255 - 19.256 -\begin{figure}[ht] 19.257 - \interaction{mq.tutorial.qnew} 19.258 - \caption{Creating a new patch} 19.259 - \label{ex:mq:qnew} 19.260 -\end{figure} 19.261 - 19.262 -\subsection{Creating a new patch} 19.263 - 19.264 -To begin work on a new patch, use the \hgxcmd{mq}{qnew} command. This 19.265 -command takes one argument, the name of the patch to create. MQ will 19.266 -use this as the name of an actual file in the \sdirname{.hg/patches} 19.267 -directory, as you can see in figure~\ref{ex:mq:qnew}. 19.268 - 19.269 -Also newly present in the \sdirname{.hg/patches} directory are two 19.270 -other files, \sfilename{series} and \sfilename{status}. The 19.271 -\sfilename{series} file lists all of the patches that MQ knows about 19.272 -for this repository, with one patch per line. Mercurial uses the 19.273 -\sfilename{status} file for internal book-keeping; it tracks all of the 19.274 -patches that MQ has \emph{applied} in this repository. 19.275 - 19.276 -\begin{note} 19.277 - You may sometimes want to edit the \sfilename{series} file by hand; 19.278 - for example, to change the sequence in which some patches are 19.279 - applied. However, manually editing the \sfilename{status} file is 19.280 - almost always a bad idea, as it's easy to corrupt MQ's idea of what 19.281 - is happening. 19.282 -\end{note} 19.283 - 19.284 -Once you have created your new patch, you can edit files in the 19.285 -working directory as you usually would. All of the normal Mercurial 19.286 -commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as 19.287 -they did before. 19.288 - 19.289 -\subsection{Refreshing a patch} 19.290 - 19.291 -When you reach a point where you want to save your work, use the 19.292 -\hgxcmd{mq}{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch 19.293 -you are working on. This command folds the changes you have made in 19.294 -the working directory into your patch, and updates its corresponding 19.295 -changeset to contain those changes. 19.296 - 19.297 -\begin{figure}[ht] 19.298 - \interaction{mq.tutorial.qrefresh} 19.299 - \caption{Refreshing a patch} 19.300 - \label{ex:mq:qrefresh} 19.301 -\end{figure} 19.302 - 19.303 -You can run \hgxcmd{mq}{qrefresh} as often as you like, so it's a good way 19.304 -to ``checkpoint'' your work. Refresh your patch at an opportune 19.305 -time; try an experiment; and if the experiment doesn't work out, 19.306 -\hgcmd{revert} your modifications back to the last time you refreshed. 19.307 - 19.308 -\begin{figure}[ht] 19.309 - \interaction{mq.tutorial.qrefresh2} 19.310 - \caption{Refresh a patch many times to accumulate changes} 19.311 - \label{ex:mq:qrefresh2} 19.312 -\end{figure} 19.313 - 19.314 -\subsection{Stacking and tracking patches} 19.315 - 19.316 -Once you have finished working on a patch, or need to work on another, 19.317 -you can use the \hgxcmd{mq}{qnew} command again to create a new patch. 19.318 -Mercurial will apply this patch on top of your existing patch. See 19.319 -figure~\ref{ex:mq:qnew2} for an example. Notice that the patch 19.320 -contains the changes in our prior patch as part of its context (you 19.321 -can see this more clearly in the output of \hgcmd{annotate}). 19.322 - 19.323 -\begin{figure}[ht] 19.324 - \interaction{mq.tutorial.qnew2} 19.325 - \caption{Stacking a second patch on top of the first} 19.326 - \label{ex:mq:qnew2} 19.327 -\end{figure} 19.328 - 19.329 -So far, with the exception of \hgxcmd{mq}{qnew} and \hgxcmd{mq}{qrefresh}, we've 19.330 -been careful to only use regular Mercurial commands. However, MQ 19.331 -provides many commands that are easier to use when you are thinking 19.332 -about patches, as illustrated in figure~\ref{ex:mq:qseries}: 19.333 - 19.334 -\begin{itemize} 19.335 -\item The \hgxcmd{mq}{qseries} command lists every patch that MQ knows 19.336 - about in this repository, from oldest to newest (most recently 19.337 - \emph{created}). 19.338 -\item The \hgxcmd{mq}{qapplied} command lists every patch that MQ has 19.339 - \emph{applied} in this repository, again from oldest to newest (most 19.340 - recently applied). 19.341 -\end{itemize} 19.342 - 19.343 -\begin{figure}[ht] 19.344 - \interaction{mq.tutorial.qseries} 19.345 - \caption{Understanding the patch stack with \hgxcmd{mq}{qseries} and 19.346 - \hgxcmd{mq}{qapplied}} 19.347 - \label{ex:mq:qseries} 19.348 -\end{figure} 19.349 - 19.350 -\subsection{Manipulating the patch stack} 19.351 - 19.352 -The previous discussion implied that there must be a difference 19.353 -between ``known'' and ``applied'' patches, and there is. MQ can 19.354 -manage a patch without it being applied in the repository. 19.355 - 19.356 -An \emph{applied} patch has a corresponding changeset in the 19.357 -repository, and the effects of the patch and changeset are visible in 19.358 -the working directory. You can undo the application of a patch using 19.359 -the \hgxcmd{mq}{qpop} command. MQ still \emph{knows about}, or manages, a 19.360 -popped patch, but the patch no longer has a corresponding changeset in 19.361 -the repository, and the working directory does not contain the changes 19.362 -made by the patch. Figure~\ref{fig:mq:stack} illustrates the 19.363 -difference between applied and tracked patches. 19.364 - 19.365 -\begin{figure}[ht] 19.366 - \centering 19.367 - \grafix{mq-stack} 19.368 - \caption{Applied and unapplied patches in the MQ patch stack} 19.369 - \label{fig:mq:stack} 19.370 -\end{figure} 19.371 - 19.372 -You can reapply an unapplied, or popped, patch using the \hgxcmd{mq}{qpush} 19.373 -command. This creates a new changeset to correspond to the patch, and 19.374 -the patch's changes once again become present in the working 19.375 -directory. See figure~\ref{ex:mq:qpop} for examples of \hgxcmd{mq}{qpop} 19.376 -and \hgxcmd{mq}{qpush} in action. Notice that once we have popped a patch 19.377 -or two patches, the output of \hgxcmd{mq}{qseries} remains the same, while 19.378 -that of \hgxcmd{mq}{qapplied} has changed. 19.379 - 19.380 -\begin{figure}[ht] 19.381 - \interaction{mq.tutorial.qpop} 19.382 - \caption{Modifying the stack of applied patches} 19.383 - \label{ex:mq:qpop} 19.384 -\end{figure} 19.385 - 19.386 -\subsection{Pushing and popping many patches} 19.387 - 19.388 -While \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} each operate on a single patch at 19.389 -a time by default, you can push and pop many patches in one go. The 19.390 -\hgxopt{mq}{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all 19.391 -unapplied patches, while the \hgxopt{mq}{qpop}{-a} option to \hgxcmd{mq}{qpop} 19.392 -causes it to pop all applied patches. (For some more ways to push and 19.393 -pop many patches, see section~\ref{sec:mq:perf} below.) 19.394 - 19.395 -\begin{figure}[ht] 19.396 - \interaction{mq.tutorial.qpush-a} 19.397 - \caption{Pushing all unapplied patches} 19.398 - \label{ex:mq:qpush-a} 19.399 -\end{figure} 19.400 - 19.401 -\subsection{Safety checks, and overriding them} 19.402 - 19.403 -Several MQ commands check the working directory before they do 19.404 -anything, and fail if they find any modifications. They do this to 19.405 -ensure that you won't lose any changes that you have made, but not yet 19.406 -incorporated into a patch. Figure~\ref{ex:mq:add} illustrates this; 19.407 -the \hgxcmd{mq}{qnew} command will not create a new patch if there are 19.408 -outstanding changes, caused in this case by the \hgcmd{add} of 19.409 -\filename{file3}. 19.410 - 19.411 -\begin{figure}[ht] 19.412 - \interaction{mq.tutorial.add} 19.413 - \caption{Forcibly creating a patch} 19.414 - \label{ex:mq:add} 19.415 -\end{figure} 19.416 - 19.417 -Commands that check the working directory all take an ``I know what 19.418 -I'm doing'' option, which is always named \option{-f}. The exact 19.419 -meaning of \option{-f} depends on the command. For example, 19.420 -\hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}} will incorporate any outstanding 19.421 -changes into the new patch it creates, but 19.422 -\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}} will revert modifications to any 19.423 -files affected by the patch that it is popping. Be sure to read the 19.424 -documentation for a command's \option{-f} option before you use it! 19.425 - 19.426 -\subsection{Working on several patches at once} 19.427 - 19.428 -The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost} 19.429 -applied patch. This means that you can suspend work on one patch (by 19.430 -refreshing it), pop or push to make a different patch the top, and 19.431 -work on \emph{that} patch for a while. 19.432 - 19.433 -Here's an example that illustrates how you can use this ability. 19.434 -Let's say you're developing a new feature as two patches. The first 19.435 -is a change to the core of your software, and the second---layered on 19.436 -top of the first---changes the user interface to use the code you just 19.437 -added to the core. If you notice a bug in the core while you're 19.438 -working on the UI patch, it's easy to fix the core. Simply 19.439 -\hgxcmd{mq}{qrefresh} the UI patch to save your in-progress changes, and 19.440 -\hgxcmd{mq}{qpop} down to the core patch. Fix the core bug, 19.441 -\hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI 19.442 -patch to continue where you left off. 19.443 - 19.444 -\section{More about patches} 19.445 -\label{sec:mq:adv-patch} 19.446 - 19.447 -MQ uses the GNU \command{patch} command to apply patches, so it's 19.448 -helpful to know a few more detailed aspects of how \command{patch} 19.449 -works, and about patches themselves. 19.450 - 19.451 -\subsection{The strip count} 19.452 - 19.453 -If you look at the file headers in a patch, you will notice that the 19.454 -pathnames usually have an extra component on the front that isn't 19.455 -present in the actual path name. This is a holdover from the way that 19.456 -people used to generate patches (people still do this, but it's 19.457 -somewhat rare with modern revision control tools). 19.458 - 19.459 -Alice would unpack a tarball, edit her files, then decide that she 19.460 -wanted to create a patch. So she'd rename her working directory, 19.461 -unpack the tarball again (hence the need for the rename), and use the 19.462 -\cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to 19.463 -recursively generate a patch between the unmodified directory and the 19.464 -modified one. The result would be that the name of the unmodified 19.465 -directory would be at the front of the left-hand path in every file 19.466 -header, and the name of the modified directory would be at the front 19.467 -of the right-hand path. 19.468 - 19.469 -Since someone receiving a patch from the Alices of the net would be 19.470 -unlikely to have unmodified and modified directories with exactly the 19.471 -same names, the \command{patch} command has a \cmdopt{patch}{-p} 19.472 -option that indicates the number of leading path name components to 19.473 -strip when trying to apply a patch. This number is called the 19.474 -\emph{strip count}. 19.475 - 19.476 -An option of ``\texttt{-p1}'' means ``use a strip count of one''. If 19.477 -\command{patch} sees a file name \filename{foo/bar/baz} in a file 19.478 -header, it will strip \filename{foo} and try to patch a file named 19.479 -\filename{bar/baz}. (Strictly speaking, the strip count refers to the 19.480 -number of \emph{path separators} (and the components that go with them 19.481 -) to strip. A strip count of one will turn \filename{foo/bar} into 19.482 -\filename{bar}, but \filename{/foo/bar} (notice the extra leading 19.483 -slash) into \filename{foo/bar}.) 19.484 - 19.485 -The ``standard'' strip count for patches is one; almost all patches 19.486 -contain one leading path name component that needs to be stripped. 19.487 -Mercurial's \hgcmd{diff} command generates path names in this form, 19.488 -and the \hgcmd{import} command and MQ expect patches to have a strip 19.489 -count of one. 19.490 - 19.491 -If you receive a patch from someone that you want to add to your patch 19.492 -queue, and the patch needs a strip count other than one, you cannot 19.493 -just \hgxcmd{mq}{qimport} the patch, because \hgxcmd{mq}{qimport} does not yet 19.494 -have a \texttt{-p} option (see~\bug{311}). Your best bet is to 19.495 -\hgxcmd{mq}{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}} 19.496 -to apply their patch, followed by \hgcmd{addremove} to pick up any 19.497 -files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}. 19.498 -This complexity may become unnecessary; see~\bug{311} for details. 19.499 -\subsection{Strategies for applying a patch} 19.500 - 19.501 -When \command{patch} applies a hunk, it tries a handful of 19.502 -successively less accurate strategies to try to make the hunk apply. 19.503 -This falling-back technique often makes it possible to take a patch 19.504 -that was generated against an old version of a file, and apply it 19.505 -against a newer version of that file. 19.506 - 19.507 -First, \command{patch} tries an exact match, where the line numbers, 19.508 -the context, and the text to be modified must apply exactly. If it 19.509 -cannot make an exact match, it tries to find an exact match for the 19.510 -context, without honouring the line numbering information. If this 19.511 -succeeds, it prints a line of output saying that the hunk was applied, 19.512 -but at some \emph{offset} from the original line number. 19.513 - 19.514 -If a context-only match fails, \command{patch} removes the first and 19.515 -last lines of the context, and tries a \emph{reduced} context-only 19.516 -match. If the hunk with reduced context succeeds, it prints a message 19.517 -saying that it applied the hunk with a \emph{fuzz factor} (the number 19.518 -after the fuzz factor indicates how many lines of context 19.519 -\command{patch} had to trim before the patch applied). 19.520 - 19.521 -When neither of these techniques works, \command{patch} prints a 19.522 -message saying that the hunk in question was rejected. It saves 19.523 -rejected hunks (also simply called ``rejects'') to a file with the 19.524 -same name, and an added \sfilename{.rej} extension. It also saves an 19.525 -unmodified copy of the file with a \sfilename{.orig} extension; the 19.526 -copy of the file without any extensions will contain any changes made 19.527 -by hunks that \emph{did} apply cleanly. If you have a patch that 19.528 -modifies \filename{foo} with six hunks, and one of them fails to 19.529 -apply, you will have: an unmodified \filename{foo.orig}, a 19.530 -\filename{foo.rej} containing one hunk, and \filename{foo}, containing 19.531 -the changes made by the five successful hunks. 19.532 - 19.533 -\subsection{Some quirks of patch representation} 19.534 - 19.535 -There are a few useful things to know about how \command{patch} works 19.536 -with files. 19.537 -\begin{itemize} 19.538 -\item This should already be obvious, but \command{patch} cannot 19.539 - handle binary files. 19.540 -\item Neither does it care about the executable bit; it creates new 19.541 - files as readable, but not executable. 19.542 -\item \command{patch} treats the removal of a file as a diff between 19.543 - the file to be removed and the empty file. So your idea of ``I 19.544 - deleted this file'' looks like ``every line of this file was 19.545 - deleted'' in a patch. 19.546 -\item It treats the addition of a file as a diff between the empty 19.547 - file and the file to be added. So in a patch, your idea of ``I 19.548 - added this file'' looks like ``every line of this file was added''. 19.549 -\item It treats a renamed file as the removal of the old name, and the 19.550 - addition of the new name. This means that renamed files have a big 19.551 - footprint in patches. (Note also that Mercurial does not currently 19.552 - try to infer when files have been renamed or copied in a patch.) 19.553 -\item \command{patch} cannot represent empty files, so you cannot use 19.554 - a patch to represent the notion ``I added this empty file to the 19.555 - tree''. 19.556 -\end{itemize} 19.557 -\subsection{Beware the fuzz} 19.558 - 19.559 -While applying a hunk at an offset, or with a fuzz factor, will often 19.560 -be completely successful, these inexact techniques naturally leave 19.561 -open the possibility of corrupting the patched file. The most common 19.562 -cases typically involve applying a patch twice, or at an incorrect 19.563 -location in the file. If \command{patch} or \hgxcmd{mq}{qpush} ever 19.564 -mentions an offset or fuzz factor, you should make sure that the 19.565 -modified files are correct afterwards. 19.566 - 19.567 -It's often a good idea to refresh a patch that has applied with an 19.568 -offset or fuzz factor; refreshing the patch generates new context 19.569 -information that will make it apply cleanly. I say ``often,'' not 19.570 -``always,'' because sometimes refreshing a patch will make it fail to 19.571 -apply against a different revision of the underlying files. In some 19.572 -cases, such as when you're maintaining a patch that must sit on top of 19.573 -multiple versions of a source tree, it's acceptable to have a patch 19.574 -apply with some fuzz, provided you've verified the results of the 19.575 -patching process in such cases. 19.576 - 19.577 -\subsection{Handling rejection} 19.578 - 19.579 -If \hgxcmd{mq}{qpush} fails to apply a patch, it will print an error 19.580 -message and exit. If it has left \sfilename{.rej} files behind, it is 19.581 -usually best to fix up the rejected hunks before you push more patches 19.582 -or do any further work. 19.583 - 19.584 -If your patch \emph{used to} apply cleanly, and no longer does because 19.585 -you've changed the underlying code that your patches are based on, 19.586 -Mercurial Queues can help; see section~\ref{sec:mq:merge} for details. 19.587 - 19.588 -Unfortunately, there aren't any great techniques for dealing with 19.589 -rejected hunks. Most often, you'll need to view the \sfilename{.rej} 19.590 -file and edit the target file, applying the rejected hunks by hand. 19.591 - 19.592 -If you're feeling adventurous, Neil Brown, a Linux kernel hacker, 19.593 -wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more 19.594 -vigorous than \command{patch} in its attempts to make a patch apply. 19.595 - 19.596 -Another Linux kernel hacker, Chris Mason (the author of Mercurial 19.597 -Queues), wrote a similar tool called 19.598 -\command{mpatch}~\cite{web:mpatch}, which takes a simple approach to 19.599 -automating the application of hunks rejected by \command{patch}. The 19.600 -\command{mpatch} command can help with four common reasons that a hunk 19.601 -may be rejected: 19.602 - 19.603 -\begin{itemize} 19.604 -\item The context in the middle of a hunk has changed. 19.605 -\item A hunk is missing some context at the beginning or end. 19.606 -\item A large hunk might apply better---either entirely or in 19.607 - part---if it was broken up into smaller hunks. 19.608 -\item A hunk removes lines with slightly different content than those 19.609 - currently present in the file. 19.610 -\end{itemize} 19.611 - 19.612 -If you use \command{wiggle} or \command{mpatch}, you should be doubly 19.613 -careful to check your results when you're done. In fact, 19.614 -\command{mpatch} enforces this method of double-checking the tool's 19.615 -output, by automatically dropping you into a merge program when it has 19.616 -done its job, so that you can verify its work and finish off any 19.617 -remaining merges. 19.618 - 19.619 -\section{Getting the best performance out of MQ} 19.620 -\label{sec:mq:perf} 19.621 - 19.622 -MQ is very efficient at handling a large number of patches. I ran 19.623 -some performance experiments in mid-2006 for a talk that I gave at the 19.624 -2006 EuroPython conference~\cite{web:europython}. I used as my data 19.625 -set the Linux 2.6.17-mm1 patch series, which consists of 1,738 19.626 -patches. I applied these on top of a Linux kernel repository 19.627 -containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux 19.628 -2.6.17. 19.629 - 19.630 -On my old, slow laptop, I was able to 19.631 -\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} all 1,738 patches in 3.5 minutes, 19.632 -and \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} them all in 30 seconds. (On a 19.633 -newer laptop, the time to push all patches dropped to two minutes.) I 19.634 -could \hgxcmd{mq}{qrefresh} one of the biggest patches (which made 22,779 19.635 -lines of changes to 287 files) in 6.6 seconds. 19.636 - 19.637 -Clearly, MQ is well suited to working in large trees, but there are a 19.638 -few tricks you can use to get the best performance of it. 19.639 - 19.640 -First of all, try to ``batch'' operations together. Every time you 19.641 -run \hgxcmd{mq}{qpush} or \hgxcmd{mq}{qpop}, these commands scan the working 19.642 -directory once to make sure you haven't made some changes and then 19.643 -forgotten to run \hgxcmd{mq}{qrefresh}. On a small tree, the time that 19.644 -this scan takes is unnoticeable. However, on a medium-sized tree 19.645 -(containing tens of thousands of files), it can take a second or more. 19.646 - 19.647 -The \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} commands allow you to push and pop 19.648 -multiple patches at a time. You can identify the ``destination 19.649 -patch'' that you want to end up at. When you \hgxcmd{mq}{qpush} with a 19.650 -destination specified, it will push patches until that patch is at the 19.651 -top of the applied stack. When you \hgxcmd{mq}{qpop} to a destination, MQ 19.652 -will pop patches until the destination patch is at the top. 19.653 - 19.654 -You can identify a destination patch using either the name of the 19.655 -patch, or by number. If you use numeric addressing, patches are 19.656 -counted from zero; this means that the first patch is zero, the second 19.657 -is one, and so on. 19.658 - 19.659 -\section{Updating your patches when the underlying code changes} 19.660 -\label{sec:mq:merge} 19.661 - 19.662 -It's common to have a stack of patches on top of an underlying 19.663 -repository that you don't modify directly. If you're working on 19.664 -changes to third-party code, or on a feature that is taking longer to 19.665 -develop than the rate of change of the code beneath, you will often 19.666 -need to sync up with the underlying code, and fix up any hunks in your 19.667 -patches that no longer apply. This is called \emph{rebasing} your 19.668 -patch series. 19.669 - 19.670 -The simplest way to do this is to \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} 19.671 -your patches, then \hgcmd{pull} changes into the underlying 19.672 -repository, and finally \hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}} your 19.673 -patches again. MQ will stop pushing any time it runs across a patch 19.674 -that fails to apply during conflicts, allowing you to fix your 19.675 -conflicts, \hgxcmd{mq}{qrefresh} the affected patch, and continue pushing 19.676 -until you have fixed your entire stack. 19.677 - 19.678 -This approach is easy to use and works well if you don't expect 19.679 -changes to the underlying code to affect how well your patches apply. 19.680 -If your patch stack touches code that is modified frequently or 19.681 -invasively in the underlying repository, however, fixing up rejected 19.682 -hunks by hand quickly becomes tiresome. 19.683 - 19.684 -It's possible to partially automate the rebasing process. If your 19.685 -patches apply cleanly against some revision of the underlying repo, MQ 19.686 -can use this information to help you to resolve conflicts between your 19.687 -patches and a different revision. 19.688 - 19.689 -The process is a little involved. 19.690 -\begin{enumerate} 19.691 -\item To begin, \hgcmdargs{qpush}{-a} all of your patches on top of 19.692 - the revision where you know that they apply cleanly. 19.693 -\item Save a backup copy of your patch directory using 19.694 - \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}. This prints 19.695 - the name of the directory that it has saved the patches in. It will 19.696 - save the patches to a directory called 19.697 - \sdirname{.hg/patches.\emph{N}}, where \texttt{\emph{N}} is a small 19.698 - integer. It also commits a ``save changeset'' on top of your 19.699 - applied patches; this is for internal book-keeping, and records the 19.700 - states of the \sfilename{series} and \sfilename{status} files. 19.701 -\item Use \hgcmd{pull} to bring new changes into the underlying 19.702 - repository. (Don't run \hgcmdargs{pull}{-u}; see below for why.) 19.703 -\item Update to the new tip revision, using 19.704 - \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you 19.705 - have pushed. 19.706 -\item Merge all patches using \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m} 19.707 - \hgxopt{mq}{qpush}{-a}}. The \hgxopt{mq}{qpush}{-m} option to \hgxcmd{mq}{qpush} 19.708 - tells MQ to perform a three-way merge if the patch fails to apply. 19.709 -\end{enumerate} 19.710 - 19.711 -During the \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}, each patch in the 19.712 -\sfilename{series} file is applied normally. If a patch applies with 19.713 -fuzz or rejects, MQ looks at the queue you \hgxcmd{mq}{qsave}d, and 19.714 -performs a three-way merge with the corresponding changeset. This 19.715 -merge uses Mercurial's normal merge machinery, so it may pop up a GUI 19.716 -merge tool to help you to resolve problems. 19.717 - 19.718 -When you finish resolving the effects of a patch, MQ refreshes your 19.719 -patch based on the result of the merge. 19.720 - 19.721 -At the end of this process, your repository will have one extra head 19.722 -from the old patch queue, and a copy of the old patch queue will be in 19.723 -\sdirname{.hg/patches.\emph{N}}. You can remove the extra head using 19.724 -\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}} 19.725 -or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once 19.726 -you are sure that you no longer need it as a backup. 19.727 - 19.728 -\section{Identifying patches} 19.729 - 19.730 -MQ commands that work with patches let you refer to a patch either by 19.731 -using its name or by a number. By name is obvious enough; pass the 19.732 -name \filename{foo.patch} to \hgxcmd{mq}{qpush}, for example, and it will 19.733 -push patches until \filename{foo.patch} is applied. 19.734 - 19.735 -As a shortcut, you can refer to a patch using both a name and a 19.736 -numeric offset; \texttt{foo.patch-2} means ``two patches before 19.737 -\texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches 19.738 -after \texttt{bar.patch}''. 19.739 - 19.740 -Referring to a patch by index isn't much different. The first patch 19.741 -printed in the output of \hgxcmd{mq}{qseries} is patch zero (yes, it's one 19.742 -of those start-at-zero counting systems); the second is patch one; and 19.743 -so on. 19.744 - 19.745 -MQ also makes it easy to work with patches when you are using normal 19.746 -Mercurial commands. Every command that accepts a changeset ID will 19.747 -also accept the name of an applied patch. MQ augments the tags 19.748 -normally in the repository with an eponymous one for each applied 19.749 -patch. In addition, the special tags \index{tags!special tag 19.750 - names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag 19.751 - names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and 19.752 -topmost applied patches, respectively. 19.753 - 19.754 -These additions to Mercurial's normal tagging capabilities make 19.755 -dealing with patches even more of a breeze. 19.756 -\begin{itemize} 19.757 -\item Want to patchbomb a mailing list with your latest series of 19.758 - changes? 19.759 - \begin{codesample4} 19.760 - hg email qbase:qtip 19.761 - \end{codesample4} 19.762 - (Don't know what ``patchbombing'' is? See 19.763 - section~\ref{sec:hgext:patchbomb}.) 19.764 -\item Need to see all of the patches since \texttt{foo.patch} that 19.765 - have touched files in a subdirectory of your tree? 19.766 - \begin{codesample4} 19.767 - hg log -r foo.patch:qtip \emph{subdir} 19.768 - \end{codesample4} 19.769 -\end{itemize} 19.770 - 19.771 -Because MQ makes the names of patches available to the rest of 19.772 -Mercurial through its normal internal tag machinery, you don't need to 19.773 -type in the entire name of a patch when you want to identify it by 19.774 -name. 19.775 - 19.776 -\begin{figure}[ht] 19.777 - \interaction{mq.id.output} 19.778 - \caption{Using MQ's tag features to work with patches} 19.779 - \label{ex:mq:id} 19.780 -\end{figure} 19.781 - 19.782 -Another nice consequence of representing patch names as tags is that 19.783 -when you run the \hgcmd{log} command, it will display a patch's name 19.784 -as a tag, simply as part of its normal output. This makes it easy to 19.785 -visually distinguish applied patches from underlying ``normal'' 19.786 -revisions. Figure~\ref{ex:mq:id} shows a few normal Mercurial 19.787 -commands in use with applied patches. 19.788 - 19.789 -\section{Useful things to know about} 19.790 - 19.791 -There are a number of aspects of MQ usage that don't fit tidily into 19.792 -sections of their own, but that are good to know. Here they are, in 19.793 -one place. 19.794 - 19.795 -\begin{itemize} 19.796 -\item Normally, when you \hgxcmd{mq}{qpop} a patch and \hgxcmd{mq}{qpush} it 19.797 - again, the changeset that represents the patch after the pop/push 19.798 - will have a \emph{different identity} than the changeset that 19.799 - represented the hash beforehand. See 19.800 - section~\ref{sec:mqref:cmd:qpush} for information as to why this is. 19.801 -\item It's not a good idea to \hgcmd{merge} changes from another 19.802 - branch with a patch changeset, at least if you want to maintain the 19.803 - ``patchiness'' of that changeset and changesets below it on the 19.804 - patch stack. If you try to do this, it will appear to succeed, but 19.805 - MQ will become confused. 19.806 -\end{itemize} 19.807 - 19.808 -\section{Managing patches in a repository} 19.809 -\label{sec:mq:repo} 19.810 - 19.811 -Because MQ's \sdirname{.hg/patches} directory resides outside a 19.812 -Mercurial repository's working directory, the ``underlying'' Mercurial 19.813 -repository knows nothing about the management or presence of patches. 19.814 - 19.815 -This presents the interesting possibility of managing the contents of 19.816 -the patch directory as a Mercurial repository in its own right. This 19.817 -can be a useful way to work. For example, you can work on a patch for 19.818 -a while, \hgxcmd{mq}{qrefresh} it, then \hgcmd{commit} the current state of 19.819 -the patch. This lets you ``roll back'' to that version of the patch 19.820 -later on. 19.821 - 19.822 -You can then share different versions of the same patch stack among 19.823 -multiple underlying repositories. I use this when I am developing a 19.824 -Linux kernel feature. I have a pristine copy of my kernel sources for 19.825 -each of several CPU architectures, and a cloned repository under each 19.826 -that contains the patches I am working on. When I want to test a 19.827 -change on a different architecture, I push my current patches to the 19.828 -patch repository associated with that kernel tree, pop and push all of 19.829 -my patches, and build and test that kernel. 19.830 - 19.831 -Managing patches in a repository makes it possible for multiple 19.832 -developers to work on the same patch series without colliding with 19.833 -each other, all on top of an underlying source base that they may or 19.834 -may not control. 19.835 - 19.836 -\subsection{MQ support for patch repositories} 19.837 - 19.838 -MQ helps you to work with the \sdirname{.hg/patches} directory as a 19.839 -repository; when you prepare a repository for working with patches 19.840 -using \hgxcmd{mq}{qinit}, you can pass the \hgxopt{mq}{qinit}{-c} option to 19.841 -create the \sdirname{.hg/patches} directory as a Mercurial repository. 19.842 - 19.843 -\begin{note} 19.844 - If you forget to use the \hgxopt{mq}{qinit}{-c} option, you can simply go 19.845 - into the \sdirname{.hg/patches} directory at any time and run 19.846 - \hgcmd{init}. Don't forget to add an entry for the 19.847 - \sfilename{status} file to the \sfilename{.hgignore} file, though 19.848 - 19.849 - (\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} does this for you 19.850 - automatically); you \emph{really} don't want to manage the 19.851 - \sfilename{status} file. 19.852 -\end{note} 19.853 - 19.854 -As a convenience, if MQ notices that the \dirname{.hg/patches} 19.855 -directory is a repository, it will automatically \hgcmd{add} every 19.856 -patch that you create and import. 19.857 - 19.858 -MQ provides a shortcut command, \hgxcmd{mq}{qcommit}, that runs 19.859 -\hgcmd{commit} in the \sdirname{.hg/patches} directory. This saves 19.860 -some bothersome typing. 19.861 - 19.862 -Finally, as a convenience to manage the patch directory, you can 19.863 -define the alias \command{mq} on Unix systems. For example, on Linux 19.864 -systems using the \command{bash} shell, you can include the following 19.865 -snippet in your \tildefile{.bashrc}. 19.866 - 19.867 -\begin{codesample2} 19.868 - alias mq=`hg -R \$(hg root)/.hg/patches' 19.869 -\end{codesample2} 19.870 - 19.871 -You can then issue commands of the form \cmdargs{mq}{pull} from 19.872 -the main repository. 19.873 - 19.874 -\subsection{A few things to watch out for} 19.875 - 19.876 -MQ's support for working with a repository full of patches is limited 19.877 -in a few small respects. 19.878 - 19.879 -MQ cannot automatically detect changes that you make to the patch 19.880 -directory. If you \hgcmd{pull}, manually edit, or \hgcmd{update} 19.881 -changes to patches or the \sfilename{series} file, you will have to 19.882 -\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} and then 19.883 -\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} in the underlying repository to 19.884 -see those changes show up there. If you forget to do this, you can 19.885 -confuse MQ's idea of which patches are applied. 19.886 - 19.887 -\section{Third party tools for working with patches} 19.888 -\label{sec:mq:tools} 19.889 - 19.890 -Once you've been working with patches for a while, you'll find 19.891 -yourself hungry for tools that will help you to understand and 19.892 -manipulate the patches you're dealing with. 19.893 - 19.894 -The \command{diffstat} command~\cite{web:diffstat} generates a 19.895 -histogram of the modifications made to each file in a patch. It 19.896 -provides a good way to ``get a sense of'' a patch---which files it 19.897 -affects, and how much change it introduces to each file and as a 19.898 -whole. (I find that it's a good idea to use \command{diffstat}'s 19.899 -\cmdopt{diffstat}{-p} option as a matter of course, as otherwise it 19.900 -will try to do clever things with prefixes of file names that 19.901 -inevitably confuse at least me.) 19.902 - 19.903 -\begin{figure}[ht] 19.904 - \interaction{mq.tools.tools} 19.905 - \caption{The \command{diffstat}, \command{filterdiff}, and \command{lsdiff} commands} 19.906 - \label{ex:mq:tools} 19.907 -\end{figure} 19.908 - 19.909 -The \package{patchutils} package~\cite{web:patchutils} is invaluable. 19.910 -It provides a set of small utilities that follow the ``Unix 19.911 -philosophy;'' each does one useful thing with a patch. The 19.912 -\package{patchutils} command I use most is \command{filterdiff}, which 19.913 -extracts subsets from a patch file. For example, given a patch that 19.914 -modifies hundreds of files across dozens of directories, a single 19.915 -invocation of \command{filterdiff} can generate a smaller patch that 19.916 -only touches files whose names match a particular glob pattern. See 19.917 -section~\ref{mq-collab:tips:interdiff} for another example. 19.918 - 19.919 -\section{Good ways to work with patches} 19.920 - 19.921 -Whether you are working on a patch series to submit to a free software 19.922 -or open source project, or a series that you intend to treat as a 19.923 -sequence of regular changesets when you're done, you can use some 19.924 -simple techniques to keep your work well organised. 19.925 - 19.926 -Give your patches descriptive names. A good name for a patch might be 19.927 -\filename{rework-device-alloc.patch}, because it will immediately give 19.928 -you a hint what the purpose of the patch is. Long names shouldn't be 19.929 -a problem; you won't be typing the names often, but you \emph{will} be 19.930 -running commands like \hgxcmd{mq}{qapplied} and \hgxcmd{mq}{qtop} over and over. 19.931 -Good naming becomes especially important when you have a number of 19.932 -patches to work with, or if you are juggling a number of different 19.933 -tasks and your patches only get a fraction of your attention. 19.934 - 19.935 -Be aware of what patch you're working on. Use the \hgxcmd{mq}{qtop} 19.936 -command and skim over the text of your patches frequently---for 19.937 -example, using \hgcmdargs{tip}{\hgopt{tip}{-p}})---to be sure of where 19.938 -you stand. I have several times worked on and \hgxcmd{mq}{qrefresh}ed a 19.939 -patch other than the one I intended, and it's often tricky to migrate 19.940 -changes into the right patch after making them in the wrong one. 19.941 - 19.942 -For this reason, it is very much worth investing a little time to 19.943 -learn how to use some of the third-party tools I described in 19.944 -section~\ref{sec:mq:tools}, particularly \command{diffstat} and 19.945 -\command{filterdiff}. The former will give you a quick idea of what 19.946 -changes your patch is making, while the latter makes it easy to splice 19.947 -hunks selectively out of one patch and into another. 19.948 - 19.949 -\section{MQ cookbook} 19.950 - 19.951 -\subsection{Manage ``trivial'' patches} 19.952 - 19.953 -Because the overhead of dropping files into a new Mercurial repository 19.954 -is so low, it makes a lot of sense to manage patches this way even if 19.955 -you simply want to make a few changes to a source tarball that you 19.956 -downloaded. 19.957 - 19.958 -Begin by downloading and unpacking the source tarball, 19.959 -and turning it into a Mercurial repository. 19.960 -\interaction{mq.tarball.download} 19.961 - 19.962 -Continue by creating a patch stack and making your changes. 19.963 -\interaction{mq.tarball.qinit} 19.964 - 19.965 -Let's say a few weeks or months pass, and your package author releases 19.966 -a new version. First, bring their changes into the repository. 19.967 -\interaction{mq.tarball.newsource} 19.968 -The pipeline starting with \hgcmd{locate} above deletes all files in 19.969 -the working directory, so that \hgcmd{commit}'s 19.970 -\hgopt{commit}{--addremove} option can actually tell which files have 19.971 -really been removed in the newer version of the source. 19.972 - 19.973 -Finally, you can apply your patches on top of the new tree. 19.974 -\interaction{mq.tarball.repush} 19.975 - 19.976 -\subsection{Combining entire patches} 19.977 -\label{sec:mq:combine} 19.978 - 19.979 -MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire 19.980 -patches. This ``folds'' the patches you name, in the order you name 19.981 -them, into the topmost applied patch, and concatenates their 19.982 -descriptions onto the end of its description. The patches that you 19.983 -fold must be unapplied before you fold them. 19.984 - 19.985 -The order in which you fold patches matters. If your topmost applied 19.986 -patch is \texttt{foo}, and you \hgxcmd{mq}{qfold} \texttt{bar} and 19.987 -\texttt{quux} into it, you will end up with a patch that has the same 19.988 -effect as if you applied first \texttt{foo}, then \texttt{bar}, 19.989 -followed by \texttt{quux}. 19.990 - 19.991 -\subsection{Merging part of one patch into another} 19.992 - 19.993 -Merging \emph{part} of one patch into another is more difficult than 19.994 -combining entire patches. 19.995 - 19.996 -If you want to move changes to entire files, you can use 19.997 -\command{filterdiff}'s \cmdopt{filterdiff}{-i} and 19.998 -\cmdopt{filterdiff}{-x} options to choose the modifications to snip 19.999 -out of one patch, concatenating its output onto the end of the patch 19.1000 -you want to merge into. You usually won't need to modify the patch 19.1001 -you've merged the changes from. Instead, MQ will report some rejected 19.1002 -hunks when you \hgxcmd{mq}{qpush} it (from the hunks you moved into the 19.1003 -other patch), and you can simply \hgxcmd{mq}{qrefresh} the patch to drop 19.1004 -the duplicate hunks. 19.1005 - 19.1006 -If you have a patch that has multiple hunks modifying a file, and you 19.1007 -only want to move a few of those hunks, the job becomes more messy, 19.1008 -but you can still partly automate it. Use \cmdargs{lsdiff}{-nvv} to 19.1009 -print some metadata about the patch. 19.1010 -\interaction{mq.tools.lsdiff} 19.1011 - 19.1012 -This command prints three different kinds of number: 19.1013 -\begin{itemize} 19.1014 -\item (in the first column) a \emph{file number} to identify each file 19.1015 - modified in the patch; 19.1016 -\item (on the next line, indented) the line number within a modified 19.1017 - file where a hunk starts; and 19.1018 -\item (on the same line) a \emph{hunk number} to identify that hunk. 19.1019 -\end{itemize} 19.1020 - 19.1021 -You'll have to use some visual inspection, and reading of the patch, 19.1022 -to identify the file and hunk numbers you'll want, but you can then 19.1023 -pass them to to \command{filterdiff}'s \cmdopt{filterdiff}{--files} 19.1024 -and \cmdopt{filterdiff}{--hunks} options, to select exactly the file 19.1025 -and hunk you want to extract. 19.1026 - 19.1027 -Once you have this hunk, you can concatenate it onto the end of your 19.1028 -destination patch and continue with the remainder of 19.1029 -section~\ref{sec:mq:combine}. 19.1030 - 19.1031 -\section{Differences between quilt and MQ} 19.1032 - 19.1033 -If you are already familiar with quilt, MQ provides a similar command 19.1034 -set. There are a few differences in the way that it works. 19.1035 - 19.1036 -You will already have noticed that most quilt commands have MQ 19.1037 -counterparts that simply begin with a ``\texttt{q}''. The exceptions 19.1038 -are quilt's \texttt{add} and \texttt{remove} commands, the 19.1039 -counterparts for which are the normal Mercurial \hgcmd{add} and 19.1040 -\hgcmd{remove} commands. There is no MQ equivalent of the quilt 19.1041 -\texttt{edit} command. 19.1042 - 19.1043 -%%% Local Variables: 19.1044 -%%% mode: latex 19.1045 -%%% TeX-master: "00book" 19.1046 -%%% End:
20.1 --- a/en/ch13-mq-collab.tex Thu Mar 05 21:52:23 2009 +0200 20.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 20.3 @@ -1,392 +0,0 @@ 20.4 -\chapter{Advanced uses of Mercurial Queues} 20.5 -\label{chap:mq-collab} 20.6 - 20.7 -While it's easy to pick up straightforward uses of Mercurial Queues, 20.8 -use of a little discipline and some of MQ's less frequently used 20.9 -capabilities makes it possible to work in complicated development 20.10 -environments. 20.11 - 20.12 -In this chapter, I will use as an example a technique I have used to 20.13 -manage the development of an Infiniband device driver for the Linux 20.14 -kernel. The driver in question is large (at least as drivers go), 20.15 -with 25,000 lines of code spread across 35 source files. It is 20.16 -maintained by a small team of developers. 20.17 - 20.18 -While much of the material in this chapter is specific to Linux, the 20.19 -same principles apply to any code base for which you're not the 20.20 -primary owner, and upon which you need to do a lot of development. 20.21 - 20.22 -\section{The problem of many targets} 20.23 - 20.24 -The Linux kernel changes rapidly, and has never been internally 20.25 -stable; developers frequently make drastic changes between releases. 20.26 -This means that a version of the driver that works well with a 20.27 -particular released version of the kernel will not even \emph{compile} 20.28 -correctly against, typically, any other version. 20.29 - 20.30 -To maintain a driver, we have to keep a number of distinct versions of 20.31 -Linux in mind. 20.32 -\begin{itemize} 20.33 -\item One target is the main Linux kernel development tree. 20.34 - Maintenance of the code is in this case partly shared by other 20.35 - developers in the kernel community, who make ``drive-by'' 20.36 - modifications to the driver as they develop and refine kernel 20.37 - subsystems. 20.38 -\item We also maintain a number of ``backports'' to older versions of 20.39 - the Linux kernel, to support the needs of customers who are running 20.40 - older Linux distributions that do not incorporate our drivers. (To 20.41 - \emph{backport} a piece of code is to modify it to work in an older 20.42 - version of its target environment than the version it was developed 20.43 - for.) 20.44 -\item Finally, we make software releases on a schedule that is 20.45 - necessarily not aligned with those used by Linux distributors and 20.46 - kernel developers, so that we can deliver new features to customers 20.47 - without forcing them to upgrade their entire kernels or 20.48 - distributions. 20.49 -\end{itemize} 20.50 - 20.51 -\subsection{Tempting approaches that don't work well} 20.52 - 20.53 -There are two ``standard'' ways to maintain a piece of software that 20.54 -has to target many different environments. 20.55 - 20.56 -The first is to maintain a number of branches, each intended for a 20.57 -single target. The trouble with this approach is that you must 20.58 -maintain iron discipline in the flow of changes between repositories. 20.59 -A new feature or bug fix must start life in a ``pristine'' repository, 20.60 -then percolate out to every backport repository. Backport changes are 20.61 -more limited in the branches they should propagate to; a backport 20.62 -change that is applied to a branch where it doesn't belong will 20.63 -probably stop the driver from compiling. 20.64 - 20.65 -The second is to maintain a single source tree filled with conditional 20.66 -statements that turn chunks of code on or off depending on the 20.67 -intended target. Because these ``ifdefs'' are not allowed in the 20.68 -Linux kernel tree, a manual or automatic process must be followed to 20.69 -strip them out and yield a clean tree. A code base maintained in this 20.70 -fashion rapidly becomes a rat's nest of conditional blocks that are 20.71 -difficult to understand and maintain. 20.72 - 20.73 -Neither of these approaches is well suited to a situation where you 20.74 -don't ``own'' the canonical copy of a source tree. In the case of a 20.75 -Linux driver that is distributed with the standard kernel, Linus's 20.76 -tree contains the copy of the code that will be treated by the world 20.77 -as canonical. The upstream version of ``my'' driver can be modified 20.78 -by people I don't know, without me even finding out about it until 20.79 -after the changes show up in Linus's tree. 20.80 - 20.81 -These approaches have the added weakness of making it difficult to 20.82 -generate well-formed patches to submit upstream. 20.83 - 20.84 -In principle, Mercurial Queues seems like a good candidate to manage a 20.85 -development scenario such as the above. While this is indeed the 20.86 -case, MQ contains a few added features that make the job more 20.87 -pleasant. 20.88 - 20.89 -\section{Conditionally applying patches with guards} 20.90 - 20.91 -Perhaps the best way to maintain sanity with so many targets is to be 20.92 -able to choose specific patches to apply for a given situation. MQ 20.93 -provides a feature called ``guards'' (which originates with quilt's 20.94 -\texttt{guards} command) that does just this. To start off, let's 20.95 -create a simple repository for experimenting in. 20.96 -\interaction{mq.guards.init} 20.97 -This gives us a tiny repository that contains two patches that don't 20.98 -have any dependencies on each other, because they touch different files. 20.99 - 20.100 -The idea behind conditional application is that you can ``tag'' a 20.101 -patch with a \emph{guard}, which is simply a text string of your 20.102 -choosing, then tell MQ to select specific guards to use when applying 20.103 -patches. MQ will then either apply, or skip over, a guarded patch, 20.104 -depending on the guards that you have selected. 20.105 - 20.106 -A patch can have an arbitrary number of guards; 20.107 -each one is \emph{positive} (``apply this patch if this guard is 20.108 -selected'') or \emph{negative} (``skip this patch if this guard is 20.109 -selected''). A patch with no guards is always applied. 20.110 - 20.111 -\section{Controlling the guards on a patch} 20.112 - 20.113 -The \hgxcmd{mq}{qguard} command lets you determine which guards should 20.114 -apply to a patch, or display the guards that are already in effect. 20.115 -Without any arguments, it displays the guards on the current topmost 20.116 -patch. 20.117 -\interaction{mq.guards.qguard} 20.118 -To set a positive guard on a patch, prefix the name of the guard with 20.119 -a ``\texttt{+}''. 20.120 -\interaction{mq.guards.qguard.pos} 20.121 -To set a negative guard on a patch, prefix the name of the guard with 20.122 -a ``\texttt{-}''. 20.123 -\interaction{mq.guards.qguard.neg} 20.124 - 20.125 -\begin{note} 20.126 - The \hgxcmd{mq}{qguard} command \emph{sets} the guards on a patch; it 20.127 - doesn't \emph{modify} them. What this means is that if you run 20.128 - \hgcmdargs{qguard}{+a +b} on a patch, then \hgcmdargs{qguard}{+c} on 20.129 - the same patch, the \emph{only} guard that will be set on it 20.130 - afterwards is \texttt{+c}. 20.131 -\end{note} 20.132 - 20.133 -Mercurial stores guards in the \sfilename{series} file; the form in 20.134 -which they are stored is easy both to understand and to edit by hand. 20.135 -(In other words, you don't have to use the \hgxcmd{mq}{qguard} command if 20.136 -you don't want to; it's okay to simply edit the \sfilename{series} 20.137 -file.) 20.138 -\interaction{mq.guards.series} 20.139 - 20.140 -\section{Selecting the guards to use} 20.141 - 20.142 -The \hgxcmd{mq}{qselect} command determines which guards are active at a 20.143 -given time. The effect of this is to determine which patches MQ will 20.144 -apply the next time you run \hgxcmd{mq}{qpush}. It has no other effect; in 20.145 -particular, it doesn't do anything to patches that are already 20.146 -applied. 20.147 - 20.148 -With no arguments, the \hgxcmd{mq}{qselect} command lists the guards 20.149 -currently in effect, one per line of output. Each argument is treated 20.150 -as the name of a guard to apply. 20.151 -\interaction{mq.guards.qselect.foo} 20.152 -In case you're interested, the currently selected guards are stored in 20.153 -the \sfilename{guards} file. 20.154 -\interaction{mq.guards.qselect.cat} 20.155 -We can see the effect the selected guards have when we run 20.156 -\hgxcmd{mq}{qpush}. 20.157 -\interaction{mq.guards.qselect.qpush} 20.158 - 20.159 -A guard cannot start with a ``\texttt{+}'' or ``\texttt{-}'' 20.160 -character. The name of a guard must not contain white space, but most 20.161 -other characters are acceptable. If you try to use a guard with an 20.162 -invalid name, MQ will complain: 20.163 -\interaction{mq.guards.qselect.error} 20.164 -Changing the selected guards changes the patches that are applied. 20.165 -\interaction{mq.guards.qselect.quux} 20.166 -You can see in the example below that negative guards take precedence 20.167 -over positive guards. 20.168 -\interaction{mq.guards.qselect.foobar} 20.169 - 20.170 -\section{MQ's rules for applying patches} 20.171 - 20.172 -The rules that MQ uses when deciding whether to apply a patch 20.173 -are as follows. 20.174 -\begin{itemize} 20.175 -\item A patch that has no guards is always applied. 20.176 -\item If the patch has any negative guard that matches any currently 20.177 - selected guard, the patch is skipped. 20.178 -\item If the patch has any positive guard that matches any currently 20.179 - selected guard, the patch is applied. 20.180 -\item If the patch has positive or negative guards, but none matches 20.181 - any currently selected guard, the patch is skipped. 20.182 -\end{itemize} 20.183 - 20.184 -\section{Trimming the work environment} 20.185 - 20.186 -In working on the device driver I mentioned earlier, I don't apply the 20.187 -patches to a normal Linux kernel tree. Instead, I use a repository 20.188 -that contains only a snapshot of the source files and headers that are 20.189 -relevant to Infiniband development. This repository is~1\% the size 20.190 -of a kernel repository, so it's easier to work with. 20.191 - 20.192 -I then choose a ``base'' version on top of which the patches are 20.193 -applied. This is a snapshot of the Linux kernel tree as of a revision 20.194 -of my choosing. When I take the snapshot, I record the changeset ID 20.195 -from the kernel repository in the commit message. Since the snapshot 20.196 -preserves the ``shape'' and content of the relevant parts of the 20.197 -kernel tree, I can apply my patches on top of either my tiny 20.198 -repository or a normal kernel tree. 20.199 - 20.200 -Normally, the base tree atop which the patches apply should be a 20.201 -snapshot of a very recent upstream tree. This best facilitates the 20.202 -development of patches that can easily be submitted upstream with few 20.203 -or no modifications. 20.204 - 20.205 -\section{Dividing up the \sfilename{series} file} 20.206 - 20.207 -I categorise the patches in the \sfilename{series} file into a number 20.208 -of logical groups. Each section of like patches begins with a block 20.209 -of comments that describes the purpose of the patches that follow. 20.210 - 20.211 -The sequence of patch groups that I maintain follows. The ordering of 20.212 -these groups is important; I'll describe why after I introduce the 20.213 -groups. 20.214 -\begin{itemize} 20.215 -\item The ``accepted'' group. Patches that the development team has 20.216 - submitted to the maintainer of the Infiniband subsystem, and which 20.217 - he has accepted, but which are not present in the snapshot that the 20.218 - tiny repository is based on. These are ``read only'' patches, 20.219 - present only to transform the tree into a similar state as it is in 20.220 - the upstream maintainer's repository. 20.221 -\item The ``rework'' group. Patches that I have submitted, but that 20.222 - the upstream maintainer has requested modifications to before he 20.223 - will accept them. 20.224 -\item The ``pending'' group. Patches that I have not yet submitted to 20.225 - the upstream maintainer, but which we have finished working on. 20.226 - These will be ``read only'' for a while. If the upstream maintainer 20.227 - accepts them upon submission, I'll move them to the end of the 20.228 - ``accepted'' group. If he requests that I modify any, I'll move 20.229 - them to the beginning of the ``rework'' group. 20.230 -\item The ``in progress'' group. Patches that are actively being 20.231 - developed, and should not be submitted anywhere yet. 20.232 -\item The ``backport'' group. Patches that adapt the source tree to 20.233 - older versions of the kernel tree. 20.234 -\item The ``do not ship'' group. Patches that for some reason should 20.235 - never be submitted upstream. For example, one such patch might 20.236 - change embedded driver identification strings to make it easier to 20.237 - distinguish, in the field, between an out-of-tree version of the 20.238 - driver and a version shipped by a distribution vendor. 20.239 -\end{itemize} 20.240 - 20.241 -Now to return to the reasons for ordering groups of patches in this 20.242 -way. We would like the lowest patches in the stack to be as stable as 20.243 -possible, so that we will not need to rework higher patches due to 20.244 -changes in context. Putting patches that will never be changed first 20.245 -in the \sfilename{series} file serves this purpose. 20.246 - 20.247 -We would also like the patches that we know we'll need to modify to be 20.248 -applied on top of a source tree that resembles the upstream tree as 20.249 -closely as possible. This is why we keep accepted patches around for 20.250 -a while. 20.251 - 20.252 -The ``backport'' and ``do not ship'' patches float at the end of the 20.253 -\sfilename{series} file. The backport patches must be applied on top 20.254 -of all other patches, and the ``do not ship'' patches might as well 20.255 -stay out of harm's way. 20.256 - 20.257 -\section{Maintaining the patch series} 20.258 - 20.259 -In my work, I use a number of guards to control which patches are to 20.260 -be applied. 20.261 - 20.262 -\begin{itemize} 20.263 -\item ``Accepted'' patches are guarded with \texttt{accepted}. I 20.264 - enable this guard most of the time. When I'm applying the patches 20.265 - on top of a tree where the patches are already present, I can turn 20.266 - this patch off, and the patches that follow it will apply cleanly. 20.267 -\item Patches that are ``finished'', but not yet submitted, have no 20.268 - guards. If I'm applying the patch stack to a copy of the upstream 20.269 - tree, I don't need to enable any guards in order to get a reasonably 20.270 - safe source tree. 20.271 -\item Those patches that need reworking before being resubmitted are 20.272 - guarded with \texttt{rework}. 20.273 -\item For those patches that are still under development, I use 20.274 - \texttt{devel}. 20.275 -\item A backport patch may have several guards, one for each version 20.276 - of the kernel to which it applies. For example, a patch that 20.277 - backports a piece of code to~2.6.9 will have a~\texttt{2.6.9} guard. 20.278 -\end{itemize} 20.279 -This variety of guards gives me considerable flexibility in 20.280 -determining what kind of source tree I want to end up with. For most 20.281 -situations, the selection of appropriate guards is automated during 20.282 -the build process, but I can manually tune the guards to use for less 20.283 -common circumstances. 20.284 - 20.285 -\subsection{The art of writing backport patches} 20.286 - 20.287 -Using MQ, writing a backport patch is a simple process. All such a 20.288 -patch has to do is modify a piece of code that uses a kernel feature 20.289 -not present in the older version of the kernel, so that the driver 20.290 -continues to work correctly under that older version. 20.291 - 20.292 -A useful goal when writing a good backport patch is to make your code 20.293 -look as if it was written for the older version of the kernel you're 20.294 -targeting. The less obtrusive the patch, the easier it will be to 20.295 -understand and maintain. If you're writing a collection of backport 20.296 -patches to avoid the ``rat's nest'' effect of lots of 20.297 -\texttt{\#ifdef}s (hunks of source code that are only used 20.298 -conditionally) in your code, don't introduce version-dependent 20.299 -\texttt{\#ifdef}s into the patches. Instead, write several patches, 20.300 -each of which makes unconditional changes, and control their 20.301 -application using guards. 20.302 - 20.303 -There are two reasons to divide backport patches into a distinct 20.304 -group, away from the ``regular'' patches whose effects they modify. 20.305 -The first is that intermingling the two makes it more difficult to use 20.306 -a tool like the \hgext{patchbomb} extension to automate the process of 20.307 -submitting the patches to an upstream maintainer. The second is that 20.308 -a backport patch could perturb the context in which a subsequent 20.309 -regular patch is applied, making it impossible to apply the regular 20.310 -patch cleanly \emph{without} the earlier backport patch already being 20.311 -applied. 20.312 - 20.313 -\section{Useful tips for developing with MQ} 20.314 - 20.315 -\subsection{Organising patches in directories} 20.316 - 20.317 -If you're working on a substantial project with MQ, it's not difficult 20.318 -to accumulate a large number of patches. For example, I have one 20.319 -patch repository that contains over 250 patches. 20.320 - 20.321 -If you can group these patches into separate logical categories, you 20.322 -can if you like store them in different directories; MQ has no 20.323 -problems with patch names that contain path separators. 20.324 - 20.325 -\subsection{Viewing the history of a patch} 20.326 -\label{mq-collab:tips:interdiff} 20.327 - 20.328 -If you're developing a set of patches over a long time, it's a good 20.329 -idea to maintain them in a repository, as discussed in 20.330 -section~\ref{sec:mq:repo}. If you do so, you'll quickly discover that 20.331 -using the \hgcmd{diff} command to look at the history of changes to a 20.332 -patch is unworkable. This is in part because you're looking at the 20.333 -second derivative of the real code (a diff of a diff), but also 20.334 -because MQ adds noise to the process by modifying time stamps and 20.335 -directory names when it updates a patch. 20.336 - 20.337 -However, you can use the \hgext{extdiff} extension, which is bundled 20.338 -with Mercurial, to turn a diff of two versions of a patch into 20.339 -something readable. To do this, you will need a third-party package 20.340 -called \package{patchutils}~\cite{web:patchutils}. This provides a 20.341 -command named \command{interdiff}, which shows the differences between 20.342 -two diffs as a diff. Used on two versions of the same diff, it 20.343 -generates a diff that represents the diff from the first to the second 20.344 -version. 20.345 - 20.346 -You can enable the \hgext{extdiff} extension in the usual way, by 20.347 -adding a line to the \rcsection{extensions} section of your \hgrc. 20.348 -\begin{codesample2} 20.349 - [extensions] 20.350 - extdiff = 20.351 -\end{codesample2} 20.352 -The \command{interdiff} command expects to be passed the names of two 20.353 -files, but the \hgext{extdiff} extension passes the program it runs a 20.354 -pair of directories, each of which can contain an arbitrary number of 20.355 -files. We thus need a small program that will run \command{interdiff} 20.356 -on each pair of files in these two directories. This program is 20.357 -available as \sfilename{hg-interdiff} in the \dirname{examples} 20.358 -directory of the source code repository that accompanies this book. 20.359 -\excode{hg-interdiff} 20.360 - 20.361 -With the \sfilename{hg-interdiff} program in your shell's search path, 20.362 -you can run it as follows, from inside an MQ patch directory: 20.363 -\begin{codesample2} 20.364 - hg extdiff -p hg-interdiff -r A:B my-change.patch 20.365 -\end{codesample2} 20.366 -Since you'll probably want to use this long-winded command a lot, you 20.367 -can get \hgext{hgext} to make it available as a normal Mercurial 20.368 -command, again by editing your \hgrc. 20.369 -\begin{codesample2} 20.370 - [extdiff] 20.371 - cmd.interdiff = hg-interdiff 20.372 -\end{codesample2} 20.373 -This directs \hgext{hgext} to make an \texttt{interdiff} command 20.374 -available, so you can now shorten the previous invocation of 20.375 -\hgxcmd{extdiff}{extdiff} to something a little more wieldy. 20.376 -\begin{codesample2} 20.377 - hg interdiff -r A:B my-change.patch 20.378 -\end{codesample2} 20.379 - 20.380 -\begin{note} 20.381 - The \command{interdiff} command works well only if the underlying 20.382 - files against which versions of a patch are generated remain the 20.383 - same. If you create a patch, modify the underlying files, and then 20.384 - regenerate the patch, \command{interdiff} may not produce useful 20.385 - output. 20.386 -\end{note} 20.387 - 20.388 -The \hgext{extdiff} extension is useful for more than merely improving 20.389 -the presentation of MQ~patches. To read more about it, go to 20.390 -section~\ref{sec:hgext:extdiff}. 20.391 - 20.392 -%%% Local Variables: 20.393 -%%% mode: latex 20.394 -%%% TeX-master: "00book" 20.395 -%%% End:
21.1 --- a/en/ch14-hgext.tex Thu Mar 05 21:52:23 2009 +0200 21.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 21.3 @@ -1,428 +0,0 @@ 21.4 -\chapter{Adding functionality with extensions} 21.5 -\label{chap:hgext} 21.6 - 21.7 -While the core of Mercurial is quite complete from a functionality 21.8 -standpoint, it's deliberately shorn of fancy features. This approach 21.9 -of preserving simplicity keeps the software easy to deal with for both 21.10 -maintainers and users. 21.11 - 21.12 -However, Mercurial doesn't box you in with an inflexible command set: 21.13 -you can add features to it as \emph{extensions} (sometimes known as 21.14 -\emph{plugins}). We've already discussed a few of these extensions in 21.15 -earlier chapters. 21.16 -\begin{itemize} 21.17 -\item Section~\ref{sec:tour-merge:fetch} covers the \hgext{fetch} 21.18 - extension; this combines pulling new changes and merging them with 21.19 - local changes into a single command, \hgxcmd{fetch}{fetch}. 21.20 -\item In chapter~\ref{chap:hook}, we covered several extensions that 21.21 - are useful for hook-related functionality: \hgext{acl} adds access 21.22 - control lists; \hgext{bugzilla} adds integration with the Bugzilla 21.23 - bug tracking system; and \hgext{notify} sends notification emails on 21.24 - new changes. 21.25 -\item The Mercurial Queues patch management extension is so invaluable 21.26 - that it merits two chapters and an appendix all to itself. 21.27 - Chapter~\ref{chap:mq} covers the basics; 21.28 - chapter~\ref{chap:mq-collab} discusses advanced topics; and 21.29 - appendix~\ref{chap:mqref} goes into detail on each command. 21.30 -\end{itemize} 21.31 - 21.32 -In this chapter, we'll cover some of the other extensions that are 21.33 -available for Mercurial, and briefly touch on some of the machinery 21.34 -you'll need to know about if you want to write an extension of your 21.35 -own. 21.36 -\begin{itemize} 21.37 -\item In section~\ref{sec:hgext:inotify}, we'll discuss the 21.38 - possibility of \emph{huge} performance improvements using the 21.39 - \hgext{inotify} extension. 21.40 -\end{itemize} 21.41 - 21.42 -\section{Improve performance with the \hgext{inotify} extension} 21.43 -\label{sec:hgext:inotify} 21.44 - 21.45 -Are you interested in having some of the most common Mercurial 21.46 -operations run as much as a hundred times faster? Read on! 21.47 - 21.48 -Mercurial has great performance under normal circumstances. For 21.49 -example, when you run the \hgcmd{status} command, Mercurial has to 21.50 -scan almost every directory and file in your repository so that it can 21.51 -display file status. Many other Mercurial commands need to do the 21.52 -same work behind the scenes; for example, the \hgcmd{diff} command 21.53 -uses the status machinery to avoid doing an expensive comparison 21.54 -operation on files that obviously haven't changed. 21.55 - 21.56 -Because obtaining file status is crucial to good performance, the 21.57 -authors of Mercurial have optimised this code to within an inch of its 21.58 -life. However, there's no avoiding the fact that when you run 21.59 -\hgcmd{status}, Mercurial is going to have to perform at least one 21.60 -expensive system call for each managed file to determine whether it's 21.61 -changed since the last time Mercurial checked. For a sufficiently 21.62 -large repository, this can take a long time. 21.63 - 21.64 -To put a number on the magnitude of this effect, I created a 21.65 -repository containing 150,000 managed files. I timed \hgcmd{status} 21.66 -as taking ten seconds to run, even when \emph{none} of those files had 21.67 -been modified. 21.68 - 21.69 -Many modern operating systems contain a file notification facility. 21.70 -If a program signs up to an appropriate service, the operating system 21.71 -will notify it every time a file of interest is created, modified, or 21.72 -deleted. On Linux systems, the kernel component that does this is 21.73 -called \texttt{inotify}. 21.74 - 21.75 -Mercurial's \hgext{inotify} extension talks to the kernel's 21.76 -\texttt{inotify} component to optimise \hgcmd{status} commands. The 21.77 -extension has two components. A daemon sits in the background and 21.78 -receives notifications from the \texttt{inotify} subsystem. It also 21.79 -listens for connections from a regular Mercurial command. The 21.80 -extension modifies Mercurial's behaviour so that instead of scanning 21.81 -the filesystem, it queries the daemon. Since the daemon has perfect 21.82 -information about the state of the repository, it can respond with a 21.83 -result instantaneously, avoiding the need to scan every directory and 21.84 -file in the repository. 21.85 - 21.86 -Recall the ten seconds that I measured plain Mercurial as taking to 21.87 -run \hgcmd{status} on a 150,000 file repository. With the 21.88 -\hgext{inotify} extension enabled, the time dropped to 0.1~seconds, a 21.89 -factor of \emph{one hundred} faster. 21.90 - 21.91 -Before we continue, please pay attention to some caveats. 21.92 -\begin{itemize} 21.93 -\item The \hgext{inotify} extension is Linux-specific. Because it 21.94 - interfaces directly to the Linux kernel's \texttt{inotify} 21.95 - subsystem, it does not work on other operating systems. 21.96 -\item It should work on any Linux distribution that was released after 21.97 - early~2005. Older distributions are likely to have a kernel that 21.98 - lacks \texttt{inotify}, or a version of \texttt{glibc} that does not 21.99 - have the necessary interfacing support. 21.100 -\item Not all filesystems are suitable for use with the 21.101 - \hgext{inotify} extension. Network filesystems such as NFS are a 21.102 - non-starter, for example, particularly if you're running Mercurial 21.103 - on several systems, all mounting the same network filesystem. The 21.104 - kernel's \texttt{inotify} system has no way of knowing about changes 21.105 - made on another system. Most local filesystems (e.g.~ext3, XFS, 21.106 - ReiserFS) should work fine. 21.107 -\end{itemize} 21.108 - 21.109 -The \hgext{inotify} extension is not yet shipped with Mercurial as of 21.110 -May~2007, so it's a little more involved to set up than other 21.111 -extensions. But the performance improvement is worth it! 21.112 - 21.113 -The extension currently comes in two parts: a set of patches to the 21.114 -Mercurial source code, and a library of Python bindings to the 21.115 -\texttt{inotify} subsystem. 21.116 -\begin{note} 21.117 - There are \emph{two} Python \texttt{inotify} binding libraries. One 21.118 - of them is called \texttt{pyinotify}, and is packaged by some Linux 21.119 - distributions as \texttt{python-inotify}. This is \emph{not} the 21.120 - one you'll need, as it is too buggy and inefficient to be practical. 21.121 -\end{note} 21.122 -To get going, it's best to already have a functioning copy of 21.123 -Mercurial installed. 21.124 -\begin{note} 21.125 - If you follow the instructions below, you'll be \emph{replacing} and 21.126 - overwriting any existing installation of Mercurial that you might 21.127 - already have, using the latest ``bleeding edge'' Mercurial code. 21.128 - Don't say you weren't warned! 21.129 -\end{note} 21.130 -\begin{enumerate} 21.131 -\item Clone the Python \texttt{inotify} binding repository. Build and 21.132 - install it. 21.133 - \begin{codesample4} 21.134 - hg clone http://hg.kublai.com/python/inotify 21.135 - cd inotify 21.136 - python setup.py build --force 21.137 - sudo python setup.py install --skip-build 21.138 - \end{codesample4} 21.139 -\item Clone the \dirname{crew} Mercurial repository. Clone the 21.140 - \hgext{inotify} patch repository so that Mercurial Queues will be 21.141 - able to apply patches to your cope of the \dirname{crew} repository. 21.142 - \begin{codesample4} 21.143 - hg clone http://hg.intevation.org/mercurial/crew 21.144 - hg clone crew inotify 21.145 - hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches 21.146 - \end{codesample4} 21.147 -\item Make sure that you have the Mercurial Queues extension, 21.148 - \hgext{mq}, enabled. If you've never used MQ, read 21.149 - section~\ref{sec:mq:start} to get started quickly. 21.150 -\item Go into the \dirname{inotify} repo, and apply all of the 21.151 - \hgext{inotify} patches using the \hgxopt{mq}{qpush}{-a} option to 21.152 - the \hgxcmd{mq}{qpush} command. 21.153 - \begin{codesample4} 21.154 - cd inotify 21.155 - hg qpush -a 21.156 - \end{codesample4} 21.157 - If you get an error message from \hgxcmd{mq}{qpush}, you should not 21.158 - continue. Instead, ask for help. 21.159 -\item Build and install the patched version of Mercurial. 21.160 - \begin{codesample4} 21.161 - python setup.py build --force 21.162 - sudo python setup.py install --skip-build 21.163 - \end{codesample4} 21.164 -\end{enumerate} 21.165 -Once you've build a suitably patched version of Mercurial, all you 21.166 -need to do to enable the \hgext{inotify} extension is add an entry to 21.167 -your \hgrc. 21.168 -\begin{codesample2} 21.169 - [extensions] 21.170 - inotify = 21.171 -\end{codesample2} 21.172 -When the \hgext{inotify} extension is enabled, Mercurial will 21.173 -automatically and transparently start the status daemon the first time 21.174 -you run a command that needs status in a repository. It runs one 21.175 -status daemon per repository. 21.176 - 21.177 -The status daemon is started silently, and runs in the background. If 21.178 -you look at a list of running processes after you've enabled the 21.179 -\hgext{inotify} extension and run a few commands in different 21.180 -repositories, you'll thus see a few \texttt{hg} processes sitting 21.181 -around, waiting for updates from the kernel and queries from 21.182 -Mercurial. 21.183 - 21.184 -The first time you run a Mercurial command in a repository when you 21.185 -have the \hgext{inotify} extension enabled, it will run with about the 21.186 -same performance as a normal Mercurial command. This is because the 21.187 -status daemon needs to perform a normal status scan so that it has a 21.188 -baseline against which to apply later updates from the kernel. 21.189 -However, \emph{every} subsequent command that does any kind of status 21.190 -check should be noticeably faster on repositories of even fairly 21.191 -modest size. Better yet, the bigger your repository is, the greater a 21.192 -performance advantage you'll see. The \hgext{inotify} daemon makes 21.193 -status operations almost instantaneous on repositories of all sizes! 21.194 - 21.195 -If you like, you can manually start a status daemon using the 21.196 -\hgxcmd{inotify}{inserve} command. This gives you slightly finer 21.197 -control over how the daemon ought to run. This command will of course 21.198 -only be available when the \hgext{inotify} extension is enabled. 21.199 - 21.200 -When you're using the \hgext{inotify} extension, you should notice 21.201 -\emph{no difference at all} in Mercurial's behaviour, with the sole 21.202 -exception of status-related commands running a whole lot faster than 21.203 -they used to. You should specifically expect that commands will not 21.204 -print different output; neither should they give different results. 21.205 -If either of these situations occurs, please report a bug. 21.206 - 21.207 -\section{Flexible diff support with the \hgext{extdiff} extension} 21.208 -\label{sec:hgext:extdiff} 21.209 - 21.210 -Mercurial's built-in \hgcmd{diff} command outputs plaintext unified 21.211 -diffs. 21.212 -\interaction{extdiff.diff} 21.213 -If you would like to use an external tool to display modifications, 21.214 -you'll want to use the \hgext{extdiff} extension. This will let you 21.215 -use, for example, a graphical diff tool. 21.216 - 21.217 -The \hgext{extdiff} extension is bundled with Mercurial, so it's easy 21.218 -to set up. In the \rcsection{extensions} section of your \hgrc, 21.219 -simply add a one-line entry to enable the extension. 21.220 -\begin{codesample2} 21.221 - [extensions] 21.222 - extdiff = 21.223 -\end{codesample2} 21.224 -This introduces a command named \hgxcmd{extdiff}{extdiff}, which by 21.225 -default uses your system's \command{diff} command to generate a 21.226 -unified diff in the same form as the built-in \hgcmd{diff} command. 21.227 -\interaction{extdiff.extdiff} 21.228 -The result won't be exactly the same as with the built-in \hgcmd{diff} 21.229 -variations, because the output of \command{diff} varies from one 21.230 -system to another, even when passed the same options. 21.231 - 21.232 -As the ``\texttt{making snapshot}'' lines of output above imply, the 21.233 -\hgxcmd{extdiff}{extdiff} command works by creating two snapshots of 21.234 -your source tree. The first snapshot is of the source revision; the 21.235 -second, of the target revision or working directory. The 21.236 -\hgxcmd{extdiff}{extdiff} command generates these snapshots in a 21.237 -temporary directory, passes the name of each directory to an external 21.238 -diff viewer, then deletes the temporary directory. For efficiency, it 21.239 -only snapshots the directories and files that have changed between the 21.240 -two revisions. 21.241 - 21.242 -Snapshot directory names have the same base name as your repository. 21.243 -If your repository path is \dirname{/quux/bar/foo}, then \dirname{foo} 21.244 -will be the name of each snapshot directory. Each snapshot directory 21.245 -name has its changeset ID appended, if appropriate. If a snapshot is 21.246 -of revision \texttt{a631aca1083f}, the directory will be named 21.247 -\dirname{foo.a631aca1083f}. A snapshot of the working directory won't 21.248 -have a changeset ID appended, so it would just be \dirname{foo} in 21.249 -this example. To see what this looks like in practice, look again at 21.250 -the \hgxcmd{extdiff}{extdiff} example above. Notice that the diff has 21.251 -the snapshot directory names embedded in its header. 21.252 - 21.253 -The \hgxcmd{extdiff}{extdiff} command accepts two important options. 21.254 -The \hgxopt{extdiff}{extdiff}{-p} option lets you choose a program to 21.255 -view differences with, instead of \command{diff}. With the 21.256 -\hgxopt{extdiff}{extdiff}{-o} option, you can change the options that 21.257 -\hgxcmd{extdiff}{extdiff} passes to the program (by default, these 21.258 -options are ``\texttt{-Npru}'', which only make sense if you're 21.259 -running \command{diff}). In other respects, the 21.260 -\hgxcmd{extdiff}{extdiff} command acts similarly to the built-in 21.261 -\hgcmd{diff} command: you use the same option names, syntax, and 21.262 -arguments to specify the revisions you want, the files you want, and 21.263 -so on. 21.264 - 21.265 -As an example, here's how to run the normal system \command{diff} 21.266 -command, getting it to generate context diffs (using the 21.267 -\cmdopt{diff}{-c} option) instead of unified diffs, and five lines of 21.268 -context instead of the default three (passing \texttt{5} as the 21.269 -argument to the \cmdopt{diff}{-C} option). 21.270 -\interaction{extdiff.extdiff-ctx} 21.271 - 21.272 -Launching a visual diff tool is just as easy. Here's how to launch 21.273 -the \command{kdiff3} viewer. 21.274 -\begin{codesample2} 21.275 - hg extdiff -p kdiff3 -o '' 21.276 -\end{codesample2} 21.277 - 21.278 -If your diff viewing command can't deal with directories, you can 21.279 -easily work around this with a little scripting. For an example of 21.280 -such scripting in action with the \hgext{mq} extension and the 21.281 -\command{interdiff} command, see 21.282 -section~\ref{mq-collab:tips:interdiff}. 21.283 - 21.284 -\subsection{Defining command aliases} 21.285 - 21.286 -It can be cumbersome to remember the options to both the 21.287 -\hgxcmd{extdiff}{extdiff} command and the diff viewer you want to use, 21.288 -so the \hgext{extdiff} extension lets you define \emph{new} commands 21.289 -that will invoke your diff viewer with exactly the right options. 21.290 - 21.291 -All you need to do is edit your \hgrc, and add a section named 21.292 -\rcsection{extdiff}. Inside this section, you can define multiple 21.293 -commands. Here's how to add a \texttt{kdiff3} command. Once you've 21.294 -defined this, you can type ``\texttt{hg kdiff3}'' and the 21.295 -\hgext{extdiff} extension will run \command{kdiff3} for you. 21.296 -\begin{codesample2} 21.297 - [extdiff] 21.298 - cmd.kdiff3 = 21.299 -\end{codesample2} 21.300 -If you leave the right hand side of the definition empty, as above, 21.301 -the \hgext{extdiff} extension uses the name of the command you defined 21.302 -as the name of the external program to run. But these names don't 21.303 -have to be the same. Here, we define a command named ``\texttt{hg wibble}'', which runs \command{kdiff3}. 21.304 -\begin{codesample2} 21.305 - [extdiff] 21.306 - cmd.wibble = kdiff3 21.307 -\end{codesample2} 21.308 - 21.309 -You can also specify the default options that you want to invoke your 21.310 -diff viewing program with. The prefix to use is ``\texttt{opts.}'', 21.311 -followed by the name of the command to which the options apply. This 21.312 -example defines a ``\texttt{hg vimdiff}'' command that runs the 21.313 -\command{vim} editor's \texttt{DirDiff} extension. 21.314 -\begin{codesample2} 21.315 - [extdiff] 21.316 - cmd.vimdiff = vim 21.317 - opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)' 21.318 -\end{codesample2} 21.319 - 21.320 -\section{Cherrypicking changes with the \hgext{transplant} extension} 21.321 -\label{sec:hgext:transplant} 21.322 - 21.323 -Need to have a long chat with Brendan about this. 21.324 - 21.325 -\section{Send changes via email with the \hgext{patchbomb} extension} 21.326 -\label{sec:hgext:patchbomb} 21.327 - 21.328 -Many projects have a culture of ``change review'', in which people 21.329 -send their modifications to a mailing list for others to read and 21.330 -comment on before they commit the final version to a shared 21.331 -repository. Some projects have people who act as gatekeepers; they 21.332 -apply changes from other people to a repository to which those others 21.333 -don't have access. 21.334 - 21.335 -Mercurial makes it easy to send changes over email for review or 21.336 -application, via its \hgext{patchbomb} extension. The extension is so 21.337 -namd because changes are formatted as patches, and it's usual to send 21.338 -one changeset per email message. Sending a long series of changes by 21.339 -email is thus much like ``bombing'' the recipient's inbox, hence 21.340 -``patchbomb''. 21.341 - 21.342 -As usual, the basic configuration of the \hgext{patchbomb} extension 21.343 -takes just one or two lines in your \hgrc. 21.344 -\begin{codesample2} 21.345 - [extensions] 21.346 - patchbomb = 21.347 -\end{codesample2} 21.348 -Once you've enabled the extension, you will have a new command 21.349 -available, named \hgxcmd{patchbomb}{email}. 21.350 - 21.351 -The safest and best way to invoke the \hgxcmd{patchbomb}{email} 21.352 -command is to \emph{always} run it first with the 21.353 -\hgxopt{patchbomb}{email}{-n} option. This will show you what the 21.354 -command \emph{would} send, without actually sending anything. Once 21.355 -you've had a quick glance over the changes and verified that you are 21.356 -sending the right ones, you can rerun the same command, with the 21.357 -\hgxopt{patchbomb}{email}{-n} option removed. 21.358 - 21.359 -The \hgxcmd{patchbomb}{email} command accepts the same kind of 21.360 -revision syntax as every other Mercurial command. For example, this 21.361 -command will send every revision between 7 and \texttt{tip}, 21.362 -inclusive. 21.363 -\begin{codesample2} 21.364 - hg email -n 7:tip 21.365 -\end{codesample2} 21.366 -You can also specify a \emph{repository} to compare with. If you 21.367 -provide a repository but no revisions, the \hgxcmd{patchbomb}{email} 21.368 -command will send all revisions in the local repository that are not 21.369 -present in the remote repository. If you additionally specify 21.370 -revisions or a branch name (the latter using the 21.371 -\hgxopt{patchbomb}{email}{-b} option), this will constrain the 21.372 -revisions sent. 21.373 - 21.374 -It's perfectly safe to run the \hgxcmd{patchbomb}{email} command 21.375 -without the names of the people you want to send to: if you do this, 21.376 -it will just prompt you for those values interactively. (If you're 21.377 -using a Linux or Unix-like system, you should have enhanced 21.378 -\texttt{readline}-style editing capabilities when entering those 21.379 -headers, too, which is useful.) 21.380 - 21.381 -When you are sending just one revision, the \hgxcmd{patchbomb}{email} 21.382 -command will by default use the first line of the changeset 21.383 -description as the subject of the single email message it sends. 21.384 - 21.385 -If you send multiple revisions, the \hgxcmd{patchbomb}{email} command 21.386 -will usually send one message per changeset. It will preface the 21.387 -series with an introductory message, in which you should describe the 21.388 -purpose of the series of changes you're sending. 21.389 - 21.390 -\subsection{Changing the behaviour of patchbombs} 21.391 - 21.392 -Not every project has exactly the same conventions for sending changes 21.393 -in email; the \hgext{patchbomb} extension tries to accommodate a 21.394 -number of variations through command line options. 21.395 -\begin{itemize} 21.396 -\item You can write a subject for the introductory message on the 21.397 - command line using the \hgxopt{patchbomb}{email}{-s} option. This 21.398 - takes one argument, the text of the subject to use. 21.399 -\item To change the email address from which the messages originate, 21.400 - use the \hgxopt{patchbomb}{email}{-f} option. This takes one 21.401 - argument, the email address to use. 21.402 -\item The default behaviour is to send unified diffs (see 21.403 - section~\ref{sec:mq:patch} for a description of the format), one per 21.404 - message. You can send a binary bundle instead with the 21.405 - \hgxopt{patchbomb}{email}{-b} option. 21.406 -\item Unified diffs are normally prefaced with a metadata header. You 21.407 - can omit this, and send unadorned diffs, with the 21.408 - \hgxopt{patchbomb}{email}{--plain} option. 21.409 -\item Diffs are normally sent ``inline'', in the same body part as the 21.410 - description of a patch. This makes it easiest for the largest 21.411 - number of readers to quote and respond to parts of a diff, as some 21.412 - mail clients will only quote the first MIME body part in a message. 21.413 - If you'd prefer to send the description and the diff in separate 21.414 - body parts, use the \hgxopt{patchbomb}{email}{-a} option. 21.415 -\item Instead of sending mail messages, you can write them to an 21.416 - \texttt{mbox}-format mail folder using the 21.417 - \hgxopt{patchbomb}{email}{-m} option. That option takes one 21.418 - argument, the name of the file to write to. 21.419 -\item If you would like to add a \command{diffstat}-format summary to 21.420 - each patch, and one to the introductory message, use the 21.421 - \hgxopt{patchbomb}{email}{-d} option. The \command{diffstat} 21.422 - command displays a table containing the name of each file patched, 21.423 - the number of lines affected, and a histogram showing how much each 21.424 - file is modified. This gives readers a qualitative glance at how 21.425 - complex a patch is. 21.426 -\end{itemize} 21.427 - 21.428 -%%% Local Variables: 21.429 -%%% mode: latex 21.430 -%%% TeX-master: "00book" 21.431 -%%% End: