Mercurial > hgbook
annotate ja/tour-basic.tex @ 784:386cdca52f0b
a bit more tour-basic.tex
author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
---|---|
date | Wed, 03 Jun 2009 19:12:11 +0900 |
parents | b15bea650f30 |
children | 7dd855842de4 |
rev | line source |
---|---|
783 | 1 %\chapter{A tour of Mercurial: the basics} |
2 \chapter{Mercurial$B%D%"!<(B: $B4pK\(B} | |
95
47ea206351d5
Split tour into two sections.
Bryan O'Sullivan <bos@serpentine.com>
parents:
94
diff
changeset
|
3 \label{chap:tour-basic} |
84 | 4 |
783 | 5 %\section{Installing Mercurial on your system} |
6 \section{$B%7%9%F%`$X$N(BMercurial$B$N%$%s%9%H!<%k(B} | |
84 | 7 \label{sec:tour:install} |
8 | |
783 | 9 %Prebuilt binary packages of Mercurial are available for every popular |
10 %operating system. These make it easy to start using Mercurial on your | |
11 %computer immediately. | |
12 | |
13 $B?M5$$N9b$$%*%Z%l!<%F%#%s%0%7%9%F%`$G$O(BMercurial$B$N%S%k%I:Q$_%P%$%J%j%Q%C(B | |
14 $B%1!<%8$,Ds6!$5$l$F$$$k!%$3$l$rMQ$$$l$PFI<T$N7W;;5!$N>e$GD>$A$K(BMercurial | |
15 $B$r;H$&$3$H$,$G$-$k!%(B | |
85
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
16 |
84 | 17 \subsection{Linux} |
18 | |
783 | 19 %Because each Linux distribution has its own packaging tools, policies, |
20 %and rate of development, it's difficult to give a comprehensive set of | |
21 %instructions on how to install Mercurial binaries. The version of | |
22 %Mercurial that you will end up with can vary depending on how active | |
23 %the person is who maintains the package for your distribution. | |
24 | |
25 Linux$B$N3F%G%#%9%H%j%S%e!<%7%g%s$O$=$l$>$lFH<+$N%Q%C%1!<%8%D!<%k!$%]%j(B | |
26 $B%7!<!$3+H/%Z!<%9$r;}$C$F$$$k$?$a!$A4$F$rLVMe$7$F(BMercurial$B%P%$%J%j$N%$%s%9(B | |
27 $B%H!<%k<j=g$r=R$Y$k$3$H$O:$Fq$G$"$k!%$=$l$>$l$N%G%#%9%H%j%S%e!<%7%g%s$GMx(B | |
28 $BMQ2DG=$J(BMercurial$B$N%P!<%8%g%s$O!$%Q%C%1!<%8%a%s%F%J$N3hF0$K0MB8$9$k!%(B | |
84 | 29 |
783 | 30 %To keep things simple, I will focus on installing Mercurial from the |
31 %command line under the most popular Linux distributions. Most of | |
32 %these distributions provide graphical package managers that will let | |
33 %you install Mercurial with a single click; the package name to look | |
34 %for is \texttt{mercurial}. | |
35 | |
36 $BC1=c2=$N$?$a$K!$BgB??t$N(BLinux$B%G%#%9%H%j%S%e!<%7%g%s$G%3%^%s%I%i%$%s$+$i(B | |
37 Mercurial$B$r%$%s%9%H!<%k$9$kJ}K!$K8BDj$7$F@bL@$9$k$3$H$K$9$k!%$3$l$i$NBgH>(B | |
38 $B$N%G%#%9%H%j%S%e!<%7%g%s$G$O!$(BMercurial$B$r%/%j%C%/(B1$B2s$G%$%s%9%H!<%k$G$-$k(B | |
39 $B$h$&$J%0%i%U%#%+%k$J%Q%C%1!<%8%^%M!<%8%c$rMQ0U$7$F$$$k!%(B | |
84 | 40 |
85
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
41 \begin{itemize} |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
42 \item[Debian] |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
43 \begin{codesample4} |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
44 apt-get install mercurial |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
45 \end{codesample4} |
84 | 46 |
85
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
47 \item[Fedora Core] |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
48 \begin{codesample4} |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
49 yum install mercurial |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
50 \end{codesample4} |
84 | 51 |
85
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
52 \item[Gentoo] |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
53 \begin{codesample4} |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
54 emerge mercurial |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
55 \end{codesample4} |
84 | 56 |
85
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
57 \item[OpenSUSE] |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
58 \begin{codesample4} |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
59 yum install mercurial |
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
60 \end{codesample4} |
84 | 61 |
783 | 62 %\item[Ubuntu] Ubuntu's Mercurial package is based on Debian's. To |
63 % install it, run the following command. | |
64 \item[Ubuntu] Ubuntu$B$N(BMercurial package$B$O(BDebian$B$N$b$N$r85$K$7$F$$$k!%$3(B | |
65 $B$l$r%$%s%9%H!<%k$9$k$?$a$K$O<!$N%3%^%s%I$r<B9T$9$k!%(B | |
262
6a847f7902a7
Update description of Ubuntu package.
Bryan O'Sullivan <bos@serpentine.com>
parents:
174
diff
changeset
|
66 \begin{codesample4} |
6a847f7902a7
Update description of Ubuntu package.
Bryan O'Sullivan <bos@serpentine.com>
parents:
174
diff
changeset
|
67 apt-get install mercurial |
6a847f7902a7
Update description of Ubuntu package.
Bryan O'Sullivan <bos@serpentine.com>
parents:
174
diff
changeset
|
68 \end{codesample4} |
783 | 69 % The Ubuntu package for Mercurial tends to lag behind the Debian |
70 % version by a considerable time margin (at the time of writing, seven | |
71 % months), which in some cases will mean that on Ubuntu, you may run | |
72 % into problems that have since been fixed in the Debian package. | |
73 Ubuntu$B$N(BMercurial$B%Q%C%1!<%8$O(BDebian$B$N$b$N$KHf$Y$FL5;k$G$-$J$$$[$I$NCY$l(B | |
74 $B$,$"$k!J$3$l$r=q$$$F$$$k;~E@$G$O(B7$B%+7n!K!%$3$N$?$a!$(BUbuntu$B$G(B | |
75 $B$O(BDebian$B$G$O$9$G$K2r7h$5$l$?LdBj$KD>LL$9$k$+$b$7$l$J$$!%(B | |
85
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
76 \end{itemize} |
84 | 77 |
264 | 78 \subsection{Solaris} |
79 | |
80 XXX. | |
81 | |
84 | 82 \subsection{Mac OS X} |
83 | |
783 | 84 %Lee Cantey publishes an installer of Mercurial for Mac OS~X at |
85 %\url{http://mercurial.berkwood.com}. This package works on both | |
86 %Intel-~and Power-based Macs. Before you can use it, you must install | |
87 %a compatible version of Universal MacPython~\cite{web:macpython}. This | |
88 %is easy to do; simply follow the instructions on Lee's site. | |
89 | |
90 Lee Cantey$B$O(BMac OS~X$B8~$1$N(BMercurial$B%$%s%9%H!<%i$r(B | |
91 \url{http://mercurial.berkwood.com}$B$GG[I[$7$F$$$k!%$3$N%Q%C%1!<%8$O(B | |
92 Intel-~$B$H(BPower-$B%Y!<%9$N(BMac$BN>J}$GF0:n$9$k!%$3$l$r;H$&A0$K!$8_49@-$N$"$k%P!<(B | |
93 $B%8%g%s$N(BUniversal MacPython~\cite{web:macpython}$B$r%$%s%9%H!<%k$9$kI,MW$,(B | |
94 $B$"$k!%%$%s%9%H!<%k$O4JC1$G!$(BLee$B$N%5%$%H$K$"$k<j=g$K=>$&$@$1$G$"$k!%(B | |
84 | 95 |
96 \subsection{Windows} | |
97 | |
783 | 98 %Lee Cantey also publishes an installer of Mercurial for Windows at |
99 %\url{http://mercurial.berkwood.com}. This package has no external | |
100 %dependencies; it ``just works''. | |
101 | |
102 Lee Cantey$B$O(BWindows$B8~$1$N(BMercurial$B%$%s%9%H!<%i$b(B | |
103 \url{http://mercurial.berkwood.com}$B$GG[I[$7$F$$$k!%$3$N%Q%C%1!<%8$O30It(B | |
104 $B$N%=%U%H%&%'%"$K0MB8$;$:!$C1FH$G<B9T2DG=$G$"$k!%(B | |
84 | 105 |
106 \begin{note} | |
783 | 107 % The Windows version of Mercurial does not automatically convert line |
108 % endings between Windows and Unix styles. If you want to share work | |
109 % with Unix users, you must do a little additional configuration | |
110 % work. XXX Flesh this out. | |
111 Windows$B%P!<%8%g%s$N(BMercurial$B$O!$(BWindows$B$H(BUnix$B$N4V$G9TKv$N2~9T%3!<%I$r<+(B | |
112 $BF0$GJQ49$7$J$$!%(BUnix$B%f!<%6$H:n6H$r9T$$$?$$>l9g$O!$DI2C$N@_Dj$r9T$&I,MW(B | |
113 $B$,$"$k!%(BXXX Flesh this out. | |
84 | 114 \end{note} |
115 | |
783 | 116 %\section{Getting started} |
117 \section{Mercurial$B$r;H$&(B} | |
87 | 118 |
783 | 119 %To begin, we'll use the \hgcmd{version} command to find out whether |
120 %Mercurial is actually installed properly. The actual version | |
121 %information that it prints isn't so important; it's whether it prints | |
122 %anything at all that we care about. | |
123 %\interaction{tour.version} | |
124 | |
125 $B$^$:(B\hgcmd{version}$B%3%^%s%I$G(BMercurial$B$,<B:]$K@5$7$/%$%s%9%H!<%k$5$l$?$+(B | |
126 $B$r3NG'$7$F$_$h$&!%I=<($5$l$k$+$I$&$+$,LdBj$G$"$C$F!$I=<($5$l$k%P!<%8%g%s(B | |
127 $B>pJs$OFC$K=EMW$G$O$J$$!%(B | |
87 | 128 \interaction{tour.version} |
129 | |
783 | 130 %\subsection{Built-in help} |
131 \subsection{$BAH$_9~$_%X%k%W(B} | |
87 | 132 |
783 | 133 %Mercurial provides a built-in help system. This is invaluable for those |
134 %times when you find yourself stuck trying to remember how to run a | |
135 %command. If you are completely stuck, simply run \hgcmd{help}; it | |
136 %will print a brief list of commands, along with a description of what | |
137 %each does. If you ask for help on a specific command (as below), it | |
138 %prints more detailed information. | |
139 %\interaction{tour.help} | |
140 %For a more impressive level of detail (which you won't usually need) | |
141 %run \hgcmdargs{help}{\hggopt{-v}}. The \hggopt{-v} option is short | |
142 %for \hggopt{--verbose}, and tells Mercurial to print more information | |
143 %than it usually would. | |
144 | |
145 Mercurial$B$OAH$_9~$_$N%X%k%W%7%9%F%`$rHw$($F$$$k!%$3$l$O%3%^%s%I$N;H$$J}$K(B | |
146 $B5M$^$C$?;~$KLr$KN)$D!%2?$r<B9T$7$?$iNI$$$N$+A4$/J,$+$i$J$$>l9g$OC1$K(B | |
147 \hgcmd{help}$B$r<B9T$9$k!%$3$l$O%3%^%s%I$N0lIt$r@bL@$H6&$K%j%9%HI=<($9$k!%(B | |
148 $BFCDj$N%3%^%s%I$K$D$$$F%X%k%W$,8+$?$$>l9g$O!$2<5-$N$h$&$K$9$k$H$h$j>\:Y$J(B | |
149 $B>pJs$,F@$i$l$k!%(B | |
87 | 150 \interaction{tour.help} |
783 | 151 $BDL>oI,MW$H$7$J$$$h$&$J6K$a$F>\$7$$@bL@$,I,MW$J>l9g$O(B |
152 \hgcmdargs{help}{\hggopt{-v}}$B$r<B9T$9$k!%(B\hggopt{-v}$B$O(B\hggopt{--verbose} | |
153 $B%*%W%7%g%s$NC;=L7A$G!$$h$j>\:Y$J>pJs$rI=<($9$k%*%W%7%g%s$G$"$k!%(B | |
87 | 154 |
783 | 155 %\section{Working with a repository} |
156 \section{$B%j%]%8%H%j$r;H$C$?:n6H(B} | |
87 | 157 |
783 | 158 %In Mercurial, everything happens inside a \emph{repository}. The |
159 %repository for a project contains all of the files that ``belong to'' | |
160 %that project, along with a historical record of the project's files. | |
87 | 161 |
783 | 162 Mercurial$B$G$O(B\emph{$B%j%]%8%H%jFb(B}$B$G0l@Z$,5/$-$k!%%W%m%8%'%/%H$N%j%]%8%H%j(B |
163 $B$O=jB0$9$kA4$F$N%U%!%$%k$H$=$l$i$NMzNr>pJs$r;}$D!%(B | |
87 | 164 |
783 | 165 %There's nothing particularly magical about a repository; it is simply |
166 %a directory tree in your filesystem that Mercurial treats as special. | |
167 %You can rename or delete a repository any time you like, using either the | |
168 %command line or your file browser. | |
169 | |
170 $B%j%]%8%H%j$K$OFC$KIT;W5D$J$H$3$m$O$J$$!%%j%]%8%H%j$O(BMercurial$B$,FCJL$N07$$(B | |
171 $B$r$9$k$@$1$N%U%!%$%k%7%9%F%`>e$NC1$J$k%G%#%l%/%H%j%D%j!<$K$9$.$J$$!%(B | |
172 $B%j%]%8%H%j$O%3%^%s%I%i%$%s$d%U%!%$%k%V%i%&%6$+$i$$$D$G$bL>A0$rJQ$($?$j>C(B | |
173 $B5n$9$k$3$H$,$G$-$k!%(B | |
174 | |
175 %\subsection{Making a local copy of a repository} | |
176 \subsection{$B%j%]%8%H%j$N%m!<%+%k%3%T!<$r:n$k(B} | |
87 | 177 |
783 | 178 %\emph{Copying} a repository is just a little bit special. While you |
179 %could use a normal file copying command to make a copy of a | |
180 %repository, it's best to use a built-in command that Mercurial | |
181 %provides. This command is called \hgcmd{clone}, because it creates an | |
182 %identical copy of an existing repository. | |
183 %\interaction{tour.clone} | |
184 %If our clone succeeded, we should now have a local directory called | |
185 %\dirname{hello}. This directory will contain some files. | |
186 %\interaction{tour.ls} | |
187 %These files have the same contents and history in our repository as | |
188 %they do in the repository we cloned. | |
87 | 189 |
784
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
190 $B%j%]%8%H%j$N(B\emph{$B%3%T!<(B}$B$O$d$dFC<l$G$"$k!%DL>o$N%U%!%$%k%3%T!<%3%^%s%I$r(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
191 $B;H$C$F%j%]%8%H%j$N%3%T!<$r:n@.$9$k$3$H$b$G$-$k$,!$(BMercurial$B$NAH$_9~$_%3%^(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
192 $B%s%I$r;H$C$F%3%T!<$9$k$N$,0lHVNI$$!%$3$N%3%^%s%I$O(B\hgcmd{clone}$B$H8F$P$l!$(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
193 $B4{B8$N%j%]%8%H%j$N40A4$J%3%T!<$r:n@.$9$k!%(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
194 \interaction{tour.clone} |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
195 $B%/%m!<%s$,@.8y$9$k$H(B\dirname{hello}$B$H$$$&%m!<%+%k%G%#%l%/%H%j$,$G$-$k!%(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
196 $B$3$N%G%#%l%/%H%j$K$O%*%j%8%J%k$HF10l$N%U%!%$%k$,4^$^$l$k!%(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
197 \interaction{tour.ls} |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
198 $B$3$l$i$N%U%!%$%k$O%/%m!<%s$7$?%j%]%8%H%jFb$HA4$/F1$8FbMF$HMzNr$r;}$C$F$$(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
199 $B$k!%(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
200 |
783 | 201 %Every Mercurial repository is complete, self-contained, and |
202 %independent. It contains its own private copy of a project's files | |
203 %and history. A cloned repository remembers the location of the | |
204 %repository it was cloned from, but it does not communicate with that | |
205 %repository, or any other, unless you tell it to. | |
87 | 206 |
784
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
207 $BA4$F$N(BMercurial$B%j%]%8%H%j$O40A4$+$D<+8J=<B-E*$GFHN)$G$"$k!%%j%]%8%H%j$O%W(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
208 $B%m%8%'%/%H$KB0$9%U%!%$%k$N%W%i%$%Y!<%H%3%T!<$HMzNr$r;}$D!%%/%m!<%s$5$l$?(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
209 $B%j%]%8%H%j$O%/%m!<%s85$N%j%]%8%H%j$N>l=j$r5-21$7$F$$$k$,!$%f!<%6$,;X<($7(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
210 $B$J$$8B$j!$$=$N%j%]%8%H%j$dB>$N%j%]%8%H%j$HDL?.$r9T$&$3$H$O$J$$!%(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
211 |
783 | 212 %What this means for now is that we're free to experiment with our |
213 %repository, safe in the knowledge that it's a private ``sandbox'' that | |
214 %won't affect anyone else. | |
85
b7c69a68b0cc
A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents:
84
diff
changeset
|
215 |
784
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
216 $B:#$NCJ3,$G$O%m!<%+%k$J%j%]%8%H%j$H$O30It$X2?$N1F6A$b5Z$\$5$J$$%W%i%$%Y!<(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
217 $B%H$J(B``$B%5%s%I%\%C%/%9(B''$B$G!$$3$NCf$G$I$s$J$3$H$G$b;n$9$3$H$,$G$-$k$H2r<a$7(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
218 $B$F$*$1$P==J,$G$"$k!%(B |
386cdca52f0b
a bit more tour-basic.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
783
diff
changeset
|
219 |
783 | 220 %\subsection{What's in a repository?} |
221 \subsection{$B%j%]%8%H%j$K$O2?$,4^$^$l$k$+!)(B} | |
88
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
222 |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
223 When we take a more detailed look inside a repository, we can see that |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
224 it contains a directory named \dirname{.hg}. This is where Mercurial |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
225 keeps all of its metadata for the repository. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
226 \interaction{tour.ls-a} |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
227 |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
228 The contents of the \dirname{.hg} directory and its subdirectories are |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
229 private to Mercurial. Every other file and directory in the |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
230 repository is yours to do with as you please. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
231 |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
232 To introduce a little terminology, the \dirname{.hg} directory is the |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
233 ``real'' repository, and all of the files and directories that coexist |
91 | 234 with it are said to live in the \emph{working directory}. An easy way |
235 to remember the distinction is that the \emph{repository} contains the | |
88
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
236 \emph{history} of your project, while the \emph{working directory} |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
237 contains a \emph{snapshot} of your project at a particular point in |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
238 history. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
239 |
783 | 240 %\section{A tour through history} |
241 \section{$BMzNr$rC)$k(B} | |
88
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
242 |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
243 One of the first things we might want to do with a new, unfamiliar |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
244 repository is understand its history. The \hgcmd{log} command gives |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
245 us a view of history. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
246 \interaction{tour.log} |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
247 By default, this command prints a brief paragraph of output for each |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
248 change to the project that was recorded. In Mercurial terminology, we |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
249 call each of these recorded events a \emph{changeset}, because it can |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
250 contain a record of changes to several files. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
251 |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
252 The fields in a record of output from \hgcmd{log} are as follows. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
253 \begin{itemize} |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
254 \item[\texttt{changeset}] This field has the format of a number, |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
255 followed by a colon, followed by a hexadecimal string. These are |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
256 \emph{identifiers} for the changeset. There are two identifiers |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
257 because the number is shorter and easier to type than the hex |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
258 string. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
259 \item[\texttt{user}] The identity of the person who created the |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
260 changeset. This is a free-form field, but it most often contains a |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
261 person's name and email address. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
262 \item[\texttt{date}] The date and time on which the changeset was |
158
d3f8aec5beff
Fix typos in chapter 2.
Steve Guidon <steve.guidon@gmail.com>
parents:
102
diff
changeset
|
263 created, and the timezone in which it was created. (The date and |
88
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
264 time are local to that timezone; they display what time and date it |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
265 was for the person who created the changeset.) |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
266 \item[\texttt{summary}] The first line of the text message that the |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
267 creator of the changeset entered to describe the changeset. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
268 \end{itemize} |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
269 The default output printed by \hgcmd{log} is purely a summary; it is |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
270 missing a lot of detail. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
271 |
99 | 272 Figure~\ref{fig:tour-basic:history} provides a graphical representation of |
97 | 273 the history of the \dirname{hello} repository, to make it a little |
274 easier to see which direction history is ``flowing'' in. We'll be | |
275 returning to this figure several times in this chapter and the chapter | |
276 that follows. | |
277 | |
96
7d7ddc3a57af
Split tour into two chapters.
Bryan O'Sullivan <bos@serpentine.com>
parents:
95
diff
changeset
|
278 \begin{figure}[ht] |
7d7ddc3a57af
Split tour into two chapters.
Bryan O'Sullivan <bos@serpentine.com>
parents:
95
diff
changeset
|
279 \centering |
7d7ddc3a57af
Split tour into two chapters.
Bryan O'Sullivan <bos@serpentine.com>
parents:
95
diff
changeset
|
280 \grafix{tour-history} |
7d7ddc3a57af
Split tour into two chapters.
Bryan O'Sullivan <bos@serpentine.com>
parents:
95
diff
changeset
|
281 \caption{Graphical history of the \dirname{hello} repository} |
99 | 282 \label{fig:tour-basic:history} |
96
7d7ddc3a57af
Split tour into two chapters.
Bryan O'Sullivan <bos@serpentine.com>
parents:
95
diff
changeset
|
283 \end{figure} |
7d7ddc3a57af
Split tour into two chapters.
Bryan O'Sullivan <bos@serpentine.com>
parents:
95
diff
changeset
|
284 |
783 | 285 %\subsection{Changesets, revisions, and talking to other people} |
286 \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} | |
88
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
287 |
97 | 288 As English is a notoriously sloppy language, and computer science has |
99 | 289 a hallowed history of terminological confusion (why use one term when |
290 four will do?), revision control has a variety of words and phrases | |
291 that mean the same thing. If you are talking about Mercurial history | |
292 with other people, you will find that the word ``changeset'' is often | |
293 compressed to ``change'' or (when written) ``cset'', and sometimes a | |
294 changeset is referred to as a ``revision'' or a ``rev''. | |
88
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
295 |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
296 While it doesn't matter what \emph{word} you use to refer to the |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
297 concept of ``a~changeset'', the \emph{identifier} that you use to |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
298 refer to ``a~\emph{specific} changeset'' is of great importance. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
299 Recall that the \texttt{changeset} field in the output from |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
300 \hgcmd{log} identifies a changeset using both a number and a |
97 | 301 hexadecimal string. |
302 \begin{itemize} | |
303 \item The revision number is \emph{only valid in that repository}, | |
304 \item while the hex string is the \emph{permanent, unchanging | |
305 identifier} that will always identify that exact changeset in | |
306 \emph{every} copy of the repository. | |
307 \end{itemize} | |
88
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
308 This distinction is important. If you send someone an email talking |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
309 about ``revision~33'', there's a high likelihood that their |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
310 revision~33 will \emph{not be the same} as yours. The reason for this |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
311 is that a revision number depends on the order in which changes |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
312 arrived in a repository, and there is no guarantee that the same |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
313 changes will happen in the same order in different repositories. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
314 Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
315 while in another as $1,0,2$. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
316 |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
317 Mercurial uses revision numbers purely as a convenient shorthand. If |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
318 you need to discuss a changeset with someone, or make a record of a |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
319 changeset for some other reason (for example, in a bug report), use |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
320 the hexadecimal identifier. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
321 |
783 | 322 %\subsection{Viewing specific revisions} |
323 \subsection{$BFCDj$N%j%S%8%g%s$r8+$k(B} | |
88
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
324 |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
325 To narrow the output of \hgcmd{log} down to a single revision, use the |
91 | 326 \hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a |
327 revision number or a long-form changeset identifier, and you can | |
328 provide as many revisions as you want. \interaction{tour.log-r} | |
88
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
329 |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
330 If you want to see the history of several revisions without having to |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
331 list each one, you can use \emph{range notation}; this lets you |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
332 express the idea ``I want all revisions between $a$ and $b$, |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
333 inclusive''. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
334 \interaction{tour.log.range} |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
335 Mercurial also honours the order in which you specify revisions, so |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
336 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
337 prints $4,3,2$. |
d351032c189c
Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents:
87
diff
changeset
|
338 |
783 | 339 %\subsection{More detailed information} |
340 \subsection{$B$h$j>\:Y$J>pJs(B} | |
91 | 341 |
342 While the summary information printed by \hgcmd{log} is useful if you | |
343 already know what you're looking for, you may need to see a complete | |
344 description of the change, or a list of the files changed, if you're | |
345 trying to decide whether a changeset is the one you're looking for. | |
346 The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) | |
347 option gives you this extra detail. | |
348 \interaction{tour.log-v} | |
349 | |
350 If you want to see both the description and content of a change, add | |
351 the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays | |
352 the content of a change as a \emph{unified diff} (if you've never seen | |
353 a unified diff before, see section~\ref{sec:mq:patch} for an overview). | |
354 \interaction{tour.log-vp} | |
355 | |
783 | 356 %\section{All about command options} |
357 \section{$B%3%^%s%I%*%W%7%g%s$N$9$Y$F(B} | |
91 | 358 |
359 Let's take a brief break from exploring Mercurial commands to discuss | |
360 a pattern in the way that they work; you may find this useful to keep | |
158
d3f8aec5beff
Fix typos in chapter 2.
Steve Guidon <steve.guidon@gmail.com>
parents:
102
diff
changeset
|
361 in mind as we continue our tour. |
91 | 362 |
363 Mercurial has a consistent and straightforward approach to dealing | |
364 with the options that you can pass to commands. It follows the | |
365 conventions for options that are common to modern Linux and Unix | |
366 systems. | |
367 \begin{itemize} | |
368 \item Every option has a long name. For example, as we've already | |
369 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. | |
370 \item Most options have short names, too. Instead of | |
371 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that | |
372 some options don't have short names is that the options in question | |
373 are rarely used.) | |
374 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), | |
375 while short options start with one (e.g.~\hgopt{log}{-r}). | |
376 \item Option naming and usage is consistent across commands. For | |
377 example, every command that lets you specify a changeset~ID or | |
378 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} | |
379 arguments. | |
380 \end{itemize} | |
381 In the examples throughout this book, I use short options instead of | |
382 long. This just reflects my own preference, so don't read anything | |
383 significant into it. | |
384 | |
385 Most commands that print output of some kind will print more output | |
386 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less | |
387 when passed \hggopt{-q} (or \hggopt{--quiet}). | |
388 | |
783 | 389 %\section{Making and reviewing changes} |
390 \section{$BJQ99$N;EJ}!$JQ99$N%l%S%e!<(B} | |
91 | 391 |
392 Now that we have a grasp of viewing history in Mercurial, let's take a | |
393 look at making some changes and examining them. | |
394 | |
395 The first thing we'll do is isolate our experiment in a repository of | |
396 its own. We use the \hgcmd{clone} command, but we don't need to | |
397 clone a copy of the remote repository. Since we already have a copy | |
398 of it locally, we can just clone that instead. This is much faster | |
399 than cloning over the network, and cloning a local repository uses | |
400 less disk space in most cases, too. | |
401 \interaction{tour.reclone} | |
402 As an aside, it's often good practice to keep a ``pristine'' copy of a | |
403 remote repository around, which you can then make temporary clones of | |
404 to create sandboxes for each task you want to work on. This lets you | |
405 work on multiple tasks in parallel, each isolated from the others | |
406 until it's complete and you're ready to integrate it back. Because | |
407 local clones are so cheap, there's almost no overhead to cloning and | |
408 destroying repositories whenever you want. | |
409 | |
410 In our \dirname{my-hello} repository, we have a file | |
411 \filename{hello.c} that contains the classic ``hello, world'' program. | |
412 Let's use the ancient and venerable \command{sed} command to edit this | |
413 file so that it prints a second line of output. (I'm only using | |
414 \command{sed} to do this because it's easy to write a scripted example | |
415 this way. Since you're not under the same constraint, you probably | |
416 won't want to use \command{sed}; simply use your preferred text editor to | |
417 do the same thing.) | |
418 \interaction{tour.sed} | |
419 | |
420 Mercurial's \hgcmd{status} command will tell us what Mercurial knows | |
421 about the files in the repository. | |
422 \interaction{tour.status} | |
423 The \hgcmd{status} command prints no output for some files, but a line | |
424 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell | |
425 it to, \hgcmd{status} will not print any output for files that have | |
783 | 426 not been modified. |
91 | 427 |
428 The ``\texttt{M}'' indicates that Mercurial has noticed that we | |
97 | 429 modified \filename{hello.c}. We didn't need to \emph{inform} |
430 Mercurial that we were going to modify the file before we started, or | |
431 that we had modified the file after we were done; it was able to | |
432 figure this out itself. | |
91 | 433 |
434 It's a little bit helpful to know that we've modified | |
435 \filename{hello.c}, but we might prefer to know exactly \emph{what} | |
436 changes we've made to it. To do this, we use the \hgcmd{diff} | |
437 command. | |
438 \interaction{tour.diff} | |
439 | |
783 | 440 %\section{Recording changes in a new changeset} |
441 \section{$B?7$?$J%A%'%s%8%;%C%H$XJQ99$r5-O?$9$k(B} | |
91 | 442 |
443 We can modify files, build and test our changes, and use | |
444 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're | |
445 satisfied with what we've done and arrive at a natural stopping point | |
446 where we want to record our work in a new changeset. | |
447 | |
448 The \hgcmd{commit} command lets us create a new changeset; we'll | |
783 | 449 usually refer to this as ``making a commit'' or ``committing''. |
91 | 450 |
783 | 451 %\subsection{Setting up a username} |
452 \subsection{$B%f!<%6L>$r@_Dj$9$k(B} | |
102 | 453 |
174
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
454 When you try to run \hgcmd{commit} for the first time, it is not |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
455 guaranteed to succeed. Mercurial records your name and address with |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
456 each change that you commit, so that you and others will later be able |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
457 to tell who made each change. Mercurial tries to automatically figure |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
458 out a sensible username to commit the change with. It will attempt |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
459 each of the following methods, in order: |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
460 \begin{enumerate} |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
461 \item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit} |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
462 command on the command line, followed by a username, this is always |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
463 given the highest precedence. |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
464 \item If you have set the \envar{HGUSER} environment variable, this is |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
465 checked next. |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
466 \item If you create a file in your home directory called |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
467 \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
468 used next. To see what the contents of this file should look like, |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
469 refer to section~\ref{sec:tour-basic:username} below. |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
470 \item If you have set the \envar{EMAIL} environment variable, this |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
471 will be used next. |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
472 \item Mercurial will query your system to find out your local user |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
473 name and host name, and construct a username from these components. |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
474 Since this often results in a username that is not very useful, it |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
475 will print a warning if it has to do this. |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
476 \end{enumerate} |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
477 If all of these mechanisms fail, Mercurial will fail, printing an |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
478 error message. In this case, it will not let you commit until you set |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
479 up a username. |
102 | 480 |
174
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
481 You should think of the \envar{HGUSER} environment variable and the |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
482 \hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
483 \emph{override} Mercurial's default selection of username. For normal |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
484 use, the simplest and most robust way to set a username for yourself |
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
485 is by creating a \sfilename{.hgrc} file; see below for details. |
102 | 486 |
783 | 487 %\subsubsection{Creating a Mercurial configuration file} |
488 \subsubsection{Mercurial$B$N@_Dj%U%!%$%k$r:n@.$9$k(B} | |
174
ef6a1427d0af
Update tour info more usefully.
Bryan O'Sullivan <bos@serpentine.com>
parents:
158
diff
changeset
|
489 \label{sec:tour-basic:username} |
102 | 490 |
491 To set a user name, use your favourite editor to create a file called | |
492 \sfilename{.hgrc} in your home directory. Mercurial will use this | |
493 file to look up your personalised configuration settings. The initial | |
494 contents of your \sfilename{.hgrc} should look like this. | |
495 \begin{codesample2} | |
496 # This is a Mercurial configuration file. | |
497 [ui] | |
498 username = Firstname Lastname <email.address@domain.net> | |
499 \end{codesample2} | |
500 The ``\texttt{[ui]}'' line begins a \emph{section} of the config file, | |
501 so you can read the ``\texttt{username = ...}'' line as meaning ``set | |
502 the value of the \texttt{username} item in the \texttt{ui} section''. | |
503 A section continues until a new section begins, or the end of the | |
504 file. Mercurial ignores empty lines and treats any text from | |
505 ``\texttt{\#}'' to the end of a line as a comment. | |
506 | |
783 | 507 %\subsubsection{Choosing a user name} |
508 \subsubsection{$B%f!<%6L>$rA*$V(B} | |
102 | 509 |
510 You can use any text you like as the value of the \texttt{username} | |
511 config item, since this information is for reading by other people, | |
512 but for interpreting by Mercurial. The convention that most people | |
513 follow is to use their name and email address, as in the example | |
514 above. | |
515 | |
516 \begin{note} | |
517 Mercurial's built-in web server obfuscates email addresses, to make | |
518 it more difficult for the email harvesting tools that spammers use. | |
519 This reduces the likelihood that you'll start receiving more junk | |
520 email if you publish a Mercurial repository on the web. | |
521 \end{note} | |
522 | |
783 | 523 %\subsection{Writing a commit message} |
524 \subsection{$B%3%_%C%H%a%C%;!<%8$r=q$/(B} | |
91 | 525 |
526 When we commit a change, Mercurial drops us into a text editor, to | |
527 enter a message that will describe the modifications we've made in | |
528 this changeset. This is called the \emph{commit message}. It will be | |
529 a record for readers of what we did and why, and it will be printed by | |
530 \hgcmd{log} after we've finished committing. | |
531 \interaction{tour.commit} | |
532 | |
533 The editor that the \hgcmd{commit} command drops us into will contain | |
534 an empty line, followed by a number of lines starting with | |
535 ``\texttt{HG:}''. | |
536 \begin{codesample2} | |
537 \emph{empty line} | |
538 HG: changed hello.c | |
539 \end{codesample2} | |
540 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses | |
541 them only to tell us which files it's recording changes to. Modifying | |
542 or deleting these lines has no effect. | |
543 | |
783 | 544 %\subsection{Writing a good commit message} |
545 \subsection{$B$h$$%3%_%C%H%a%C%;!<%8$N=q$-J}(B} | |
91 | 546 |
547 Since \hgcmd{log} only prints the first line of a commit message by | |
548 default, it's best to write a commit message whose first line stands | |
549 alone. Here's a real example of a commit message that \emph{doesn't} | |
550 follow this guideline, and hence has a summary that is not readable. | |
551 \begin{codesample2} | |
552 changeset: 73:584af0e231be | |
553 user: Censored Person <censored.person@example.org> | |
554 date: Tue Sep 26 21:37:07 2006 -0700 | |
555 summary: include buildmeister/commondefs. Add an exports and install | |
556 \end{codesample2} | |
557 | |
558 As far as the remainder of the contents of the commit message are | |
559 concerned, there are no hard-and-fast rules. Mercurial itself doesn't | |
560 interpret or care about the contents of the commit message, though | |
561 your project may have policies that dictate a certain kind of | |
562 formatting. | |
563 | |
564 My personal preference is for short, but informative, commit messages | |
565 that tell me something that I can't figure out with a quick glance at | |
566 the output of \hgcmdargs{log}{--patch}. | |
567 | |
783 | 568 %\subsection{Aborting a commit} |
569 \subsection{$B%3%_%C%H$rCf;_$9$k(B} | |
91 | 570 |
571 If you decide that you don't want to commit while in the middle of | |
572 editing a commit message, simply exit from your editor without saving | |
573 the file that it's editing. This will cause nothing to happen to | |
574 either the repository or the working directory. | |
575 | |
576 If we run the \hgcmd{commit} command without any arguments, it records | |
577 all of the changes we've made, as reported by \hgcmd{status} and | |
578 \hgcmd{diff}. | |
579 | |
783 | 580 %\subsection{Admiring our new handiwork} |
581 \subsection{$B?7$?$J:n6H$r>N;?$9$k(B} | |
91 | 582 |
583 Once we've finished the commit, we can use the \hgcmd{tip} command to | |
584 display the changeset we just created. This command produces output | |
585 that is identical to \hgcmd{log}, but it only displays the newest | |
586 revision in the repository. | |
587 \interaction{tour.tip} | |
588 We refer to the newest revision in the repository as the tip revision, | |
589 or simply the tip. | |
590 | |
783 | 591 %\section{Sharing changes} |
592 \section{$BJQ99$r6&M-$9$k(B} | |
91 | 593 |
594 We mentioned earlier that repositories in Mercurial are | |
595 self-contained. This means that the changeset we just created exists | |
596 only in our \dirname{my-hello} repository. Let's look at a few ways | |
597 that we can propagate this change into other repositories. | |
598 | |
783 | 599 %\subsection{Pulling changes from another repository} |
600 \subsection{$BB>$N%j%]%8%H%j$+$iJQ99$r(Bpull$B$9$k(B} | |
91 | 601 \label{sec:tour:pull} |
602 | |
603 To get started, let's clone our original \dirname{hello} repository, | |
604 which does not contain the change we just committed. We'll call our | |
605 temporary repository \dirname{hello-pull}. | |
606 \interaction{tour.clone-pull} | |
607 | |
608 We'll use the \hgcmd{pull} command to bring changes from | |
609 \dirname{my-hello} into \dirname{hello-pull}. However, blindly | |
610 pulling unknown changes into a repository is a somewhat scary | |
611 prospect. Mercurial provides the \hgcmd{incoming} command to tell us | |
612 what changes the \hgcmd{pull} command \emph{would} pull into the | |
613 repository, without actually pulling the changes in. | |
614 \interaction{tour.incoming} | |
615 (Of course, someone could cause more changesets to appear in the | |
616 repository that we ran \hgcmd{incoming} in, before we get a chance to | |
617 \hgcmd{pull} the changes, so that we could end up pulling changes that we | |
618 didn't expect.) | |
619 | |
620 Bringing changes into a repository is a simple matter of running the | |
621 \hgcmd{pull} command, and telling it which repository to pull from. | |
622 \interaction{tour.pull} | |
623 As you can see from the before-and-after output of \hgcmd{tip}, we | |
624 have successfully pulled changes into our repository. There remains | |
92 | 625 one step before we can see these changes in the working directory. |
91 | 626 |
783 | 627 %\subsection{Updating the working directory} |
628 \subsection{$B%o!<%-%s%0%G%#%l%/%H%j$r99?7$9$k(B} | |
91 | 629 |
92 | 630 We have so far glossed over the relationship between a repository and |
91 | 631 its working directory. The \hgcmd{pull} command that we ran in |
632 section~\ref{sec:tour:pull} brought changes into the repository, but | |
633 if we check, there's no sign of those changes in the working | |
634 directory. This is because \hgcmd{pull} does not (by default) touch | |
635 the working directory. Instead, we use the \hgcmd{update} command to | |
636 do this. | |
637 \interaction{tour.update} | |
638 | |
639 It might seem a bit strange that \hgcmd{pull} doesn't update the | |
640 working directory automatically. There's actually a good reason for | |
641 this: you can use \hgcmd{update} to update the working directory to | |
642 the state it was in at \emph{any revision} in the history of the | |
643 repository. If you had the working directory updated to an old | |
644 revision---to hunt down the origin of a bug, say---and ran a | |
645 \hgcmd{pull} which automatically updated the working directory to a | |
646 new revision, you might not be terribly happy. | |
647 | |
648 However, since pull-then-update is such a common thing to do, | |
649 Mercurial lets you combine the two by passing the \hgopt{pull}{-u} | |
650 option to \hgcmd{pull}. | |
651 \begin{codesample2} | |
652 hg pull -u | |
653 \end{codesample2} | |
92 | 654 If you look back at the output of \hgcmd{pull} in |
655 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u}, | |
656 you can see that it printed a helpful reminder that we'd have to take | |
657 an explicit step to update the working directory: | |
658 \begin{codesample2} | |
659 (run 'hg update' to get a working copy) | |
660 \end{codesample2} | |
91 | 661 |
662 To find out what revision the working directory is at, use the | |
663 \hgcmd{parents} command. | |
664 \interaction{tour.parents} | |
101
321732566ac1
A few bits of terminological clarification.
Bryan O'Sullivan <bos@serpentine.com>
parents:
99
diff
changeset
|
665 If you look back at figure~\ref{fig:tour-basic:history}, you'll see |
321732566ac1
A few bits of terminological clarification.
Bryan O'Sullivan <bos@serpentine.com>
parents:
99
diff
changeset
|
666 arrows connecting each changeset. The node that the arrow leads |
321732566ac1
A few bits of terminological clarification.
Bryan O'Sullivan <bos@serpentine.com>
parents:
99
diff
changeset
|
667 \emph{from} in each case is a parent, and the node that the arrow |
321732566ac1
A few bits of terminological clarification.
Bryan O'Sullivan <bos@serpentine.com>
parents:
99
diff
changeset
|
668 leads \emph{to} is its child. The working directory has a parent in |
321732566ac1
A few bits of terminological clarification.
Bryan O'Sullivan <bos@serpentine.com>
parents:
99
diff
changeset
|
669 just the same way; this is the changeset that the working directory |
321732566ac1
A few bits of terminological clarification.
Bryan O'Sullivan <bos@serpentine.com>
parents:
99
diff
changeset
|
670 currently contains. |
321732566ac1
A few bits of terminological clarification.
Bryan O'Sullivan <bos@serpentine.com>
parents:
99
diff
changeset
|
671 |
91 | 672 To update the working directory to a particular revision, give a |
673 revision number or changeset~ID to the \hgcmd{update} command. | |
674 \interaction{tour.older} | |
675 If you omit an explicit revision, \hgcmd{update} will update to the | |
94 | 676 tip revision, as shown by the second call to \hgcmd{update} in the |
677 example above. | |
91 | 678 |
783 | 679 %\subsection{Pushing changes to another repository} |
680 \subsection{$BB>$N%j%]%8%H%j$KJQ99$r(Bpush$B$9$k(B} | |
92 | 681 |
682 Mercurial lets us push changes to another repository, from the | |
683 repository we're currently visiting. As with the example of | |
684 \hgcmd{pull} above, we'll create a temporary repository to push our | |
685 changes into. | |
686 \interaction{tour.clone-push} | |
687 The \hgcmd{outgoing} command tells us what changes would be pushed | |
688 into another repository. | |
689 \interaction{tour.outgoing} | |
690 And the \hgcmd{push} command does the actual push. | |
691 \interaction{tour.push} | |
692 As with \hgcmd{pull}, the \hgcmd{push} command does not update the | |
693 working directory in the repository that it's pushing changes into. | |
694 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u} | |
695 option that updates the other repository's working directory.) | |
696 | |
697 What happens if we try to pull or push changes and the receiving | |
698 repository already has those changes? Nothing too exciting. | |
699 \interaction{tour.push.nothing} | |
700 | |
783 | 701 %\subsection{Sharing changes over a network} |
702 \subsection{$BJQ99$r%M%C%H%o!<%/$rDL$8$F6&M-$9$k(B} | |
93 | 703 |
704 The commands we have covered in the previous few sections are not | |
705 limited to working with local repositories. Each works in exactly the | |
706 same fashion over a network connection; simply pass in a URL instead | |
707 of a local path. | |
708 \interaction{tour.outgoing.net} | |
709 In this example, we can see what changes we could push to the remote | |
710 repository, but the repository is understandably not set up to let | |
711 anonymous users push to it. | |
712 \interaction{tour.push.net} | |
713 | |
783 | 714 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
715 %%% mode: yatex |
84 | 716 %%% TeX-master: "00book" |
783 | 717 %%% End: |