hgbook
changeset 26:1bc6c1f0192a
More MQ content.
Skeletal preface.
Skeletal preface.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Tue Jul 11 23:48:25 2006 -0700 (2006-07-11) |
parents | 9d5b6d303ef5 |
children | 535e87792eb1 |
files | en/00book.tex en/99defs.tex en/Makefile en/mq.tex en/preface.tex |
line diff
1.1 --- a/en/00book.tex Sun Jul 09 23:18:39 2006 -0700 1.2 +++ b/en/00book.tex Tue Jul 11 23:48:25 2006 -0700 1.3 @@ -1,3 +1,5 @@ 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 @@ -32,6 +34,7 @@ 1.10 1.11 \pagenumbering{arabic} 1.12 1.13 +\include{preface} 1.14 \include{intro} 1.15 \include{mq} 1.16
2.1 --- a/en/99defs.tex Sun Jul 09 23:18:39 2006 -0700 2.2 +++ b/en/99defs.tex Tue Jul 11 23:48:25 2006 -0700 2.3 @@ -1,3 +1,4 @@ 2.4 +\newcommand{\bug}[1]{\index{Mercurial issue!no.~#1}\href{http://www.selenic.com/mercurial/bts/issue#1}{Mercurial issue no.~#1}} 2.5 \newcommand{\tildefile}[1]{\texttt{\~{}/#1}} 2.6 \newcommand{\filename}[1]{\texttt{#1}} 2.7 \newcommand{\dirname}[1]{\texttt{#1}} 2.8 @@ -6,7 +7,7 @@ 2.9 \newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}} 2.10 \newcommand{\hgcmd}[1]{\index{\texttt{#1} command}``\texttt{hg #1}''} 2.11 \newcommand{\command}[1]{\index{\texttt{#1} command}\texttt{#1}} 2.12 -\newcommand{\cmdargs}[2]{\index{\texttt{#1} command}\texttt{#1 #2}} 2.13 +\newcommand{\cmdargs}[2]{\index{\texttt{#1} command}``\texttt{#1 #2}''} 2.14 \newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''} 2.15 \newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}} 2.16 \newcommand{\cmdopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
3.1 --- a/en/Makefile Sun Jul 09 23:18:39 2006 -0700 3.2 +++ b/en/Makefile Tue Jul 11 23:48:25 2006 -0700 3.3 @@ -6,6 +6,7 @@ 3.4 00book.tex \ 3.5 99book.bib \ 3.6 99defs.tex \ 3.7 + preface.tex \ 3.8 intro.tex \ 3.9 mq.tex \ 3.10 build_id.tex 3.11 @@ -38,6 +39,7 @@ 3.12 cd $(dir $@) && makeindex $(basename $(notdir $@)) 3.13 TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1) 3.14 TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1) 3.15 + if grep 'Reference.*undefined' $(@:.pdf=.log); then exit 1; fi 3.16 endef 3.17 3.18 pdf/hgbook.pdf: $(sources) $(image-sources:%.svg=%_pdf.png) examples
4.1 --- a/en/mq.tex Sun Jul 09 23:18:39 2006 -0700 4.2 +++ b/en/mq.tex Tue Jul 11 23:48:25 2006 -0700 4.3 @@ -128,6 +128,7 @@ 4.4 where you cannot use Mercurial and MQ. 4.5 4.6 \section{Understanding patches} 4.7 +\label{sec:mq:patch} 4.8 4.9 Because MQ doesn't hide its patch-oriented nature, it is helpful to 4.10 understand what patches are, and a little about the tools that work 4.11 @@ -179,7 +180,7 @@ 4.12 deletion and one insertion. 4.13 4.14 We will return to ome of the more subtle aspects of patches later (in 4.15 -section~\ref{ex:mq:adv-patch}), but you should have enough information 4.16 +section~\ref{sec:mq:adv-patch}), but you should have enough information 4.17 now to use MQ. 4.18 4.19 \section{Getting started with Mercurial Queues} 4.20 @@ -380,8 +381,58 @@ 4.21 \label{sec:mq:adv-patch} 4.22 4.23 MQ uses the GNU \command{patch} command to apply patches, so it's 4.24 -helpful to know about a few more detailed aspects of how 4.25 -\command{patch} works. 4.26 +helpful to know a few more detailed aspects of how \command{patch} 4.27 +works, and about patches themselves. 4.28 + 4.29 +\subsection{The strip count} 4.30 + 4.31 +If you look at the file headers in a patch, you will notice that the 4.32 +pathnames usually have an extra component on the front that isn't 4.33 +present in the actual path name. This is a holdover from the way that 4.34 +people used to generate patches (people still do this, but it's 4.35 +somewhat rare with modern revision control tools). 4.36 + 4.37 +Alice would unpack a tarball, edit her files, then decide that she 4.38 +wanted to create a patch. So she'd rename her working directory, 4.39 +unpack the tarball again (hence the need for the rename), and use the 4.40 +\cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to 4.41 +recursively generate a patch between the unmodified directory and the 4.42 +modified one. The result would be that the name of the unmodified 4.43 +directory would be at the front of the left-hand path in every file 4.44 +header, and the name of the modified directory would be at the front 4.45 +of the right-hand path. 4.46 + 4.47 +Since someone receiving a patch from the Alices of the net would be 4.48 +unlikely to have unmodified and modified directories with exactly the 4.49 +same names, the \command{patch} command has a \cmdopt{patch}{-p} 4.50 +option that indicates the number of leading path name components to 4.51 +strip when trying to apply a patch. This number is called the 4.52 +\emph{strip count}. 4.53 + 4.54 +An option of ``\texttt{-p1}'' means ``use a strip count of one''. If 4.55 +\command{patch} sees a file name \filename{foo/bar/baz} in a file 4.56 +header, it will strip \filename{foo} and try to patch a file named 4.57 +\filename{bar/baz}. (Strictly speaking, the strip count refers to the 4.58 +number of \emph{path separators} (and the components that go with them 4.59 +) to strip. A strip count of one will turn \filename{foo/bar} into 4.60 +\filename{bar}, but \filename{/foo/bar} (notice the extra leading 4.61 +slash) into \filename{foo/bar}.) 4.62 + 4.63 +The ``standard'' strip count for patches is one; almost all patches 4.64 +contain one leading path name component that needs to be stripped. 4.65 +Mercurial's \hgcmd{diff} command generates path names in this form, 4.66 +and the \hgcmd{import} command and MQ expect patches to have a strip 4.67 +count of one. 4.68 + 4.69 +If you receive a patch from someone that you want to add to your patch 4.70 +queue, and the patch needs a strip count other than one, you cannot 4.71 +just \hgcmd{qimport} the patch, because \hgcmd{qimport} does not yet 4.72 +have a \texttt{-p} option (see~\bug{311}). Your best bet is to 4.73 +\hgcmd{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}} 4.74 +to apply their patch, followed by \hgcmd{addremove} to pick up any 4.75 +files added or removed by the patch, followed by \hgcmd{qrefresh}. 4.76 +This complexity may become unnecessary; see~\bug{311} for details. 4.77 +\subsection{Strategies for applying a patch} 4.78 4.79 When \command{patch} applies a hunk, it tries a handful of 4.80 successively less accurate strategies to try to make the hunk apply. 4.81 @@ -604,6 +655,24 @@ 4.82 or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once 4.83 you are sure that you no longer need it as a backup. 4.84 4.85 +\section{Useful things to know about} 4.86 + 4.87 +There are a number of aspects of MQ usage that don't fit tidily into 4.88 +sections of their own, but that are good to know. Here they are, in 4.89 +one place. 4.90 + 4.91 +\begin{itemize} 4.92 +\item Normally, when you \hgcmd{qpop} a patch and \hgcmd{qpush} it 4.93 + again, the changeset that represents the patch after the pop/push 4.94 + will have a \emph{different identity} than the changeset that 4.95 + represented the hash beforehand. See section~\ref{sec:mq:cmd:qpush} 4.96 + for information as to why this is. 4.97 +\item It's not a good idea to \hgcmd{merge} changes from another 4.98 + branch with a patch changeset, at least if you want to maintain the 4.99 + ``patchiness'' of that changeset and changesets below it on the 4.100 + patch stack. If you try to do this, it will appear to succeed, but 4.101 + MQ will become confused. 4.102 +\end{itemize} 4.103 \section{Managing patches in a repository} 4.104 4.105 Because MQ's \sdirname{.hg/patches} directory resides outside a 4.106 @@ -617,14 +686,14 @@ 4.107 the patch. This lets you ``roll back'' to that version of the patch 4.108 later on. 4.109 4.110 -In addition, you can then share different versions of the same patch 4.111 -stack among multiple underlying repositories. I use this when I am 4.112 -developing a Linux kernel feature. I have a pristine copy of my 4.113 -kernel sources for each of several CPU architectures, and a cloned 4.114 -repository under each that contains the patches I am working on. When 4.115 -I want to test a change on a different architecture, I push my current 4.116 -patches to the patch repository associated with that kernel tree, pop 4.117 -and push all of my patches, and build and test that kernel. 4.118 +You can then share different versions of the same patch stack among 4.119 +multiple underlying repositories. I use this when I am developing a 4.120 +Linux kernel feature. I have a pristine copy of my kernel sources for 4.121 +each of several CPU architectures, and a cloned repository under each 4.122 +that contains the patches I am working on. When I want to test a 4.123 +change on a different architecture, I push my current patches to the 4.124 +patch repository associated with that kernel tree, pop and push all of 4.125 +my patches, and build and test that kernel. 4.126 4.127 Managing patches in a repository makes it possible for multiple 4.128 developers to work on the same patch series without colliding with 4.129 @@ -669,7 +738,7 @@ 4.130 see those changes show up there. If you forget to do this, you can 4.131 confuse MQ's idea of which patches are applied. 4.132 4.133 -\section{Commands for working with patches} 4.134 +\section{Third party tools for working with patches} 4.135 \label{sec:mq:tools} 4.136 4.137 Once you've been working with patches for a while, you'll find 4.138 @@ -801,9 +870,11 @@ 4.139 4.140 This command prints three different kinds of number: 4.141 \begin{itemize} 4.142 -\item a \emph{file number} to identify each file modified in the patch; 4.143 -\item the line number within a modified file that a hunk starts at; and 4.144 -\item a \emph{hunk number} to identify that hunk. 4.145 +\item (in the first column) a \emph{file number} to identify each file 4.146 + modified in the patch; 4.147 +\item (on the next line, indented) the line number within a modified 4.148 + file where a hunk starts; and 4.149 +\item (on the same line) a \emph{hunk number} to identify that hunk. 4.150 \end{itemize} 4.151 4.152 You'll have to use some visual inspection, and reading of the patch, 4.153 @@ -815,6 +886,18 @@ 4.154 Once you have this hunk, you can concatenate it onto the end of your 4.155 destination patch and continue with the remainder of 4.156 section~\ref{sec:mq:combine}. 4.157 + 4.158 +\section{Differences between quilt and MQ} 4.159 + 4.160 +If you are already familiar with quilt, MQ provides a similar command 4.161 +set. There are a few differences in the way that it works. 4.162 + 4.163 +You will already have noticed that most quilt commands have MQ 4.164 +counterparts that simply begin with a ``\texttt{q}''. The exceptions 4.165 +are quilt's \texttt{add} and \texttt{remove} commands, the 4.166 +counterparts for which are the normal Mercurial \hgcmd{add} and 4.167 +\hgcmd{remove} commands. There is no MQ equivalent of the quilt 4.168 +\texttt{edit} command. 4.169 \section{MQ command reference} 4.170 \label{sec:mq:cmdref} 4.171 4.172 @@ -953,6 +1036,7 @@ 4.173 This will become the topmost applied patch if you run \hgcmd{qpop}. 4.174 4.175 \subsection{\hgcmd{qpush}---push patches onto the stack} 4.176 +\label{sec:mq:cmd:qpush} 4.177 4.178 The \hgcmd{qpush} command adds patches onto the applied stack. By 4.179 default, it adds only one patch. 4.180 @@ -960,7 +1044,7 @@ 4.181 This command creates a new changeset to represent each applied patch, 4.182 and updates the working directory to apply the effects of the patches. 4.183 4.184 -The data used when creating a changeset are as follows: 4.185 +The default data used when creating a changeset are as follows: 4.186 \begin{itemize} 4.187 \item The commit date and time zone are the current date and time 4.188 zone. Because these data are used to compute the identity of a 4.189 @@ -973,6 +1057,8 @@ 4.190 before the first diff header. If there is no such text, a default 4.191 commit message is used that identifies the name of the patch. 4.192 \end{itemize} 4.193 +If a patch contains a Mercurial patch header (XXX add link), the 4.194 +information in the patch header overrides these defaults. 4.195 4.196 Options: 4.197 \begin{itemize} 4.198 @@ -1016,15 +1102,87 @@ 4.199 changeset to differ from the previous changeset that identified the 4.200 patch. 4.201 4.202 +\subsection{\hgcmd{qrestore}---restore saved queue state} 4.203 + 4.204 +XXX No idea what this does. 4.205 + 4.206 +\subsection{\hgcmd{qsave}---save current queue state} 4.207 + 4.208 +XXX Likewise. 4.209 + 4.210 +\subsection{\hgcmd{qseries}---print the entire patch series} 4.211 + 4.212 +The \hgcmd{qseries} command prints the entire patch series from the 4.213 +\sfilename{series} file. It prints only patch names, not empty lines 4.214 +or comments. It prints in order from first to be applied to last. 4.215 + 4.216 +\subsection{\hgcmd{qtop}---print the name of the current patch} 4.217 + 4.218 +The \hgcmd{qtop} prints the name of the topmost currently applied 4.219 +patch. 4.220 + 4.221 +\subsection{\hgcmd{qunapplied}---print patches not yet applied} 4.222 + 4.223 +The \hgcmd{qunapplied} command prints the names of patches from the 4.224 +\sfilename{series} file that are not yet applied. It prints them in 4.225 +order from the next patch that will be pushed to the last. 4.226 + 4.227 +\subsection{\hgcmd{qversion}} 4.228 + 4.229 +The \hgcmd{qversion} command prints the version of MQ that is in use. 4.230 + 4.231 +\subsection{\hgcmd{strip}---remove a revision and descendants} 4.232 + 4.233 +The \hgcmd{strip} command removes a revision, and all of its 4.234 +descendants, from the repository. It undoes the effects of the 4.235 +removed revisions from the repository, and updates the working 4.236 +directory to the first parent of the removed revision. 4.237 + 4.238 +The \hgcmd{strip} command saves a backup of the removed changesets in 4.239 +a bundle, so that they can be reapplied if removed in error. 4.240 + 4.241 +Options: 4.242 +\begin{itemize} 4.243 +\item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed 4.244 + with the stripped changesets in the backup bundle. 4.245 +\item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all 4.246 + heads. XXX This should be renamed, and use \texttt{-f} to strip revs 4.247 + when there are pending changes. 4.248 +\item[\hgopt{strip}{-n}] Do not save a backup bundle. 4.249 +\end{itemize} 4.250 \section{MQ file reference} 4.251 4.252 4.253 \subsection{The \sfilename{series} file} 4.254 4.255 - 4.256 +The \sfilename{series} file contains a list of the names of all 4.257 +patches that MQ can apply. It is represented as a list of names, with 4.258 +one name saved per line. Leading and trailing white space in each 4.259 +line are ignored. 4.260 + 4.261 +Lines may contain comments. A comment begins with the ``\texttt{\#}'' 4.262 +character, and extends to the end of the line. Empty lines, and lines 4.263 +that contain only comments, are ignored. 4.264 + 4.265 +You will often need to edit the \sfilename{series} file by hand, hence 4.266 +the support for comments and empty lines noted above. For example, 4.267 +you can comment out a patch temporarily, and \hgcmd{qpush} will skip 4.268 +over that patch when applying patches. You can also change the order 4.269 +in which patches are applied by reordering their entries in the 4.270 +\sfilename{series} file. 4.271 + 4.272 +Placing the \sfilename{series} file under revision control is also 4.273 +supported; it is a good idea to place all of the patches that it 4.274 +refers to under revision control, as well. If you create a patch 4.275 +directory using the \hgopt{qinit}{-c} option to \hgcmd{qinit}, this 4.276 +will be done for you automatically. 4.277 \subsection{The \sfilename{status} file} 4.278 4.279 - 4.280 +The \sfilename{status} file contains the names and changeset hashes of 4.281 +all patches that MQ currently has applied. Unlike the 4.282 +\sfilename{series} file, this file is not intended for editing. You 4.283 +should not place this file under revision control, or modify it in any 4.284 +way. It is used by MQ strictly for internal book-keeping. 4.285 4.286 %%% Local Variables: 4.287 %%% mode: latex
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 5.2 +++ b/en/preface.tex Tue Jul 11 23:48:25 2006 -0700 5.3 @@ -0,0 +1,34 @@ 5.4 +\chapter*{Preface} 5.5 +\addcontentsline{toc}{chapter}{Preface} 5.6 +\label{chap:preface} 5.7 + 5.8 +Distributed revision control is a relatively new territory, and has 5.9 +thus far grown due to people's willingness to strike out into 5.10 +ill-charted territory. 5.11 + 5.12 +I am writing a book about distributed revision control because I 5.13 +believe that it is an important subject that deserves a field guide. 5.14 +I chose to write about Mercurial because it is the easiest tool to 5.15 +learn the terrain with, and yet it scales to the demands of real, 5.16 +challenging environments where many other revision control tools fail. 5.17 + 5.18 +\section{This book is a work in progress} 5.19 + 5.20 +I am releasing this book while I am still writing it, in the hope that 5.21 +it will prove useful to others. I also hope that readers will 5.22 +contribute as they see fit. 5.23 + 5.24 +\section{Colophon---this book is Free} 5.25 + 5.26 +This book is licensed under the Open Publication License, and is 5.27 +produced entirely using Free Software tools. It is typeset with 5.28 +\LaTeX{}; illustrations are drawn and rendered with 5.29 +\href{http://www.inkscape.org/}{Inkscape}. 5.30 + 5.31 +The complete source code for this book is published as a Mercurial 5.32 +repository, at \url{http://hg.serpentine.com/mercurial/book}. 5.33 + 5.34 +%%% Local Variables: 5.35 +%%% mode: latex 5.36 +%%% TeX-master: "00book" 5.37 +%%% End: