hgbook
changeset 88:d351032c189c
Progress with log coverage.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu Oct 12 10:33:03 2006 -0700 (2006-10-12) |
parents | 0995016342f8 |
children | 2914e2373139 |
files | en/examples/tour en/tour.tex |
line diff
1.1 --- a/en/examples/tour Wed Oct 04 17:11:53 2006 -0700 1.2 +++ b/en/examples/tour Thu Oct 12 10:33:03 2006 -0700 1.3 @@ -16,3 +16,22 @@ 1.4 1.5 ls -l 1.6 ls hello 1.7 + 1.8 +#$ name: ls-a 1.9 + 1.10 +cd hello 1.11 +ls -a 1.12 + 1.13 +#$ name: log 1.14 + 1.15 +hg log 1.16 + 1.17 +#$ name: log-r 1.18 + 1.19 +hg log -r 3 1.20 +hg log -r ff5d7b70a2a9 1.21 +hg log -r 1 -r 4 1.22 + 1.23 +#$ name: log.range 1.24 + 1.25 +hg log -r 2:4
2.1 --- a/en/tour.tex Wed Oct 04 17:11:53 2006 -0700 2.2 +++ b/en/tour.tex Thu Oct 12 10:33:03 2006 -0700 2.3 @@ -108,7 +108,7 @@ 2.4 You can rename delete a repository any time you like, using either the 2.5 command line or your file browser. 2.6 2.7 -\subsection{Making a copy of a repository} 2.8 +\subsection{Making a local copy of a repository} 2.9 2.10 \emph{Copying} a repository is just a little bit special. While you 2.11 could use a normal file copying command to make a copy of a 2.12 @@ -132,6 +132,105 @@ 2.13 repository, safe in the knowledge that it's a private ``sandbox'' that 2.14 won't affect anyone else. 2.15 2.16 +\subsection{What's in a repository?} 2.17 + 2.18 +When we take a more detailed look inside a repository, we can see that 2.19 +it contains a directory named \dirname{.hg}. This is where Mercurial 2.20 +keeps all of its metadata for the repository. 2.21 +\interaction{tour.ls-a} 2.22 + 2.23 +The contents of the \dirname{.hg} directory and its subdirectories are 2.24 +private to Mercurial. Every other file and directory in the 2.25 +repository is yours to do with as you please. 2.26 + 2.27 +To introduce a little terminology, the \dirname{.hg} directory is the 2.28 +``real'' repository, and all of the files and directories that coexist 2.29 +with it are said to live in the ``working directory''. An easy way to 2.30 +remember the distinction is that the \emph{repository} contains the 2.31 +\emph{history} of your project, while the \emph{working directory} 2.32 +contains a \emph{snapshot} of your project at a particular point in 2.33 +history. 2.34 + 2.35 +\section{A tour through history} 2.36 + 2.37 +One of the first things we might want to do with a new, unfamiliar 2.38 +repository is understand its history. The \hgcmd{log} command gives 2.39 +us a view of history. 2.40 +\interaction{tour.log} 2.41 +By default, this command prints a brief paragraph of output for each 2.42 +change to the project that was recorded. In Mercurial terminology, we 2.43 +call each of these recorded events a \emph{changeset}, because it can 2.44 +contain a record of changes to several files. 2.45 + 2.46 +The fields in a record of output from \hgcmd{log} are as follows. 2.47 +\begin{itemize} 2.48 +\item[\texttt{changeset}] This field has the format of a number, 2.49 + followed by a colon, followed by a hexadecimal string. These are 2.50 + \emph{identifiers} for the changeset. There are two identifiers 2.51 + because the number is shorter and easier to type than the hex 2.52 + string. 2.53 +\item[\texttt{user}] The identity of the person who created the 2.54 + changeset. This is a free-form field, but it most often contains a 2.55 + person's name and email address. 2.56 +\item[\texttt{date}] The date and time on which the changeset was 2.57 + created, and the timezone in which it was created. (Thef date and 2.58 + time are local to that timezone; they display what time and date it 2.59 + was for the person who created the changeset.) 2.60 +\item[\texttt{summary}] The first line of the text message that the 2.61 + creator of the changeset entered to describe the changeset. 2.62 +\end{itemize} 2.63 +The default output printed by \hgcmd{log} is purely a summary; it is 2.64 +missing a lot of detail. 2.65 + 2.66 +\subsection{Changesets, revisions, and identification} 2.67 + 2.68 +English being a notoriously sloppy language, we have a variety of 2.69 +terms that have the same meaning. If you are talking about Mercurial 2.70 +history with other people, you will find that the word ``changeset'' 2.71 +is often compressed to ``change'' or ``cset'', and sometimes a 2.72 +changeset is referred to as a ``revision'' or a ``rev''. 2.73 + 2.74 +While it doesn't matter what \emph{word} you use to refer to the 2.75 +concept of ``a~changeset'', the \emph{identifier} that you use to 2.76 +refer to ``a~\emph{specific} changeset'' is of great importance. 2.77 +Recall that the \texttt{changeset} field in the output from 2.78 +\hgcmd{log} identifies a changeset using both a number and a 2.79 +hexadecimal string. The number is \emph{only valid in that 2.80 + repository}, while the hex string is the \emph{permanent, unchanging 2.81 + identifier} that will always identify that changeset in every copy 2.82 +of the repository. 2.83 + 2.84 +This distinction is important. If you send someone an email talking 2.85 +about ``revision~33'', there's a high likelihood that their 2.86 +revision~33 will \emph{not be the same} as yours. The reason for this 2.87 +is that a revision number depends on the order in which changes 2.88 +arrived in a repository, and there is no guarantee that the same 2.89 +changes will happen in the same order in different repositories. 2.90 +Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, 2.91 +while in another as $1,0,2$. 2.92 + 2.93 +Mercurial uses revision numbers purely as a convenient shorthand. If 2.94 +you need to discuss a changeset with someone, or make a record of a 2.95 +changeset for some other reason (for example, in a bug report), use 2.96 +the hexadecimal identifier. 2.97 + 2.98 +\subsection{Viewing specific revisions} 2.99 + 2.100 +To narrow the output of \hgcmd{log} down to a single revision, use the 2.101 +\hgopt{log}{-r} option. You can use either a revision number or a 2.102 +long-form changeset identifier, and you can provide as many revisions 2.103 +as you want. 2.104 +\interaction{tour.log-r} 2.105 + 2.106 +If you want to see the history of several revisions without having to 2.107 +list each one, you can use \emph{range notation}; this lets you 2.108 +express the idea ``I want all revisions between $a$ and $b$, 2.109 +inclusive''. 2.110 +\interaction{tour.log.range} 2.111 +Mercurial also honours the order in which you specify revisions, so 2.112 +\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} 2.113 +prints $4,3,2$. 2.114 + 2.115 %%% Local Variables: 2.116 %%% mode: latex 2.117 %%% TeX-master: "00book"