hgbook
changeset 189:3c6c5b551c96
Merge backout.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Apr 16 14:23:11 2007 -0700 (2007-04-16) |
parents | d3dd1bedba3c b60e2de6dbc3 |
children | cd066590e2e3 |
files | en/examples/tour.commit-no-user.out |
line diff
1.1 --- a/.hgignore Mon Apr 16 14:22:25 2007 -0700 1.2 +++ b/.hgignore Mon Apr 16 14:23:11 2007 -0700 1.3 @@ -6,6 +6,7 @@ 1.4 1.5 beta/*.tex 1.6 build_id.tex 1.7 +hg_id.tex 1.8 *.4[ct][ct] 1.9 *.aux 1.10 *.bbl
2.1 --- a/en/00book.tex Mon Apr 16 14:22:25 2007 -0700 2.2 +++ b/en/00book.tex Mon Apr 16 14:23:11 2007 -0700 2.3 @@ -13,13 +13,14 @@ 2.4 2.5 \include{99defs} 2.6 2.7 -\title{Distributed revision control with Mercurial} 2.8 -\author{Bryan O'Sullivan} 2.9 +\title{Distributed revision control with Mercurial} \author{Bryan 2.10 + O'Sullivan} 2.11 \date{Copyright \copyright\ 2006, 2007 Bryan O'Sullivan.\\ 2.12 This material may be distributed only subject to the terms and 2.13 conditions set forth in version 1.0 of the Open Publication License. 2.14 Please refer to Appendix~\ref{cha:opl} for the license text.\\ 2.15 - This book was prepared from revision \input{build_id}.} 2.16 + This book was prepared from revision \input{build_id} of its sources 2.17 + using revision \input{hg_id} of Mercurial.} 2.18 2.19 \makeindex 2.20 2.21 @@ -43,6 +44,7 @@ 2.22 \include{daily} 2.23 \include{collab} 2.24 \include{filenames} 2.25 +\include{branch} 2.26 \include{undo} 2.27 \include{hook} 2.28 \include{template}
3.1 --- a/en/99book.bib Mon Apr 16 14:22:25 2007 -0700 3.2 +++ b/en/99book.bib Mon Apr 16 14:23:11 2007 -0700 3.3 @@ -62,3 +62,9 @@ 3.4 title = {Universal MacPython}, 3.5 note = {\url{http://bob.pythonmac.org/archives/2006/04/10/python-and-universal-binaries-on-mac-os-x/}}, 3.6 } 3.7 + 3.8 +@Misc{web:putty, 3.9 + author = {Simon Tatham}, 3.10 + title = {PuTTY---open source ssh client for Windows}, 3.11 + note = {\url{http://www.chiark.greenend.org.uk/~sgtatham/putty/}}, 3.12 +}
4.1 --- a/en/99defs.tex Mon Apr 16 14:22:25 2007 -0700 4.2 +++ b/en/99defs.tex Mon Apr 16 14:23:11 2007 -0700 4.3 @@ -68,7 +68,12 @@ 4.4 section!\texttt{#2} entry}\texttt{#2}} 4.5 4.6 % hgrc file. 4.7 -\newcommand{\hgrc}{\index{\texttt{hgrc} file}\texttt{hgrc}} 4.8 +\newcommand{\hgrc}{\index{configuration file!\texttt{hgrc} 4.9 + (Linux/Unix)}\index{\texttt{hgrc} configuration file}\texttt{hgrc}} 4.10 + 4.11 +% Mercurial.ini file. 4.12 +\newcommand{\hgini}{\index{configuration file!\texttt{Mercurial.ini} 4.13 + (Windows)}\index{\texttt{Mercurial.ini} configuration file}\texttt{Mercurial.ini}} 4.14 4.15 % Hook name. 4.16 \newcommand{\hook}[1]{\index{\texttt{#1} hook}\index{hooks!\texttt{#1}}\texttt{#1}}
5.1 --- a/en/Makefile Mon Apr 16 14:22:25 2007 -0700 5.2 +++ b/en/Makefile Mon Apr 16 14:23:11 2007 -0700 5.3 @@ -1,17 +1,17 @@ 5.4 # This makefile requires GNU make. 5.5 5.6 -hg_id := $(shell hg parents --template '{node|short}\n') 5.7 - 5.8 sources := \ 5.9 00book.tex \ 5.10 99book.bib \ 5.11 99defs.tex \ 5.12 build_id.tex \ 5.13 + branch.tex \ 5.14 cmdref.tex \ 5.15 collab.tex \ 5.16 concepts.tex \ 5.17 daily.tex \ 5.18 filenames.tex \ 5.19 + hg_id.tex \ 5.20 hook.tex \ 5.21 intro.tex \ 5.22 mq.tex \ 5.23 @@ -25,6 +25,7 @@ 5.24 undo.tex 5.25 5.26 image-sources := \ 5.27 + feature-branches.dot \ 5.28 filelog.svg \ 5.29 kdiff3.png \ 5.30 metadata.svg \ 5.31 @@ -54,6 +55,7 @@ 5.32 example-sources := \ 5.33 backout \ 5.34 bisect \ 5.35 + branching \ 5.36 cmdref \ 5.37 daily.copy \ 5.38 daily.files \ 5.39 @@ -78,6 +80,9 @@ 5.40 tour \ 5.41 tour-merge-conflict 5.42 5.43 +example-prereqs := \ 5.44 + /usr/bin/merge 5.45 + 5.46 dist-sources := \ 5.47 ../html/hgicon.png \ 5.48 ../html/index.html.var \ 5.49 @@ -88,6 +93,13 @@ 5.50 -output-directory $(dir $(1)) \ 5.51 -jobname $(basename $(notdir $(1))) 5.52 5.53 +hg = $(shell which hg) 5.54 + 5.55 +hg-id = $(shell hg parents --template '{node|short}\n') 5.56 + 5.57 +hg-version = $(shell hg version -q | \ 5.58 + sed 's,.*(version \(unknown\|[a-f0-9]*\)),\1,') 5.59 + 5.60 all: pdf html 5.61 5.62 pdf: pdf/hgbook.pdf 5.63 @@ -110,25 +122,21 @@ 5.64 5.65 html: onepage split 5.66 5.67 -onepage: html/onepage/hgbook.html 5.68 - 5.69 -split: html/split/hgbook.html 5.70 +htlatex := /usr/bin/htlatex 5.71 + 5.72 +onepage: $(htlatex) html/onepage/hgbook.html 5.73 + 5.74 +split: $(htlatex) html/split/hgbook.html 5.75 5.76 # This is a horrible hack to work around the fact that the htlatex 5.77 # command in tex4ht is itself a horrible hack. I really don't want to 5.78 # include verbatim the big wad of TeX that is repeated in that script, 5.79 -# so instead I mangle the script itself. 5.80 +# but I've given up and run a hacked copy as htlatex.book here. 5.81 5.82 define htlatex 5.83 mkdir -p $(dir $(1)) 5.84 - head -2 $(shell which htlatex) > $(dir $(1))/htlatex.book 5.85 - cp 99book.bib $(dir $@) 5.86 - echo '(cd $(dir $@) && bibtex $(basename $(notdir $@)))' >> $(dir $(1))/htlatex.book 5.87 - echo '(cd $(dir $@) && makeindex $(basename $(notdir $@)))' >> $(dir $(1))/htlatex.book 5.88 - head -3 $(shell which htlatex) >> $(dir $(1))/htlatex.book 5.89 - echo 'echo status $$$$' >> $(dir $(1))/htlatex.book 5.90 - chmod 755 $(dir $(1))/htlatex.book 5.91 - TEXINPUTS=$(dir $(2)): $(dir $(1))/htlatex.book $(2) "bookhtml,html4-uni,$(3)" " -cunihtf -utf8" "" "$(call latex-options,$(1))" || (rm -f $(1); exit 1) 5.92 + cp 99book.bib $(dir $(1)) 5.93 + TEXINPUTS=$(dir $(2)): ./htlatex.book $(2) "bookhtml,html4-uni,$(3)" " -cunihtf -utf8" "$(dir $(1))" "$(call latex-options,$(1))" || (rm -f $(1); exit 1) 5.94 cd $(dir $(1)) && tex4ht -f/$(basename $(notdir $(1))) -cvalidate -cunihtf 5.95 cd $(dir $(1)) && t4ht -f/$(basename $(notdir $(1))) 5.96 ./fixhtml.py $(dir $(1))/*.html 5.97 @@ -165,7 +173,7 @@ 5.98 %.eps: %.dot 5.99 dot -Tps -o $@ $< 5.100 5.101 -examples: examples/.run 5.102 +examples: $(example-prereqs) examples/.run 5.103 5.104 examples/.run: $(example-sources:%=examples/%.run) 5.105 touch examples/.run 5.106 @@ -174,7 +182,10 @@ 5.107 cd examples && ./run-example $(notdir $<) 5.108 5.109 build_id.tex: $(wildcard ../.hg/00changelog.[id]) 5.110 - echo -n $(hg_id) > build_id.tex 5.111 + echo -n $(hg-id) > build_id.tex 5.112 + 5.113 +hg_id.tex: $(hg) 5.114 + echo -n $(hg-version) > hg_id.tex 5.115 5.116 clean: 5.117 rm -rf dist html pdf \ 5.118 @@ -182,7 +193,7 @@ 5.119 $(image-dot:%.dot=%.png) \ 5.120 $(image-svg:%.svg=%.pdf) \ 5.121 $(image-svg:%.svg=%.png) \ 5.122 - examples/*.{lxo,run} examples/.run build_id.tex 5.123 + examples/*.{lxo,run} examples/.run build_id.tex hg_id.tex 5.124 5.125 install: pdf split $(dist-sources) 5.126 rm -rf dist
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 6.2 +++ b/en/branch.tex Mon Apr 16 14:23:11 2007 -0700 6.3 @@ -0,0 +1,9 @@ 6.4 +\chapter{Managing branchy development} 6.5 +\label{chap:branch} 6.6 + 6.7 + 6.8 + 6.9 +%%% Local Variables: 6.10 +%%% mode: latex 6.11 +%%% TeX-master: "00book" 6.12 +%%% End:
7.1 --- a/en/collab.tex Mon Apr 16 14:22:25 2007 -0700 7.2 +++ b/en/collab.tex Mon Apr 16 14:23:11 2007 -0700 7.3 @@ -74,7 +74,7 @@ 7.4 7.5 \subsection{A single central repository} 7.6 7.7 -For smaller projects, migrating from a centralised revision control 7.8 +For smaller projects migrating from a centralised revision control 7.9 tool, perhaps the easiest way to get started is to have changes flow 7.10 through a single shared central repository. This is also the 7.11 most common ``building block'' for more ambitious workflow schemes. 7.12 @@ -84,7 +84,7 @@ 7.13 developers have permission to push a change back when they're ready 7.14 for other people to see it. 7.15 7.16 -Under this model, it can still sometimes make sense for people to pull 7.17 +Under this model, it can still often make sense for people to pull 7.18 changes directly from each other, without going through the central 7.19 repository. Consider a case in which I have a tentative bug fix, but 7.20 I am worried that if I were to publish it to the central repository, 7.21 @@ -102,6 +102,97 @@ 7.22 needs of people who don't have push access, and those who want to use 7.23 web browsers to browse the repository's history. 7.24 7.25 +\subsection{Working with multiple branches} 7.26 + 7.27 +Projects of any significant size naturally tend to make progress on 7.28 +several fronts simultaneously. In the case of software, it's common 7.29 +for a project to go through periodic official releases. A release 7.30 +might then go into ``maintenance mode'' for a while after its first 7.31 +publication; maintenance releases tend to contain only bug fixes, not 7.32 +new features. In parallel with these maintenance releases, one or 7.33 +more future releases may be under development. People normally use 7.34 +the word ``branch'' to refer to one of these many slightly different 7.35 +directions in which development is proceeding. 7.36 + 7.37 +Mercurial is particularly well suited to managing a number of 7.38 +simultaneous, but not identical, branches. Each ``development 7.39 +direction'' can live in its own central repository, and you can merge 7.40 +changes from one to another as the need arises. Because repositories 7.41 +are independent of each other, unstable changes in a development 7.42 +branch will never affect a stable branch unless someone explicitly 7.43 +merges those changes in. 7.44 + 7.45 +Here's an example of how this can work in practice. Let's say you 7.46 +have one ``main branch'' on a central server. 7.47 +\interaction{branching.init} 7.48 +People clone it, make changes locally, test them, and push them back. 7.49 + 7.50 +Once the main branch reaches a release milestone, you can use the 7.51 +\hgcmd{tag} command to give a permanent name to the milestone 7.52 +revision. 7.53 +\interaction{branching.tag} 7.54 +Let's say some ongoing development occurs on the main branch. 7.55 +\interaction{branching.main} 7.56 +Using the tag that was recorded at the milestone, people who clone 7.57 +that repository at any time in the future can use \hgcmd{update} to 7.58 +get a copy of the working directory exactly as it was when that tagged 7.59 +revision was committed. 7.60 +\interaction{branching.update} 7.61 + 7.62 +In addition, immediately after the main branch is tagged, someone can 7.63 +then clone the main branch on the server to a new ``stable'' branch, 7.64 +also on the server. 7.65 +\interaction{branching.clone} 7.66 + 7.67 +Someone who needs to make a change to the stable branch can then clone 7.68 +\emph{that} repository, make their changes, commit, and push their 7.69 +changes back there. 7.70 +\interaction{branching.stable} 7.71 +Because Mercurial repositories are independent, and Mercurial doesn't 7.72 +move changes around automatically, the stable and main branches are 7.73 +\emph{isolated} from each other. The changes that you made on the 7.74 +main branch don't ``leak'' to the stable branch, and vice versa. 7.75 + 7.76 +You'll often want all of your bugfixes on the stable branch to show up 7.77 +on the main branch, too. Rather than rewrite a bugfix on the main 7.78 +branch, you can simply pull and merge changes from the stable to the 7.79 +main branch, and Mercurial will bring those bugfixes in for you. 7.80 +\interaction{branching.merge} 7.81 +The main branch will still contain changes that are not on the stable 7.82 +branch, but it will also contain all of the bugfixes from the stable 7.83 +branch. The stable branch remains unaffected by these changes. 7.84 + 7.85 +\subsection{Feature branches} 7.86 + 7.87 +For larger projects, an effective way to manage change is to break up 7.88 +a team into smaller groups. Each group has a shared branch of its 7.89 +own, cloned from a single ``master'' branch used by the entire 7.90 +project. People working on an individual branch are typically quite 7.91 +isolated from developments on other branches. 7.92 + 7.93 +\begin{figure}[ht] 7.94 + \centering 7.95 + \grafix{feature-branches} 7.96 + \caption{Feature branches} 7.97 + \label{fig:collab:feature-branches} 7.98 +\end{figure} 7.99 + 7.100 +When a particular feature is deemed to be in suitable shape, someone 7.101 +on that feature team pulls and merges from the master branch into the 7.102 +feature branch, then pushes back up to the master branch. 7.103 + 7.104 +\subsection{The release train} 7.105 + 7.106 +Some projects are organised on a ``train'' basis: a release is 7.107 +scheduled to happen every few months, and whatever features are ready 7.108 +when the ``train'' is ready to leave are allowed in. 7.109 + 7.110 +This model resembles working with feature branches. The difference is 7.111 +that when a feature branch misses a train, someone on the feature team 7.112 +pulls and merges the changes that went out on that train release into 7.113 +the feature branch, and the team continues its work on top of that 7.114 +release so that their feature can make the next release. 7.115 + 7.116 \subsection{The Linux kernel model} 7.117 7.118 The development of the Linux kernel has a shallow hierarchical 7.119 @@ -132,12 +223,16 @@ 7.120 to Linus. In addition, there are several well known branches that 7.121 people use for different purposes. For example, a few people maintain 7.122 ``stable'' repositories of older versions of the kernel, to which they 7.123 -apply critical fixes as needed. 7.124 +apply critical fixes as needed. Some maintainers publish multiple 7.125 +trees: one for experimental changes; one for changes that they are 7.126 +about to feed upstream; and so on. Others just publish a single 7.127 +tree. 7.128 7.129 This model has two notable features. The first is that it's ``pull 7.130 only''. You have to ask, convince, or beg another developer to take a 7.131 -change from you, because there are no shared trees, and there's no way 7.132 -to push changes into a tree that someone else controls. 7.133 +change from you, because there are almost no trees to which more than 7.134 +one person can push, and there's no way to push changes into a tree 7.135 +that someone else controls. 7.136 7.137 The second is that it's based on reputation and acclaim. If you're an 7.138 unknown, Linus will probably ignore changes from you without even 7.139 @@ -162,6 +257,35 @@ 7.140 of development is astounding. And yet Linux is a highly successful, 7.141 well-regarded piece of software. 7.142 7.143 +\subsection{Pull-only versus shared-push collaboration} 7.144 + 7.145 +A perpetual source of heat in the open source community is whether a 7.146 +development model in which people only ever pull changes from others 7.147 +is ``better than'' one in which multiple people can push changes to a 7.148 +shared repository. 7.149 + 7.150 +Typically, the backers of the shared-push model use tools that 7.151 +actively enforce this approach. If you're using a centralised 7.152 +revision control tool such as Subversion, there's no way to make a 7.153 +choice over which model you'll use: the tool gives you shared-push, 7.154 +and if you want to do anything else, you'll have to roll your own 7.155 +approach on top (such as applying a patch by hand). 7.156 + 7.157 +A good distributed revision control tool, such as Mercurial, will 7.158 +support both models. You and your collaborators can then structure 7.159 +how you work together based on your own needs and preferences, not on 7.160 +what contortions your tools force you into. 7.161 + 7.162 +\subsection{Where collaboration meets branch management} 7.163 + 7.164 +Once you and your team set up some shared repositories and start 7.165 +propagating changes back and forth between local and shared repos, you 7.166 +begin to face a related, but slightly different challenge: that of 7.167 +managing the multiple directions in which your team may be moving at 7.168 +once. Even though this subject is intimately related to how your team 7.169 +collaborates, it's dense enough to merit treatment of its own, in 7.170 +chapter~\ref{chap:branch}. 7.171 + 7.172 \section{The technical side of sharing} 7.173 7.174 \subsection{Informal sharing with \hgcmd{serve}} 7.175 @@ -222,10 +346,287 @@ 7.176 correctly, and find out what URL you should send to your 7.177 collaborators, start it with the \hggopt{-v} option. 7.178 7.179 -\subsection{Using \command{ssh} as a tunnel} 7.180 +\subsection{Using the Secure Shell (ssh) protocol} 7.181 \label{sec:collab:ssh} 7.182 7.183 -\subsection{Serving HTTP with a CGI script} 7.184 +You can pull and push changes securely over a network connection using 7.185 +the Secure Shell (\texttt{ssh}) protocol. To use this successfully, 7.186 +you may have to do a little bit of configuration on the client or 7.187 +server sides. 7.188 + 7.189 +If you're not familiar with ssh, it's a network protocol that lets you 7.190 +securely communicate with another computer. To use it with Mercurial, 7.191 +you'll be setting up one or more user accounts on a server so that 7.192 +remote users can log in and execute commands. 7.193 + 7.194 +(If you \emph{are} familiar with ssh, you'll probably find some of the 7.195 +material that follows to be elementary in nature.) 7.196 + 7.197 +\subsubsection{How to read and write ssh URLs} 7.198 + 7.199 +An ssh URL tends to look like this: 7.200 +\begin{codesample2} 7.201 + ssh://bos@hg.serpentine.com:22/hg/hgbook 7.202 +\end{codesample2} 7.203 +\begin{enumerate} 7.204 +\item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh 7.205 + protocol. 7.206 +\item The ``\texttt{bos@}'' component indicates what username to log 7.207 + into the server as. You can leave this out if the remote username 7.208 + is the same as your local username. 7.209 +\item The ``\texttt{hg.serpentine.com}'' gives the hostname of the 7.210 + server to log into. 7.211 +\item The ``:22'' identifies the port number to connect to the server 7.212 + on. The default port is~22, so you only need to specify this part 7.213 + if you're \emph{not} using port~22. 7.214 +\item The remainder of the URL is the local path to the repository on 7.215 + the server. 7.216 +\end{enumerate} 7.217 + 7.218 +There's plenty of scope for confusion with the path component of ssh 7.219 +URLs, as there is no standard way for tools to interpret it. Some 7.220 +programs behave differently than others when dealing with these paths. 7.221 +This isn't an ideal situation, but it's unlikely to change. Please 7.222 +read the following paragraphs carefully. 7.223 + 7.224 +Mercurial treats the path to a repository on the server as relative to 7.225 +the remote user's home directory. For example, if user \texttt{foo} 7.226 +on the server has a home directory of \dirname{/home/foo}, then an ssh 7.227 +URL that contains a path component of \dirname{bar} 7.228 +\emph{really} refers to the directory \dirname{/home/foo/bar}. 7.229 + 7.230 +If you want to specify a path relative to another user's home 7.231 +directory, you can use a path that starts with a tilde character 7.232 +followed by the user's name (let's call them \texttt{otheruser}), like 7.233 +this. 7.234 +\begin{codesample2} 7.235 + ssh://server/~otheruser/hg/repo 7.236 +\end{codesample2} 7.237 + 7.238 +And if you really want to specify an \emph{absolute} path on the 7.239 +server, begin the path component with two slashes, as in this example. 7.240 +\begin{codesample2} 7.241 + ssh://server//absolute/path 7.242 +\end{codesample2} 7.243 + 7.244 +\subsubsection{Finding an ssh client for your system} 7.245 + 7.246 +Almost every Unix-like system comes with OpenSSH preinstalled. If 7.247 +you're using such a system, run \Verb|which ssh| to find out if 7.248 +the \command{ssh} command is installed (it's usually in 7.249 +\dirname{/usr/bin}). In the unlikely event that it isn't present, 7.250 +take a look at your system documentation to figure out how to install 7.251 +it. 7.252 + 7.253 +On Windows, you'll first need to choose download a suitable ssh 7.254 +client. There are two alternatives. 7.255 +\begin{itemize} 7.256 +\item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides 7.257 + a complete suite of ssh client commands. 7.258 +\item If you have a high tolerance for pain, you can use the Cygwin 7.259 + port of OpenSSH. 7.260 +\end{itemize} 7.261 +In either case, you'll need to edit your \hgini\ file to tell 7.262 +Mercurial where to find the actual client command. For example, if 7.263 +you're using PuTTY, you'll need to use the \command{plink} command as 7.264 +a command-line ssh client. 7.265 +\begin{codesample2} 7.266 + [ui] 7.267 + ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key" 7.268 +\end{codesample2} 7.269 + 7.270 +\begin{note} 7.271 + The path to \command{plink} shouldn't contain any whitespace 7.272 + characters, or Mercurial may not be able to run it correctly (so 7.273 + putting it in \dirname{C:\\Program Files} is probably not be a good 7.274 + idea). 7.275 +\end{note} 7.276 + 7.277 +\subsubsection{Generating a key pair} 7.278 + 7.279 +To avoid the need to repetitively type a password every time you need 7.280 +to use your ssh client, I recommend generating a key pair. On a 7.281 +Unix-like system, the \command{ssh-keygen} command will do the trick. 7.282 +On Windows, if you're using PuTTY, the \command{puttygen} command is 7.283 +what you'll need. 7.284 + 7.285 +When you generate a key pair, it's usually \emph{highly} advisable to 7.286 +protect it with a passphrase. (The only time that you might not want 7.287 +to do this id when you're using the ssh protocol for automated tasks 7.288 +on a secure network.) 7.289 + 7.290 +Simply generating a key pair isn't enough, however. You'll need to 7.291 +add the public key to the set of authorised keys for whatever user 7.292 +you're logging in remotely as. For servers using OpenSSH (the vast 7.293 +majority), this will mean adding the public key to a list in a file 7.294 +called \sfilename{authorized\_keys} in their \sdirname{.ssh} 7.295 +directory. 7.296 + 7.297 +On a Unix-like system, your public key will have a \filename{.pub} 7.298 +extension. If you're using \command{puttygen} on Windows, you can 7.299 +save the public key to a file of your choosing, or paste it from the 7.300 +window it's displayed in straight into the 7.301 +\sfilename{authorized\_keys} file. 7.302 + 7.303 +\subsubsection{Using an authentication agent} 7.304 + 7.305 +An authentication agent is a daemon that stores passphrases in memory 7.306 +(so it will forget passphrases if you log out and log back in again). 7.307 +An ssh client will notice if it's running, and query it for a 7.308 +passphrase. If there's no authentication agent running, or the agent 7.309 +doesn't store the necessary passphrase, you'll have to type your 7.310 +passphrase every time Mercurial tries to communicate with a server on 7.311 +your behalf (e.g.~whenever you pull or push changes). 7.312 + 7.313 +The downside of storing passphrases in an agent is that it's possible 7.314 +for a well-prepared attacker to recover the plain text of your 7.315 +passphrases, in some cases even if your system has been power-cycled. 7.316 +You should make your own judgment as to whether this is an acceptable 7.317 +risk. It certainly saves a lot of repeated typing. 7.318 + 7.319 +On Unix-like systems, the agent is called \command{ssh-agent}, and 7.320 +it's often run automatically for you when you log in. You'll need to 7.321 +use the \command{ssh-add} command to add passphrases to the agent's 7.322 +store. On Windows, if you're using PuTTY, the \command{pageant} 7.323 +command acts as the agent. It adds an icon to your system tray that 7.324 +will let you manage stored passphrases. 7.325 + 7.326 +\subsubsection{Configuring the server side properly} 7.327 + 7.328 +Because ssh can be fiddly to set up if you're new to it, there's a 7.329 +variety of things that can go wrong. Add Mercurial on top, and 7.330 +there's plenty more scope for head-scratching. Most of these 7.331 +potential problems occur on the server side, not the client side. The 7.332 +good news is that once you've gotten a configuration working, it will 7.333 +usually continue to work indefinitely. 7.334 + 7.335 +Before you try using Mercurial to talk to an ssh server, it's best to 7.336 +make sure that you can use the normal \command{ssh} or \command{putty} 7.337 +command to talk to the server first. If you run into problems with 7.338 +using these commands directly, Mercurial surely won't work. Worse, it 7.339 +will obscure the underlying problem. Any time you want to debug 7.340 +ssh-related Mercurial problems, you should drop back to making sure 7.341 +that plain ssh client commands work first, \emph{before} you worry 7.342 +about whether there's a problem with Mercurial. 7.343 + 7.344 +The first thing to be sure of on the server side is that you can 7.345 +actually log in from another machine at all. If you can't use 7.346 +\command{ssh} or \command{putty} to log in, the error message you get 7.347 +may give you a few hints as to what's wrong. The most common problems 7.348 +are as follows. 7.349 +\begin{itemize} 7.350 +\item If you get a ``connection refused'' error, either there isn't an 7.351 + SSH daemon running on the server at all, or it's inaccessible due to 7.352 + firewall configuration. 7.353 +\item If you get a ``no route to host'' error, you either have an 7.354 + incorrect address for the server or a seriously locked down firewall 7.355 + that won't admit its existence at all. 7.356 +\item If you get a ``permission denied'' error, you may have mistyped 7.357 + the username on the server, or you could have mistyped your key's 7.358 + passphrase or the remote user's password. 7.359 +\end{itemize} 7.360 +In summary, if you're having trouble talking to the server's ssh 7.361 +daemon, first make sure that one is running at all. On many systems 7.362 +it will be installed, but disabled, by default. Once you're done with 7.363 +this step, you should then check that the server's firewall is 7.364 +configured to allow incoming connections on the port the ssh daemon is 7.365 +listening on (usually~22). Don't worry about more exotic 7.366 +possibilities for misconfiguration until you've checked these two 7.367 +first. 7.368 + 7.369 +If you're using an authentication agent on the client side to store 7.370 +passphrases for your keys, you ought to be able to log into the server 7.371 +without being prompted for a passphrase or a password. If you're 7.372 +prompted for a passphrase, there are a few possible culprits. 7.373 +\begin{itemize} 7.374 +\item You might have forgotten to use \command{ssh-add} or 7.375 + \command{pageant} to store the passphrase. 7.376 +\item You might have stored the passphrase for the wrong key. 7.377 +\end{itemize} 7.378 +If you're being prompted for the remote user's password, there are 7.379 +another few possible problems to check. 7.380 +\begin{itemize} 7.381 +\item Either the user's home directory or their \sdirname{.ssh} 7.382 + directory might have excessively liberal permissions. As a result, 7.383 + the ssh daemon will not trust or read their 7.384 + \sfilename{authorized\_keys} file. For example, a group-writable 7.385 + home or \sdirname{.ssh} directory will often cause this symptom. 7.386 +\item The user's \sfilename{authorized\_keys} file may have a problem. 7.387 + If anyone other than the user owns or can write to that file, the 7.388 + ssh daemon will not trust or read it. 7.389 +\end{itemize} 7.390 + 7.391 +In the ideal world, you should be able to run the following command 7.392 +successfully, and it should print exactly one line of output, the 7.393 +current date and time. 7.394 +\begin{codesample2} 7.395 + ssh myserver date 7.396 +\end{codesample2} 7.397 + 7.398 +If on your server you have login scripts that print banners or other 7.399 +junk even when running non-interactive commands like this, you should 7.400 +fix them before you continue, so that they only print output if 7.401 +they're run interactively. Otherwise these banners will at least 7.402 +clutter up Mercurial's output. Worse, they could potentially cause 7.403 +problems with running Mercurial commands remotely. (The usual way to 7.404 +see if a login script is running in an interactive shell is to check 7.405 +the return code from the command \Verb|tty -s|.) 7.406 + 7.407 +Once you've verified that plain old ssh is working with your server, 7.408 +the next step is to ensure that Mercurial runs on the server. The 7.409 +following command should run successfully: 7.410 +\begin{codesample2} 7.411 + ssh myserver hg version 7.412 +\end{codesample2} 7.413 +If you see an error message instead of normal \hgcmd{version} output, 7.414 +this is usually because you haven't installed Mercurial to 7.415 +\dirname{/usr/bin}. Don't worry if this is the case; you don't need 7.416 +to do that. But you should check for a few possible problems. 7.417 +\begin{itemize} 7.418 +\item Is Mercurial really installed on the server at all? I know this 7.419 + sounds trivial, but it's worth checking! 7.420 +\item Maybe your shell's search path (usually set via the \envar{PATH} 7.421 + environment variable) is simply misconfigured. 7.422 +\item Perhaps your \envar{PATH} environment variable is only being set 7.423 + to point to the location of the \command{hg} executable if the login 7.424 + session is interactive. This can happen if you're setting the path 7.425 + in the wrong shell login script. See your shell's documentation for 7.426 + details. 7.427 +\item The \envar{PYTHONPATH} environment variable may need to contain 7.428 + the path to the Mercurial Python modules. It might not be set at 7.429 + all; it could be incorrect; or it may be set only if the login is 7.430 + interactive. 7.431 +\end{itemize} 7.432 + 7.433 +If you can run \hgcmd{version} over an ssh connection, well done! 7.434 +You've got the server and client sorted out. You should now be able 7.435 +to use Mercurial to access repositories hosted by that username on 7.436 +that server. If you run into problems with Mercurial and ssh at this 7.437 +point, try using the \hggopt{--debug} option to get a clearer picture 7.438 +of what's going on. 7.439 + 7.440 +\subsubsection{Using compression with ssh} 7.441 + 7.442 +Mercurial does not compress data when it uses the ssh protocol, 7.443 +because the ssh protocol can transparently compress data. However, 7.444 +the default behaviour of ssh clients is \emph{not} to request 7.445 +compression. 7.446 + 7.447 +Over any network other than a fast LAN (even a wireless network), 7.448 +using compression is likely to significantly speed up Mercurial's 7.449 +network operations. For example, over a WAN, someone measured 7.450 +compression as reducing the amount of time required to clone a 7.451 +particularly large repository from~51 minutes to~17 minutes. 7.452 + 7.453 +Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C} 7.454 +option which turns on compression. You can easily edit your \hgrc\ to 7.455 +enable compression for all of Mercurial's uses of the ssh protocol. 7.456 +\begin{codesample2} 7.457 + [ui] 7.458 + ssh = ssh -C 7.459 +\end{codesample2} 7.460 + 7.461 +\subsection{Serving over HTTP with a CGI script} 7.462 \label{sec:collab:cgi} 7.463 7.464
8.1 --- a/en/daily.tex Mon Apr 16 14:22:25 2007 -0700 8.2 +++ b/en/daily.tex Mon Apr 16 14:23:11 2007 -0700 8.3 @@ -41,7 +41,7 @@ 8.4 8.5 What's going on is that in the former case, we explicitly named the 8.6 file to add on the command line, so the assumption that Mercurial 8.7 -makes in such cases is that we know what you were doing, and it 8.8 +makes in such cases is that you know what you were doing, and it 8.9 doesn't print any output. 8.10 8.11 However, when we \emph{imply} the names of files by giving the name of 8.12 @@ -247,9 +247,11 @@ 8.13 8.14 When you use the \hgcmd{copy} command, Mercurial makes a copy of each 8.15 source file as it currently stands in the working directory. This 8.16 -means that if you make some modifications to a file, then copy it 8.17 -without first having committed those changes, the new copy will 8.18 -contain your modifications. 8.19 +means that if you make some modifications to a file, then \hgcmd{copy} 8.20 +it without first having committed those changes, the new copy will 8.21 +also contain the modifications you have made up until that point. (I 8.22 +find this behaviour a little counterintuitive, which is why I mention 8.23 +it here.) 8.24 8.25 The \hgcmd{copy} command acts similarly to the Unix \command{cp} 8.26 command (you can use the \hgcmd{cp} alias if you prefer). The last 8.27 @@ -366,6 +368,27 @@ 8.28 directory with the same name. This is documented as~\bug{29}. 8.29 \interaction{issue29.go} 8.30 8.31 +\section{Recovering from mistakes} 8.32 + 8.33 +Mercurial has some useful commands that will help you to recover from 8.34 +some common mistakes. 8.35 + 8.36 +The \hgcmd{revert} command lets you undo changes that you have made to 8.37 +your working directory. For example, if you \hgcmd{add} a file by 8.38 +accident, just run \hgcmd{revert} with the name of the file you added, 8.39 +and while the file won't be touched in any way, it won't be tracked 8.40 +for adding by Mercurial any longer, either. You can also use 8.41 +\hgcmd{revert} to get rid of erroneous changes to a file. 8.42 + 8.43 +It's useful to remember that the \hgcmd{revert} command is useful for 8.44 +changes that you have not yet committed. Once you've committed a 8.45 +change, if you decide it was a mistake, you can still do something 8.46 +about it, though your options may be more limited. 8.47 + 8.48 +For more information about the \hgcmd{revert} command, and details 8.49 +about how to deal with changes you have already committed, see 8.50 +chapter~\ref{chap:undo}. 8.51 + 8.52 %%% Local Variables: 8.53 %%% mode: latex 8.54 %%% TeX-master: "00book"
9.1 --- a/en/examples/backout Mon Apr 16 14:22:25 2007 -0700 9.2 +++ b/en/examples/backout Mon Apr 16 14:23:11 2007 -0700 9.3 @@ -6,7 +6,7 @@ 9.4 export HGMERGE=$(mktemp) 9.5 echo '#!/bin/sh' >> $HGMERGE 9.6 echo 'echo first change > "$1"' >> $HGMERGE 9.7 -echo 'echo third change > "$1"' >> $HGMERGE 9.8 +echo 'echo third change >> "$1"' >> $HGMERGE 9.9 chmod 700 $HGMERGE 9.10 9.11 #$ name: init
10.1 --- a/en/examples/backout.manual.merge.out Mon Apr 16 14:22:25 2007 -0700 10.2 +++ b/en/examples/backout.manual.merge.out Mon Apr 16 14:23:11 2007 -0700 10.3 @@ -4,4 +4,5 @@ 10.4 (branch merge, don't forget to commit) 10.5 $ \textbf{hg commit -m 'merged backout with previous tip'} 10.6 $ \textbf{cat myfile} 10.7 +first change 10.8 third change
11.1 --- a/en/examples/backout.non-tip.cat.out Mon Apr 16 14:22:25 2007 -0700 11.2 +++ b/en/examples/backout.non-tip.cat.out Mon Apr 16 14:23:11 2007 -0700 11.3 @@ -1,2 +1,3 @@ 11.4 $ \textbf{cat myfile} 11.5 +first change 11.6 third change
12.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 12.2 +++ b/en/examples/branching Mon Apr 16 14:23:11 2007 -0700 12.3 @@ -0,0 +1,62 @@ 12.4 +#!/bin/bash 12.5 + 12.6 +#$ name: init 12.7 + 12.8 +hg init main 12.9 +cd main 12.10 +echo 'This is a boring feature.' > myfile 12.11 +hg commit -A -m 'We have reached an important milestone!' 12.12 + 12.13 +#$ name: tag 12.14 + 12.15 +hg tag v1.0 12.16 +hg tip 12.17 +hg tags 12.18 + 12.19 +#$ name: main 12.20 + 12.21 +cd ../main 12.22 +echo 'This is exciting and new!' >> myfile 12.23 +hg commit -m 'Add a new feature' 12.24 +cat myfile 12.25 + 12.26 +#$ name: update 12.27 + 12.28 +cd .. 12.29 +hg clone -U main main-old 12.30 +cd main-old 12.31 +hg update v1.0 12.32 +cat myfile 12.33 + 12.34 +#$ name: clone 12.35 + 12.36 +cd .. 12.37 +hg clone -rv1.0 main stable 12.38 + 12.39 +#$ name: stable 12.40 + 12.41 +hg clone stable stable-fix 12.42 +cd stable-fix 12.43 +echo 'This is a fix to a boring feature.' > myfile 12.44 +hg commit -m 'Fix a bug' 12.45 +hg push 12.46 + 12.47 +#$ name: 12.48 + 12.49 +export HGMERGE=$(mktemp) 12.50 +echo '#!/bin/sh' > $HGMERGE 12.51 +echo 'echo "This is a fix to a boring feature." > "$1"' >> $HGMERGE 12.52 +echo 'echo "This is exciting and new!" >> "$1"' >> $HGMERGE 12.53 +chmod 700 $HGMERGE 12.54 + 12.55 +#$ name: merge 12.56 + 12.57 +cd ../main 12.58 +hg pull ../stable 12.59 +hg merge 12.60 +hg commit -m 'Bring in bugfix from stable branch' 12.61 +cat myfile 12.62 + 12.63 +#$ name: 12.64 + 12.65 +rm $HGMERGE
13.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 13.2 +++ b/en/examples/branching.clone.out Mon Apr 16 14:23:11 2007 -0700 13.3 @@ -0,0 +1,8 @@ 13.4 +$ \textbf{cd ..} 13.5 +$ \textbf{hg clone -rv1.0 main stable} 13.6 +requesting all changes 13.7 +adding changesets 13.8 +adding manifests 13.9 +adding file changes 13.10 +added 1 changesets with 1 changes to 1 files 13.11 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved
14.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 14.2 +++ b/en/examples/branching.init.out Mon Apr 16 14:23:11 2007 -0700 14.3 @@ -0,0 +1,5 @@ 14.4 +$ \textbf{hg init main} 14.5 +$ \textbf{cd main} 14.6 +$ \textbf{echo 'This is a boring feature.' > myfile} 14.7 +$ \textbf{hg commit -A -m 'We have reached an important milestone!'} 14.8 +adding myfile
15.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 15.2 +++ b/en/examples/branching.main.out Mon Apr 16 14:23:11 2007 -0700 15.3 @@ -0,0 +1,6 @@ 15.4 +$ \textbf{cd ../main} 15.5 +$ \textbf{echo 'This is exciting and new!' >> myfile} 15.6 +$ \textbf{hg commit -m 'Add a new feature'} 15.7 +$ \textbf{cat myfile} 15.8 +This is a boring feature. 15.9 +This is exciting and new!
16.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 16.2 +++ b/en/examples/branching.merge.out Mon Apr 16 14:23:11 2007 -0700 16.3 @@ -0,0 +1,17 @@ 16.4 +$ \textbf{cd ../main} 16.5 +$ \textbf{hg pull ../stable} 16.6 +pulling from ../stable 16.7 +searching for changes 16.8 +adding changesets 16.9 +adding manifests 16.10 +adding file changes 16.11 +added 1 changesets with 1 changes to 1 files (+1 heads) 16.12 +(run 'hg heads' to see heads, 'hg merge' to merge) 16.13 +$ \textbf{hg merge} 16.14 +merging myfile 16.15 +0 files updated, 1 files merged, 0 files removed, 0 files unresolved 16.16 +(branch merge, don't forget to commit) 16.17 +$ \textbf{hg commit -m 'Bring in bugfix from stable branch'} 16.18 +$ \textbf{cat myfile} 16.19 +This is a fix to a boring feature. 16.20 +This is exciting and new!
17.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 17.2 +++ b/en/examples/branching.stable.out Mon Apr 16 14:23:11 2007 -0700 17.3 @@ -0,0 +1,12 @@ 17.4 +$ \textbf{hg clone stable stable-fix} 17.5 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved 17.6 +$ \textbf{cd stable-fix} 17.7 +$ \textbf{echo 'This is a fix to a boring feature.' > myfile} 17.8 +$ \textbf{hg commit -m 'Fix a bug'} 17.9 +$ \textbf{hg push} 17.10 +pushing to /tmp/branchingfJgZac/stable 17.11 +searching for changes 17.12 +adding changesets 17.13 +adding manifests 17.14 +adding file changes 17.15 +added 1 changesets with 1 changes to 1 files
18.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 18.2 +++ b/en/examples/branching.tag.out Mon Apr 16 14:23:11 2007 -0700 18.3 @@ -0,0 +1,11 @@ 18.4 +$ \textbf{hg tag v1.0} 18.5 +$ \textbf{hg tip} 18.6 +changeset: 18.7 +tag: tip 18.8 +user: Bryan O'Sullivan <bos@serpentine.com> 18.9 + 18.10 +summary: Added tag v1.0 for changeset 18.11 + 18.12 +$ \textbf{hg tags} 18.13 +tip 18.14 +v1.0
19.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 19.2 +++ b/en/examples/branching.update.out Mon Apr 16 14:23:11 2007 -0700 19.3 @@ -0,0 +1,7 @@ 19.4 +$ \textbf{cd ..} 19.5 +$ \textbf{hg clone -U main main-old} 19.6 +$ \textbf{cd main-old} 19.7 +$ \textbf{hg update v1.0} 19.8 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved 19.9 +$ \textbf{cat myfile} 19.10 +This is a boring feature.
20.1 --- a/en/examples/daily.copy Mon Apr 16 14:22:25 2007 -0700 20.2 +++ b/en/examples/daily.copy Mon Apr 16 14:23:11 2007 -0700 20.3 @@ -58,7 +58,9 @@ 20.4 20.5 #$ name: simple 20.6 20.7 -hg copy a c 20.8 +mkdir k 20.9 +hg copy a k 20.10 +ls k 20.11 20.12 #$ name: dir-dest 20.13
21.1 --- a/en/examples/daily.copy.simple.out Mon Apr 16 14:22:25 2007 -0700 21.2 +++ b/en/examples/daily.copy.simple.out Mon Apr 16 14:23:11 2007 -0700 21.3 @@ -1,2 +1,4 @@ 21.4 -$ \textbf{hg copy a c} 21.5 -c/a: not overwriting - file exists 21.6 +$ \textbf{mkdir k} 21.7 +$ \textbf{hg copy a k} 21.8 +$ \textbf{ls k} 21.9 +a
22.1 --- a/en/examples/hook.ws Mon Apr 16 14:22:25 2007 -0700 22.2 +++ b/en/examples/hook.ws Mon Apr 16 14:23:11 2007 -0700 22.3 @@ -3,7 +3,7 @@ 22.4 hg init a 22.5 cd a 22.6 echo '[hooks]' > .hg/hgrc 22.7 -echo "pretxncommit.whitespace = hg export tip | (! grep -qP '^\\+.*[ \\t]$')" >> .hg/hgrc 22.8 +echo "pretxncommit.whitespace = hg export tip | (! egrep -q '^\\+.*[ \\t]$')" >> .hg/hgrc 22.9 22.10 #$ name: simple 22.11 22.12 @@ -24,7 +24,7 @@ 22.13 cat .hg/hgrc 22.14 echo 'a ' >> a 22.15 hg commit -A -m 'add new line with trailing whitespace' 22.16 -perl -pi -e 's,\s+$,,' a 22.17 +sed -i 's, *$,,' a 22.18 hg commit -A -m 'trimmed trailing whitespace' 22.19 22.20 #$ name:
23.1 --- a/en/examples/hook.ws.better.out Mon Apr 16 14:22:25 2007 -0700 23.2 +++ b/en/examples/hook.ws.better.out Mon Apr 16 14:23:11 2007 -0700 23.3 @@ -8,9 +8,9 @@ 23.4 abort: pretxncommit.whitespace hook exited with status 1 23.5 transaction abort! 23.6 rollback completed 23.7 -$ \textbf{perl -pi -e 's,\textbackslash{}s+$,,' a} 23.8 +$ \textbf{sed -i 's, *$,,' a} 23.9 $ \textbf{hg commit -A -m 'trimmed trailing whitespace'} 23.10 -a, line 1: trailing whitespace added 23.11 +a, line 2: trailing whitespace added 23.12 commit message saved to .hg/commit.save 23.13 abort: pretxncommit.whitespace hook exited with status 1 23.14 transaction abort!
24.1 --- a/en/examples/hook.ws.simple.out Mon Apr 16 14:22:25 2007 -0700 24.2 +++ b/en/examples/hook.ws.simple.out Mon Apr 16 14:23:11 2007 -0700 24.3 @@ -1,6 +1,6 @@ 24.4 $ \textbf{cat .hg/hgrc} 24.5 [hooks] 24.6 -pretxncommit.whitespace = hg export tip | (! grep -qP '^\textbackslash{}+.*[ \textbackslash{}t]$') 24.7 +pretxncommit.whitespace = hg export tip | (! egrep -q '^\textbackslash{}+.*[ \textbackslash{}t]$') 24.8 $ \textbf{echo 'a ' > a} 24.9 $ \textbf{hg commit -A -m 'test with trailing whitespace'} 24.10 adding a
25.1 --- a/en/examples/mq.tarball Mon Apr 16 14:22:25 2007 -0700 25.2 +++ b/en/examples/mq.tarball Mon Apr 16 14:23:11 2007 -0700 25.3 @@ -2,6 +2,7 @@ 25.4 25.5 cp $EXAMPLE_DIR/data/netplug-*.tar.bz2 . 25.6 ln -s /bin/true download 25.7 +export PATH=`pwd`:$PATH 25.8 25.9 #$ name: download 25.10
26.1 --- a/en/examples/mq.tutorial.qnew2.out Mon Apr 16 14:22:25 2007 -0700 26.2 +++ b/en/examples/mq.tutorial.qnew2.out Mon Apr 16 14:23:11 2007 -0700 26.3 @@ -1,6 +1,6 @@ 26.4 $ \textbf{hg qnew second.patch} 26.5 $ \textbf{hg log --style=compact --limit=2} 26.6 -2[second.patch,qtip,tip] 26.7 +2[qtip,second.patch,tip] 26.8 New patch: second.patch 26.9 26.10 1[first.patch,qbase] 26.11 @@ -9,7 +9,7 @@ 26.12 $ \textbf{echo 'line 4' >> file1} 26.13 $ \textbf{hg qrefresh} 26.14 $ \textbf{hg tip --style=compact --patch} 26.15 -2[second.patch,qtip,tip] 26.16 +2[qtip,second.patch,tip] 26.17 patch queue: second.patch 26.18 26.19 diff -r -r file1
27.1 --- a/en/examples/run-example Mon Apr 16 14:22:25 2007 -0700 27.2 +++ b/en/examples/run-example Mon Apr 16 14:23:11 2007 -0700 27.3 @@ -46,6 +46,13 @@ 27.4 raise 27.5 return False 27.6 27.7 +def find_path_to(program): 27.8 + for p in os.environ.get('PATH', os.defpath).split(os.pathsep): 27.9 + name = os.path.join(p, program) 27.10 + if os.access(name, os.X_OK): 27.11 + return p 27.12 + return None 27.13 + 27.14 class example: 27.15 shell = '/usr/bin/env bash' 27.16 ps1 = '__run_example_ps1__ ' 27.17 @@ -92,21 +99,22 @@ 27.18 27.19 timeout = 5 27.20 27.21 - def read(self): 27.22 + def read(self, hint): 27.23 events = self.poll.poll(self.timeout * 1000) 27.24 if not events: 27.25 - print >> sys.stderr, '[timed out after %d seconds]' % self.timeout 27.26 + print >> sys.stderr, ('[%stimed out after %d seconds]' % 27.27 + (hint, self.timeout)) 27.28 os.kill(self.pid, signal.SIGHUP) 27.29 return '' 27.30 return os.read(self.cfd, 1024) 27.31 27.32 - def receive(self): 27.33 + def receive(self, hint): 27.34 out = cStringIO.StringIO() 27.35 while True: 27.36 try: 27.37 if self.verbose: 27.38 sys.stderr.write('< ') 27.39 - s = self.read() 27.40 + s = self.read(hint) 27.41 except OSError, err: 27.42 if err.errno == errno.EIO: 27.43 return '', '' 27.44 @@ -120,9 +128,9 @@ 27.45 if s.endswith(self.ps2): 27.46 return self.ps2, s.replace('\r\n', '\n')[:-len(self.ps2)] 27.47 27.48 - def sendreceive(self, s): 27.49 + def sendreceive(self, s, hint): 27.50 self.send(s) 27.51 - ps, r = self.receive() 27.52 + ps, r = self.receive(hint) 27.53 if r.startswith(s): 27.54 r = r[len(s):] 27.55 return ps, r 27.56 @@ -147,6 +155,16 @@ 27.57 print >> rcfp, 'PS1="%s"' % self.ps1 27.58 print >> rcfp, 'PS2="%s"' % self.ps2 27.59 print >> rcfp, 'unset HISTFILE' 27.60 + path = ['/usr/bin', '/bin'] 27.61 + hg = find_path_to('hg') 27.62 + if hg and hg not in path: 27.63 + path.append(hg) 27.64 + def re_export(envar): 27.65 + v = os.getenv(envar) 27.66 + if v is not None: 27.67 + print >> rcfp, 'export ' + envar + '=' + v 27.68 + print >> rcfp, 'export PATH=' + ':'.join(path) 27.69 + re_export('PYTHONPATH') 27.70 print >> rcfp, 'export EXAMPLE_DIR="%s"' % os.getcwd() 27.71 print >> rcfp, 'export HGMERGE=merge' 27.72 print >> rcfp, 'export LANG=C' 27.73 @@ -160,8 +178,8 @@ 27.74 sys.stderr.flush() 27.75 self.pid, self.cfd = pty.fork() 27.76 if self.pid == 0: 27.77 - cmdline = ['/usr/bin/env', 'bash', '--noediting', '--noprofile', 27.78 - '--norc'] 27.79 + cmdline = ['/usr/bin/env', '-i', 'bash', '--noediting', 27.80 + '--noprofile', '--norc'] 27.81 try: 27.82 os.execv(cmdline[0], cmdline) 27.83 except OSError, err: 27.84 @@ -188,13 +206,15 @@ 27.85 ] 27.86 27.87 err = False 27.88 + read_hint = '' 27.89 27.90 try: 27.91 try: 27.92 # eat first prompt string from shell 27.93 - self.read() 27.94 + self.read(read_hint) 27.95 # setup env and prompt 27.96 - ps, output = self.sendreceive('source %s\n' % rcfile) 27.97 + ps, output = self.sendreceive('source %s\n' % rcfile, 27.98 + read_hint) 27.99 for hunk in self.parse(): 27.100 # is this line a processing instruction? 27.101 m = self.pi_re.match(hunk) 27.102 @@ -214,6 +234,7 @@ 27.103 err |= self.rename_output(ofp_basename, ignore) 27.104 if out: 27.105 ofp_basename = '%s.%s' % (self.name, out) 27.106 + read_hint = ofp_basename + ' ' 27.107 ofp = open(ofp_basename + '.tmp', 'w') 27.108 else: 27.109 ofp = None 27.110 @@ -221,7 +242,7 @@ 27.111 ignore.append(rest) 27.112 elif hunk.strip(): 27.113 # it's something we should execute 27.114 - newps, output = self.sendreceive(hunk) 27.115 + newps, output = self.sendreceive(hunk, read_hint) 27.116 if not ofp: 27.117 continue 27.118 # first, print the command we ran 27.119 @@ -243,7 +264,7 @@ 27.120 raise 27.121 else: 27.122 try: 27.123 - ps, output = self.sendreceive('exit\n') 27.124 + ps, output = self.sendreceive('exit\n', read_hint) 27.125 if ofp is not None: 27.126 ofp.write(output) 27.127 ofp.close() 27.128 @@ -324,7 +345,9 @@ 27.129 print >> sys.stderr, '%s: not a file, or not executable' % a 27.130 errs += 1 27.131 return errs 27.132 - for name in os.listdir(path): 27.133 + names = os.listdir(path) 27.134 + names.sort() 27.135 + for name in names: 27.136 if name == 'run-example' or name.startswith('.'): continue 27.137 if name.endswith('.out') or name.endswith('~'): continue 27.138 if name.endswith('.run'): continue
28.1 --- a/en/examples/tour Mon Apr 16 14:22:25 2007 -0700 28.2 +++ b/en/examples/tour Mon Apr 16 14:23:11 2007 -0700 28.3 @@ -14,6 +14,7 @@ 28.4 28.5 #$ name: ls 28.6 #$ ignore: ^drwx.* 28.7 +#$ ignore: ^total \d+ 28.8 28.9 ls -l 28.10 ls hello 28.11 @@ -67,16 +68,6 @@ 28.12 #$ name: 28.13 28.14 export HGEDITOR='echo Added an extra line of output >' 28.15 -HGRCPATH_ORIG=$HGRCPATH 28.16 -export HGRCPATH= 28.17 - 28.18 -#$ name: commit-no-user 28.19 - 28.20 -hg commit 28.21 - 28.22 -#$ name: 28.23 - 28.24 -export HGRCPATH=$HGRCPATH_ORIG 28.25 28.26 #$ name: commit 28.27
29.1 --- a/en/examples/tour.commit-no-user.out Mon Apr 16 14:22:25 2007 -0700 29.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 29.3 @@ -1,1 +0,0 @@ 29.4 -$ \textbf{hg commit}
30.1 --- a/en/examples/tour.commit.out Mon Apr 16 14:22:25 2007 -0700 30.2 +++ b/en/examples/tour.commit.out Mon Apr 16 14:23:11 2007 -0700 30.3 @@ -1,2 +1,1 @@ 30.4 $ \textbf{hg commit} 30.5 -nothing changed
31.1 --- a/en/examples/tour.incoming.out Mon Apr 16 14:22:25 2007 -0700 31.2 +++ b/en/examples/tour.incoming.out Mon Apr 16 14:23:11 2007 -0700 31.3 @@ -1,5 +1,6 @@ 31.4 $ \textbf{cd hello-pull} 31.5 $ \textbf{hg incoming ../my-hello} 31.6 +comparing with ../my-hello 31.7 searching for changes 31.8 changeset: 31.9 tag: tip
32.1 --- a/en/examples/tour.outgoing.net.out Mon Apr 16 14:22:25 2007 -0700 32.2 +++ b/en/examples/tour.outgoing.net.out Mon Apr 16 14:23:11 2007 -0700 32.3 @@ -1,4 +1,5 @@ 32.4 $ \textbf{hg outgoing http://hg.serpentine.com/tutorial/hello} 32.5 +comparing with http://hg.serpentine.com/tutorial/hello 32.6 searching for changes 32.7 changeset: 32.8 tag: tip
33.1 --- a/en/examples/tour.outgoing.out Mon Apr 16 14:22:25 2007 -0700 33.2 +++ b/en/examples/tour.outgoing.out Mon Apr 16 14:23:11 2007 -0700 33.3 @@ -1,5 +1,6 @@ 33.4 $ \textbf{cd my-hello} 33.5 $ \textbf{hg outgoing ../hello-push} 33.6 +comparing with ../hello-push 33.7 searching for changes 33.8 changeset: 33.9 tag: tip
34.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 34.2 +++ b/en/feature-branches.dot Mon Apr 16 14:23:11 2007 -0700 34.3 @@ -0,0 +1,8 @@ 34.4 +digraph feature_branches { 34.5 + master -> crypto; 34.6 + master -> filesystems; 34.7 + master -> ipc; 34.8 + master -> memory; 34.9 + master -> network; 34.10 + master -> security; 34.11 +}
35.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 35.2 +++ b/en/htlatex.book Mon Apr 16 14:23:11 2007 -0700 35.3 @@ -0,0 +1,12 @@ 35.4 +#!/bin/bash 35.5 +# 35.6 +# This script is horrible. It's essentially a hacked copy of 35.7 +# /usr/bin/htlatex from Fedora Core 6. I apologise for any lasting 35.8 +# pain reading it causes. 35.9 + 35.10 +latex $5 '\makeatletter\def\HCode{\futurelet\HCode\HChar}\def\HChar{\ifx"\HCode\def\HCode"##1"{\Link##1}\expandafter\HCode\else\expandafter\Link\fi}\def\Link#1.a.b.c.{\g@addto@macro\@documentclasshook{\RequirePackage[#1,html]{tex4ht}}\let\HCode\documentstyle\def\documentstyle{\let\documentstyle\HCode\expandafter\def\csname tex4ht\endcsname{#1,html}\def\HCode####1{\documentstyle[tex4ht,}\@ifnextchar[{\HCode}{\documentstyle[tex4ht]}}}\makeatother\HCode '$2'.a.b.c.\input ' $1 35.11 +(cd $4 && bibtex hgbook) 35.12 +(cd $4 && makeindex hgbook) 35.13 +latex $5 '\makeatletter\def\HCode{\futurelet\HCode\HChar}\def\HChar{\ifx"\HCode\def\HCode"##1"{\Link##1}\expandafter\HCode\else\expandafter\Link\fi}\def\Link#1.a.b.c.{\g@addto@macro\@documentclasshook{\RequirePackage[#1,html]{tex4ht}}\let\HCode\documentstyle\def\documentstyle{\let\documentstyle\HCode\expandafter\def\csname tex4ht\endcsname{#1,html}\def\HCode####1{\documentstyle[tex4ht,}\@ifnextchar[{\HCode}{\documentstyle[tex4ht]}}}\makeatother\HCode '$2'.a.b.c.\input ' $1 35.14 +latex $5 '\makeatletter\def\HCode{\futurelet\HCode\HChar}\def\HChar{\ifx"\HCode\def\HCode"##1"{\Link##1}\expandafter\HCode\else\expandafter\Link\fi}\def\Link#1.a.b.c.{\g@addto@macro\@documentclasshook{\RequirePackage[#1,html]{tex4ht}}\let\HCode\documentstyle\def\documentstyle{\let\documentstyle\HCode\expandafter\def\csname tex4ht\endcsname{#1,html}\def\HCode####1{\documentstyle[tex4ht,}\@ifnextchar[{\HCode}{\documentstyle[tex4ht]}}}\makeatother\HCode '$2'.a.b.c.\input ' $1 35.15 +echo status $$
36.1 --- a/en/tour-basic.tex Mon Apr 16 14:22:25 2007 -0700 36.2 +++ b/en/tour-basic.tex Mon Apr 16 14:23:11 2007 -0700 36.3 @@ -358,21 +358,41 @@ 36.4 36.5 \subsection{Setting up a username} 36.6 36.7 -When you try to run \hgcmd{commit} for the first time, it may succeed 36.8 -immediately, or it may fail with an error message that looks like 36.9 -this. 36.10 -\interaction{tour.commit-no-user} 36.11 -If it succeeds for you, the chances are that either you already have a 36.12 -file called \sfilename{.hgrc} in your home directory, or an 36.13 -environment variable set named \envar{EMAIL}. 36.14 - 36.15 -When you commit, Mercurial wants to know what your name is, so that it 36.16 -can record it. If you have created a \sfilename{.hgrc} file, it will 36.17 -look in there. If it doesn't find something suitable, it will see if 36.18 -your \envar{EMAIL} address is set. If neither of these is present, it 36.19 -will produce the error message you can see above. 36.20 +When you try to run \hgcmd{commit} for the first time, it is not 36.21 +guaranteed to succeed. Mercurial records your name and address with 36.22 +each change that you commit, so that you and others will later be able 36.23 +to tell who made each change. Mercurial tries to automatically figure 36.24 +out a sensible username to commit the change with. It will attempt 36.25 +each of the following methods, in order: 36.26 +\begin{enumerate} 36.27 +\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit} 36.28 + command on the command line, followed by a username, this is always 36.29 + given the highest precedence. 36.30 +\item If you have set the \envar{HGUSER} environment variable, this is 36.31 + checked next. 36.32 +\item If you create a file in your home directory called 36.33 + \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be 36.34 + used next. To see what the contents of this file should look like, 36.35 + refer to section~\ref{sec:tour-basic:username} below. 36.36 +\item If you have set the \envar{EMAIL} environment variable, this 36.37 + will be used next. 36.38 +\item Mercurial will query your system to find out your local user 36.39 + name and host name, and construct a username from these components. 36.40 + Since this often results in a username that is not very useful, it 36.41 + will print a warning if it has to do this. 36.42 +\end{enumerate} 36.43 +If all of these mechanisms fail, Mercurial will fail, printing an 36.44 +error message. In this case, it will not let you commit until you set 36.45 +up a username. 36.46 + 36.47 +You should think of the \envar{HGUSER} environment variable and the 36.48 +\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to 36.49 +\emph{override} Mercurial's default selection of username. For normal 36.50 +use, the simplest and most robust way to set a username for yourself 36.51 +is by creating a \sfilename{.hgrc} file; see below for details. 36.52 36.53 \subsubsection{Creating a Mercurial configuration file} 36.54 +\label{sec:tour-basic:username} 36.55 36.56 To set a user name, use your favourite editor to create a file called 36.57 \sfilename{.hgrc} in your home directory. Mercurial will use this