hgbook
changeset 402:b05e35d641e4
Copying the files from en to es and taking intro chapter
author | Igor TAmara <igor@tamarapatino.org> |
---|---|
date | Fri Nov 07 21:42:57 2008 -0500 (2008-11-07) |
parents | 3e78daaad99b |
children | 4cdeb830118b |
files | es/Leame.1st es/cmdref.tex es/collab.tex es/filenames.tex es/intro.tex es/srcinstall.tex es/template.tex |
line diff
1.1 --- a/es/Leame.1st Fri Nov 07 21:33:22 2008 -0500 1.2 +++ b/es/Leame.1st Fri Nov 07 21:42:57 2008 -0500 1.3 @@ -102,6 +102,7 @@ 1.4 || undo.tex || Igor Támara || 100% || 26/10/2008 || 07/11/2008 || 1.5 || tour-merge.tex || Javier Rojas || 100% || 28/10/2008 || 03/11/2008 || 1.6 || concepts.tex || Javier Rojas || 7% || 03/11/2008 || || 1.7 +|| intro.tex || Igor Támara || 0% || 08/11/2008 || || 1.8 1.9 == Archivos en proceso de revisión == 1.10 ||'''archivo''' || '''revisor''' ||'''Estado'''||'''Inicio'''|| '''Fin''' ||
2.1 --- a/es/cmdref.tex Fri Nov 07 21:33:22 2008 -0500 2.2 +++ b/es/cmdref.tex Fri Nov 07 21:42:57 2008 -0500 2.3 @@ -0,0 +1,176 @@ 2.4 +\chapter{Command reference} 2.5 +\label{cmdref} 2.6 + 2.7 +\cmdref{add}{add files at the next commit} 2.8 +\optref{add}{I}{include} 2.9 +\optref{add}{X}{exclude} 2.10 +\optref{add}{n}{dry-run} 2.11 + 2.12 +\cmdref{diff}{print changes in history or working directory} 2.13 + 2.14 +Show differences between revisions for the specified files or 2.15 +directories, using the unified diff format. For a description of the 2.16 +unified diff format, see section~\ref{sec:mq:patch}. 2.17 + 2.18 +By default, this command does not print diffs for files that Mercurial 2.19 +considers to contain binary data. To control this behaviour, see the 2.20 +\hgopt{diff}{-a} and \hgopt{diff}{--git} options. 2.21 + 2.22 +\subsection{Options} 2.23 + 2.24 +\loptref{diff}{nodates} 2.25 + 2.26 +Omit date and time information when printing diff headers. 2.27 + 2.28 +\optref{diff}{B}{ignore-blank-lines} 2.29 + 2.30 +Do not print changes that only insert or delete blank lines. A line 2.31 +that contains only whitespace is not considered blank. 2.32 + 2.33 +\optref{diff}{I}{include} 2.34 + 2.35 +Include files and directories whose names match the given patterns. 2.36 + 2.37 +\optref{diff}{X}{exclude} 2.38 + 2.39 +Exclude files and directories whose names match the given patterns. 2.40 + 2.41 +\optref{diff}{a}{text} 2.42 + 2.43 +If this option is not specified, \hgcmd{diff} will refuse to print 2.44 +diffs for files that it detects as binary. Specifying \hgopt{diff}{-a} 2.45 +forces \hgcmd{diff} to treat all files as text, and generate diffs for 2.46 +all of them. 2.47 + 2.48 +This option is useful for files that are ``mostly text'' but have a 2.49 +few embedded NUL characters. If you use it on files that contain a 2.50 +lot of binary data, its output will be incomprehensible. 2.51 + 2.52 +\optref{diff}{b}{ignore-space-change} 2.53 + 2.54 +Do not print a line if the only change to that line is in the amount 2.55 +of white space it contains. 2.56 + 2.57 +\optref{diff}{g}{git} 2.58 + 2.59 +Print \command{git}-compatible diffs. XXX reference a format 2.60 +description. 2.61 + 2.62 +\optref{diff}{p}{show-function} 2.63 + 2.64 +Display the name of the enclosing function in a hunk header, using a 2.65 +simple heuristic. This functionality is enabled by default, so the 2.66 +\hgopt{diff}{-p} option has no effect unless you change the value of 2.67 +the \rcitem{diff}{showfunc} config item, as in the following example. 2.68 +\interaction{cmdref.diff-p} 2.69 + 2.70 +\optref{diff}{r}{rev} 2.71 + 2.72 +Specify one or more revisions to compare. The \hgcmd{diff} command 2.73 +accepts up to two \hgopt{diff}{-r} options to specify the revisions to 2.74 +compare. 2.75 + 2.76 +\begin{enumerate} 2.77 +\setcounter{enumi}{0} 2.78 +\item Display the differences between the parent revision of the 2.79 + working directory and the working directory. 2.80 +\item Display the differences between the specified changeset and the 2.81 + working directory. 2.82 +\item Display the differences between the two specified changesets. 2.83 +\end{enumerate} 2.84 + 2.85 +You can specify two revisions using either two \hgopt{diff}{-r} 2.86 +options or revision range notation. For example, the two revision 2.87 +specifications below are equivalent. 2.88 +\begin{codesample2} 2.89 + hg diff -r 10 -r 20 2.90 + hg diff -r10:20 2.91 +\end{codesample2} 2.92 + 2.93 +When you provide two revisions, Mercurial treats the order of those 2.94 +revisions as significant. Thus, \hgcmdargs{diff}{-r10:20} will 2.95 +produce a diff that will transform files from their contents as of 2.96 +revision~10 to their contents as of revision~20, while 2.97 +\hgcmdargs{diff}{-r20:10} means the opposite: the diff that will 2.98 +transform files from their revision~20 contents to their revision~10 2.99 +contents. You cannot reverse the ordering in this way if you are 2.100 +diffing against the working directory. 2.101 + 2.102 +\optref{diff}{w}{ignore-all-space} 2.103 + 2.104 +\cmdref{version}{print version and copyright information} 2.105 + 2.106 +This command displays the version of Mercurial you are running, and 2.107 +its copyright license. There are four kinds of version string that 2.108 +you may see. 2.109 +\begin{itemize} 2.110 +\item The string ``\texttt{unknown}''. This version of Mercurial was 2.111 + not built in a Mercurial repository, and cannot determine its own 2.112 + version. 2.113 +\item A short numeric string, such as ``\texttt{1.1}''. This is a 2.114 + build of a revision of Mercurial that was identified by a specific 2.115 + tag in the repository where it was built. (This doesn't necessarily 2.116 + mean that you're running an official release; someone else could 2.117 + have added that tag to any revision in the repository where they 2.118 + built Mercurial.) 2.119 +\item A hexadecimal string, such as ``\texttt{875489e31abe}''. This 2.120 + is a build of the given revision of Mercurial. 2.121 +\item A hexadecimal string followed by a date, such as 2.122 + ``\texttt{875489e31abe+20070205}''. This is a build of the given 2.123 + revision of Mercurial, where the build repository contained some 2.124 + local changes that had not been committed. 2.125 +\end{itemize} 2.126 + 2.127 +\subsection{Tips and tricks} 2.128 + 2.129 +\subsubsection{Why do the results of \hgcmd{diff} and \hgcmd{status} 2.130 + differ?} 2.131 +\label{cmdref:diff-vs-status} 2.132 + 2.133 +When you run the \hgcmd{status} command, you'll see a list of files 2.134 +that Mercurial will record changes for the next time you perform a 2.135 +commit. If you run the \hgcmd{diff} command, you may notice that it 2.136 +prints diffs for only a \emph{subset} of the files that \hgcmd{status} 2.137 +listed. There are two possible reasons for this. 2.138 + 2.139 +The first is that \hgcmd{status} prints some kinds of modifications 2.140 +that \hgcmd{diff} doesn't normally display. The \hgcmd{diff} command 2.141 +normally outputs unified diffs, which don't have the ability to 2.142 +represent some changes that Mercurial can track. Most notably, 2.143 +traditional diffs can't represent a change in whether or not a file is 2.144 +executable, but Mercurial records this information. 2.145 + 2.146 +If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will 2.147 +display \command{git}-compatible diffs that \emph{can} display this 2.148 +extra information. 2.149 + 2.150 +The second possible reason that \hgcmd{diff} might be printing diffs 2.151 +for a subset of the files displayed by \hgcmd{status} is that if you 2.152 +invoke it without any arguments, \hgcmd{diff} prints diffs against the 2.153 +first parent of the working directory. If you have run \hgcmd{merge} 2.154 +to merge two changesets, but you haven't yet committed the results of 2.155 +the merge, your working directory has two parents (use \hgcmd{parents} 2.156 +to see them). While \hgcmd{status} prints modifications relative to 2.157 +\emph{both} parents after an uncommitted merge, \hgcmd{diff} still 2.158 +operates relative only to the first parent. You can get it to print 2.159 +diffs relative to the second parent by specifying that parent with the 2.160 +\hgopt{diff}{-r} option. There is no way to print diffs relative to 2.161 +both parents. 2.162 + 2.163 +\subsubsection{Generating safe binary diffs} 2.164 + 2.165 +If you use the \hgopt{diff}{-a} option to force Mercurial to print 2.166 +diffs of files that are either ``mostly text'' or contain lots of 2.167 +binary data, those diffs cannot subsequently be applied by either 2.168 +Mercurial's \hgcmd{import} command or the system's \command{patch} 2.169 +command. 2.170 + 2.171 +If you want to generate a diff of a binary file that is safe to use as 2.172 +input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you 2.173 +generate the patch. The system \command{patch} command cannot handle 2.174 +binary patches at all. 2.175 + 2.176 +%%% Local Variables: 2.177 +%%% mode: latex 2.178 +%%% TeX-master: "00book" 2.179 +%%% End:
3.1 --- a/es/collab.tex Fri Nov 07 21:33:22 2008 -0500 3.2 +++ b/es/collab.tex Fri Nov 07 21:42:57 2008 -0500 3.3 @@ -0,0 +1,1118 @@ 3.4 +\chapter{Collaborating with other people} 3.5 +\label{cha:collab} 3.6 + 3.7 +As a completely decentralised tool, Mercurial doesn't impose any 3.8 +policy on how people ought to work with each other. However, if 3.9 +you're new to distributed revision control, it helps to have some 3.10 +tools and examples in mind when you're thinking about possible 3.11 +workflow models. 3.12 + 3.13 +\section{Mercurial's web interface} 3.14 + 3.15 +Mercurial has a powerful web interface that provides several 3.16 +useful capabilities. 3.17 + 3.18 +For interactive use, the web interface lets you browse a single 3.19 +repository or a collection of repositories. You can view the history 3.20 +of a repository, examine each change (comments and diffs), and view 3.21 +the contents of each directory and file. 3.22 + 3.23 +Also for human consumption, the web interface provides an RSS feed of 3.24 +the changes in a repository. This lets you ``subscribe'' to a 3.25 +repository using your favourite feed reader, and be automatically 3.26 +notified of activity in that repository as soon as it happens. I find 3.27 +this capability much more convenient than the model of subscribing to 3.28 +a mailing list to which notifications are sent, as it requires no 3.29 +additional configuration on the part of whoever is serving the 3.30 +repository. 3.31 + 3.32 +The web interface also lets remote users clone a repository, pull 3.33 +changes from it, and (when the server is configured to permit it) push 3.34 +changes back to it. Mercurial's HTTP tunneling protocol aggressively 3.35 +compresses data, so that it works efficiently even over low-bandwidth 3.36 +network connections. 3.37 + 3.38 +The easiest way to get started with the web interface is to use your 3.39 +web browser to visit an existing repository, such as the master 3.40 +Mercurial repository at 3.41 +\url{http://www.selenic.com/repo/hg?style=gitweb}. 3.42 + 3.43 +If you're interested in providing a web interface to your own 3.44 +repositories, Mercurial provides two ways to do this. The first is 3.45 +using the \hgcmd{serve} command, which is best suited to short-term 3.46 +``lightweight'' serving. See section~\ref{sec:collab:serve} below for 3.47 +details of how to use this command. If you have a long-lived 3.48 +repository that you'd like to make permanently available, Mercurial 3.49 +has built-in support for the CGI (Common Gateway Interface) standard, 3.50 +which all common web servers support. See 3.51 +section~\ref{sec:collab:cgi} for details of CGI configuration. 3.52 + 3.53 +\section{Collaboration models} 3.54 + 3.55 +With a suitably flexible tool, making decisions about workflow is much 3.56 +more of a social engineering challenge than a technical one. 3.57 +Mercurial imposes few limitations on how you can structure the flow of 3.58 +work in a project, so it's up to you and your group to set up and live 3.59 +with a model that matches your own particular needs. 3.60 + 3.61 +\subsection{Factors to keep in mind} 3.62 + 3.63 +The most important aspect of any model that you must keep in mind is 3.64 +how well it matches the needs and capabilities of the people who will 3.65 +be using it. This might seem self-evident; even so, you still can't 3.66 +afford to forget it for a moment. 3.67 + 3.68 +I once put together a workflow model that seemed to make perfect sense 3.69 +to me, but that caused a considerable amount of consternation and 3.70 +strife within my development team. In spite of my attempts to explain 3.71 +why we needed a complex set of branches, and how changes ought to flow 3.72 +between them, a few team members revolted. Even though they were 3.73 +smart people, they didn't want to pay attention to the constraints we 3.74 +were operating under, or face the consequences of those constraints in 3.75 +the details of the model that I was advocating. 3.76 + 3.77 +Don't sweep foreseeable social or technical problems under the rug. 3.78 +Whatever scheme you put into effect, you should plan for mistakes and 3.79 +problem scenarios. Consider adding automated machinery to prevent, or 3.80 +quickly recover from, trouble that you can anticipate. As an example, 3.81 +if you intend to have a branch with not-for-release changes in it, 3.82 +you'd do well to think early about the possibility that someone might 3.83 +accidentally merge those changes into a release branch. You could 3.84 +avoid this particular problem by writing a hook that prevents changes 3.85 +from being merged from an inappropriate branch. 3.86 + 3.87 +\subsection{Informal anarchy} 3.88 + 3.89 +I wouldn't suggest an ``anything goes'' approach as something 3.90 +sustainable, but it's a model that's easy to grasp, and it works 3.91 +perfectly well in a few unusual situations. 3.92 + 3.93 +As one example, many projects have a loose-knit group of collaborators 3.94 +who rarely physically meet each other. Some groups like to overcome 3.95 +the isolation of working at a distance by organising occasional 3.96 +``sprints''. In a sprint, a number of people get together in a single 3.97 +location (a company's conference room, a hotel meeting room, that kind 3.98 +of place) and spend several days more or less locked in there, hacking 3.99 +intensely on a handful of projects. 3.100 + 3.101 +A sprint is the perfect place to use the \hgcmd{serve} command, since 3.102 +\hgcmd{serve} does not requires any fancy server infrastructure. You 3.103 +can get started with \hgcmd{serve} in moments, by reading 3.104 +section~\ref{sec:collab:serve} below. Then simply tell the person 3.105 +next to you that you're running a server, send the URL to them in an 3.106 +instant message, and you immediately have a quick-turnaround way to 3.107 +work together. They can type your URL into their web browser and 3.108 +quickly review your changes; or they can pull a bugfix from you and 3.109 +verify it; or they can clone a branch containing a new feature and try 3.110 +it out. 3.111 + 3.112 +The charm, and the problem, with doing things in an ad hoc fashion 3.113 +like this is that only people who know about your changes, and where 3.114 +they are, can see them. Such an informal approach simply doesn't 3.115 +scale beyond a handful people, because each individual needs to know 3.116 +about $n$ different repositories to pull from. 3.117 + 3.118 +\subsection{A single central repository} 3.119 + 3.120 +For smaller projects migrating from a centralised revision control 3.121 +tool, perhaps the easiest way to get started is to have changes flow 3.122 +through a single shared central repository. This is also the 3.123 +most common ``building block'' for more ambitious workflow schemes. 3.124 + 3.125 +Contributors start by cloning a copy of this repository. They can 3.126 +pull changes from it whenever they need to, and some (perhaps all) 3.127 +developers have permission to push a change back when they're ready 3.128 +for other people to see it. 3.129 + 3.130 +Under this model, it can still often make sense for people to pull 3.131 +changes directly from each other, without going through the central 3.132 +repository. Consider a case in which I have a tentative bug fix, but 3.133 +I am worried that if I were to publish it to the central repository, 3.134 +it might subsequently break everyone else's trees as they pull it. To 3.135 +reduce the potential for damage, I can ask you to clone my repository 3.136 +into a temporary repository of your own and test it. This lets us put 3.137 +off publishing the potentially unsafe change until it has had a little 3.138 +testing. 3.139 + 3.140 +In this kind of scenario, people usually use the \command{ssh} 3.141 +protocol to securely push changes to the central repository, as 3.142 +documented in section~\ref{sec:collab:ssh}. It's also usual to 3.143 +publish a read-only copy of the repository over HTTP using CGI, as in 3.144 +section~\ref{sec:collab:cgi}. Publishing over HTTP satisfies the 3.145 +needs of people who don't have push access, and those who want to use 3.146 +web browsers to browse the repository's history. 3.147 + 3.148 +\subsection{Working with multiple branches} 3.149 + 3.150 +Projects of any significant size naturally tend to make progress on 3.151 +several fronts simultaneously. In the case of software, it's common 3.152 +for a project to go through periodic official releases. A release 3.153 +might then go into ``maintenance mode'' for a while after its first 3.154 +publication; maintenance releases tend to contain only bug fixes, not 3.155 +new features. In parallel with these maintenance releases, one or 3.156 +more future releases may be under development. People normally use 3.157 +the word ``branch'' to refer to one of these many slightly different 3.158 +directions in which development is proceeding. 3.159 + 3.160 +Mercurial is particularly well suited to managing a number of 3.161 +simultaneous, but not identical, branches. Each ``development 3.162 +direction'' can live in its own central repository, and you can merge 3.163 +changes from one to another as the need arises. Because repositories 3.164 +are independent of each other, unstable changes in a development 3.165 +branch will never affect a stable branch unless someone explicitly 3.166 +merges those changes in. 3.167 + 3.168 +Here's an example of how this can work in practice. Let's say you 3.169 +have one ``main branch'' on a central server. 3.170 +\interaction{branching.init} 3.171 +People clone it, make changes locally, test them, and push them back. 3.172 + 3.173 +Once the main branch reaches a release milestone, you can use the 3.174 +\hgcmd{tag} command to give a permanent name to the milestone 3.175 +revision. 3.176 +\interaction{branching.tag} 3.177 +Let's say some ongoing development occurs on the main branch. 3.178 +\interaction{branching.main} 3.179 +Using the tag that was recorded at the milestone, people who clone 3.180 +that repository at any time in the future can use \hgcmd{update} to 3.181 +get a copy of the working directory exactly as it was when that tagged 3.182 +revision was committed. 3.183 +\interaction{branching.update} 3.184 + 3.185 +In addition, immediately after the main branch is tagged, someone can 3.186 +then clone the main branch on the server to a new ``stable'' branch, 3.187 +also on the server. 3.188 +\interaction{branching.clone} 3.189 + 3.190 +Someone who needs to make a change to the stable branch can then clone 3.191 +\emph{that} repository, make their changes, commit, and push their 3.192 +changes back there. 3.193 +\interaction{branching.stable} 3.194 +Because Mercurial repositories are independent, and Mercurial doesn't 3.195 +move changes around automatically, the stable and main branches are 3.196 +\emph{isolated} from each other. The changes that you made on the 3.197 +main branch don't ``leak'' to the stable branch, and vice versa. 3.198 + 3.199 +You'll often want all of your bugfixes on the stable branch to show up 3.200 +on the main branch, too. Rather than rewrite a bugfix on the main 3.201 +branch, you can simply pull and merge changes from the stable to the 3.202 +main branch, and Mercurial will bring those bugfixes in for you. 3.203 +\interaction{branching.merge} 3.204 +The main branch will still contain changes that are not on the stable 3.205 +branch, but it will also contain all of the bugfixes from the stable 3.206 +branch. The stable branch remains unaffected by these changes. 3.207 + 3.208 +\subsection{Feature branches} 3.209 + 3.210 +For larger projects, an effective way to manage change is to break up 3.211 +a team into smaller groups. Each group has a shared branch of its 3.212 +own, cloned from a single ``master'' branch used by the entire 3.213 +project. People working on an individual branch are typically quite 3.214 +isolated from developments on other branches. 3.215 + 3.216 +\begin{figure}[ht] 3.217 + \centering 3.218 + \grafix{feature-branches} 3.219 + \caption{Feature branches} 3.220 + \label{fig:collab:feature-branches} 3.221 +\end{figure} 3.222 + 3.223 +When a particular feature is deemed to be in suitable shape, someone 3.224 +on that feature team pulls and merges from the master branch into the 3.225 +feature branch, then pushes back up to the master branch. 3.226 + 3.227 +\subsection{The release train} 3.228 + 3.229 +Some projects are organised on a ``train'' basis: a release is 3.230 +scheduled to happen every few months, and whatever features are ready 3.231 +when the ``train'' is ready to leave are allowed in. 3.232 + 3.233 +This model resembles working with feature branches. The difference is 3.234 +that when a feature branch misses a train, someone on the feature team 3.235 +pulls and merges the changes that went out on that train release into 3.236 +the feature branch, and the team continues its work on top of that 3.237 +release so that their feature can make the next release. 3.238 + 3.239 +\subsection{The Linux kernel model} 3.240 + 3.241 +The development of the Linux kernel has a shallow hierarchical 3.242 +structure, surrounded by a cloud of apparent chaos. Because most 3.243 +Linux developers use \command{git}, a distributed revision control 3.244 +tool with capabilities similar to Mercurial, it's useful to describe 3.245 +the way work flows in that environment; if you like the ideas, the 3.246 +approach translates well across tools. 3.247 + 3.248 +At the center of the community sits Linus Torvalds, the creator of 3.249 +Linux. He publishes a single source repository that is considered the 3.250 +``authoritative'' current tree by the entire developer community. 3.251 +Anyone can clone Linus's tree, but he is very choosy about whose trees 3.252 +he pulls from. 3.253 + 3.254 +Linus has a number of ``trusted lieutenants''. As a general rule, he 3.255 +pulls whatever changes they publish, in most cases without even 3.256 +reviewing those changes. Some of those lieutenants are generally 3.257 +agreed to be ``maintainers'', responsible for specific subsystems 3.258 +within the kernel. If a random kernel hacker wants to make a change 3.259 +to a subsystem that they want to end up in Linus's tree, they must 3.260 +find out who the subsystem's maintainer is, and ask that maintainer to 3.261 +take their change. If the maintainer reviews their changes and agrees 3.262 +to take them, they'll pass them along to Linus in due course. 3.263 + 3.264 +Individual lieutenants have their own approaches to reviewing, 3.265 +accepting, and publishing changes; and for deciding when to feed them 3.266 +to Linus. In addition, there are several well known branches that 3.267 +people use for different purposes. For example, a few people maintain 3.268 +``stable'' repositories of older versions of the kernel, to which they 3.269 +apply critical fixes as needed. Some maintainers publish multiple 3.270 +trees: one for experimental changes; one for changes that they are 3.271 +about to feed upstream; and so on. Others just publish a single 3.272 +tree. 3.273 + 3.274 +This model has two notable features. The first is that it's ``pull 3.275 +only''. You have to ask, convince, or beg another developer to take a 3.276 +change from you, because there are almost no trees to which more than 3.277 +one person can push, and there's no way to push changes into a tree 3.278 +that someone else controls. 3.279 + 3.280 +The second is that it's based on reputation and acclaim. If you're an 3.281 +unknown, Linus will probably ignore changes from you without even 3.282 +responding. But a subsystem maintainer will probably review them, and 3.283 +will likely take them if they pass their criteria for suitability. 3.284 +The more ``good'' changes you contribute to a maintainer, the more 3.285 +likely they are to trust your judgment and accept your changes. If 3.286 +you're well-known and maintain a long-lived branch for something Linus 3.287 +hasn't yet accepted, people with similar interests may pull your 3.288 +changes regularly to keep up with your work. 3.289 + 3.290 +Reputation and acclaim don't necessarily cross subsystem or ``people'' 3.291 +boundaries. If you're a respected but specialised storage hacker, and 3.292 +you try to fix a networking bug, that change will receive a level of 3.293 +scrutiny from a network maintainer comparable to a change from a 3.294 +complete stranger. 3.295 + 3.296 +To people who come from more orderly project backgrounds, the 3.297 +comparatively chaotic Linux kernel development process often seems 3.298 +completely insane. It's subject to the whims of individuals; people 3.299 +make sweeping changes whenever they deem it appropriate; and the pace 3.300 +of development is astounding. And yet Linux is a highly successful, 3.301 +well-regarded piece of software. 3.302 + 3.303 +\subsection{Pull-only versus shared-push collaboration} 3.304 + 3.305 +A perpetual source of heat in the open source community is whether a 3.306 +development model in which people only ever pull changes from others 3.307 +is ``better than'' one in which multiple people can push changes to a 3.308 +shared repository. 3.309 + 3.310 +Typically, the backers of the shared-push model use tools that 3.311 +actively enforce this approach. If you're using a centralised 3.312 +revision control tool such as Subversion, there's no way to make a 3.313 +choice over which model you'll use: the tool gives you shared-push, 3.314 +and if you want to do anything else, you'll have to roll your own 3.315 +approach on top (such as applying a patch by hand). 3.316 + 3.317 +A good distributed revision control tool, such as Mercurial, will 3.318 +support both models. You and your collaborators can then structure 3.319 +how you work together based on your own needs and preferences, not on 3.320 +what contortions your tools force you into. 3.321 + 3.322 +\subsection{Where collaboration meets branch management} 3.323 + 3.324 +Once you and your team set up some shared repositories and start 3.325 +propagating changes back and forth between local and shared repos, you 3.326 +begin to face a related, but slightly different challenge: that of 3.327 +managing the multiple directions in which your team may be moving at 3.328 +once. Even though this subject is intimately related to how your team 3.329 +collaborates, it's dense enough to merit treatment of its own, in 3.330 +chapter~\ref{chap:branch}. 3.331 + 3.332 +\section{The technical side of sharing} 3.333 + 3.334 +The remainder of this chapter is devoted to the question of serving 3.335 +data to your collaborators. 3.336 + 3.337 +\section{Informal sharing with \hgcmd{serve}} 3.338 +\label{sec:collab:serve} 3.339 + 3.340 +Mercurial's \hgcmd{serve} command is wonderfully suited to small, 3.341 +tight-knit, and fast-paced group environments. It also provides a 3.342 +great way to get a feel for using Mercurial commands over a network. 3.343 + 3.344 +Run \hgcmd{serve} inside a repository, and in under a second it will 3.345 +bring up a specialised HTTP server; this will accept connections from 3.346 +any client, and serve up data for that repository until you terminate 3.347 +it. Anyone who knows the URL of the server you just started, and can 3.348 +talk to your computer over the network, can then use a web browser or 3.349 +Mercurial to read data from that repository. A URL for a 3.350 +\hgcmd{serve} instance running on a laptop is likely to look something 3.351 +like \Verb|http://my-laptop.local:8000/|. 3.352 + 3.353 +The \hgcmd{serve} command is \emph{not} a general-purpose web server. 3.354 +It can do only two things: 3.355 +\begin{itemize} 3.356 +\item Allow people to browse the history of the repository it's 3.357 + serving, from their normal web browsers. 3.358 +\item Speak Mercurial's wire protocol, so that people can 3.359 + \hgcmd{clone} or \hgcmd{pull} changes from that repository. 3.360 +\end{itemize} 3.361 +In particular, \hgcmd{serve} won't allow remote users to \emph{modify} 3.362 +your repository. It's intended for read-only use. 3.363 + 3.364 +If you're getting started with Mercurial, there's nothing to prevent 3.365 +you from using \hgcmd{serve} to serve up a repository on your own 3.366 +computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and 3.367 +so on to talk to that server as if the repository was hosted remotely. 3.368 +This can help you to quickly get acquainted with using commands on 3.369 +network-hosted repositories. 3.370 + 3.371 +\subsection{A few things to keep in mind} 3.372 + 3.373 +Because it provides unauthenticated read access to all clients, you 3.374 +should only use \hgcmd{serve} in an environment where you either don't 3.375 +care, or have complete control over, who can access your network and 3.376 +pull data from your repository. 3.377 + 3.378 +The \hgcmd{serve} command knows nothing about any firewall software 3.379 +you might have installed on your system or network. It cannot detect 3.380 +or control your firewall software. If other people are unable to talk 3.381 +to a running \hgcmd{serve} instance, the second thing you should do 3.382 +(\emph{after} you make sure that they're using the correct URL) is 3.383 +check your firewall configuration. 3.384 + 3.385 +By default, \hgcmd{serve} listens for incoming connections on 3.386 +port~8000. If another process is already listening on the port you 3.387 +want to use, you can specify a different port to listen on using the 3.388 +\hgopt{serve}{-p} option. 3.389 + 3.390 +Normally, when \hgcmd{serve} starts, it prints no output, which can be 3.391 +a bit unnerving. If you'd like to confirm that it is indeed running 3.392 +correctly, and find out what URL you should send to your 3.393 +collaborators, start it with the \hggopt{-v} option. 3.394 + 3.395 +\section{Using the Secure Shell (ssh) protocol} 3.396 +\label{sec:collab:ssh} 3.397 + 3.398 +You can pull and push changes securely over a network connection using 3.399 +the Secure Shell (\texttt{ssh}) protocol. To use this successfully, 3.400 +you may have to do a little bit of configuration on the client or 3.401 +server sides. 3.402 + 3.403 +If you're not familiar with ssh, it's a network protocol that lets you 3.404 +securely communicate with another computer. To use it with Mercurial, 3.405 +you'll be setting up one or more user accounts on a server so that 3.406 +remote users can log in and execute commands. 3.407 + 3.408 +(If you \emph{are} familiar with ssh, you'll probably find some of the 3.409 +material that follows to be elementary in nature.) 3.410 + 3.411 +\subsection{How to read and write ssh URLs} 3.412 + 3.413 +An ssh URL tends to look like this: 3.414 +\begin{codesample2} 3.415 + ssh://bos@hg.serpentine.com:22/hg/hgbook 3.416 +\end{codesample2} 3.417 +\begin{enumerate} 3.418 +\item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh 3.419 + protocol. 3.420 +\item The ``\texttt{bos@}'' component indicates what username to log 3.421 + into the server as. You can leave this out if the remote username 3.422 + is the same as your local username. 3.423 +\item The ``\texttt{hg.serpentine.com}'' gives the hostname of the 3.424 + server to log into. 3.425 +\item The ``:22'' identifies the port number to connect to the server 3.426 + on. The default port is~22, so you only need to specify this part 3.427 + if you're \emph{not} using port~22. 3.428 +\item The remainder of the URL is the local path to the repository on 3.429 + the server. 3.430 +\end{enumerate} 3.431 + 3.432 +There's plenty of scope for confusion with the path component of ssh 3.433 +URLs, as there is no standard way for tools to interpret it. Some 3.434 +programs behave differently than others when dealing with these paths. 3.435 +This isn't an ideal situation, but it's unlikely to change. Please 3.436 +read the following paragraphs carefully. 3.437 + 3.438 +Mercurial treats the path to a repository on the server as relative to 3.439 +the remote user's home directory. For example, if user \texttt{foo} 3.440 +on the server has a home directory of \dirname{/home/foo}, then an ssh 3.441 +URL that contains a path component of \dirname{bar} 3.442 +\emph{really} refers to the directory \dirname{/home/foo/bar}. 3.443 + 3.444 +If you want to specify a path relative to another user's home 3.445 +directory, you can use a path that starts with a tilde character 3.446 +followed by the user's name (let's call them \texttt{otheruser}), like 3.447 +this. 3.448 +\begin{codesample2} 3.449 + ssh://server/~otheruser/hg/repo 3.450 +\end{codesample2} 3.451 + 3.452 +And if you really want to specify an \emph{absolute} path on the 3.453 +server, begin the path component with two slashes, as in this example. 3.454 +\begin{codesample2} 3.455 + ssh://server//absolute/path 3.456 +\end{codesample2} 3.457 + 3.458 +\subsection{Finding an ssh client for your system} 3.459 + 3.460 +Almost every Unix-like system comes with OpenSSH preinstalled. If 3.461 +you're using such a system, run \Verb|which ssh| to find out if 3.462 +the \command{ssh} command is installed (it's usually in 3.463 +\dirname{/usr/bin}). In the unlikely event that it isn't present, 3.464 +take a look at your system documentation to figure out how to install 3.465 +it. 3.466 + 3.467 +On Windows, you'll first need to choose download a suitable ssh 3.468 +client. There are two alternatives. 3.469 +\begin{itemize} 3.470 +\item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides 3.471 + a complete suite of ssh client commands. 3.472 +\item If you have a high tolerance for pain, you can use the Cygwin 3.473 + port of OpenSSH. 3.474 +\end{itemize} 3.475 +In either case, you'll need to edit your \hgini\ file to tell 3.476 +Mercurial where to find the actual client command. For example, if 3.477 +you're using PuTTY, you'll need to use the \command{plink} command as 3.478 +a command-line ssh client. 3.479 +\begin{codesample2} 3.480 + [ui] 3.481 + ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key" 3.482 +\end{codesample2} 3.483 + 3.484 +\begin{note} 3.485 + The path to \command{plink} shouldn't contain any whitespace 3.486 + characters, or Mercurial may not be able to run it correctly (so 3.487 + putting it in \dirname{C:\\Program Files} is probably not a good 3.488 + idea). 3.489 +\end{note} 3.490 + 3.491 +\subsection{Generating a key pair} 3.492 + 3.493 +To avoid the need to repetitively type a password every time you need 3.494 +to use your ssh client, I recommend generating a key pair. On a 3.495 +Unix-like system, the \command{ssh-keygen} command will do the trick. 3.496 +On Windows, if you're using PuTTY, the \command{puttygen} command is 3.497 +what you'll need. 3.498 + 3.499 +When you generate a key pair, it's usually \emph{highly} advisable to 3.500 +protect it with a passphrase. (The only time that you might not want 3.501 +to do this id when you're using the ssh protocol for automated tasks 3.502 +on a secure network.) 3.503 + 3.504 +Simply generating a key pair isn't enough, however. You'll need to 3.505 +add the public key to the set of authorised keys for whatever user 3.506 +you're logging in remotely as. For servers using OpenSSH (the vast 3.507 +majority), this will mean adding the public key to a list in a file 3.508 +called \sfilename{authorized\_keys} in their \sdirname{.ssh} 3.509 +directory. 3.510 + 3.511 +On a Unix-like system, your public key will have a \filename{.pub} 3.512 +extension. If you're using \command{puttygen} on Windows, you can 3.513 +save the public key to a file of your choosing, or paste it from the 3.514 +window it's displayed in straight into the 3.515 +\sfilename{authorized\_keys} file. 3.516 + 3.517 +\subsection{Using an authentication agent} 3.518 + 3.519 +An authentication agent is a daemon that stores passphrases in memory 3.520 +(so it will forget passphrases if you log out and log back in again). 3.521 +An ssh client will notice if it's running, and query it for a 3.522 +passphrase. If there's no authentication agent running, or the agent 3.523 +doesn't store the necessary passphrase, you'll have to type your 3.524 +passphrase every time Mercurial tries to communicate with a server on 3.525 +your behalf (e.g.~whenever you pull or push changes). 3.526 + 3.527 +The downside of storing passphrases in an agent is that it's possible 3.528 +for a well-prepared attacker to recover the plain text of your 3.529 +passphrases, in some cases even if your system has been power-cycled. 3.530 +You should make your own judgment as to whether this is an acceptable 3.531 +risk. It certainly saves a lot of repeated typing. 3.532 + 3.533 +On Unix-like systems, the agent is called \command{ssh-agent}, and 3.534 +it's often run automatically for you when you log in. You'll need to 3.535 +use the \command{ssh-add} command to add passphrases to the agent's 3.536 +store. On Windows, if you're using PuTTY, the \command{pageant} 3.537 +command acts as the agent. It adds an icon to your system tray that 3.538 +will let you manage stored passphrases. 3.539 + 3.540 +\subsection{Configuring the server side properly} 3.541 + 3.542 +Because ssh can be fiddly to set up if you're new to it, there's a 3.543 +variety of things that can go wrong. Add Mercurial on top, and 3.544 +there's plenty more scope for head-scratching. Most of these 3.545 +potential problems occur on the server side, not the client side. The 3.546 +good news is that once you've gotten a configuration working, it will 3.547 +usually continue to work indefinitely. 3.548 + 3.549 +Before you try using Mercurial to talk to an ssh server, it's best to 3.550 +make sure that you can use the normal \command{ssh} or \command{putty} 3.551 +command to talk to the server first. If you run into problems with 3.552 +using these commands directly, Mercurial surely won't work. Worse, it 3.553 +will obscure the underlying problem. Any time you want to debug 3.554 +ssh-related Mercurial problems, you should drop back to making sure 3.555 +that plain ssh client commands work first, \emph{before} you worry 3.556 +about whether there's a problem with Mercurial. 3.557 + 3.558 +The first thing to be sure of on the server side is that you can 3.559 +actually log in from another machine at all. If you can't use 3.560 +\command{ssh} or \command{putty} to log in, the error message you get 3.561 +may give you a few hints as to what's wrong. The most common problems 3.562 +are as follows. 3.563 +\begin{itemize} 3.564 +\item If you get a ``connection refused'' error, either there isn't an 3.565 + SSH daemon running on the server at all, or it's inaccessible due to 3.566 + firewall configuration. 3.567 +\item If you get a ``no route to host'' error, you either have an 3.568 + incorrect address for the server or a seriously locked down firewall 3.569 + that won't admit its existence at all. 3.570 +\item If you get a ``permission denied'' error, you may have mistyped 3.571 + the username on the server, or you could have mistyped your key's 3.572 + passphrase or the remote user's password. 3.573 +\end{itemize} 3.574 +In summary, if you're having trouble talking to the server's ssh 3.575 +daemon, first make sure that one is running at all. On many systems 3.576 +it will be installed, but disabled, by default. Once you're done with 3.577 +this step, you should then check that the server's firewall is 3.578 +configured to allow incoming connections on the port the ssh daemon is 3.579 +listening on (usually~22). Don't worry about more exotic 3.580 +possibilities for misconfiguration until you've checked these two 3.581 +first. 3.582 + 3.583 +If you're using an authentication agent on the client side to store 3.584 +passphrases for your keys, you ought to be able to log into the server 3.585 +without being prompted for a passphrase or a password. If you're 3.586 +prompted for a passphrase, there are a few possible culprits. 3.587 +\begin{itemize} 3.588 +\item You might have forgotten to use \command{ssh-add} or 3.589 + \command{pageant} to store the passphrase. 3.590 +\item You might have stored the passphrase for the wrong key. 3.591 +\end{itemize} 3.592 +If you're being prompted for the remote user's password, there are 3.593 +another few possible problems to check. 3.594 +\begin{itemize} 3.595 +\item Either the user's home directory or their \sdirname{.ssh} 3.596 + directory might have excessively liberal permissions. As a result, 3.597 + the ssh daemon will not trust or read their 3.598 + \sfilename{authorized\_keys} file. For example, a group-writable 3.599 + home or \sdirname{.ssh} directory will often cause this symptom. 3.600 +\item The user's \sfilename{authorized\_keys} file may have a problem. 3.601 + If anyone other than the user owns or can write to that file, the 3.602 + ssh daemon will not trust or read it. 3.603 +\end{itemize} 3.604 + 3.605 +In the ideal world, you should be able to run the following command 3.606 +successfully, and it should print exactly one line of output, the 3.607 +current date and time. 3.608 +\begin{codesample2} 3.609 + ssh myserver date 3.610 +\end{codesample2} 3.611 + 3.612 +If, on your server, you have login scripts that print banners or other 3.613 +junk even when running non-interactive commands like this, you should 3.614 +fix them before you continue, so that they only print output if 3.615 +they're run interactively. Otherwise these banners will at least 3.616 +clutter up Mercurial's output. Worse, they could potentially cause 3.617 +problems with running Mercurial commands remotely. Mercurial makes 3.618 +tries to detect and ignore banners in non-interactive \command{ssh} 3.619 +sessions, but it is not foolproof. (If you're editing your login 3.620 +scripts on your server, the usual way to see if a login script is 3.621 +running in an interactive shell is to check the return code from the 3.622 +command \Verb|tty -s|.) 3.623 + 3.624 +Once you've verified that plain old ssh is working with your server, 3.625 +the next step is to ensure that Mercurial runs on the server. The 3.626 +following command should run successfully: 3.627 +\begin{codesample2} 3.628 + ssh myserver hg version 3.629 +\end{codesample2} 3.630 +If you see an error message instead of normal \hgcmd{version} output, 3.631 +this is usually because you haven't installed Mercurial to 3.632 +\dirname{/usr/bin}. Don't worry if this is the case; you don't need 3.633 +to do that. But you should check for a few possible problems. 3.634 +\begin{itemize} 3.635 +\item Is Mercurial really installed on the server at all? I know this 3.636 + sounds trivial, but it's worth checking! 3.637 +\item Maybe your shell's search path (usually set via the \envar{PATH} 3.638 + environment variable) is simply misconfigured. 3.639 +\item Perhaps your \envar{PATH} environment variable is only being set 3.640 + to point to the location of the \command{hg} executable if the login 3.641 + session is interactive. This can happen if you're setting the path 3.642 + in the wrong shell login script. See your shell's documentation for 3.643 + details. 3.644 +\item The \envar{PYTHONPATH} environment variable may need to contain 3.645 + the path to the Mercurial Python modules. It might not be set at 3.646 + all; it could be incorrect; or it may be set only if the login is 3.647 + interactive. 3.648 +\end{itemize} 3.649 + 3.650 +If you can run \hgcmd{version} over an ssh connection, well done! 3.651 +You've got the server and client sorted out. You should now be able 3.652 +to use Mercurial to access repositories hosted by that username on 3.653 +that server. If you run into problems with Mercurial and ssh at this 3.654 +point, try using the \hggopt{--debug} option to get a clearer picture 3.655 +of what's going on. 3.656 + 3.657 +\subsection{Using compression with ssh} 3.658 + 3.659 +Mercurial does not compress data when it uses the ssh protocol, 3.660 +because the ssh protocol can transparently compress data. However, 3.661 +the default behaviour of ssh clients is \emph{not} to request 3.662 +compression. 3.663 + 3.664 +Over any network other than a fast LAN (even a wireless network), 3.665 +using compression is likely to significantly speed up Mercurial's 3.666 +network operations. For example, over a WAN, someone measured 3.667 +compression as reducing the amount of time required to clone a 3.668 +particularly large repository from~51 minutes to~17 minutes. 3.669 + 3.670 +Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C} 3.671 +option which turns on compression. You can easily edit your \hgrc\ to 3.672 +enable compression for all of Mercurial's uses of the ssh protocol. 3.673 +\begin{codesample2} 3.674 + [ui] 3.675 + ssh = ssh -C 3.676 +\end{codesample2} 3.677 + 3.678 +If you use \command{ssh}, you can configure it to always use 3.679 +compression when talking to your server. To do this, edit your 3.680 +\sfilename{.ssh/config} file (which may not yet exist), as follows. 3.681 +\begin{codesample2} 3.682 + Host hg 3.683 + Compression yes 3.684 + HostName hg.example.com 3.685 +\end{codesample2} 3.686 +This defines an alias, \texttt{hg}. When you use it on the 3.687 +\command{ssh} command line or in a Mercurial \texttt{ssh}-protocol 3.688 +URL, it will cause \command{ssh} to connect to \texttt{hg.example.com} 3.689 +and use compression. This gives you both a shorter name to type and 3.690 +compression, each of which is a good thing in its own right. 3.691 + 3.692 +\section{Serving over HTTP using CGI} 3.693 +\label{sec:collab:cgi} 3.694 + 3.695 +Depending on how ambitious you are, configuring Mercurial's CGI 3.696 +interface can take anything from a few moments to several hours. 3.697 + 3.698 +We'll begin with the simplest of examples, and work our way towards a 3.699 +more complex configuration. Even for the most basic case, you're 3.700 +almost certainly going to need to read and modify your web server's 3.701 +configuration. 3.702 + 3.703 +\begin{note} 3.704 + Configuring a web server is a complex, fiddly, and highly 3.705 + system-dependent activity. I can't possibly give you instructions 3.706 + that will cover anything like all of the cases you will encounter. 3.707 + Please use your discretion and judgment in following the sections 3.708 + below. Be prepared to make plenty of mistakes, and to spend a lot 3.709 + of time reading your server's error logs. 3.710 +\end{note} 3.711 + 3.712 +\subsection{Web server configuration checklist} 3.713 + 3.714 +Before you continue, do take a few moments to check a few aspects of 3.715 +your system's setup. 3.716 + 3.717 +\begin{enumerate} 3.718 +\item Do you have a web server installed at all? Mac OS X ships with 3.719 + Apache, but many other systems may not have a web server installed. 3.720 +\item If you have a web server installed, is it actually running? On 3.721 + most systems, even if one is present, it will be disabled by 3.722 + default. 3.723 +\item Is your server configured to allow you to run CGI programs in 3.724 + the directory where you plan to do so? Most servers default to 3.725 + explicitly disabling the ability to run CGI programs. 3.726 +\end{enumerate} 3.727 + 3.728 +If you don't have a web server installed, and don't have substantial 3.729 +experience configuring Apache, you should consider using the 3.730 +\texttt{lighttpd} web server instead of Apache. Apache has a 3.731 +well-deserved reputation for baroque and confusing configuration. 3.732 +While \texttt{lighttpd} is less capable in some ways than Apache, most 3.733 +of these capabilities are not relevant to serving Mercurial 3.734 +repositories. And \texttt{lighttpd} is undeniably \emph{much} easier 3.735 +to get started with than Apache. 3.736 + 3.737 +\subsection{Basic CGI configuration} 3.738 + 3.739 +On Unix-like systems, it's common for users to have a subdirectory 3.740 +named something like \dirname{public\_html} in their home directory, 3.741 +from which they can serve up web pages. A file named \filename{foo} 3.742 +in this directory will be accessible at a URL of the form 3.743 +\texttt{http://www.example.com/\~username/foo}. 3.744 + 3.745 +To get started, find the \sfilename{hgweb.cgi} script that should be 3.746 +present in your Mercurial installation. If you can't quickly find a 3.747 +local copy on your system, simply download one from the master 3.748 +Mercurial repository at 3.749 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}. 3.750 + 3.751 +You'll need to copy this script into your \dirname{public\_html} 3.752 +directory, and ensure that it's executable. 3.753 +\begin{codesample2} 3.754 + cp .../hgweb.cgi ~/public_html 3.755 + chmod 755 ~/public_html/hgweb.cgi 3.756 +\end{codesample2} 3.757 +The \texttt{755} argument to \command{chmod} is a little more general 3.758 +than just making the script executable: it ensures that the script is 3.759 +executable by anyone, and that ``group'' and ``other'' write 3.760 +permissions are \emph{not} set. If you were to leave those write 3.761 +permissions enabled, Apache's \texttt{suexec} subsystem would likely 3.762 +refuse to execute the script. In fact, \texttt{suexec} also insists 3.763 +that the \emph{directory} in which the script resides must not be 3.764 +writable by others. 3.765 +\begin{codesample2} 3.766 + chmod 755 ~/public_html 3.767 +\end{codesample2} 3.768 + 3.769 +\subsubsection{What could \emph{possibly} go wrong?} 3.770 +\label{sec:collab:wtf} 3.771 + 3.772 +Once you've copied the CGI script into place, go into a web browser, 3.773 +and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi}, 3.774 +\emph{but} brace yourself for instant failure. There's a high 3.775 +probability that trying to visit this URL will fail, and there are 3.776 +many possible reasons for this. In fact, you're likely to stumble 3.777 +over almost every one of the possible errors below, so please read 3.778 +carefully. The following are all of the problems I ran into on a 3.779 +system running Fedora~7, with a fresh installation of Apache, and a 3.780 +user account that I created specially to perform this exercise. 3.781 + 3.782 +Your web server may have per-user directories disabled. If you're 3.783 +using Apache, search your config file for a \texttt{UserDir} 3.784 +directive. If there's none present, per-user directories will be 3.785 +disabled. If one exists, but its value is \texttt{disabled}, then 3.786 +per-user directories will be disabled. Otherwise, the string after 3.787 +\texttt{UserDir} gives the name of the subdirectory that Apache will 3.788 +look in under your home directory, for example \dirname{public\_html}. 3.789 + 3.790 +Your file access permissions may be too restrictive. The web server 3.791 +must be able to traverse your home directory and directories under 3.792 +your \dirname{public\_html} directory, and read files under the latter 3.793 +too. Here's a quick recipe to help you to make your permissions more 3.794 +appropriate. 3.795 +\begin{codesample2} 3.796 + chmod 755 ~ 3.797 + find ~/public_html -type d -print0 | xargs -0r chmod 755 3.798 + find ~/public_html -type f -print0 | xargs -0r chmod 644 3.799 +\end{codesample2} 3.800 + 3.801 +The other possibility with permissions is that you might get a 3.802 +completely empty window when you try to load the script. In this 3.803 +case, it's likely that your access permissions are \emph{too 3.804 + permissive}. Apache's \texttt{suexec} subsystem won't execute a 3.805 +script that's group-~or world-writable, for example. 3.806 + 3.807 +Your web server may be configured to disallow execution of CGI 3.808 +programs in your per-user web directory. Here's Apache's 3.809 +default per-user configuration from my Fedora system. 3.810 +\begin{codesample2} 3.811 + <Directory /home/*/public_html> 3.812 + AllowOverride FileInfo AuthConfig Limit 3.813 + Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec 3.814 + <Limit GET POST OPTIONS> 3.815 + Order allow,deny 3.816 + Allow from all 3.817 + </Limit> 3.818 + <LimitExcept GET POST OPTIONS> 3.819 + Order deny,allow 3.820 + Deny from all 3.821 + </LimitExcept> 3.822 + </Directory> 3.823 +\end{codesample2} 3.824 +If you find a similar-looking \texttt{Directory} group in your Apache 3.825 +configuration, the directive to look at inside it is \texttt{Options}. 3.826 +Add \texttt{ExecCGI} to the end of this list if it's missing, and 3.827 +restart the web server. 3.828 + 3.829 +If you find that Apache serves you the text of the CGI script instead 3.830 +of executing it, you may need to either uncomment (if already present) 3.831 +or add a directive like this. 3.832 +\begin{codesample2} 3.833 + AddHandler cgi-script .cgi 3.834 +\end{codesample2} 3.835 + 3.836 +The next possibility is that you might be served with a colourful 3.837 +Python backtrace claiming that it can't import a 3.838 +\texttt{mercurial}-related module. This is actually progress! The 3.839 +server is now capable of executing your CGI script. This error is 3.840 +only likely to occur if you're running a private installation of 3.841 +Mercurial, instead of a system-wide version. Remember that the web 3.842 +server runs the CGI program without any of the environment variables 3.843 +that you take for granted in an interactive session. If this error 3.844 +happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the 3.845 +directions inside it to correctly set your \envar{PYTHONPATH} 3.846 +environment variable. 3.847 + 3.848 +Finally, you are \emph{certain} to by served with another colourful 3.849 +Python backtrace: this one will complain that it can't find 3.850 +\dirname{/path/to/repository}. Edit your \sfilename{hgweb.cgi} script 3.851 +and replace the \dirname{/path/to/repository} string with the complete 3.852 +path to the repository you want to serve up. 3.853 + 3.854 +At this point, when you try to reload the page, you should be 3.855 +presented with a nice HTML view of your repository's history. Whew! 3.856 + 3.857 +\subsubsection{Configuring lighttpd} 3.858 + 3.859 +To be exhaustive in my experiments, I tried configuring the 3.860 +increasingly popular \texttt{lighttpd} web server to serve the same 3.861 +repository as I described with Apache above. I had already overcome 3.862 +all of the problems I outlined with Apache, many of which are not 3.863 +server-specific. As a result, I was fairly sure that my file and 3.864 +directory permissions were good, and that my \sfilename{hgweb.cgi} 3.865 +script was properly edited. 3.866 + 3.867 +Once I had Apache running, getting \texttt{lighttpd} to serve the 3.868 +repository was a snap (in other words, even if you're trying to use 3.869 +\texttt{lighttpd}, you should read the Apache section). I first had 3.870 +to edit the \texttt{mod\_access} section of its config file to enable 3.871 +\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were 3.872 +disabled by default on my system. I then added a few lines to the end 3.873 +of the config file, to configure these modules. 3.874 +\begin{codesample2} 3.875 + userdir.path = "public_html" 3.876 + cgi.assign = ( ".cgi" => "" ) 3.877 +\end{codesample2} 3.878 +With this done, \texttt{lighttpd} ran immediately for me. If I had 3.879 +configured \texttt{lighttpd} before Apache, I'd almost certainly have 3.880 +run into many of the same system-level configuration problems as I did 3.881 +with Apache. However, I found \texttt{lighttpd} to be noticeably 3.882 +easier to configure than Apache, even though I've used Apache for over 3.883 +a decade, and this was my first exposure to \texttt{lighttpd}. 3.884 + 3.885 +\subsection{Sharing multiple repositories with one CGI script} 3.886 + 3.887 +The \sfilename{hgweb.cgi} script only lets you publish a single 3.888 +repository, which is an annoying restriction. If you want to publish 3.889 +more than one without wracking yourself with multiple copies of the 3.890 +same script, each with different names, a better choice is to use the 3.891 +\sfilename{hgwebdir.cgi} script. 3.892 + 3.893 +The procedure to configure \sfilename{hgwebdir.cgi} is only a little 3.894 +more involved than for \sfilename{hgweb.cgi}. First, you must obtain 3.895 +a copy of the script. If you don't have one handy, you can download a 3.896 +copy from the master Mercurial repository at 3.897 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}. 3.898 + 3.899 +You'll need to copy this script into your \dirname{public\_html} 3.900 +directory, and ensure that it's executable. 3.901 +\begin{codesample2} 3.902 + cp .../hgwebdir.cgi ~/public_html 3.903 + chmod 755 ~/public_html ~/public_html/hgwebdir.cgi 3.904 +\end{codesample2} 3.905 +With basic configuration out of the way, try to visit 3.906 +\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser. It 3.907 +should display an empty list of repositories. If you get a blank 3.908 +window or error message, try walking through the list of potential 3.909 +problems in section~\ref{sec:collab:wtf}. 3.910 + 3.911 +The \sfilename{hgwebdir.cgi} script relies on an external 3.912 +configuration file. By default, it searches for a file named 3.913 +\sfilename{hgweb.config} in the same directory as itself. You'll need 3.914 +to create this file, and make it world-readable. The format of the 3.915 +file is similar to a Windows ``ini'' file, as understood by Python's 3.916 +\texttt{ConfigParser}~\cite{web:configparser} module. 3.917 + 3.918 +The easiest way to configure \sfilename{hgwebdir.cgi} is with a 3.919 +section named \texttt{collections}. This will automatically publish 3.920 +\emph{every} repository under the directories you name. The section 3.921 +should look like this: 3.922 +\begin{codesample2} 3.923 + [collections] 3.924 + /my/root = /my/root 3.925 +\end{codesample2} 3.926 +Mercurial interprets this by looking at the directory name on the 3.927 +\emph{right} hand side of the ``\texttt{=}'' sign; finding 3.928 +repositories in that directory hierarchy; and using the text on the 3.929 +\emph{left} to strip off matching text from the names it will actually 3.930 +list in the web interface. The remaining component of a path after 3.931 +this stripping has occurred is called a ``virtual path''. 3.932 + 3.933 +Given the example above, if we have a repository whose local path is 3.934 +\dirname{/my/root/this/repo}, the CGI script will strip the leading 3.935 +\dirname{/my/root} from the name, and publish the repository with a 3.936 +virtual path of \dirname{this/repo}. If the base URL for our CGI 3.937 +script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete 3.938 +URL for that repository will be 3.939 +\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}. 3.940 + 3.941 +If we replace \dirname{/my/root} on the left hand side of this example 3.942 +with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off 3.943 +\dirname{/my} from the repository name, and will give us a virtual 3.944 +path of \dirname{root/this/repo} instead of \dirname{this/repo}. 3.945 + 3.946 +The \sfilename{hgwebdir.cgi} script will recursively search each 3.947 +directory listed in the \texttt{collections} section of its 3.948 +configuration file, but it will \texttt{not} recurse into the 3.949 +repositories it finds. 3.950 + 3.951 +The \texttt{collections} mechanism makes it easy to publish many 3.952 +repositories in a ``fire and forget'' manner. You only need to set up 3.953 +the CGI script and configuration file one time. Afterwards, you can 3.954 +publish or unpublish a repository at any time by simply moving it 3.955 +into, or out of, the directory hierarchy in which you've configured 3.956 +\sfilename{hgwebdir.cgi} to look. 3.957 + 3.958 +\subsubsection{Explicitly specifying which repositories to publish} 3.959 + 3.960 +In addition to the \texttt{collections} mechanism, the 3.961 +\sfilename{hgwebdir.cgi} script allows you to publish a specific list 3.962 +of repositories. To do so, create a \texttt{paths} section, with 3.963 +contents of the following form. 3.964 +\begin{codesample2} 3.965 + [paths] 3.966 + repo1 = /my/path/to/some/repo 3.967 + repo2 = /some/path/to/another 3.968 +\end{codesample2} 3.969 +In this case, the virtual path (the component that will appear in a 3.970 +URL) is on the left hand side of each definition, while the path to 3.971 +the repository is on the right. Notice that there does not need to be 3.972 +any relationship between the virtual path you choose and the location 3.973 +of a repository in your filesystem. 3.974 + 3.975 +If you wish, you can use both the \texttt{collections} and 3.976 +\texttt{paths} mechanisms simultaneously in a single configuration 3.977 +file. 3.978 + 3.979 +\begin{note} 3.980 + If multiple repositories have the same virtual path, 3.981 + \sfilename{hgwebdir.cgi} will not report an error. Instead, it will 3.982 + behave unpredictably. 3.983 +\end{note} 3.984 + 3.985 +\subsection{Downloading source archives} 3.986 + 3.987 +Mercurial's web interface lets users download an archive of any 3.988 +revision. This archive will contain a snapshot of the working 3.989 +directory as of that revision, but it will not contain a copy of the 3.990 +repository data. 3.991 + 3.992 +By default, this feature is not enabled. To enable it, you'll need to 3.993 +add an \rcitem{web}{allow\_archive} item to the \rcsection{web} 3.994 +section of your \hgrc. 3.995 + 3.996 +\subsection{Web configuration options} 3.997 + 3.998 +Mercurial's web interfaces (the \hgcmd{serve} command, and the 3.999 +\sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a 3.1000 +number of configuration options that you can set. These belong in a 3.1001 +section named \rcsection{web}. 3.1002 +\begin{itemize} 3.1003 +\item[\rcitem{web}{allow\_archive}] Determines which (if any) archive 3.1004 + download mechanisms Mercurial supports. If you enable this 3.1005 + feature, users of the web interface will be able to download an 3.1006 + archive of whatever revision of a repository they are viewing. 3.1007 + To enable the archive feature, this item must take the form of a 3.1008 + sequence of words drawn from the list below. 3.1009 + \begin{itemize} 3.1010 + \item[\texttt{bz2}] A \command{tar} archive, compressed using 3.1011 + \texttt{bzip2} compression. This has the best compression ratio, 3.1012 + but uses the most CPU time on the server. 3.1013 + \item[\texttt{gz}] A \command{tar} archive, compressed using 3.1014 + \texttt{gzip} compression. 3.1015 + \item[\texttt{zip}] A \command{zip} archive, compressed using LZW 3.1016 + compression. This format has the worst compression ratio, but is 3.1017 + widely used in the Windows world. 3.1018 + \end{itemize} 3.1019 + If you provide an empty list, or don't have an 3.1020 + \rcitem{web}{allow\_archive} entry at all, this feature will be 3.1021 + disabled. Here is an example of how to enable all three supported 3.1022 + formats. 3.1023 + \begin{codesample4} 3.1024 + [web] 3.1025 + allow_archive = bz2 gz zip 3.1026 + \end{codesample4} 3.1027 +\item[\rcitem{web}{allowpull}] Boolean. Determines whether the web 3.1028 + interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this 3.1029 + repository over~HTTP. If set to \texttt{no} or \texttt{false}, only 3.1030 + the ``human-oriented'' portion of the web interface is available. 3.1031 +\item[\rcitem{web}{contact}] String. A free-form (but preferably 3.1032 + brief) string identifying the person or group in charge of the 3.1033 + repository. This often contains the name and email address of a 3.1034 + person or mailing list. It often makes sense to place this entry in 3.1035 + a repository's own \sfilename{.hg/hgrc} file, but it can make sense 3.1036 + to use in a global \hgrc\ if every repository has a single 3.1037 + maintainer. 3.1038 +\item[\rcitem{web}{maxchanges}] Integer. The default maximum number 3.1039 + of changesets to display in a single page of output. 3.1040 +\item[\rcitem{web}{maxfiles}] Integer. The default maximum number 3.1041 + of modified files to display in a single page of output. 3.1042 +\item[\rcitem{web}{stripes}] Integer. If the web interface displays 3.1043 + alternating ``stripes'' to make it easier to visually align rows 3.1044 + when you are looking at a table, this number controls the number of 3.1045 + rows in each stripe. 3.1046 +\item[\rcitem{web}{style}] Controls the template Mercurial uses to 3.1047 + display the web interface. Mercurial ships with two web templates, 3.1048 + named \texttt{default} and \texttt{gitweb} (the latter is much more 3.1049 + visually attractive). You can also specify a custom template of 3.1050 + your own; see chapter~\ref{chap:template} for details. Here, you 3.1051 + can see how to enable the \texttt{gitweb} style. 3.1052 + \begin{codesample4} 3.1053 + [web] 3.1054 + style = gitweb 3.1055 + \end{codesample4} 3.1056 +\item[\rcitem{web}{templates}] Path. The directory in which to search 3.1057 + for template files. By default, Mercurial searches in the directory 3.1058 + in which it was installed. 3.1059 +\end{itemize} 3.1060 +If you are using \sfilename{hgwebdir.cgi}, you can place a few 3.1061 +configuration items in a \rcsection{web} section of the 3.1062 +\sfilename{hgweb.config} file instead of a \hgrc\ file, for 3.1063 +convenience. These items are \rcitem{web}{motd} and 3.1064 +\rcitem{web}{style}. 3.1065 + 3.1066 +\subsubsection{Options specific to an individual repository} 3.1067 + 3.1068 +A few \rcsection{web} configuration items ought to be placed in a 3.1069 +repository's local \sfilename{.hg/hgrc}, rather than a user's or 3.1070 +global \hgrc. 3.1071 +\begin{itemize} 3.1072 +\item[\rcitem{web}{description}] String. A free-form (but preferably 3.1073 + brief) string that describes the contents or purpose of the 3.1074 + repository. 3.1075 +\item[\rcitem{web}{name}] String. The name to use for the repository 3.1076 + in the web interface. This overrides the default name, which is the 3.1077 + last component of the repository's path. 3.1078 +\end{itemize} 3.1079 + 3.1080 +\subsubsection{Options specific to the \hgcmd{serve} command} 3.1081 + 3.1082 +Some of the items in the \rcsection{web} section of a \hgrc\ file are 3.1083 +only for use with the \hgcmd{serve} command. 3.1084 +\begin{itemize} 3.1085 +\item[\rcitem{web}{accesslog}] Path. The name of a file into which to 3.1086 + write an access log. By default, the \hgcmd{serve} command writes 3.1087 + this information to standard output, not to a file. Log entries are 3.1088 + written in the standard ``combined'' file format used by almost all 3.1089 + web servers. 3.1090 +\item[\rcitem{web}{address}] String. The local address on which the 3.1091 + server should listen for incoming connections. By default, the 3.1092 + server listens on all addresses. 3.1093 +\item[\rcitem{web}{errorlog}] Path. The name of a file into which to 3.1094 + write an error log. By default, the \hgcmd{serve} command writes this 3.1095 + information to standard error, not to a file. 3.1096 +\item[\rcitem{web}{ipv6}] Boolean. Whether to use the IPv6 protocol. 3.1097 + By default, IPv6 is not used. 3.1098 +\item[\rcitem{web}{port}] Integer. The TCP~port number on which the 3.1099 + server should listen. The default port number used is~8000. 3.1100 +\end{itemize} 3.1101 + 3.1102 +\subsubsection{Choosing the right \hgrc\ file to add \rcsection{web} 3.1103 + items to} 3.1104 + 3.1105 +It is important to remember that a web server like Apache or 3.1106 +\texttt{lighttpd} will run under a user~ID that is different to yours. 3.1107 +CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will 3.1108 +usually also run under that user~ID. 3.1109 + 3.1110 +If you add \rcsection{web} items to your own personal \hgrc\ file, CGI 3.1111 +scripts won't read that \hgrc\ file. Those settings will thus only 3.1112 +affect the behaviour of the \hgcmd{serve} command when you run it. To 3.1113 +cause CGI scripts to see your settings, either create a \hgrc\ file in 3.1114 +the home directory of the user ID that runs your web server, or add 3.1115 +those settings to a system-wide \hgrc\ file. 3.1116 + 3.1117 + 3.1118 +%%% Local Variables: 3.1119 +%%% mode: latex 3.1120 +%%% TeX-master: "00book" 3.1121 +%%% End:
4.1 --- a/es/filenames.tex Fri Nov 07 21:33:22 2008 -0500 4.2 +++ b/es/filenames.tex Fri Nov 07 21:42:57 2008 -0500 4.3 @@ -0,0 +1,306 @@ 4.4 +\chapter{File names and pattern matching} 4.5 +\label{chap:names} 4.6 + 4.7 +Mercurial provides mechanisms that let you work with file names in a 4.8 +consistent and expressive way. 4.9 + 4.10 +\section{Simple file naming} 4.11 + 4.12 +Mercurial uses a unified piece of machinery ``under the hood'' to 4.13 +handle file names. Every command behaves uniformly with respect to 4.14 +file names. The way in which commands work with file names is as 4.15 +follows. 4.16 + 4.17 +If you explicitly name real files on the command line, Mercurial works 4.18 +with exactly those files, as you would expect. 4.19 +\interaction{filenames.files} 4.20 + 4.21 +When you provide a directory name, Mercurial will interpret this as 4.22 +``operate on every file in this directory and its subdirectories''. 4.23 +Mercurial traverses the files and subdirectories in a directory in 4.24 +alphabetical order. When it encounters a subdirectory, it will 4.25 +traverse that subdirectory before continuing with the current 4.26 +directory. 4.27 +\interaction{filenames.dirs} 4.28 + 4.29 +\section{Running commands without any file names} 4.30 + 4.31 +Mercurial's commands that work with file names have useful default 4.32 +behaviours when you invoke them without providing any file names or 4.33 +patterns. What kind of behaviour you should expect depends on what 4.34 +the command does. Here are a few rules of thumb you can use to 4.35 +predict what a command is likely to do if you don't give it any names 4.36 +to work with. 4.37 +\begin{itemize} 4.38 +\item Most commands will operate on the entire working directory. 4.39 + This is what the \hgcmd{add} command does, for example. 4.40 +\item If the command has effects that are difficult or impossible to 4.41 + reverse, it will force you to explicitly provide at least one name 4.42 + or pattern (see below). This protects you from accidentally 4.43 + deleting files by running \hgcmd{remove} with no arguments, for 4.44 + example. 4.45 +\end{itemize} 4.46 + 4.47 +It's easy to work around these default behaviours if they don't suit 4.48 +you. If a command normally operates on the whole working directory, 4.49 +you can invoke it on just the current directory and its subdirectories 4.50 +by giving it the name ``\dirname{.}''. 4.51 +\interaction{filenames.wdir-subdir} 4.52 + 4.53 +Along the same lines, some commands normally print file names relative 4.54 +to the root of the repository, even if you're invoking them from a 4.55 +subdirectory. Such a command will print file names relative to your 4.56 +subdirectory if you give it explicit names. Here, we're going to run 4.57 +\hgcmd{status} from a subdirectory, and get it to operate on the 4.58 +entire working directory while printing file names relative to our 4.59 +subdirectory, by passing it the output of the \hgcmd{root} command. 4.60 +\interaction{filenames.wdir-relname} 4.61 + 4.62 +\section{Telling you what's going on} 4.63 + 4.64 +The \hgcmd{add} example in the preceding section illustrates something 4.65 +else that's helpful about Mercurial commands. If a command operates 4.66 +on a file that you didn't name explicitly on the command line, it will 4.67 +usually print the name of the file, so that you will not be surprised 4.68 +what's going on. 4.69 + 4.70 +The principle here is of \emph{least surprise}. If you've exactly 4.71 +named a file on the command line, there's no point in repeating it 4.72 +back at you. If Mercurial is acting on a file \emph{implicitly}, 4.73 +because you provided no names, or a directory, or a pattern (see 4.74 +below), it's safest to tell you what it's doing. 4.75 + 4.76 +For commands that behave this way, you can silence them using the 4.77 +\hggopt{-q} option. You can also get them to print the name of every 4.78 +file, even those you've named explicitly, using the \hggopt{-v} 4.79 +option. 4.80 + 4.81 +\section{Using patterns to identify files} 4.82 + 4.83 +In addition to working with file and directory names, Mercurial lets 4.84 +you use \emph{patterns} to identify files. Mercurial's pattern 4.85 +handling is expressive. 4.86 + 4.87 +On Unix-like systems (Linux, MacOS, etc.), the job of matching file 4.88 +names to patterns normally falls to the shell. On these systems, you 4.89 +must explicitly tell Mercurial that a name is a pattern. On Windows, 4.90 +the shell does not expand patterns, so Mercurial will automatically 4.91 +identify names that are patterns, and expand them for you. 4.92 + 4.93 +To provide a pattern in place of a regular name on the command line, 4.94 +the mechanism is simple: 4.95 +\begin{codesample2} 4.96 + syntax:patternbody 4.97 +\end{codesample2} 4.98 +That is, a pattern is identified by a short text string that says what 4.99 +kind of pattern this is, followed by a colon, followed by the actual 4.100 +pattern. 4.101 + 4.102 +Mercurial supports two kinds of pattern syntax. The most frequently 4.103 +used is called \texttt{glob}; this is the same kind of pattern 4.104 +matching used by the Unix shell, and should be familiar to Windows 4.105 +command prompt users, too. 4.106 + 4.107 +When Mercurial does automatic pattern matching on Windows, it uses 4.108 +\texttt{glob} syntax. You can thus omit the ``\texttt{glob:}'' prefix 4.109 +on Windows, but it's safe to use it, too. 4.110 + 4.111 +The \texttt{re} syntax is more powerful; it lets you specify patterns 4.112 +using regular expressions, also known as regexps. 4.113 + 4.114 +By the way, in the examples that follow, notice that I'm careful to 4.115 +wrap all of my patterns in quote characters, so that they won't get 4.116 +expanded by the shell before Mercurial sees them. 4.117 + 4.118 +\subsection{Shell-style \texttt{glob} patterns} 4.119 + 4.120 +This is an overview of the kinds of patterns you can use when you're 4.121 +matching on glob patterns. 4.122 + 4.123 +The ``\texttt{*}'' character matches any string, within a single 4.124 +directory. 4.125 +\interaction{filenames.glob.star} 4.126 + 4.127 +The ``\texttt{**}'' pattern matches any string, and crosses directory 4.128 +boundaries. It's not a standard Unix glob token, but it's accepted by 4.129 +several popular Unix shells, and is very useful. 4.130 +\interaction{filenames.glob.starstar} 4.131 + 4.132 +The ``\texttt{?}'' pattern matches any single character. 4.133 +\interaction{filenames.glob.question} 4.134 + 4.135 +The ``\texttt{[}'' character begins a \emph{character class}. This 4.136 +matches any single character within the class. The class ends with a 4.137 +``\texttt{]}'' character. A class may contain multiple \emph{range}s 4.138 +of the form ``\texttt{a-f}'', which is shorthand for 4.139 +``\texttt{abcdef}''. 4.140 +\interaction{filenames.glob.range} 4.141 +If the first character after the ``\texttt{[}'' in a character class 4.142 +is a ``\texttt{!}'', it \emph{negates} the class, making it match any 4.143 +single character not in the class. 4.144 + 4.145 +A ``\texttt{\{}'' begins a group of subpatterns, where the whole group 4.146 +matches if any subpattern in the group matches. The ``\texttt{,}'' 4.147 +character separates subpatterns, and ``\texttt{\}}'' ends the group. 4.148 +\interaction{filenames.glob.group} 4.149 + 4.150 +\subsubsection{Watch out!} 4.151 + 4.152 +Don't forget that if you want to match a pattern in any directory, you 4.153 +should not be using the ``\texttt{*}'' match-any token, as this will 4.154 +only match within one directory. Instead, use the ``\texttt{**}'' 4.155 +token. This small example illustrates the difference between the two. 4.156 +\interaction{filenames.glob.star-starstar} 4.157 + 4.158 +\subsection{Regular expression matching with \texttt{re} patterns} 4.159 + 4.160 +Mercurial accepts the same regular expression syntax as the Python 4.161 +programming language (it uses Python's regexp engine internally). 4.162 +This is based on the Perl language's regexp syntax, which is the most 4.163 +popular dialect in use (it's also used in Java, for example). 4.164 + 4.165 +I won't discuss Mercurial's regexp dialect in any detail here, as 4.166 +regexps are not often used. Perl-style regexps are in any case 4.167 +already exhaustively documented on a multitude of web sites, and in 4.168 +many books. Instead, I will focus here on a few things you should 4.169 +know if you find yourself needing to use regexps with Mercurial. 4.170 + 4.171 +A regexp is matched against an entire file name, relative to the root 4.172 +of the repository. In other words, even if you're already in 4.173 +subbdirectory \dirname{foo}, if you want to match files under this 4.174 +directory, your pattern must start with ``\texttt{foo/}''. 4.175 + 4.176 +One thing to note, if you're familiar with Perl-style regexps, is that 4.177 +Mercurial's are \emph{rooted}. That is, a regexp starts matching 4.178 +against the beginning of a string; it doesn't look for a match 4.179 +anywhere within the string. To match anywhere in a string, start 4.180 +your pattern with ``\texttt{.*}''. 4.181 + 4.182 +\section{Filtering files} 4.183 + 4.184 +Not only does Mercurial give you a variety of ways to specify files; 4.185 +it lets you further winnow those files using \emph{filters}. Commands 4.186 +that work with file names accept two filtering options. 4.187 +\begin{itemize} 4.188 +\item \hggopt{-I}, or \hggopt{--include}, lets you specify a pattern 4.189 + that file names must match in order to be processed. 4.190 +\item \hggopt{-X}, or \hggopt{--exclude}, gives you a way to 4.191 + \emph{avoid} processing files, if they match this pattern. 4.192 +\end{itemize} 4.193 +You can provide multiple \hggopt{-I} and \hggopt{-X} options on the 4.194 +command line, and intermix them as you please. Mercurial interprets 4.195 +the patterns you provide using glob syntax by default (but you can use 4.196 +regexps if you need to). 4.197 + 4.198 +You can read a \hggopt{-I} filter as ``process only the files that 4.199 +match this filter''. 4.200 +\interaction{filenames.filter.include} 4.201 +The \hggopt{-X} filter is best read as ``process only the files that 4.202 +don't match this pattern''. 4.203 +\interaction{filenames.filter.exclude} 4.204 + 4.205 +\section{Ignoring unwanted files and directories} 4.206 + 4.207 +XXX. 4.208 + 4.209 +\section{Case sensitivity} 4.210 +\label{sec:names:case} 4.211 + 4.212 +If you're working in a mixed development environment that contains 4.213 +both Linux (or other Unix) systems and Macs or Windows systems, you 4.214 +should keep in the back of your mind the knowledge that they treat the 4.215 +case (``N'' versus ``n'') of file names in incompatible ways. This is 4.216 +not very likely to affect you, and it's easy to deal with if it does, 4.217 +but it could surprise you if you don't know about it. 4.218 + 4.219 +Operating systems and filesystems differ in the way they handle the 4.220 +\emph{case} of characters in file and directory names. There are 4.221 +three common ways to handle case in names. 4.222 +\begin{itemize} 4.223 +\item Completely case insensitive. Uppercase and lowercase versions 4.224 + of a letter are treated as identical, both when creating a file and 4.225 + during subsequent accesses. This is common on older DOS-based 4.226 + systems. 4.227 +\item Case preserving, but insensitive. When a file or directory is 4.228 + created, the case of its name is stored, and can be retrieved and 4.229 + displayed by the operating system. When an existing file is being 4.230 + looked up, its case is ignored. This is the standard arrangement on 4.231 + Windows and MacOS. The names \filename{foo} and \filename{FoO} 4.232 + identify the same file. This treatment of uppercase and lowercase 4.233 + letters as interchangeable is also referred to as \emph{case 4.234 + folding}. 4.235 +\item Case sensitive. The case of a name is significant at all times. 4.236 + The names \filename{foo} and {FoO} identify different files. This 4.237 + is the way Linux and Unix systems normally work. 4.238 +\end{itemize} 4.239 + 4.240 +On Unix-like systems, it is possible to have any or all of the above 4.241 +ways of handling case in action at once. For example, if you use a 4.242 +USB thumb drive formatted with a FAT32 filesystem on a Linux system, 4.243 +Linux will handle names on that filesystem in a case preserving, but 4.244 +insensitive, way. 4.245 + 4.246 +\subsection{Safe, portable repository storage} 4.247 + 4.248 +Mercurial's repository storage mechanism is \emph{case safe}. It 4.249 +translates file names so that they can be safely stored on both case 4.250 +sensitive and case insensitive filesystems. This means that you can 4.251 +use normal file copying tools to transfer a Mercurial repository onto, 4.252 +for example, a USB thumb drive, and safely move that drive and 4.253 +repository back and forth between a Mac, a PC running Windows, and a 4.254 +Linux box. 4.255 + 4.256 +\subsection{Detecting case conflicts} 4.257 + 4.258 +When operating in the working directory, Mercurial honours the naming 4.259 +policy of the filesystem where the working directory is located. If 4.260 +the filesystem is case preserving, but insensitive, Mercurial will 4.261 +treat names that differ only in case as the same. 4.262 + 4.263 +An important aspect of this approach is that it is possible to commit 4.264 +a changeset on a case sensitive (typically Linux or Unix) filesystem 4.265 +that will cause trouble for users on case insensitive (usually Windows 4.266 +and MacOS) users. If a Linux user commits changes to two files, one 4.267 +named \filename{myfile.c} and the other named \filename{MyFile.C}, 4.268 +they will be stored correctly in the repository. And in the working 4.269 +directories of other Linux users, they will be correctly represented 4.270 +as separate files. 4.271 + 4.272 +If a Windows or Mac user pulls this change, they will not initially 4.273 +have a problem, because Mercurial's repository storage mechanism is 4.274 +case safe. However, once they try to \hgcmd{update} the working 4.275 +directory to that changeset, or \hgcmd{merge} with that changeset, 4.276 +Mercurial will spot the conflict between the two file names that the 4.277 +filesystem would treat as the same, and forbid the update or merge 4.278 +from occurring. 4.279 + 4.280 +\subsection{Fixing a case conflict} 4.281 + 4.282 +If you are using Windows or a Mac in a mixed environment where some of 4.283 +your collaborators are using Linux or Unix, and Mercurial reports a 4.284 +case folding conflict when you try to \hgcmd{update} or \hgcmd{merge}, 4.285 +the procedure to fix the problem is simple. 4.286 + 4.287 +Just find a nearby Linux or Unix box, clone the problem repository 4.288 +onto it, and use Mercurial's \hgcmd{rename} command to change the 4.289 +names of any offending files or directories so that they will no 4.290 +longer cause case folding conflicts. Commit this change, \hgcmd{pull} 4.291 +or \hgcmd{push} it across to your Windows or MacOS system, and 4.292 +\hgcmd{update} to the revision with the non-conflicting names. 4.293 + 4.294 +The changeset with case-conflicting names will remain in your 4.295 +project's history, and you still won't be able to \hgcmd{update} your 4.296 +working directory to that changeset on a Windows or MacOS system, but 4.297 +you can continue development unimpeded. 4.298 + 4.299 +\begin{note} 4.300 + Prior to version~0.9.3, Mercurial did not use a case safe repository 4.301 + storage mechanism, and did not detect case folding conflicts. If 4.302 + you are using an older version of Mercurial on Windows or MacOS, I 4.303 + strongly recommend that you upgrade. 4.304 +\end{note} 4.305 + 4.306 +%%% Local Variables: 4.307 +%%% mode: latex 4.308 +%%% TeX-master: "00book" 4.309 +%%% End:
5.1 --- a/es/intro.tex Fri Nov 07 21:33:22 2008 -0500 5.2 +++ b/es/intro.tex Fri Nov 07 21:42:57 2008 -0500 5.3 @@ -0,0 +1,561 @@ 5.4 +\chapter{Introduction} 5.5 +\label{chap:intro} 5.6 + 5.7 +\section{About revision control} 5.8 + 5.9 +Revision control is the process of managing multiple versions of a 5.10 +piece of information. In its simplest form, this is something that 5.11 +many people do by hand: every time you modify a file, save it under a 5.12 +new name that contains a number, each one higher than the number of 5.13 +the preceding version. 5.14 + 5.15 +Manually managing multiple versions of even a single file is an 5.16 +error-prone task, though, so software tools to help automate this 5.17 +process have long been available. The earliest automated revision 5.18 +control tools were intended to help a single user to manage revisions 5.19 +of a single file. Over the past few decades, the scope of revision 5.20 +control tools has expanded greatly; they now manage multiple files, 5.21 +and help multiple people to work together. The best modern revision 5.22 +control tools have no problem coping with thousands of people working 5.23 +together on projects that consist of hundreds of thousands of files. 5.24 + 5.25 +\subsection{Why use revision control?} 5.26 + 5.27 +There are a number of reasons why you or your team might want to use 5.28 +an automated revision control tool for a project. 5.29 +\begin{itemize} 5.30 +\item It will track the history and evolution of your project, so you 5.31 + don't have to. For every change, you'll have a log of \emph{who} 5.32 + made it; \emph{why} they made it; \emph{when} they made it; and 5.33 + \emph{what} the change was. 5.34 +\item When you're working with other people, revision control software 5.35 + makes it easier for you to collaborate. For example, when people 5.36 + more or less simultaneously make potentially incompatible changes, 5.37 + the software will help you to identify and resolve those conflicts. 5.38 +\item It can help you to recover from mistakes. If you make a change 5.39 + that later turns out to be in error, you can revert to an earlier 5.40 + version of one or more files. In fact, a \emph{really} good 5.41 + revision control tool will even help you to efficiently figure out 5.42 + exactly when a problem was introduced (see 5.43 + section~\ref{sec:undo:bisect} for details). 5.44 +\item It will help you to work simultaneously on, and manage the drift 5.45 + between, multiple versions of your project. 5.46 +\end{itemize} 5.47 +Most of these reasons are equally valid---at least in theory---whether 5.48 +you're working on a project by yourself, or with a hundred other 5.49 +people. 5.50 + 5.51 +A key question about the practicality of revision control at these two 5.52 +different scales (``lone hacker'' and ``huge team'') is how its 5.53 +\emph{benefits} compare to its \emph{costs}. A revision control tool 5.54 +that's difficult to understand or use is going to impose a high cost. 5.55 + 5.56 +A five-hundred-person project is likely to collapse under its own 5.57 +weight almost immediately without a revision control tool and process. 5.58 +In this case, the cost of using revision control might hardly seem 5.59 +worth considering, since \emph{without} it, failure is almost 5.60 +guaranteed. 5.61 + 5.62 +On the other hand, a one-person ``quick hack'' might seem like a poor 5.63 +place to use a revision control tool, because surely the cost of using 5.64 +one must be close to the overall cost of the project. Right? 5.65 + 5.66 +Mercurial uniquely supports \emph{both} of these scales of 5.67 +development. You can learn the basics in just a few minutes, and due 5.68 +to its low overhead, you can apply revision control to the smallest of 5.69 +projects with ease. Its simplicity means you won't have a lot of 5.70 +abstruse concepts or command sequences competing for mental space with 5.71 +whatever you're \emph{really} trying to do. At the same time, 5.72 +Mercurial's high performance and peer-to-peer nature let you scale 5.73 +painlessly to handle large projects. 5.74 + 5.75 +No revision control tool can rescue a poorly run project, but a good 5.76 +choice of tools can make a huge difference to the fluidity with which 5.77 +you can work on a project. 5.78 + 5.79 +\subsection{The many names of revision control} 5.80 + 5.81 +Revision control is a diverse field, so much so that it doesn't 5.82 +actually have a single name or acronym. Here are a few of the more 5.83 +common names and acronyms you'll encounter: 5.84 +\begin{itemize} 5.85 +\item Revision control (RCS) 5.86 +\item Software configuration management (SCM), or configuration management 5.87 +\item Source code management 5.88 +\item Source code control, or source control 5.89 +\item Version control (VCS) 5.90 +\end{itemize} 5.91 +Some people claim that these terms actually have different meanings, 5.92 +but in practice they overlap so much that there's no agreed or even 5.93 +useful way to tease them apart. 5.94 + 5.95 +\section{A short history of revision control} 5.96 + 5.97 +The best known of the old-time revision control tools is SCCS (Source 5.98 +Code Control System), which Marc Rochkind wrote at Bell Labs, in the 5.99 +early 1970s. SCCS operated on individual files, and required every 5.100 +person working on a project to have access to a shared workspace on a 5.101 +single system. Only one person could modify a file at any time; 5.102 +arbitration for access to files was via locks. It was common for 5.103 +people to lock files, and later forget to unlock them, preventing 5.104 +anyone else from modifying those files without the help of an 5.105 +administrator. 5.106 + 5.107 +Walter Tichy developed a free alternative to SCCS in the early 1980s; 5.108 +he called his program RCS (Revison Control System). Like SCCS, RCS 5.109 +required developers to work in a single shared workspace, and to lock 5.110 +files to prevent multiple people from modifying them simultaneously. 5.111 + 5.112 +Later in the 1980s, Dick Grune used RCS as a building block for a set 5.113 +of shell scripts he initially called cmt, but then renamed to CVS 5.114 +(Concurrent Versions System). The big innovation of CVS was that it 5.115 +let developers work simultaneously and somewhat independently in their 5.116 +own personal workspaces. The personal workspaces prevented developers 5.117 +from stepping on each other's toes all the time, as was common with 5.118 +SCCS and RCS. Each developer had a copy of every project file, and 5.119 +could modify their copies independently. They had to merge their 5.120 +edits prior to committing changes to the central repository. 5.121 + 5.122 +Brian Berliner took Grune's original scripts and rewrote them in~C, 5.123 +releasing in 1989 the code that has since developed into the modern 5.124 +version of CVS. CVS subsequently acquired the ability to operate over 5.125 +a network connection, giving it a client/server architecture. CVS's 5.126 +architecture is centralised; only the server has a copy of the history 5.127 +of the project. Client workspaces just contain copies of recent 5.128 +versions of the project's files, and a little metadata to tell them 5.129 +where the server is. CVS has been enormously successful; it is 5.130 +probably the world's most widely used revision control system. 5.131 + 5.132 +In the early 1990s, Sun Microsystems developed an early distributed 5.133 +revision control system, called TeamWare. A TeamWare workspace 5.134 +contains a complete copy of the project's history. TeamWare has no 5.135 +notion of a central repository. (CVS relied upon RCS for its history 5.136 +storage; TeamWare used SCCS.) 5.137 + 5.138 +As the 1990s progressed, awareness grew of a number of problems with 5.139 +CVS. It records simultaneous changes to multiple files individually, 5.140 +instead of grouping them together as a single logically atomic 5.141 +operation. It does not manage its file hierarchy well; it is easy to 5.142 +make a mess of a repository by renaming files and directories. Worse, 5.143 +its source code is difficult to read and maintain, which made the 5.144 +``pain level'' of fixing these architectural problems prohibitive. 5.145 + 5.146 +In 2001, Jim Blandy and Karl Fogel, two developers who had worked on 5.147 +CVS, started a project to replace it with a tool that would have a 5.148 +better architecture and cleaner code. The result, Subversion, does 5.149 +not stray from CVS's centralised client/server model, but it adds 5.150 +multi-file atomic commits, better namespace management, and a number 5.151 +of other features that make it a generally better tool than CVS. 5.152 +Since its initial release, it has rapidly grown in popularity. 5.153 + 5.154 +More or less simultaneously, Graydon Hoare began working on an 5.155 +ambitious distributed revision control system that he named Monotone. 5.156 +While Monotone addresses many of CVS's design flaws and has a 5.157 +peer-to-peer architecture, it goes beyond earlier (and subsequent) 5.158 +revision control tools in a number of innovative ways. It uses 5.159 +cryptographic hashes as identifiers, and has an integral notion of 5.160 +``trust'' for code from different sources. 5.161 + 5.162 +Mercurial began life in 2005. While a few aspects of its design are 5.163 +influenced by Monotone, Mercurial focuses on ease of use, high 5.164 +performance, and scalability to very large projects. 5.165 + 5.166 +\section{Trends in revision control} 5.167 + 5.168 +There has been an unmistakable trend in the development and use of 5.169 +revision control tools over the past four decades, as people have 5.170 +become familiar with the capabilities of their tools and constrained 5.171 +by their limitations. 5.172 + 5.173 +The first generation began by managing single files on individual 5.174 +computers. Although these tools represented a huge advance over 5.175 +ad-hoc manual revision control, their locking model and reliance on a 5.176 +single computer limited them to small, tightly-knit teams. 5.177 + 5.178 +The second generation loosened these constraints by moving to 5.179 +network-centered architectures, and managing entire projects at a 5.180 +time. As projects grew larger, they ran into new problems. With 5.181 +clients needing to talk to servers very frequently, server scaling 5.182 +became an issue for large projects. An unreliable network connection 5.183 +could prevent remote users from being able to talk to the server at 5.184 +all. As open source projects started making read-only access 5.185 +available anonymously to anyone, people without commit privileges 5.186 +found that they could not use the tools to interact with a project in 5.187 +a natural way, as they could not record their changes. 5.188 + 5.189 +The current generation of revision control tools is peer-to-peer in 5.190 +nature. All of these systems have dropped the dependency on a single 5.191 +central server, and allow people to distribute their revision control 5.192 +data to where it's actually needed. Collaboration over the Internet 5.193 +has moved from constrained by technology to a matter of choice and 5.194 +consensus. Modern tools can operate offline indefinitely and 5.195 +autonomously, with a network connection only needed when syncing 5.196 +changes with another repository. 5.197 + 5.198 +\section{A few of the advantages of distributed revision control} 5.199 + 5.200 +Even though distributed revision control tools have for several years 5.201 +been as robust and usable as their previous-generation counterparts, 5.202 +people using older tools have not yet necessarily woken up to their 5.203 +advantages. There are a number of ways in which distributed tools 5.204 +shine relative to centralised ones. 5.205 + 5.206 +For an individual developer, distributed tools are almost always much 5.207 +faster than centralised tools. This is for a simple reason: a 5.208 +centralised tool needs to talk over the network for many common 5.209 +operations, because most metadata is stored in a single copy on the 5.210 +central server. A distributed tool stores all of its metadata 5.211 +locally. All else being equal, talking over the network adds overhead 5.212 +to a centralised tool. Don't underestimate the value of a snappy, 5.213 +responsive tool: you're going to spend a lot of time interacting with 5.214 +your revision control software. 5.215 + 5.216 +Distributed tools are indifferent to the vagaries of your server 5.217 +infrastructure, again because they replicate metadata to so many 5.218 +locations. If you use a centralised system and your server catches 5.219 +fire, you'd better hope that your backup media are reliable, and that 5.220 +your last backup was recent and actually worked. With a distributed 5.221 +tool, you have many backups available on every contributor's computer. 5.222 + 5.223 +The reliability of your network will affect distributed tools far less 5.224 +than it will centralised tools. You can't even use a centralised tool 5.225 +without a network connection, except for a few highly constrained 5.226 +commands. With a distributed tool, if your network connection goes 5.227 +down while you're working, you may not even notice. The only thing 5.228 +you won't be able to do is talk to repositories on other computers, 5.229 +something that is relatively rare compared with local operations. If 5.230 +you have a far-flung team of collaborators, this may be significant. 5.231 + 5.232 +\subsection{Advantages for open source projects} 5.233 + 5.234 +If you take a shine to an open source project and decide that you 5.235 +would like to start hacking on it, and that project uses a distributed 5.236 +revision control tool, you are at once a peer with the people who 5.237 +consider themselves the ``core'' of that project. If they publish 5.238 +their repositories, you can immediately copy their project history, 5.239 +start making changes, and record your work, using the same tools in 5.240 +the same ways as insiders. By contrast, with a centralised tool, you 5.241 +must use the software in a ``read only'' mode unless someone grants 5.242 +you permission to commit changes to their central server. Until then, 5.243 +you won't be able to record changes, and your local modifications will 5.244 +be at risk of corruption any time you try to update your client's view 5.245 +of the repository. 5.246 + 5.247 +\subsubsection{The forking non-problem} 5.248 + 5.249 +It has been suggested that distributed revision control tools pose 5.250 +some sort of risk to open source projects because they make it easy to 5.251 +``fork'' the development of a project. A fork happens when there are 5.252 +differences in opinion or attitude between groups of developers that 5.253 +cause them to decide that they can't work together any longer. Each 5.254 +side takes a more or less complete copy of the project's source code, 5.255 +and goes off in its own direction. 5.256 + 5.257 +Sometimes the camps in a fork decide to reconcile their differences. 5.258 +With a centralised revision control system, the \emph{technical} 5.259 +process of reconciliation is painful, and has to be performed largely 5.260 +by hand. You have to decide whose revision history is going to 5.261 +``win'', and graft the other team's changes into the tree somehow. 5.262 +This usually loses some or all of one side's revision history. 5.263 + 5.264 +What distributed tools do with respect to forking is they make forking 5.265 +the \emph{only} way to develop a project. Every single change that 5.266 +you make is potentially a fork point. The great strength of this 5.267 +approach is that a distributed revision control tool has to be really 5.268 +good at \emph{merging} forks, because forks are absolutely 5.269 +fundamental: they happen all the time. 5.270 + 5.271 +If every piece of work that everybody does, all the time, is framed in 5.272 +terms of forking and merging, then what the open source world refers 5.273 +to as a ``fork'' becomes \emph{purely} a social issue. If anything, 5.274 +distributed tools \emph{lower} the likelihood of a fork: 5.275 +\begin{itemize} 5.276 +\item They eliminate the social distinction that centralised tools 5.277 + impose: that between insiders (people with commit access) and 5.278 + outsiders (people without). 5.279 +\item They make it easier to reconcile after a social fork, because 5.280 + all that's involved from the perspective of the revision control 5.281 + software is just another merge. 5.282 +\end{itemize} 5.283 + 5.284 +Some people resist distributed tools because they want to retain tight 5.285 +control over their projects, and they believe that centralised tools 5.286 +give them this control. However, if you're of this belief, and you 5.287 +publish your CVS or Subversion repositories publically, there are 5.288 +plenty of tools available that can pull out your entire project's 5.289 +history (albeit slowly) and recreate it somewhere that you don't 5.290 +control. So while your control in this case is illusory, you are 5.291 +forgoing the ability to fluidly collaborate with whatever people feel 5.292 +compelled to mirror and fork your history. 5.293 + 5.294 +\subsection{Advantages for commercial projects} 5.295 + 5.296 +Many commercial projects are undertaken by teams that are scattered 5.297 +across the globe. Contributors who are far from a central server will 5.298 +see slower command execution and perhaps less reliability. Commercial 5.299 +revision control systems attempt to ameliorate these problems with 5.300 +remote-site replication add-ons that are typically expensive to buy 5.301 +and cantankerous to administer. A distributed system doesn't suffer 5.302 +from these problems in the first place. Better yet, you can easily 5.303 +set up multiple authoritative servers, say one per site, so that 5.304 +there's no redundant communication between repositories over expensive 5.305 +long-haul network links. 5.306 + 5.307 +Centralised revision control systems tend to have relatively low 5.308 +scalability. It's not unusual for an expensive centralised system to 5.309 +fall over under the combined load of just a few dozen concurrent 5.310 +users. Once again, the typical response tends to be an expensive and 5.311 +clunky replication facility. Since the load on a central server---if 5.312 +you have one at all---is many times lower with a distributed 5.313 +tool (because all of the data is replicated everywhere), a single 5.314 +cheap server can handle the needs of a much larger team, and 5.315 +replication to balance load becomes a simple matter of scripting. 5.316 + 5.317 +If you have an employee in the field, troubleshooting a problem at a 5.318 +customer's site, they'll benefit from distributed revision control. 5.319 +The tool will let them generate custom builds, try different fixes in 5.320 +isolation from each other, and search efficiently through history for 5.321 +the sources of bugs and regressions in the customer's environment, all 5.322 +without needing to connect to your company's network. 5.323 + 5.324 +\section{Why choose Mercurial?} 5.325 + 5.326 +Mercurial has a unique set of properties that make it a particularly 5.327 +good choice as a revision control system. 5.328 +\begin{itemize} 5.329 +\item It is easy to learn and use. 5.330 +\item It is lightweight. 5.331 +\item It scales excellently. 5.332 +\item It is easy to customise. 5.333 +\end{itemize} 5.334 + 5.335 +If you are at all familiar with revision control systems, you should 5.336 +be able to get up and running with Mercurial in less than five 5.337 +minutes. Even if not, it will take no more than a few minutes 5.338 +longer. Mercurial's command and feature sets are generally uniform 5.339 +and consistent, so you can keep track of a few general rules instead 5.340 +of a host of exceptions. 5.341 + 5.342 +On a small project, you can start working with Mercurial in moments. 5.343 +Creating new changes and branches; transferring changes around 5.344 +(whether locally or over a network); and history and status operations 5.345 +are all fast. Mercurial attempts to stay nimble and largely out of 5.346 +your way by combining low cognitive overhead with blazingly fast 5.347 +operations. 5.348 + 5.349 +The usefulness of Mercurial is not limited to small projects: it is 5.350 +used by projects with hundreds to thousands of contributors, each 5.351 +containing tens of thousands of files and hundreds of megabytes of 5.352 +source code. 5.353 + 5.354 +If the core functionality of Mercurial is not enough for you, it's 5.355 +easy to build on. Mercurial is well suited to scripting tasks, and 5.356 +its clean internals and implementation in Python make it easy to add 5.357 +features in the form of extensions. There are a number of popular and 5.358 +useful extensions already available, ranging from helping to identify 5.359 +bugs to improving performance. 5.360 + 5.361 +\section{Mercurial compared with other tools} 5.362 + 5.363 +Before you read on, please understand that this section necessarily 5.364 +reflects my own experiences, interests, and (dare I say it) biases. I 5.365 +have used every one of the revision control tools listed below, in 5.366 +most cases for several years at a time. 5.367 + 5.368 + 5.369 +\subsection{Subversion} 5.370 + 5.371 +Subversion is a popular revision control tool, developed to replace 5.372 +CVS. It has a centralised client/server architecture. 5.373 + 5.374 +Subversion and Mercurial have similarly named commands for performing 5.375 +the same operations, so if you're familiar with one, it is easy to 5.376 +learn to use the other. Both tools are portable to all popular 5.377 +operating systems. 5.378 + 5.379 +Prior to version 1.5, Subversion had no useful support for merges. 5.380 +At the time of writing, its merge tracking capability is new, and known to be 5.381 +\href{http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword}{complicated 5.382 + and buggy}. 5.383 + 5.384 +Mercurial has a substantial performance advantage over Subversion on 5.385 +every revision control operation I have benchmarked. I have measured 5.386 +its advantage as ranging from a factor of two to a factor of six when 5.387 +compared with Subversion~1.4.3's \emph{ra\_local} file store, which is 5.388 +the fastest access method available. In more realistic deployments 5.389 +involving a network-based store, Subversion will be at a substantially 5.390 +larger disadvantage. Because many Subversion commands must talk to 5.391 +the server and Subversion does not have useful replication facilities, 5.392 +server capacity and network bandwidth become bottlenecks for modestly 5.393 +large projects. 5.394 + 5.395 +Additionally, Subversion incurs substantial storage overhead to avoid 5.396 +network transactions for a few common operations, such as finding 5.397 +modified files (\texttt{status}) and displaying modifications against 5.398 +the current revision (\texttt{diff}). As a result, a Subversion 5.399 +working copy is often the same size as, or larger than, a Mercurial 5.400 +repository and working directory, even though the Mercurial repository 5.401 +contains a complete history of the project. 5.402 + 5.403 +Subversion is widely supported by third party tools. Mercurial 5.404 +currently lags considerably in this area. This gap is closing, 5.405 +however, and indeed some of Mercurial's GUI tools now outshine their 5.406 +Subversion equivalents. Like Mercurial, Subversion has an excellent 5.407 +user manual. 5.408 + 5.409 +Because Subversion doesn't store revision history on the client, it is 5.410 +well suited to managing projects that deal with lots of large, opaque 5.411 +binary files. If you check in fifty revisions to an incompressible 5.412 +10MB file, Subversion's client-side space usage stays constant The 5.413 +space used by any distributed SCM will grow rapidly in proportion to 5.414 +the number of revisions, because the differences between each revision 5.415 +are large. 5.416 + 5.417 +In addition, it's often difficult or, more usually, impossible to 5.418 +merge different versions of a binary file. Subversion's ability to 5.419 +let a user lock a file, so that they temporarily have the exclusive 5.420 +right to commit changes to it, can be a significant advantage to a 5.421 +project where binary files are widely used. 5.422 + 5.423 +Mercurial can import revision history from a Subversion repository. 5.424 +It can also export revision history to a Subversion repository. This 5.425 +makes it easy to ``test the waters'' and use Mercurial and Subversion 5.426 +in parallel before deciding to switch. History conversion is 5.427 +incremental, so you can perform an initial conversion, then small 5.428 +additional conversions afterwards to bring in new changes. 5.429 + 5.430 + 5.431 +\subsection{Git} 5.432 + 5.433 +Git is a distributed revision control tool that was developed for 5.434 +managing the Linux kernel source tree. Like Mercurial, its early 5.435 +design was somewhat influenced by Monotone. 5.436 + 5.437 +Git has a very large command set, with version~1.5.0 providing~139 5.438 +individual commands. It has something of a reputation for being 5.439 +difficult to learn. Compared to Git, Mercurial has a strong focus on 5.440 +simplicity. 5.441 + 5.442 +In terms of performance, Git is extremely fast. In several cases, it 5.443 +is faster than Mercurial, at least on Linux, while Mercurial performs 5.444 +better on other operations. However, on Windows, the performance and 5.445 +general level of support that Git provides is, at the time of writing, 5.446 +far behind that of Mercurial. 5.447 + 5.448 +While a Mercurial repository needs no maintenance, a Git repository 5.449 +requires frequent manual ``repacks'' of its metadata. Without these, 5.450 +performance degrades, while space usage grows rapidly. A server that 5.451 +contains many Git repositories that are not rigorously and frequently 5.452 +repacked will become heavily disk-bound during backups, and there have 5.453 +been instances of daily backups taking far longer than~24 hours as a 5.454 +result. A freshly packed Git repository is slightly smaller than a 5.455 +Mercurial repository, but an unpacked repository is several orders of 5.456 +magnitude larger. 5.457 + 5.458 +The core of Git is written in C. Many Git commands are implemented as 5.459 +shell or Perl scripts, and the quality of these scripts varies widely. 5.460 +I have encountered several instances where scripts charged along 5.461 +blindly in the presence of errors that should have been fatal. 5.462 + 5.463 +Mercurial can import revision history from a Git repository. 5.464 + 5.465 + 5.466 +\subsection{CVS} 5.467 + 5.468 +CVS is probably the most widely used revision control tool in the 5.469 +world. Due to its age and internal untidiness, it has been only 5.470 +lightly maintained for many years. 5.471 + 5.472 +It has a centralised client/server architecture. It does not group 5.473 +related file changes into atomic commits, making it easy for people to 5.474 +``break the build'': one person can successfully commit part of a 5.475 +change and then be blocked by the need for a merge, causing other 5.476 +people to see only a portion of the work they intended to do. This 5.477 +also affects how you work with project history. If you want to see 5.478 +all of the modifications someone made as part of a task, you will need 5.479 +to manually inspect the descriptions and timestamps of the changes 5.480 +made to each file involved (if you even know what those files were). 5.481 + 5.482 +CVS has a muddled notion of tags and branches that I will not attempt 5.483 +to even describe. It does not support renaming of files or 5.484 +directories well, making it easy to corrupt a repository. It has 5.485 +almost no internal consistency checking capabilities, so it is usually 5.486 +not even possible to tell whether or how a repository is corrupt. I 5.487 +would not recommend CVS for any project, existing or new. 5.488 + 5.489 +Mercurial can import CVS revision history. However, there are a few 5.490 +caveats that apply; these are true of every other revision control 5.491 +tool's CVS importer, too. Due to CVS's lack of atomic changes and 5.492 +unversioned filesystem hierarchy, it is not possible to reconstruct 5.493 +CVS history completely accurately; some guesswork is involved, and 5.494 +renames will usually not show up. Because a lot of advanced CVS 5.495 +administration has to be done by hand and is hence error-prone, it's 5.496 +common for CVS importers to run into multiple problems with corrupted 5.497 +repositories (completely bogus revision timestamps and files that have 5.498 +remained locked for over a decade are just two of the less interesting 5.499 +problems I can recall from personal experience). 5.500 + 5.501 +Mercurial can import revision history from a CVS repository. 5.502 + 5.503 + 5.504 +\subsection{Commercial tools} 5.505 + 5.506 +Perforce has a centralised client/server architecture, with no 5.507 +client-side caching of any data. Unlike modern revision control 5.508 +tools, Perforce requires that a user run a command to inform the 5.509 +server about every file they intend to edit. 5.510 + 5.511 +The performance of Perforce is quite good for small teams, but it 5.512 +falls off rapidly as the number of users grows beyond a few dozen. 5.513 +Modestly large Perforce installations require the deployment of 5.514 +proxies to cope with the load their users generate. 5.515 + 5.516 + 5.517 +\subsection{Choosing a revision control tool} 5.518 + 5.519 +With the exception of CVS, all of the tools listed above have unique 5.520 +strengths that suit them to particular styles of work. There is no 5.521 +single revision control tool that is best in all situations. 5.522 + 5.523 +As an example, Subversion is a good choice for working with frequently 5.524 +edited binary files, due to its centralised nature and support for 5.525 +file locking. 5.526 + 5.527 +I personally find Mercurial's properties of simplicity, performance, 5.528 +and good merge support to be a compelling combination that has served 5.529 +me well for several years. 5.530 + 5.531 + 5.532 +\section{Switching from another tool to Mercurial} 5.533 + 5.534 +Mercurial is bundled with an extension named \hgext{convert}, which 5.535 +can incrementally import revision history from several other revision 5.536 +control tools. By ``incremental'', I mean that you can convert all of 5.537 +a project's history to date in one go, then rerun the conversion later 5.538 +to obtain new changes that happened after the initial conversion. 5.539 + 5.540 +The revision control tools supported by \hgext{convert} are as 5.541 +follows: 5.542 +\begin{itemize} 5.543 +\item Subversion 5.544 +\item CVS 5.545 +\item Git 5.546 +\item Darcs 5.547 +\end{itemize} 5.548 + 5.549 +In addition, \hgext{convert} can export changes from Mercurial to 5.550 +Subversion. This makes it possible to try Subversion and Mercurial in 5.551 +parallel before committing to a switchover, without risking the loss 5.552 +of any work. 5.553 + 5.554 +The \hgxcmd{conver}{convert} command is easy to use. Simply point it 5.555 +at the path or URL of the source repository, optionally give it the 5.556 +name of the destination repository, and it will start working. After 5.557 +the initial conversion, just run the same command again to import new 5.558 +changes. 5.559 + 5.560 + 5.561 +%%% Local Variables: 5.562 +%%% mode: latex 5.563 +%%% TeX-master: "00book" 5.564 +%%% End:
6.1 --- a/es/srcinstall.tex Fri Nov 07 21:33:22 2008 -0500 6.2 +++ b/es/srcinstall.tex Fri Nov 07 21:42:57 2008 -0500 6.3 @@ -0,0 +1,53 @@ 6.4 +\chapter{Installing Mercurial from source} 6.5 +\label{chap:srcinstall} 6.6 + 6.7 +\section{On a Unix-like system} 6.8 +\label{sec:srcinstall:unixlike} 6.9 + 6.10 +If you are using a Unix-like system that has a sufficiently recent 6.11 +version of Python (2.3~or newer) available, it is easy to install 6.12 +Mercurial from source. 6.13 +\begin{enumerate} 6.14 +\item Download a recent source tarball from 6.15 + \url{http://www.selenic.com/mercurial/download}. 6.16 +\item Unpack the tarball: 6.17 + \begin{codesample4} 6.18 + gzip -dc mercurial-\emph{version}.tar.gz | tar xf - 6.19 + \end{codesample4} 6.20 +\item Go into the source directory and run the installer script. This 6.21 + will build Mercurial and install it in your home directory. 6.22 + \begin{codesample4} 6.23 + cd mercurial-\emph{version} 6.24 + python setup.py install --force --home=\$HOME 6.25 + \end{codesample4} 6.26 +\end{enumerate} 6.27 +Once the install finishes, Mercurial will be in the \texttt{bin} 6.28 +subdirectory of your home directory. Don't forget to make sure that 6.29 +this directory is present in your shell's search path. 6.30 + 6.31 +You will probably need to set the \envar{PYTHONPATH} environment 6.32 +variable so that the Mercurial executable can find the rest of the 6.33 +Mercurial packages. For example, on my laptop, I have set it to 6.34 +\texttt{/home/bos/lib/python}. The exact path that you will need to 6.35 +use depends on how Python was built for your system, but should be 6.36 +easy to figure out. If you're uncertain, look through the output of 6.37 +the installer script above, and see where the contents of the 6.38 +\texttt{mercurial} directory were installed to. 6.39 + 6.40 +\section{On Windows} 6.41 + 6.42 +Building and installing Mercurial on Windows requires a variety of 6.43 +tools, a fair amount of technical knowledge, and considerable 6.44 +patience. I very much \emph{do not recommend} this route if you are a 6.45 +``casual user''. Unless you intend to hack on Mercurial, I strongly 6.46 +suggest that you use a binary package instead. 6.47 + 6.48 +If you are intent on building Mercurial from source on Windows, follow 6.49 +the ``hard way'' directions on the Mercurial wiki at 6.50 +\url{http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall}, 6.51 +and expect the process to involve a lot of fiddly work. 6.52 + 6.53 +%%% Local Variables: 6.54 +%%% mode: latex 6.55 +%%% TeX-master: "00book" 6.56 +%%% End:
7.1 --- a/es/template.tex Fri Nov 07 21:33:22 2008 -0500 7.2 +++ b/es/template.tex Fri Nov 07 21:42:57 2008 -0500 7.3 @@ -0,0 +1,475 @@ 7.4 +\chapter{Customising the output of Mercurial} 7.5 +\label{chap:template} 7.6 + 7.7 +Mercurial provides a powerful mechanism to let you control how it 7.8 +displays information. The mechanism is based on templates. You can 7.9 +use templates to generate specific output for a single command, or to 7.10 +customise the entire appearance of the built-in web interface. 7.11 + 7.12 +\section{Using precanned output styles} 7.13 +\label{sec:style} 7.14 + 7.15 +Packaged with Mercurial are some output styles that you can use 7.16 +immediately. A style is simply a precanned template that someone 7.17 +wrote and installed somewhere that Mercurial can find. 7.18 + 7.19 +Before we take a look at Mercurial's bundled styles, let's review its 7.20 +normal output. 7.21 + 7.22 +\interaction{template.simple.normal} 7.23 + 7.24 +This is somewhat informative, but it takes up a lot of space---five 7.25 +lines of output per changeset. The \texttt{compact} style reduces 7.26 +this to three lines, presented in a sparse manner. 7.27 + 7.28 +\interaction{template.simple.compact} 7.29 + 7.30 +The \texttt{changelog} style hints at the expressive power of 7.31 +Mercurial's templating engine. This style attempts to follow the GNU 7.32 +Project's changelog guidelines\cite{web:changelog}. 7.33 + 7.34 +\interaction{template.simple.changelog} 7.35 + 7.36 +You will not be shocked to learn that Mercurial's default output style 7.37 +is named \texttt{default}. 7.38 + 7.39 +\subsection{Setting a default style} 7.40 + 7.41 +You can modify the output style that Mercurial will use for every 7.42 +command by editing your \hgrc\ file, naming the style you would 7.43 +prefer to use. 7.44 + 7.45 +\begin{codesample2} 7.46 + [ui] 7.47 + style = compact 7.48 +\end{codesample2} 7.49 + 7.50 +If you write a style of your own, you can use it by either providing 7.51 +the path to your style file, or copying your style file into a 7.52 +location where Mercurial can find it (typically the \texttt{templates} 7.53 +subdirectory of your Mercurial install directory). 7.54 + 7.55 +\section{Commands that support styles and templates} 7.56 + 7.57 +All of Mercurial's ``\texttt{log}-like'' commands let you use styles 7.58 +and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and 7.59 +\hgcmd{tip}. 7.60 + 7.61 +As I write this manual, these are so far the only commands that 7.62 +support styles and templates. Since these are the most important 7.63 +commands that need customisable output, there has been little pressure 7.64 +from the Mercurial user community to add style and template support to 7.65 +other commands. 7.66 + 7.67 +\section{The basics of templating} 7.68 + 7.69 +At its simplest, a Mercurial template is a piece of text. Some of the 7.70 +text never changes, while other parts are \emph{expanded}, or replaced 7.71 +with new text, when necessary. 7.72 + 7.73 +Before we continue, let's look again at a simple example of 7.74 +Mercurial's normal output. 7.75 + 7.76 +\interaction{template.simple.normal} 7.77 + 7.78 +Now, let's run the same command, but using a template to change its 7.79 +output. 7.80 + 7.81 +\interaction{template.simple.simplest} 7.82 + 7.83 +The example above illustrates the simplest possible template; it's 7.84 +just a piece of static text, printed once for each changeset. The 7.85 +\hgopt{log}{--template} option to the \hgcmd{log} command tells 7.86 +Mercurial to use the given text as the template when printing each 7.87 +changeset. 7.88 + 7.89 +Notice that the template string above ends with the text 7.90 +``\Verb+\n+''. This is an \emph{escape sequence}, telling Mercurial 7.91 +to print a newline at the end of each template item. If you omit this 7.92 +newline, Mercurial will run each piece of output together. See 7.93 +section~\ref{sec:template:escape} for more details of escape sequences. 7.94 + 7.95 +A template that prints a fixed string of text all the time isn't very 7.96 +useful; let's try something a bit more complex. 7.97 + 7.98 +\interaction{template.simple.simplesub} 7.99 + 7.100 +As you can see, the string ``\Verb+{desc}+'' in the template has been 7.101 +replaced in the output with the description of each changeset. Every 7.102 +time Mercurial finds text enclosed in curly braces (``\texttt{\{}'' 7.103 +and ``\texttt{\}}''), it will try to replace the braces and text with 7.104 +the expansion of whatever is inside. To print a literal curly brace, 7.105 +you must escape it, as described in section~\ref{sec:template:escape}. 7.106 + 7.107 +\section{Common template keywords} 7.108 +\label{sec:template:keyword} 7.109 + 7.110 +You can start writing simple templates immediately using the keywords 7.111 +below. 7.112 + 7.113 +\begin{itemize} 7.114 +\item[\tplkword{author}] String. The unmodified author of the changeset. 7.115 +\item[\tplkword{branches}] String. The name of the branch on which 7.116 + the changeset was committed. Will be empty if the branch name was 7.117 + \texttt{default}. 7.118 +\item[\tplkword{date}] Date information. The date when the changeset 7.119 + was committed. This is \emph{not} human-readable; you must pass it 7.120 + through a filter that will render it appropriately. See 7.121 + section~\ref{sec:template:filter} for more information on filters. 7.122 + The date is expressed as a pair of numbers. The first number is a 7.123 + Unix UTC timestamp (seconds since January 1, 1970); the second is 7.124 + the offset of the committer's timezone from UTC, in seconds. 7.125 +\item[\tplkword{desc}] String. The text of the changeset description. 7.126 +\item[\tplkword{files}] List of strings. All files modified, added, or 7.127 + removed by this changeset. 7.128 +\item[\tplkword{file\_adds}] List of strings. Files added by this 7.129 + changeset. 7.130 +\item[\tplkword{file\_dels}] List of strings. Files removed by this 7.131 + changeset. 7.132 +\item[\tplkword{node}] String. The changeset identification hash, as a 7.133 + 40-character hexadecimal string. 7.134 +\item[\tplkword{parents}] List of strings. The parents of the 7.135 + changeset. 7.136 +\item[\tplkword{rev}] Integer. The repository-local changeset revision 7.137 + number. 7.138 +\item[\tplkword{tags}] List of strings. Any tags associated with the 7.139 + changeset. 7.140 +\end{itemize} 7.141 + 7.142 +A few simple experiments will show us what to expect when we use these 7.143 +keywords; you can see the results in 7.144 +figure~\ref{fig:template:keywords}. 7.145 + 7.146 +\begin{figure} 7.147 + \interaction{template.simple.keywords} 7.148 + \caption{Template keywords in use} 7.149 + \label{fig:template:keywords} 7.150 +\end{figure} 7.151 + 7.152 +As we noted above, the date keyword does not produce human-readable 7.153 +output, so we must treat it specially. This involves using a 7.154 +\emph{filter}, about which more in section~\ref{sec:template:filter}. 7.155 + 7.156 +\interaction{template.simple.datekeyword} 7.157 + 7.158 +\section{Escape sequences} 7.159 +\label{sec:template:escape} 7.160 + 7.161 +Mercurial's templating engine recognises the most commonly used escape 7.162 +sequences in strings. When it sees a backslash (``\Verb+\+'') 7.163 +character, it looks at the following character and substitutes the two 7.164 +characters with a single replacement, as described below. 7.165 + 7.166 +\begin{itemize} 7.167 +\item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'', 7.168 + ASCII~134. 7.169 +\item[\Verb+\textbackslash n+] Newline, ASCII~12. 7.170 +\item[\Verb+\textbackslash r+] Carriage return, ASCII~15. 7.171 +\item[\Verb+\textbackslash t+] Tab, ASCII~11. 7.172 +\item[\Verb+\textbackslash v+] Vertical tab, ASCII~13. 7.173 +\item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173. 7.174 +\item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175. 7.175 +\end{itemize} 7.176 + 7.177 +As indicated above, if you want the expansion of a template to contain 7.178 +a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you 7.179 +must escape it. 7.180 + 7.181 +\section{Filtering keywords to change their results} 7.182 +\label{sec:template:filter} 7.183 + 7.184 +Some of the results of template expansion are not immediately easy to 7.185 +use. Mercurial lets you specify an optional chain of \emph{filters} 7.186 +to modify the result of expanding a keyword. You have already seen a 7.187 +common filter, \tplkwfilt{date}{isodate}, in action above, to make a 7.188 +date readable. 7.189 + 7.190 +Below is a list of the most commonly used filters that Mercurial 7.191 +supports. While some filters can be applied to any text, others can 7.192 +only be used in specific circumstances. The name of each filter is 7.193 +followed first by an indication of where it can be used, then a 7.194 +description of its effect. 7.195 + 7.196 +\begin{itemize} 7.197 +\item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+'' 7.198 + tag before the end of every line except the last. For example, 7.199 + ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''. 7.200 +\item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the 7.201 + age of the date, relative to the current time. Yields a string like 7.202 + ``\Verb+10 minutes+''. 7.203 +\item[\tplfilter{basename}] Any text, but most useful for the 7.204 + \tplkword{files} keyword and its relatives. Treat the text as a 7.205 + path, and return the basename. For example, ``\Verb+foo/bar/baz+'' 7.206 + becomes ``\Verb+baz+''. 7.207 +\item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date 7.208 + in a similar format to the Unix \tplkword{date} command, but with 7.209 + timezone included. Yields a string like 7.210 + ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''. 7.211 +\item[\tplkwfilt{author}{domain}] Any text, but most useful for the 7.212 + \tplkword{author} keyword. Finds the first string that looks like 7.213 + an email address, and extract just the domain component. For 7.214 + example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes 7.215 + ``\Verb+serpentine.com+''. 7.216 +\item[\tplkwfilt{author}{email}] Any text, but most useful for the 7.217 + \tplkword{author} keyword. Extract the first string that looks like 7.218 + an email address. For example, 7.219 + ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes 7.220 + ``\Verb+bos@serpentine.com+''. 7.221 +\item[\tplfilter{escape}] Any text. Replace the special XML/XHTML 7.222 + characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with 7.223 + XML entities. 7.224 +\item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68 7.225 + columns. This is useful before you pass text through the 7.226 + \tplfilter{tabindent} filter, and still want it to fit in an 7.227 + 80-column fixed-font window. 7.228 +\item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76 7.229 + columns. 7.230 +\item[\tplfilter{firstline}] Any text. Yield the first line of text, 7.231 + without any trailing newlines. 7.232 +\item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the 7.233 + date as a pair of readable numbers. Yields a string like 7.234 + ``\Verb+1157407993 25200+''. 7.235 +\item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the 7.236 + date as a text string in ISO~8601 format. Yields a string like 7.237 + ``\Verb+2006-09-04 15:13:13 -0700+''. 7.238 +\item[\tplfilter{obfuscate}] Any text, but most useful for the 7.239 + \tplkword{author} keyword. Yield the input text rendered as a 7.240 + sequence of XML entities. This helps to defeat some particularly 7.241 + stupid screen-scraping email harvesting spambots. 7.242 +\item[\tplkwfilt{author}{person}] Any text, but most useful for the 7.243 + \tplkword{author} keyword. Yield the text before an email address. 7.244 + For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' 7.245 + becomes ``\Verb+Bryan O'Sullivan+''. 7.246 +\item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a 7.247 + date using the same format used in email headers. Yields a string 7.248 + like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''. 7.249 +\item[\tplkwfilt{node}{short}] Changeset hash. Yield the short form 7.250 + of a changeset hash, i.e.~a 12-byte hexadecimal string. 7.251 +\item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render 7.252 + the year, month, and day of the date. Yields a string like 7.253 + ``\Verb+2006-09-04+''. 7.254 +\item[\tplfilter{strip}] Any text. Strip all leading and trailing 7.255 + whitespace from the string. 7.256 +\item[\tplfilter{tabindent}] Any text. Yield the text, with every line 7.257 + except the first starting with a tab character. 7.258 +\item[\tplfilter{urlescape}] Any text. Escape all characters that are 7.259 + considered ``special'' by URL parsers. For example, \Verb+foo bar+ 7.260 + becomes \Verb+foo%20bar+. 7.261 +\item[\tplkwfilt{author}{user}] Any text, but most useful for the 7.262 + \tplkword{author} keyword. Return the ``user'' portion of an email 7.263 + address. For example, 7.264 + ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes 7.265 + ``\Verb+bos+''. 7.266 +\end{itemize} 7.267 + 7.268 +\begin{figure} 7.269 + \interaction{template.simple.manyfilters} 7.270 + \caption{Template filters in action} 7.271 + \label{fig:template:filters} 7.272 +\end{figure} 7.273 + 7.274 +\begin{note} 7.275 + If you try to apply a filter to a piece of data that it cannot 7.276 + process, Mercurial will fail and print a Python exception. For 7.277 + example, trying to run the output of the \tplkword{desc} keyword 7.278 + into the \tplkwfilt{date}{isodate} filter is not a good idea. 7.279 +\end{note} 7.280 + 7.281 +\subsection{Combining filters} 7.282 + 7.283 +It is easy to combine filters to yield output in the form you would 7.284 +like. The following chain of filters tidies up a description, then 7.285 +makes sure that it fits cleanly into 68 columns, then indents it by a 7.286 +further 8~characters (at least on Unix-like systems, where a tab is 7.287 +conventionally 8~characters wide). 7.288 + 7.289 +\interaction{template.simple.combine} 7.290 + 7.291 +Note the use of ``\Verb+\t+'' (a tab character) in the template to 7.292 +force the first line to be indented; this is necessary since 7.293 +\tplkword{tabindent} indents all lines \emph{except} the first. 7.294 + 7.295 +Keep in mind that the order of filters in a chain is significant. The 7.296 +first filter is applied to the result of the keyword; the second to 7.297 +the result of the first filter; and so on. For example, using 7.298 +\Verb+fill68|tabindent+ gives very different results from 7.299 +\Verb+tabindent|fill68+. 7.300 + 7.301 + 7.302 +\section{From templates to styles} 7.303 + 7.304 +A command line template provides a quick and simple way to format some 7.305 +output. Templates can become verbose, though, and it's useful to be 7.306 +able to give a template a name. A style file is a template with a 7.307 +name, stored in a file. 7.308 + 7.309 +More than that, using a style file unlocks the power of Mercurial's 7.310 +templating engine in ways that are not possible using the command line 7.311 +\hgopt{log}{--template} option. 7.312 + 7.313 +\subsection{The simplest of style files} 7.314 + 7.315 +Our simple style file contains just one line: 7.316 + 7.317 +\interaction{template.simple.rev} 7.318 + 7.319 +This tells Mercurial, ``if you're printing a changeset, use the text 7.320 +on the right as the template''. 7.321 + 7.322 +\subsection{Style file syntax} 7.323 + 7.324 +The syntax rules for a style file are simple. 7.325 + 7.326 +\begin{itemize} 7.327 +\item The file is processed one line at a time. 7.328 + 7.329 +\item Leading and trailing white space are ignored. 7.330 + 7.331 +\item Empty lines are skipped. 7.332 + 7.333 +\item If a line starts with either of the characters ``\texttt{\#}'' or 7.334 + ``\texttt{;}'', the entire line is treated as a comment, and skipped 7.335 + as if empty. 7.336 + 7.337 +\item A line starts with a keyword. This must start with an 7.338 + alphabetic character or underscore, and can subsequently contain any 7.339 + alphanumeric character or underscore. (In regexp notation, a 7.340 + keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.) 7.341 + 7.342 +\item The next element must be an ``\texttt{=}'' character, which can 7.343 + be preceded or followed by an arbitrary amount of white space. 7.344 + 7.345 +\item If the rest of the line starts and ends with matching quote 7.346 + characters (either single or double quote), it is treated as a 7.347 + template body. 7.348 + 7.349 +\item If the rest of the line \emph{does not} start with a quote 7.350 + character, it is treated as the name of a file; the contents of this 7.351 + file will be read and used as a template body. 7.352 +\end{itemize} 7.353 + 7.354 +\section{Style files by example} 7.355 + 7.356 +To illustrate how to write a style file, we will construct a few by 7.357 +example. Rather than provide a complete style file and walk through 7.358 +it, we'll mirror the usual process of developing a style file by 7.359 +starting with something very simple, and walking through a series of 7.360 +successively more complete examples. 7.361 + 7.362 +\subsection{Identifying mistakes in style files} 7.363 + 7.364 +If Mercurial encounters a problem in a style file you are working on, 7.365 +it prints a terse error message that, once you figure out what it 7.366 +means, is actually quite useful. 7.367 + 7.368 +\interaction{template.svnstyle.syntax.input} 7.369 + 7.370 +Notice that \filename{broken.style} attempts to define a 7.371 +\texttt{changeset} keyword, but forgets to give any content for it. 7.372 +When instructed to use this style file, Mercurial promptly complains. 7.373 + 7.374 +\interaction{template.svnstyle.syntax.error} 7.375 + 7.376 +This error message looks intimidating, but it is not too hard to 7.377 +follow. 7.378 + 7.379 +\begin{itemize} 7.380 +\item The first component is simply Mercurial's way of saying ``I am 7.381 + giving up''. 7.382 + \begin{codesample4} 7.383 + \textbf{abort:} broken.style:1: parse error 7.384 + \end{codesample4} 7.385 + 7.386 +\item Next comes the name of the style file that contains the error. 7.387 + \begin{codesample4} 7.388 + abort: \textbf{broken.style}:1: parse error 7.389 + \end{codesample4} 7.390 + 7.391 +\item Following the file name is the line number where the error was 7.392 + encountered. 7.393 + \begin{codesample4} 7.394 + abort: broken.style:\textbf{1}: parse error 7.395 + \end{codesample4} 7.396 + 7.397 +\item Finally, a description of what went wrong. 7.398 + \begin{codesample4} 7.399 + abort: broken.style:1: \textbf{parse error} 7.400 + \end{codesample4} 7.401 + The description of the problem is not always clear (as in this 7.402 + case), but even when it is cryptic, it is almost always trivial to 7.403 + visually inspect the offending line in the style file and see what 7.404 + is wrong. 7.405 +\end{itemize} 7.406 + 7.407 +\subsection{Uniquely identifying a repository} 7.408 + 7.409 +If you would like to be able to identify a Mercurial repository 7.410 +``fairly uniquely'' using a short string as an identifier, you can 7.411 +use the first revision in the repository. 7.412 +\interaction{template.svnstyle.id} 7.413 +This is not guaranteed to be unique, but it is nevertheless useful in 7.414 +many cases. 7.415 +\begin{itemize} 7.416 +\item It will not work in a completely empty repository, because such 7.417 + a repository does not have a revision~zero. 7.418 +\item Neither will it work in the (extremely rare) case where a 7.419 + repository is a merge of two or more formerly independent 7.420 + repositories, and you still have those repositories around. 7.421 +\end{itemize} 7.422 +Here are some uses to which you could put this identifier: 7.423 +\begin{itemize} 7.424 +\item As a key into a table for a database that manages repositories 7.425 + on a server. 7.426 +\item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple. 7.427 + Save this information away when you run an automated build or other 7.428 + activity, so that you can ``replay'' the build later if necessary. 7.429 +\end{itemize} 7.430 + 7.431 +\subsection{Mimicking Subversion's output} 7.432 + 7.433 +Let's try to emulate the default output format used by another 7.434 +revision control tool, Subversion. 7.435 +\interaction{template.svnstyle.short} 7.436 + 7.437 +Since Subversion's output style is fairly simple, it is easy to 7.438 +copy-and-paste a hunk of its output into a file, and replace the text 7.439 +produced above by Subversion with the template values we'd like to see 7.440 +expanded. 7.441 +\interaction{template.svnstyle.template} 7.442 + 7.443 +There are a few small ways in which this template deviates from the 7.444 +output produced by Subversion. 7.445 +\begin{itemize} 7.446 +\item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep 7.447 + 2006}'' in the example output above) in parentheses. Mercurial's 7.448 + templating engine does not provide a way to display a date in this 7.449 + format without also printing the time and time zone. 7.450 +\item We emulate Subversion's printing of ``separator'' lines full of 7.451 + ``\texttt{-}'' characters by ending the template with such a line. 7.452 + We use the templating engine's \tplkword{header} keyword to print a 7.453 + separator line as the first line of output (see below), thus 7.454 + achieving similar output to Subversion. 7.455 +\item Subversion's output includes a count in the header of the number 7.456 + of lines in the commit message. We cannot replicate this in 7.457 + Mercurial; the templating engine does not currently provide a filter 7.458 + that counts the number of items it is passed. 7.459 +\end{itemize} 7.460 +It took me no more than a minute or two of work to replace literal 7.461 +text from an example of Subversion's output with some keywords and 7.462 +filters to give the template above. The style file simply refers to 7.463 +the template. 7.464 +\interaction{template.svnstyle.style} 7.465 + 7.466 +We could have included the text of the template file directly in the 7.467 +style file by enclosing it in quotes and replacing the newlines with 7.468 +``\verb!\n!'' sequences, but it would have made the style file too 7.469 +difficult to read. Readability is a good guide when you're trying to 7.470 +decide whether some text belongs in a style file, or in a template 7.471 +file that the style file points to. If the style file will look too 7.472 +big or cluttered if you insert a literal piece of text, drop it into a 7.473 +template instead. 7.474 + 7.475 +%%% Local Variables: 7.476 +%%% mode: latex 7.477 +%%% TeX-master: "00book" 7.478 +%%% End: