Mercurial > hgbook
changeset 785:7dd855842de4
more tour-basic.tex
| author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
|---|---|
| date | Sat, 06 Jun 2009 17:12:36 +0900 |
| parents | 386cdca52f0b |
| children | 11bc9d788428 |
| files | ja/tour-basic.tex |
| diffstat | 1 files changed, 442 insertions(+), 372 deletions(-) [+] |
line wrap: on
line diff
--- a/ja/tour-basic.tex Wed Jun 03 19:12:11 2009 +0900 +++ b/ja/tour-basic.tex Sat Jun 06 17:12:36 2009 +0900 @@ -220,496 +220,566 @@ %\subsection{What's in a repository?} \subsection{$B%j%]%8%H%j$K$O2?$,4^$^$l$k$+!)(B} -When we take a more detailed look inside a repository, we can see that -it contains a directory named \dirname{.hg}. This is where Mercurial -keeps all of its metadata for the repository. +%When we take a more detailed look inside a repository, we can see that +%it contains a directory named \dirname{.hg}. This is where Mercurial +%keeps all of its metadata for the repository. +%\interaction{tour.ls-a} + +$B%j%]%8%H%j$NFbIt$r$h$j>\$7$/8+$F$_$k$H!$(B\dirname{.hg}$B$H$$$&%G%#%l%/%H%j(B +$B$,$"$k$N$K5$$E$/!%(BMercurial$B$O$3$3$K%j%]%8%H%j$N$?$a$N%a%?%G!<%?$rJ]4I$7(B +$B$F$$$k!%(B \interaction{tour.ls-a} -The contents of the \dirname{.hg} directory and its subdirectories are -private to Mercurial. Every other file and directory in the -repository is yours to do with as you please. +%The contents of the \dirname{.hg} directory and its subdirectories are +%private to Mercurial. Every other file and directory in the +%repository is yours to do with as you please. + +\dirname{.hg}$B%G%#%l%/%H%j$NCf?H$H!$$3$N%G%#%l%/%H%j$N%5%V%G%#%l%/%H%j$O(B +Mercurial$B@lMQ$N$b$N$G$"$k!%%j%]%8%H%j$N$=$l0J30$N%U%!%$%k$H%G%#%l%/%H%j(B +$B$O%f!<%6$KB0$9!%(B -To introduce a little terminology, the \dirname{.hg} directory is the -``real'' repository, and all of the files and directories that coexist -with it are said to live in the \emph{working directory}. An easy way -to remember the distinction is that the \emph{repository} contains the -\emph{history} of your project, while the \emph{working directory} -contains a \emph{snapshot} of your project at a particular point in -history. +%To introduce a little terminology, the \dirname{.hg} directory is the +%``real'' repository, and all of the files and directories that coexist +%with it are said to live in the \emph{working directory}. An easy way +%to remember the distinction is that the \emph{repository} contains the +%\emph{history} of your project, while the \emph{working directory} +%contains a \emph{snapshot} of your project at a particular point in +%history. + +$B$3$3$G>/!9MQ8l$rDj5A$7$h$&$H;W$&!%(B\dirname{.hg}$B%G%#%l%/%H%j$r(B``$B%j%"%k(B''$B%j(B +$B%]%8%H%j!$$3$N%G%#%l%/%H%j$H0l=o$K07$o$l$k%U%!%$%k$d%G%#%l%/%H%j$r(B +\emph{$B%o!<%-%s%0%G%#%l%/%H%j(B}$B$H8F$V$3$H$K$9$k!%$3$l$i$r4JC1$K6hJL$9$k$?$a(B +$B$K!$(B\emph{$B%j%]%8%H%j(B}$B$O%W%m%8%'%/%H$N(B\emph{$BMzNr(B}$B$rJ]B8$7!$(B\emph{$B%o!<%-%s(B +$B%0%G%#%l%/%H%j(B}$B$O%W%m%8%'%/%H$NMzNr$NCf$N$"$k;~E@$N(B\emph{$B%9%J%C%W%7%g%C(B +$B%H(B}$B$r;}$D$H3P$($k$HNI$$!%(B %\section{A tour through history} \section{$BMzNr$rC)$k(B} -One of the first things we might want to do with a new, unfamiliar -repository is understand its history. The \hgcmd{log} command gives -us a view of history. +%One of the first things we might want to do with a new, unfamiliar +%repository is understand its history. The \hgcmd{log} command gives +%us a view of history. +%\interaction{tour.log} +%By default, this command prints a brief paragraph of output for each +%change to the project that was recorded. In Mercurial terminology, we +%call each of these recorded events a \emph{changeset}, because it can +%contain a record of changes to several files. + +$BL$CN$N%j%]%8%H%j$KBP$7$F$^$:$7$h$&$H;W$&$3$H$O!$$=$NMzNr$rCN$k$3$H$@$m$&!%(B +$BMzNr$O(B\hgcmd{log}$B%3%^%s%I$G8+$k$3$H$,$G$-$k!%(B \interaction{tour.log} -By default, this command prints a brief paragraph of output for each -change to the project that was recorded. In Mercurial terminology, we -call each of these recorded events a \emph{changeset}, because it can -contain a record of changes to several files. +$B%G%U%)%k%H$G$O!$$3$N%3%^%s%I$O%W%m%8%'%/%H$KBP$7$F9T$o$l$?JQ99$N3F!9$K$D(B +$B$$$F4J7i$J%Q%i%0%i%U$rI=<($9$k!%(B Mercurial$B$NMQ8l$G$O!$MzNrCf$NJQ99$N%$%Y(B +$B%s%H$r(B\emph{$B%A%'%s%8%;%C%H(B}$B$H8F$V!%$=$NM}M3$O!$J#?t$N%U%!%$%k$KBP$9$kJQ99(B +$B$N5-O?$r;}$AF@$k$+$i$G$"$k!%(B -The fields in a record of output from \hgcmd{log} are as follows. +%The fields in a record of output from \hgcmd{log} are as follows. +\hgcmd{log}$B$+$i=PNO$5$l$k5-O?$N3F%U%#!<%k%I$O<!$N$h$&$K$J$C$F$$$k!%(B \begin{itemize} -\item[\texttt{changeset}] This field has the format of a number, - followed by a colon, followed by a hexadecimal string. These are - \emph{identifiers} for the changeset. There are two identifiers - because the number is shorter and easier to type than the hex - string. -\item[\texttt{user}] The identity of the person who created the - changeset. This is a free-form field, but it most often contains a - person's name and email address. -\item[\texttt{date}] The date and time on which the changeset was - created, and the timezone in which it was created. (The date and - time are local to that timezone; they display what time and date it - was for the person who created the changeset.) -\item[\texttt{summary}] The first line of the text message that the - creator of the changeset entered to describe the changeset. +%\item[\texttt{changeset}] This field has the format of a number, +% followed by a colon, followed by a hexadecimal string. These are +% \emph{identifiers} for the changeset. There are two identifiers +% because the number is shorter and easier to type than the hex +% string. +\item[\texttt{changeset}] $B?t;z!$$=$l$KB3$/%3%m%s$*$h$S(B16$B?JJ8;zNs!%$3$l$O(B + $B%A%'%s%8%;%C%H$N(B\emph{$B<1JL;R(B}$B$G$"$k!%?t;z$OC;$/F~NO$bMF0W$G(B + $B$"$k$?$aMQ0U$5$l$F$$$k!%(B +%\item[\texttt{user}] The identity of the person who created the +% changeset. This is a free-form field, but it most often contains a +% person's name and email address. + \item[\texttt{user}] $B%A%'%s%8%;%C%H:n@.<T!%$3$N%U%#!<%k%I$N=q<0$O<+M3$@(B + $B$,!$KX$s$I$N>l9g;aL>$H(Bemail$B%"%I%l%9$G$"$k!%(B +%\item[\texttt{date}] The date and time on which the changeset was +% created, and the timezone in which it was created. (The date and +% time are local to that timezone; they display what time and date it +% was for the person who created the changeset.) + \item[\texttt{date}] $B%A%'%s%8%;%C%H$,:n@.$5$l$?F|IU$H;~9o$*$h$S%?%$%`%>!<(B + $B%s!%(B $B!JF|;~$O%A%'%s%8%;%C%H$N:n@.<T$NB0$9%?%$%`%>!<%s$K%m!<(B + $B%+%k$G$"$k!%!K(B +%\item[\texttt{summary}] The first line of the text message that the +% creator of the changeset entered to describe the changeset. + \item[\texttt{summary}] $B%F%-%9%H%a%C%;!<%8$N:G=i$N9T$O%A%'%s%8%;%C%H$N@b(B + $BL@$KF~NO$5$l$?%A%'%s%8%;%C%H$N:n@.<T$G$"$k!%(B \end{itemize} -The default output printed by \hgcmd{log} is purely a summary; it is -missing a lot of detail. +%The default output printed by \hgcmd{log} is purely a summary; it is +%missing a lot of detail. +\hgcmd{log}$B$N%G%U%)%k%H=PNO$OMWLs$K$9$.$:!$B?$/$N>\:Y>pJs$r7g$$$F$$$k!%(B -Figure~\ref{fig:tour-basic:history} provides a graphical representation of -the history of the \dirname{hello} repository, to make it a little -easier to see which direction history is ``flowing'' in. We'll be -returning to this figure several times in this chapter and the chapter -that follows. +%Figure~\ref{fig:tour-basic:history} provides a graphical representation of +%the history of the \dirname{hello} repository, to make it a little +%easier to see which direction history is ``flowing'' in. We'll be +%returning to this figure several times in this chapter and the chapter +%that follows. + +$B?^(B~\ref{fig:tour-basic:history}$B$O(B\dirname{hello}$B%j%]%8%H%j$NMzNr$r%0%i%UI=(B +$B<($7$?$b$N$G$"$k!%$3$NI=<($K$h$C$F$I$NJ}8~$NMzNr$,=gJ}8~$J$N$+M}2r$7$d$9(B +$B$/$J$C$F$$$k!%:#8e!$$3$N?^$r2?EY$+;2>H$9$k!%(B \begin{figure}[ht] \centering \grafix{tour-history} - \caption{Graphical history of the \dirname{hello} repository} - \label{fig:tour-basic:history} +% \caption{Graphical history of the \dirname{hello} repository} + \caption{\dirname{hello}$B%j%]%8%H%j$NMzNr%0%i%U(B} + \label{fig:tour-basic:history} \end{figure} %\subsection{Changesets, revisions, and talking to other people} \subsection{$B%A%'%s%8%;%C%H(B, $B%j%S%8%g%s(B, $BB>$N%f!<%6$H$N$d$j$H$j(B} -As English is a notoriously sloppy language, and computer science has -a hallowed history of terminological confusion (why use one term when -four will do?), revision control has a variety of words and phrases -that mean the same thing. If you are talking about Mercurial history -with other people, you will find that the word ``changeset'' is often -compressed to ``change'' or (when written) ``cset'', and sometimes a -changeset is referred to as a ``revision'' or a ``rev''. +%As English is a notoriously sloppy language, and computer science has +%a hallowed history of terminological confusion (why use one term when +%four will do?), revision control has a variety of words and phrases +%that mean the same thing. If you are talking about Mercurial history +%with other people, you will find that the word ``changeset'' is often +%compressed to ``change'' or (when written) ``cset'', and sometimes a +%changeset is referred to as a ``revision'' or a ``rev''. + +$B1Q8l$O$$$$2C8:$J$3$H$G0-L>$N9b$$8@8l$G$"$j!$%3%s%T%e!<%?%5%$%(%s%9$G$O@l(B +$BLgMQ8l$N:.Mp$,?S$@$7$$!%!J(B4$B?M$,(B1$B$D$NMQ8l$r;H$&$3$H$J$IM-$jF@$J$$!%!K%j%S(B +$B%8%g%s%3%s%H%m!<%k$OBt;3$NF15A8l$r;}$C$F$$$k!%B>$N?M$H(BMercurial$B$NMzNr$K$D(B +$B$$$FOC$9$H$-!$(B``$B%A%'%s%8%;%C%H(B''$B$,$7$P$7$P(B``$B%A%'%s%8(B''$B$KN,$5$l$?$j!$=q$-(B +$B8@MU$G$O(B``cset''$B$J$I$H$5$l$?$j!$;~$K$O%A%'%s%8%;%C%H$,(B``$B%j%S%8%g%s(B''$B$d(B +``rev''$B$HI=$5$l$?$j$9$k$3$H$K5$$E$/$@$m$&!%(B -While it doesn't matter what \emph{word} you use to refer to the -concept of ``a~changeset'', the \emph{identifier} that you use to -refer to ``a~\emph{specific} changeset'' is of great importance. -Recall that the \texttt{changeset} field in the output from -\hgcmd{log} identifies a changeset using both a number and a -hexadecimal string. +%While it doesn't matter what \emph{word} you use to refer to the +%concept of ``a~changeset'', the \emph{identifier} that you use to +%refer to ``a~\emph{specific} changeset'' is of great importance. +%Recall that the \texttt{changeset} field in the output from +%\hgcmd{log} identifies a changeset using both a number and a +%hexadecimal string. + +\emph{$BMQ8l(B} + +%\begin{itemize} +%\item The revision number is \emph{only valid in that repository}, +%\item while the hex string is the \emph{permanent, unchanging +% identifier} that will always identify that exact changeset in +% \emph{every} copy of the repository. +%\end{itemize} \begin{itemize} -\item The revision number is \emph{only valid in that repository}, -\item while the hex string is the \emph{permanent, unchanging - identifier} that will always identify that exact changeset in - \emph{every} copy of the repository. +\item $B%j%S%8%g%sHV9f$O(B\emph{$B$=$N%j%]%8%H%j$K8B$C$FM-8z$G$"$j(B}$B!$(B +\item $B$=$l$KBP$7$F(B16$B?JJ8;zNs$O(B\emph{$B1JB3E*$+$DITJQ$N<1JL;R(B}$B$G!$%j%]%8%H(B + $B%j$N%3%T!<(B\emph{$BA4$F(B}$B$G>o$KFCDj$N%A%'%s%8%;%C%H$r<($9!%(B \end{itemize} -This distinction is important. If you send someone an email talking -about ``revision~33'', there's a high likelihood that their -revision~33 will \emph{not be the same} as yours. The reason for this -is that a revision number depends on the order in which changes -arrived in a repository, and there is no guarantee that the same -changes will happen in the same order in different repositories. -Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, -while in another as $1,0,2$. + +%This distinction is important. If you send someone an email talking +%about ``revision~33'', there's a high likelihood that their +%revision~33 will \emph{not be the same} as yours. The reason for this +%is that a revision number depends on the order in which changes +%arrived in a repository, and there is no guarantee that the same +%changes will happen in the same order in different repositories. +%Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, +%while in another as $1,0,2$. + +$B$3$N6hJL$O=EMW$G$"$k!%(B``revision~33'' -Mercurial uses revision numbers purely as a convenient shorthand. If -you need to discuss a changeset with someone, or make a record of a -changeset for some other reason (for example, in a bug report), use -the hexadecimal identifier. + +%Mercurial uses revision numbers purely as a convenient shorthand. If +%you need to discuss a changeset with someone, or make a record of a +%changeset for some other reason (for example, in a bug report), use +%the hexadecimal identifier. + +Mercurial$B$O%j%S%8%g%sHV9f$rC1$KJXMx$N$?$a$NN,5-J}$H$7$FMQ$$$k!%C/$+$H%A%'(B +$B%s%8%;%C%H$K$D$$$F5DO@$7$?$j!$!J%P%0Js9p$J$I$N$?$a$K!K%A%'%s%8%;%C%H$r5-(B +$BO?$7$?$$>l9g$O(B16$B?J$N<1JL;R$rMxMQ$9$Y$-$G$"$k!%(B + + + %\subsection{Viewing specific revisions} \subsection{$BFCDj$N%j%S%8%g%s$r8+$k(B} -To narrow the output of \hgcmd{log} down to a single revision, use the -\hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a -revision number or a long-form changeset identifier, and you can -provide as many revisions as you want. \interaction{tour.log-r} +%To narrow the output of \hgcmd{log} down to a single revision, use the +%\hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a +%revision number or a long-form changeset identifier, and you can +%provide as many revisions as you want. \interaction{tour.log-r} -If you want to see the history of several revisions without having to -list each one, you can use \emph{range notation}; this lets you -express the idea ``I want all revisions between $a$ and $b$, -inclusive''. -\interaction{tour.log.range} -Mercurial also honours the order in which you specify revisions, so -\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} -prints $4,3,2$. +%If you want to see the history of several revisions without having to +%list each one, you can use \emph{range notation}; this lets you +%express the idea ``I want all revisions between $a$ and $b$, +%inclusive''. +%\interaction{tour.log.range} +%Mercurial also honours the order in which you specify revisions, so +%\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} +%prints $4,3,2$. %\subsection{More detailed information} \subsection{$B$h$j>\:Y$J>pJs(B} -While the summary information printed by \hgcmd{log} is useful if you -already know what you're looking for, you may need to see a complete -description of the change, or a list of the files changed, if you're -trying to decide whether a changeset is the one you're looking for. -The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) -option gives you this extra detail. -\interaction{tour.log-v} +%While the summary information printed by \hgcmd{log} is useful if you +%already know what you're looking for, you may need to see a complete +%description of the change, or a list of the files changed, if you're +%trying to decide whether a changeset is the one you're looking for. +%The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) +%option gives you this extra detail. +%\interaction{tour.log-v} -If you want to see both the description and content of a change, add -the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays -the content of a change as a \emph{unified diff} (if you've never seen -a unified diff before, see section~\ref{sec:mq:patch} for an overview). -\interaction{tour.log-vp} +%If you want to see both the description and content of a change, add +%the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays +%the content of a change as a \emph{unified diff} (if you've never seen +%a unified diff before, see section~\ref{sec:mq:patch} for an overview). +%\interaction{tour.log-vp} %\section{All about command options} \section{$B%3%^%s%I%*%W%7%g%s$N$9$Y$F(B} -Let's take a brief break from exploring Mercurial commands to discuss -a pattern in the way that they work; you may find this useful to keep -in mind as we continue our tour. +%Let's take a brief break from exploring Mercurial commands to discuss +%a pattern in the way that they work; you may find this useful to keep +%in mind as we continue our tour. -Mercurial has a consistent and straightforward approach to dealing -with the options that you can pass to commands. It follows the -conventions for options that are common to modern Linux and Unix -systems. -\begin{itemize} -\item Every option has a long name. For example, as we've already - seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. -\item Most options have short names, too. Instead of - \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that - some options don't have short names is that the options in question - are rarely used.) -\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), - while short options start with one (e.g.~\hgopt{log}{-r}). -\item Option naming and usage is consistent across commands. For - example, every command that lets you specify a changeset~ID or - revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} - arguments. -\end{itemize} -In the examples throughout this book, I use short options instead of -long. This just reflects my own preference, so don't read anything -significant into it. +%Mercurial has a consistent and straightforward approach to dealing +%with the options that you can pass to commands. It follows the +%conventions for options that are common to modern Linux and Unix +%systems. +%\begin{itemize} +%\item Every option has a long name. For example, as we've already +% seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. +%\item Most options have short names, too. Instead of +% \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that +% some options don't have short names is that the options in question +% are rarely used.) +%\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), +% while short options start with one (e.g.~\hgopt{log}{-r}). +%\item Option naming and usage is consistent across commands. For +% example, every command that lets you specify a changeset~ID or +% revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} +% arguments. +%\end{itemize} +%In the examples throughout this book, I use short options instead of +%long. This just reflects my own preference, so don't read anything +%significant into it. -Most commands that print output of some kind will print more output -when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less -when passed \hggopt{-q} (or \hggopt{--quiet}). +%Most commands that print output of some kind will print more output +%when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less +%when passed \hggopt{-q} (or \hggopt{--quiet}). %\section{Making and reviewing changes} \section{$BJQ99$N;EJ}!$JQ99$N%l%S%e!<(B} -Now that we have a grasp of viewing history in Mercurial, let's take a -look at making some changes and examining them. +%Now that we have a grasp of viewing history in Mercurial, let's take a +%look at making some changes and examining them. -The first thing we'll do is isolate our experiment in a repository of -its own. We use the \hgcmd{clone} command, but we don't need to -clone a copy of the remote repository. Since we already have a copy -of it locally, we can just clone that instead. This is much faster -than cloning over the network, and cloning a local repository uses -less disk space in most cases, too. -\interaction{tour.reclone} -As an aside, it's often good practice to keep a ``pristine'' copy of a -remote repository around, which you can then make temporary clones of -to create sandboxes for each task you want to work on. This lets you -work on multiple tasks in parallel, each isolated from the others -until it's complete and you're ready to integrate it back. Because -local clones are so cheap, there's almost no overhead to cloning and -destroying repositories whenever you want. +%The first thing we'll do is isolate our experiment in a repository of +%its own. We use the \hgcmd{clone} command, but we don't need to +%clone a copy of the remote repository. Since we already have a copy +%of it locally, we can just clone that instead. This is much faster +%than cloning over the network, and cloning a local repository uses +%less disk space in most cases, too. +%\interaction{tour.reclone} +%As an aside, it's often good practice to keep a ``pristine'' copy of a +%remote repository around, which you can then make temporary clones of +%to create sandboxes for each task you want to work on. This lets you +%work on multiple tasks in parallel, each isolated from the others +%until it's complete and you're ready to integrate it back. Because +%local clones are so cheap, there's almost no overhead to cloning and +%destroying repositories whenever you want. -In our \dirname{my-hello} repository, we have a file -\filename{hello.c} that contains the classic ``hello, world'' program. -Let's use the ancient and venerable \command{sed} command to edit this -file so that it prints a second line of output. (I'm only using -\command{sed} to do this because it's easy to write a scripted example -this way. Since you're not under the same constraint, you probably -won't want to use \command{sed}; simply use your preferred text editor to -do the same thing.) -\interaction{tour.sed} +%In our \dirname{my-hello} repository, we have a file +%\filename{hello.c} that contains the classic ``hello, world'' program. +%Let's use the ancient and venerable \command{sed} command to edit this +%file so that it prints a second line of output. (I'm only using +%\command{sed} to do this because it's easy to write a scripted example +%this way. Since you're not under the same constraint, you probably +%won't want to use \command{sed}; simply use your preferred text editor to +%do the same thing.) +%\interaction{tour.sed} -Mercurial's \hgcmd{status} command will tell us what Mercurial knows -about the files in the repository. -\interaction{tour.status} -The \hgcmd{status} command prints no output for some files, but a line -starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell -it to, \hgcmd{status} will not print any output for files that have -not been modified. +%Mercurial's \hgcmd{status} command will tell us what Mercurial knows +%about the files in the repository. +%\interaction{tour.status} +%The \hgcmd{status} command prints no output for some files, but a line +%starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell +%it to, \hgcmd{status} will not print any output for files that have +%not been modified. -The ``\texttt{M}'' indicates that Mercurial has noticed that we -modified \filename{hello.c}. We didn't need to \emph{inform} -Mercurial that we were going to modify the file before we started, or -that we had modified the file after we were done; it was able to -figure this out itself. +%The ``\texttt{M}'' indicates that Mercurial has noticed that we +%modified \filename{hello.c}. We didn't need to \emph{inform} +%Mercurial that we were going to modify the file before we started, or +%that we had modified the file after we were done; it was able to +%figure this out itself. -It's a little bit helpful to know that we've modified -\filename{hello.c}, but we might prefer to know exactly \emph{what} -changes we've made to it. To do this, we use the \hgcmd{diff} -command. -\interaction{tour.diff} +%It's a little bit helpful to know that we've modified +%\filename{hello.c}, but we might prefer to know exactly \emph{what} +%changes we've made to it. To do this, we use the \hgcmd{diff} +%command. +%\interaction{tour.diff} %\section{Recording changes in a new changeset} \section{$B?7$?$J%A%'%s%8%;%C%H$XJQ99$r5-O?$9$k(B} -We can modify files, build and test our changes, and use -\hgcmd{status} and \hgcmd{diff} to review our changes, until we're -satisfied with what we've done and arrive at a natural stopping point -where we want to record our work in a new changeset. +%We can modify files, build and test our changes, and use +%\hgcmd{status} and \hgcmd{diff} to review our changes, until we're +%satisfied with what we've done and arrive at a natural stopping point +%where we want to record our work in a new changeset. -The \hgcmd{commit} command lets us create a new changeset; we'll -usually refer to this as ``making a commit'' or ``committing''. +%The \hgcmd{commit} command lets us create a new changeset; we'll +%usually refer to this as ``making a commit'' or ``committing''. %\subsection{Setting up a username} \subsection{$B%f!<%6L>$r@_Dj$9$k(B} -When you try to run \hgcmd{commit} for the first time, it is not -guaranteed to succeed. Mercurial records your name and address with -each change that you commit, so that you and others will later be able -to tell who made each change. Mercurial tries to automatically figure -out a sensible username to commit the change with. It will attempt -each of the following methods, in order: -\begin{enumerate} -\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit} - command on the command line, followed by a username, this is always - given the highest precedence. -\item If you have set the \envar{HGUSER} environment variable, this is - checked next. -\item If you create a file in your home directory called - \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be - used next. To see what the contents of this file should look like, - refer to section~\ref{sec:tour-basic:username} below. -\item If you have set the \envar{EMAIL} environment variable, this - will be used next. -\item Mercurial will query your system to find out your local user - name and host name, and construct a username from these components. - Since this often results in a username that is not very useful, it - will print a warning if it has to do this. -\end{enumerate} -If all of these mechanisms fail, Mercurial will fail, printing an -error message. In this case, it will not let you commit until you set -up a username. +%When you try to run \hgcmd{commit} for the first time, it is not +%guaranteed to succeed. Mercurial records your name and address with +%each change that you commit, so that you and others will later be able +%to tell who made each change. Mercurial tries to automatically figure +%out a sensible username to commit the change with. It will attempt +%each of the following methods, in order: +%\begin{enumerate} +%\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit} +% command on the command line, followed by a username, this is always +% given the highest precedence. +%\item If you have set the \envar{HGUSER} environment variable, this is +% checked next. +%\item If you create a file in your home directory called +% \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be +% used next. To see what the contents of this file should look like, +% refer to section~\ref{sec:tour-basic:username} below. +%\item If you have set the \envar{EMAIL} environment variable, this +% will be used next. +%\item Mercurial will query your system to find out your local user +% name and host name, and construct a username from these components. +% Since this often results in a username that is not very useful, it +% will print a warning if it has to do this. +%\end{enumerate} +%If all of these mechanisms fail, Mercurial will fail, printing an +%error message. In this case, it will not let you commit until you set +%up a username. -You should think of the \envar{HGUSER} environment variable and the -\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to -\emph{override} Mercurial's default selection of username. For normal -use, the simplest and most robust way to set a username for yourself -is by creating a \sfilename{.hgrc} file; see below for details. +%You should think of the \envar{HGUSER} environment variable and the +%\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to +%\emph{override} Mercurial's default selection of username. For normal +%use, the simplest and most robust way to set a username for yourself +%is by creating a \sfilename{.hgrc} file; see below for details. %\subsubsection{Creating a Mercurial configuration file} \subsubsection{Mercurial$B$N@_Dj%U%!%$%k$r:n@.$9$k(B} \label{sec:tour-basic:username} -To set a user name, use your favourite editor to create a file called -\sfilename{.hgrc} in your home directory. Mercurial will use this -file to look up your personalised configuration settings. The initial -contents of your \sfilename{.hgrc} should look like this. -\begin{codesample2} - # This is a Mercurial configuration file. - [ui] - username = Firstname Lastname <email.address@domain.net> -\end{codesample2} -The ``\texttt{[ui]}'' line begins a \emph{section} of the config file, -so you can read the ``\texttt{username = ...}'' line as meaning ``set -the value of the \texttt{username} item in the \texttt{ui} section''. -A section continues until a new section begins, or the end of the -file. Mercurial ignores empty lines and treats any text from -``\texttt{\#}'' to the end of a line as a comment. +%To set a user name, use your favourite editor to create a file called +%\sfilename{.hgrc} in your home directory. Mercurial will use this +%file to look up your personalised configuration settings. The initial +%contents of your \sfilename{.hgrc} should look like this. +%\begin{codesample2} +% # This is a Mercurial configuration file. +% [ui] +% username = Firstname Lastname <email.address@domain.net> +%\end{codesample2} +%The ``\texttt{[ui]}'' line begins a \emph{section} of the config file, +%so you can read the ``\texttt{username = ...}'' line as meaning ``set +%the value of the \texttt{username} item in the \texttt{ui} section''. +%A section continues until a new section begins, or the end of the +%file. Mercurial ignores empty lines and treats any text from +%``\texttt{\#}'' to the end of a line as a comment. %\subsubsection{Choosing a user name} \subsubsection{$B%f!<%6L>$rA*$V(B} -You can use any text you like as the value of the \texttt{username} -config item, since this information is for reading by other people, -but for interpreting by Mercurial. The convention that most people -follow is to use their name and email address, as in the example -above. +%You can use any text you like as the value of the \texttt{username} +%config item, since this information is for reading by other people, +%but for interpreting by Mercurial. The convention that most people +%follow is to use their name and email address, as in the example +%above. -\begin{note} - Mercurial's built-in web server obfuscates email addresses, to make - it more difficult for the email harvesting tools that spammers use. - This reduces the likelihood that you'll start receiving more junk - email if you publish a Mercurial repository on the web. -\end{note} +%\begin{note} +% Mercurial's built-in web server obfuscates email addresses, to make +% it more difficult for the email harvesting tools that spammers use. +% This reduces the likelihood that you'll start receiving more junk +% email if you publish a Mercurial repository on the web. +%\end{note} %\subsection{Writing a commit message} \subsection{$B%3%_%C%H%a%C%;!<%8$r=q$/(B} -When we commit a change, Mercurial drops us into a text editor, to -enter a message that will describe the modifications we've made in -this changeset. This is called the \emph{commit message}. It will be -a record for readers of what we did and why, and it will be printed by -\hgcmd{log} after we've finished committing. -\interaction{tour.commit} +%When we commit a change, Mercurial drops us into a text editor, to +%enter a message that will describe the modifications we've made in +%this changeset. This is called the \emph{commit message}. It will be +%a record for readers of what we did and why, and it will be printed by +%\hgcmd{log} after we've finished committing. +%\interaction{tour.commit} -The editor that the \hgcmd{commit} command drops us into will contain -an empty line, followed by a number of lines starting with -``\texttt{HG:}''. -\begin{codesample2} - \emph{empty line} - HG: changed hello.c -\end{codesample2} -Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses -them only to tell us which files it's recording changes to. Modifying -or deleting these lines has no effect. +%The editor that the \hgcmd{commit} command drops us into will contain +%an empty line, followed by a number of lines starting with +%``\texttt{HG:}''. +%\begin{codesample2} +% \emph{empty line} +% HG: changed hello.c +%\end{codesample2} +%Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses +%them only to tell us which files it's recording changes to. Modifying +%or deleting these lines has no effect. %\subsection{Writing a good commit message} \subsection{$B$h$$%3%_%C%H%a%C%;!<%8$N=q$-J}(B} -Since \hgcmd{log} only prints the first line of a commit message by -default, it's best to write a commit message whose first line stands -alone. Here's a real example of a commit message that \emph{doesn't} -follow this guideline, and hence has a summary that is not readable. -\begin{codesample2} - changeset: 73:584af0e231be - user: Censored Person <censored.person@example.org> - date: Tue Sep 26 21:37:07 2006 -0700 - summary: include buildmeister/commondefs. Add an exports and install -\end{codesample2} +%Since \hgcmd{log} only prints the first line of a commit message by +%default, it's best to write a commit message whose first line stands +%alone. Here's a real example of a commit message that \emph{doesn't} +%follow this guideline, and hence has a summary that is not readable. +%\begin{codesample2} +% changeset: 73:584af0e231be +% user: Censored Person <censored.person@example.org> +% date: Tue Sep 26 21:37:07 2006 -0700 +% summary: include buildmeister/commondefs. Add an exports and install +%\end{codesample2} -As far as the remainder of the contents of the commit message are -concerned, there are no hard-and-fast rules. Mercurial itself doesn't -interpret or care about the contents of the commit message, though -your project may have policies that dictate a certain kind of -formatting. +%As far as the remainder of the contents of the commit message are +%concerned, there are no hard-and-fast rules. Mercurial itself doesn't +%interpret or care about the contents of the commit message, though +%your project may have policies that dictate a certain kind of +%formatting. -My personal preference is for short, but informative, commit messages -that tell me something that I can't figure out with a quick glance at -the output of \hgcmdargs{log}{--patch}. +%My personal preference is for short, but informative, commit messages +%that tell me something that I can't figure out with a quick glance at +%the output of \hgcmdargs{log}{--patch}. %\subsection{Aborting a commit} \subsection{$B%3%_%C%H$rCf;_$9$k(B} -If you decide that you don't want to commit while in the middle of -editing a commit message, simply exit from your editor without saving -the file that it's editing. This will cause nothing to happen to -either the repository or the working directory. +%If you decide that you don't want to commit while in the middle of +%editing a commit message, simply exit from your editor without saving +%the file that it's editing. This will cause nothing to happen to +%either the repository or the working directory. -If we run the \hgcmd{commit} command without any arguments, it records -all of the changes we've made, as reported by \hgcmd{status} and -\hgcmd{diff}. +%If we run the \hgcmd{commit} command without any arguments, it records +%all of the changes we've made, as reported by \hgcmd{status} and +%\hgcmd{diff}. %\subsection{Admiring our new handiwork} \subsection{$B?7$?$J:n6H$r>N;?$9$k(B} -Once we've finished the commit, we can use the \hgcmd{tip} command to -display the changeset we just created. This command produces output -that is identical to \hgcmd{log}, but it only displays the newest -revision in the repository. -\interaction{tour.tip} -We refer to the newest revision in the repository as the tip revision, -or simply the tip. +%Once we've finished the commit, we can use the \hgcmd{tip} command to +%display the changeset we just created. This command produces output +%that is identical to \hgcmd{log}, but it only displays the newest +%revision in the repository. +%\interaction{tour.tip} +%We refer to the newest revision in the repository as the tip revision, +%or simply the tip. %\section{Sharing changes} \section{$BJQ99$r6&M-$9$k(B} -We mentioned earlier that repositories in Mercurial are -self-contained. This means that the changeset we just created exists -only in our \dirname{my-hello} repository. Let's look at a few ways -that we can propagate this change into other repositories. +%We mentioned earlier that repositories in Mercurial are +%self-contained. This means that the changeset we just created exists +%only in our \dirname{my-hello} repository. Let's look at a few ways +%that we can propagate this change into other repositories. %\subsection{Pulling changes from another repository} \subsection{$BB>$N%j%]%8%H%j$+$iJQ99$r(Bpull$B$9$k(B} \label{sec:tour:pull} -To get started, let's clone our original \dirname{hello} repository, -which does not contain the change we just committed. We'll call our -temporary repository \dirname{hello-pull}. -\interaction{tour.clone-pull} +%To get started, let's clone our original \dirname{hello} repository, +%which does not contain the change we just committed. We'll call our +%temporary repository \dirname{hello-pull}. +%\interaction{tour.clone-pull} -We'll use the \hgcmd{pull} command to bring changes from -\dirname{my-hello} into \dirname{hello-pull}. However, blindly -pulling unknown changes into a repository is a somewhat scary -prospect. Mercurial provides the \hgcmd{incoming} command to tell us -what changes the \hgcmd{pull} command \emph{would} pull into the -repository, without actually pulling the changes in. -\interaction{tour.incoming} -(Of course, someone could cause more changesets to appear in the -repository that we ran \hgcmd{incoming} in, before we get a chance to -\hgcmd{pull} the changes, so that we could end up pulling changes that we -didn't expect.) +%We'll use the \hgcmd{pull} command to bring changes from +%\dirname{my-hello} into \dirname{hello-pull}. However, blindly +%pulling unknown changes into a repository is a somewhat scary +%prospect. Mercurial provides the \hgcmd{incoming} command to tell us +%what changes the \hgcmd{pull} command \emph{would} pull into the +%repository, without actually pulling the changes in. +%\interaction{tour.incoming} +%(Of course, someone could cause more changesets to appear in the +%repository that we ran \hgcmd{incoming} in, before we get a chance to +%\hgcmd{pull} the changes, so that we could end up pulling changes that we +%didn't expect.) -Bringing changes into a repository is a simple matter of running the -\hgcmd{pull} command, and telling it which repository to pull from. -\interaction{tour.pull} -As you can see from the before-and-after output of \hgcmd{tip}, we -have successfully pulled changes into our repository. There remains -one step before we can see these changes in the working directory. +%Bringing changes into a repository is a simple matter of running the +%\hgcmd{pull} command, and telling it which repository to pull from. +%\interaction{tour.pull} +%As you can see from the before-and-after output of \hgcmd{tip}, we +%have successfully pulled changes into our repository. There remains +%one step before we can see these changes in the working directory. %\subsection{Updating the working directory} \subsection{$B%o!<%-%s%0%G%#%l%/%H%j$r99?7$9$k(B} -We have so far glossed over the relationship between a repository and -its working directory. The \hgcmd{pull} command that we ran in -section~\ref{sec:tour:pull} brought changes into the repository, but -if we check, there's no sign of those changes in the working -directory. This is because \hgcmd{pull} does not (by default) touch -the working directory. Instead, we use the \hgcmd{update} command to -do this. -\interaction{tour.update} +%We have so far glossed over the relationship between a repository and +%its working directory. The \hgcmd{pull} command that we ran in +%section~\ref{sec:tour:pull} brought changes into the repository, but +%if we check, there's no sign of those changes in the working +%directory. This is because \hgcmd{pull} does not (by default) touch +%the working directory. Instead, we use the \hgcmd{update} command to +%do this. +%\interaction{tour.update} -It might seem a bit strange that \hgcmd{pull} doesn't update the -working directory automatically. There's actually a good reason for -this: you can use \hgcmd{update} to update the working directory to -the state it was in at \emph{any revision} in the history of the -repository. If you had the working directory updated to an old -revision---to hunt down the origin of a bug, say---and ran a -\hgcmd{pull} which automatically updated the working directory to a -new revision, you might not be terribly happy. +%It might seem a bit strange that \hgcmd{pull} doesn't update the +%working directory automatically. There's actually a good reason for +%this: you can use \hgcmd{update} to update the working directory to +%the state it was in at \emph{any revision} in the history of the +%repository. If you had the working directory updated to an old +%revision---to hunt down the origin of a bug, say---and ran a +%\hgcmd{pull} which automatically updated the working directory to a +%new revision, you might not be terribly happy. -However, since pull-then-update is such a common thing to do, -Mercurial lets you combine the two by passing the \hgopt{pull}{-u} -option to \hgcmd{pull}. -\begin{codesample2} - hg pull -u -\end{codesample2} -If you look back at the output of \hgcmd{pull} in -section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u}, -you can see that it printed a helpful reminder that we'd have to take -an explicit step to update the working directory: -\begin{codesample2} - (run 'hg update' to get a working copy) -\end{codesample2} +%However, since pull-then-update is such a common thing to do, +%Mercurial lets you combine the two by passing the \hgopt{pull}{-u} +%option to \hgcmd{pull}. +%\begin{codesample2} +% hg pull -u +%\end{codesample2} +%If you look back at the output of \hgcmd{pull} in +%section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u}, +%you can see that it printed a helpful reminder that we'd have to take +%an explicit step to update the working directory: +%\begin{codesample2} +% (run 'hg update' to get a working copy) +%\end{codesample2} -To find out what revision the working directory is at, use the -\hgcmd{parents} command. -\interaction{tour.parents} -If you look back at figure~\ref{fig:tour-basic:history}, you'll see -arrows connecting each changeset. The node that the arrow leads -\emph{from} in each case is a parent, and the node that the arrow -leads \emph{to} is its child. The working directory has a parent in -just the same way; this is the changeset that the working directory -currently contains. +%To find out what revision the working directory is at, use the +%\hgcmd{parents} command. +%\interaction{tour.parents} +%If you look back at figure~\ref{fig:tour-basic:history}, you'll see +%arrows connecting each changeset. The node that the arrow leads +%\emph{from} in each case is a parent, and the node that the arrow +%leads \emph{to} is its child. The working directory has a parent in +%just the same way; this is the changeset that the working directory +%currently contains. -To update the working directory to a particular revision, give a -revision number or changeset~ID to the \hgcmd{update} command. -\interaction{tour.older} -If you omit an explicit revision, \hgcmd{update} will update to the -tip revision, as shown by the second call to \hgcmd{update} in the -example above. +%To update the working directory to a particular revision, give a +%revision number or changeset~ID to the \hgcmd{update} command. +%\interaction{tour.older} +%If you omit an explicit revision, \hgcmd{update} will update to the +%tip revision, as shown by the second call to \hgcmd{update} in the +%example above. %\subsection{Pushing changes to another repository} \subsection{$BB>$N%j%]%8%H%j$KJQ99$r(Bpush$B$9$k(B} -Mercurial lets us push changes to another repository, from the -repository we're currently visiting. As with the example of -\hgcmd{pull} above, we'll create a temporary repository to push our -changes into. -\interaction{tour.clone-push} -The \hgcmd{outgoing} command tells us what changes would be pushed -into another repository. -\interaction{tour.outgoing} -And the \hgcmd{push} command does the actual push. -\interaction{tour.push} -As with \hgcmd{pull}, the \hgcmd{push} command does not update the -working directory in the repository that it's pushing changes into. -(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u} -option that updates the other repository's working directory.) +%Mercurial lets us push changes to another repository, from the +%repository we're currently visiting. As with the example of +%\hgcmd{pull} above, we'll create a temporary repository to push our +%changes into. +%\interaction{tour.clone-push} +%The \hgcmd{outgoing} command tells us what changes would be pushed +%into another repository. +%\interaction{tour.outgoing} +%And the \hgcmd{push} command does the actual push. +%\interaction{tour.push} +%As with \hgcmd{pull}, the \hgcmd{push} command does not update the +%working directory in the repository that it's pushing changes into. +%(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u} +%option that updates the other repository's working directory.) -What happens if we try to pull or push changes and the receiving -repository already has those changes? Nothing too exciting. -\interaction{tour.push.nothing} +%What happens if we try to pull or push changes and the receiving +%repository already has those changes? Nothing too exciting. +%\interaction{tour.push.nothing} %\subsection{Sharing changes over a network} \subsection{$BJQ99$r%M%C%H%o!<%/$rDL$8$F6&M-$9$k(B} -The commands we have covered in the previous few sections are not -limited to working with local repositories. Each works in exactly the -same fashion over a network connection; simply pass in a URL instead -of a local path. -\interaction{tour.outgoing.net} -In this example, we can see what changes we could push to the remote -repository, but the repository is understandably not set up to let -anonymous users push to it. -\interaction{tour.push.net} +%The commands we have covered in the previous few sections are not +%limited to working with local repositories. Each works in exactly the +%same fashion over a network connection; simply pass in a URL instead +%of a local path. +%\interaction{tour.outgoing.net} +%In this example, we can see what changes we could push to the remote +%repository, but the repository is understandably not set up to let +%anonymous users push to it. +%\interaction{tour.push.net} + + + %%% Local Variables: %%% mode: yatex