hgbook
changeset 91:7524d52d9577
More tour progress.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu Oct 12 16:01:40 2006 -0700 (2006-10-12) |
parents | 9d0432dc167a |
children | 72d207927dc4 |
files | en/examples/tour en/tour.tex |
line diff
1.1 --- a/en/examples/tour Thu Oct 12 14:46:54 2006 -0700 1.2 +++ b/en/examples/tour Thu Oct 12 16:01:40 2006 -0700 1.3 @@ -35,3 +35,73 @@ 1.4 #$ name: log.range 1.5 1.6 hg log -r 2:4 1.7 + 1.8 +#$ name: log-v 1.9 + 1.10 +hg log -v -r 3 1.11 + 1.12 +#$ name: log-vp 1.13 + 1.14 +hg log -v -p -r 2 1.15 + 1.16 +#$ name: reclone 1.17 + 1.18 +cd .. 1.19 +hg clone hello my-hello 1.20 +cd my-hello 1.21 + 1.22 +#$ name: sed 1.23 + 1.24 +sed -i '/printf/a\\tprintf("hello again!\\n");' hello.c 1.25 + 1.26 +#$ name: status 1.27 + 1.28 +ls 1.29 +hg status 1.30 + 1.31 +#$ name: diff 1.32 + 1.33 +hg diff 1.34 + 1.35 +#$ name: 1.36 + 1.37 +export HGEDITOR='echo Added an extra line of output >' 1.38 + 1.39 +#$ name: commit 1.40 + 1.41 +hg commit 1.42 + 1.43 +#$ name: tip 1.44 + 1.45 +hg tip -vp 1.46 + 1.47 +#$ name: clone-pull 1.48 + 1.49 +cd .. 1.50 +hg clone hello hello-pull 1.51 + 1.52 +#$ name: incoming 1.53 + 1.54 +cd hello-pull 1.55 +hg incoming ../my-hello 1.56 + 1.57 +#$ name: pull 1.58 + 1.59 +hg tip 1.60 +hg pull ../my-hello 1.61 +hg tip 1.62 + 1.63 +#$ name: update 1.64 + 1.65 +grep printf hello.c 1.66 +hg update tip 1.67 +grep printf hello.c 1.68 + 1.69 +#$ name: parents 1.70 + 1.71 +hg parents 1.72 + 1.73 +#$ name: older 1.74 + 1.75 +hg update 2 1.76 +hg parents
2.1 --- a/en/tour.tex Thu Oct 12 14:46:54 2006 -0700 2.2 +++ b/en/tour.tex Thu Oct 12 16:01:40 2006 -0700 2.3 @@ -145,8 +145,8 @@ 2.4 2.5 To introduce a little terminology, the \dirname{.hg} directory is the 2.6 ``real'' repository, and all of the files and directories that coexist 2.7 -with it are said to live in the ``working directory''. An easy way to 2.8 -remember the distinction is that the \emph{repository} contains the 2.9 +with it are said to live in the \emph{working directory}. An easy way 2.10 +to remember the distinction is that the \emph{repository} contains the 2.11 \emph{history} of your project, while the \emph{working directory} 2.12 contains a \emph{snapshot} of your project at a particular point in 2.13 history. 2.14 @@ -217,10 +217,9 @@ 2.15 \subsection{Viewing specific revisions} 2.16 2.17 To narrow the output of \hgcmd{log} down to a single revision, use the 2.18 -\hgopt{log}{-r} option. You can use either a revision number or a 2.19 -long-form changeset identifier, and you can provide as many revisions 2.20 -as you want. 2.21 -\interaction{tour.log-r} 2.22 +\hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a 2.23 +revision number or a long-form changeset identifier, and you can 2.24 +provide as many revisions as you want. \interaction{tour.log-r} 2.25 2.26 If you want to see the history of several revisions without having to 2.27 list each one, you can use \emph{range notation}; this lets you 2.28 @@ -231,6 +230,248 @@ 2.29 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} 2.30 prints $4,3,2$. 2.31 2.32 +\subsection{More detailed information} 2.33 + 2.34 +While the summary information printed by \hgcmd{log} is useful if you 2.35 +already know what you're looking for, you may need to see a complete 2.36 +description of the change, or a list of the files changed, if you're 2.37 +trying to decide whether a changeset is the one you're looking for. 2.38 +The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) 2.39 +option gives you this extra detail. 2.40 +\interaction{tour.log-v} 2.41 + 2.42 +If you want to see both the description and content of a change, add 2.43 +the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays 2.44 +the content of a change as a \emph{unified diff} (if you've never seen 2.45 +a unified diff before, see section~\ref{sec:mq:patch} for an overview). 2.46 +\interaction{tour.log-vp} 2.47 + 2.48 +\section{All about command options} 2.49 + 2.50 +Let's take a brief break from exploring Mercurial commands to discuss 2.51 +a pattern in the way that they work; you may find this useful to keep 2.52 +in mind as we continiue our tour. 2.53 + 2.54 +Mercurial has a consistent and straightforward approach to dealing 2.55 +with the options that you can pass to commands. It follows the 2.56 +conventions for options that are common to modern Linux and Unix 2.57 +systems. 2.58 +\begin{itemize} 2.59 +\item Every option has a long name. For example, as we've already 2.60 + seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. 2.61 +\item Most options have short names, too. Instead of 2.62 + \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that 2.63 + some options don't have short names is that the options in question 2.64 + are rarely used.) 2.65 +\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), 2.66 + while short options start with one (e.g.~\hgopt{log}{-r}). 2.67 +\item Option naming and usage is consistent across commands. For 2.68 + example, every command that lets you specify a changeset~ID or 2.69 + revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} 2.70 + arguments. 2.71 +\end{itemize} 2.72 +In the examples throughout this book, I use short options instead of 2.73 +long. This just reflects my own preference, so don't read anything 2.74 +significant into it. 2.75 + 2.76 +Most commands that print output of some kind will print more output 2.77 +when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less 2.78 +when passed \hggopt{-q} (or \hggopt{--quiet}). 2.79 + 2.80 +\section{Making and reviewing changes} 2.81 + 2.82 +Now that we have a grasp of viewing history in Mercurial, let's take a 2.83 +look at making some changes and examining them. 2.84 + 2.85 +The first thing we'll do is isolate our experiment in a repository of 2.86 +its own. We use the \hgcmd{clone} command, but we don't need to 2.87 +clone a copy of the remote repository. Since we already have a copy 2.88 +of it locally, we can just clone that instead. This is much faster 2.89 +than cloning over the network, and cloning a local repository uses 2.90 +less disk space in most cases, too. 2.91 +\interaction{tour.reclone} 2.92 +As an aside, it's often good practice to keep a ``pristine'' copy of a 2.93 +remote repository around, which you can then make temporary clones of 2.94 +to create sandboxes for each task you want to work on. This lets you 2.95 +work on multiple tasks in parallel, each isolated from the others 2.96 +until it's complete and you're ready to integrate it back. Because 2.97 +local clones are so cheap, there's almost no overhead to cloning and 2.98 +destroying repositories whenever you want. 2.99 + 2.100 +In our \dirname{my-hello} repository, we have a file 2.101 +\filename{hello.c} that contains the classic ``hello, world'' program. 2.102 +Let's use the ancient and venerable \command{sed} command to edit this 2.103 +file so that it prints a second line of output. (I'm only using 2.104 +\command{sed} to do this because it's easy to write a scripted example 2.105 +this way. Since you're not under the same constraint, you probably 2.106 +won't want to use \command{sed}; simply use your preferred text editor to 2.107 +do the same thing.) 2.108 +\interaction{tour.sed} 2.109 + 2.110 +Mercurial's \hgcmd{status} command will tell us what Mercurial knows 2.111 +about the files in the repository. 2.112 +\interaction{tour.status} 2.113 +The \hgcmd{status} command prints no output for some files, but a line 2.114 +starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell 2.115 +it to, \hgcmd{status} will not print any output for files that have 2.116 +not been modified. 2.117 + 2.118 +The ``\texttt{M}'' indicates that Mercurial has noticed that we 2.119 +modified \filename{hello.c}. Notice that we didn't need to 2.120 +\emph{inform} Mercurial that we were going to modify the file before 2.121 +we started, or that we had modified the file after we were done; it 2.122 +was able to figure this out itself. 2.123 + 2.124 +It's a little bit helpful to know that we've modified 2.125 +\filename{hello.c}, but we might prefer to know exactly \emph{what} 2.126 +changes we've made to it. To do this, we use the \hgcmd{diff} 2.127 +command. 2.128 +\interaction{tour.diff} 2.129 + 2.130 +\section{Recording changes in a new changeset} 2.131 + 2.132 +We can modify files, build and test our changes, and use 2.133 +\hgcmd{status} and \hgcmd{diff} to review our changes, until we're 2.134 +satisfied with what we've done and arrive at a natural stopping point 2.135 +where we want to record our work in a new changeset. 2.136 + 2.137 +The \hgcmd{commit} command lets us create a new changeset; we'll 2.138 +usually refer to this as ``making a commit'' or ``committing''. 2.139 + 2.140 +\subsection{Writing a commit message} 2.141 + 2.142 +When we commit a change, Mercurial drops us into a text editor, to 2.143 +enter a message that will describe the modifications we've made in 2.144 +this changeset. This is called the \emph{commit message}. It will be 2.145 +a record for readers of what we did and why, and it will be printed by 2.146 +\hgcmd{log} after we've finished committing. 2.147 +\interaction{tour.commit} 2.148 + 2.149 +The editor that the \hgcmd{commit} command drops us into will contain 2.150 +an empty line, followed by a number of lines starting with 2.151 +``\texttt{HG:}''. 2.152 +\begin{codesample2} 2.153 + \emph{empty line} 2.154 + HG: changed hello.c 2.155 +\end{codesample2} 2.156 +Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses 2.157 +them only to tell us which files it's recording changes to. Modifying 2.158 +or deleting these lines has no effect. 2.159 + 2.160 +\subsection{Writing a good commit message} 2.161 + 2.162 +Since \hgcmd{log} only prints the first line of a commit message by 2.163 +default, it's best to write a commit message whose first line stands 2.164 +alone. Here's a real example of a commit message that \emph{doesn't} 2.165 +follow this guideline, and hence has a summary that is not readable. 2.166 +\begin{codesample2} 2.167 + changeset: 73:584af0e231be 2.168 + user: Censored Person <censored.person@example.org> 2.169 + date: Tue Sep 26 21:37:07 2006 -0700 2.170 + summary: include buildmeister/commondefs. Add an exports and install 2.171 +\end{codesample2} 2.172 + 2.173 +As far as the remainder of the contents of the commit message are 2.174 +concerned, there are no hard-and-fast rules. Mercurial itself doesn't 2.175 +interpret or care about the contents of the commit message, though 2.176 +your project may have policies that dictate a certain kind of 2.177 +formatting. 2.178 + 2.179 +My personal preference is for short, but informative, commit messages 2.180 +that tell me something that I can't figure out with a quick glance at 2.181 +the output of \hgcmdargs{log}{--patch}. 2.182 + 2.183 +\subsection{Aborting a commit} 2.184 + 2.185 +If you decide that you don't want to commit while in the middle of 2.186 +editing a commit message, simply exit from your editor without saving 2.187 +the file that it's editing. This will cause nothing to happen to 2.188 +either the repository or the working directory. 2.189 + 2.190 +If we run the \hgcmd{commit} command without any arguments, it records 2.191 +all of the changes we've made, as reported by \hgcmd{status} and 2.192 +\hgcmd{diff}. 2.193 + 2.194 +\subsection{Admiring our new handywork} 2.195 + 2.196 +Once we've finished the commit, we can use the \hgcmd{tip} command to 2.197 +display the changeset we just created. This command produces output 2.198 +that is identical to \hgcmd{log}, but it only displays the newest 2.199 +revision in the repository. 2.200 +\interaction{tour.tip} 2.201 +We refer to the newest revision in the repository as the tip revision, 2.202 +or simply the tip. 2.203 + 2.204 +\section{Sharing changes} 2.205 + 2.206 +We mentioned earlier that repositories in Mercurial are 2.207 +self-contained. This means that the changeset we just created exists 2.208 +only in our \dirname{my-hello} repository. Let's look at a few ways 2.209 +that we can propagate this change into other repositories. 2.210 + 2.211 +\subsection{Pulling changes from another repository} 2.212 +\label{sec:tour:pull} 2.213 + 2.214 +To get started, let's clone our original \dirname{hello} repository, 2.215 +which does not contain the change we just committed. We'll call our 2.216 +temporary repository \dirname{hello-pull}. 2.217 +\interaction{tour.clone-pull} 2.218 + 2.219 +We'll use the \hgcmd{pull} command to bring changes from 2.220 +\dirname{my-hello} into \dirname{hello-pull}. However, blindly 2.221 +pulling unknown changes into a repository is a somewhat scary 2.222 +prospect. Mercurial provides the \hgcmd{incoming} command to tell us 2.223 +what changes the \hgcmd{pull} command \emph{would} pull into the 2.224 +repository, without actually pulling the changes in. 2.225 +\interaction{tour.incoming} 2.226 +(Of course, someone could cause more changesets to appear in the 2.227 +repository that we ran \hgcmd{incoming} in, before we get a chance to 2.228 +\hgcmd{pull} the changes, so that we could end up pulling changes that we 2.229 +didn't expect.) 2.230 + 2.231 +Bringing changes into a repository is a simple matter of running the 2.232 +\hgcmd{pull} command, and telling it which repository to pull from. 2.233 +\interaction{tour.pull} 2.234 +As you can see from the before-and-after output of \hgcmd{tip}, we 2.235 +have successfully pulled changes into our repository. There remains 2.236 +one step before we can work with those changes. 2.237 + 2.238 +\section{Updating the working directory} 2.239 + 2.240 +We have so far glossed over the relatioship between a repository and 2.241 +its working directory. The \hgcmd{pull} command that we ran in 2.242 +section~\ref{sec:tour:pull} brought changes into the repository, but 2.243 +if we check, there's no sign of those changes in the working 2.244 +directory. This is because \hgcmd{pull} does not (by default) touch 2.245 +the working directory. Instead, we use the \hgcmd{update} command to 2.246 +do this. 2.247 +\interaction{tour.update} 2.248 + 2.249 +It might seem a bit strange that \hgcmd{pull} doesn't update the 2.250 +working directory automatically. There's actually a good reason for 2.251 +this: you can use \hgcmd{update} to update the working directory to 2.252 +the state it was in at \emph{any revision} in the history of the 2.253 +repository. If you had the working directory updated to an old 2.254 +revision---to hunt down the origin of a bug, say---and ran a 2.255 +\hgcmd{pull} which automatically updated the working directory to a 2.256 +new revision, you might not be terribly happy. 2.257 + 2.258 +However, since pull-then-update is such a common thing to do, 2.259 +Mercurial lets you combine the two by passing the \hgopt{pull}{-u} 2.260 +option to \hgcmd{pull}. 2.261 +\begin{codesample2} 2.262 + hg pull -u 2.263 +\end{codesample2} 2.264 + 2.265 +To find out what revision the working directory is at, use the 2.266 +\hgcmd{parents} command. 2.267 +\interaction{tour.parents} 2.268 +To update the working directory to a particular revision, give a 2.269 +revision number or changeset~ID to the \hgcmd{update} command. 2.270 +\interaction{tour.older} 2.271 +If you omit an explicit revision, \hgcmd{update} will update to the 2.272 +tip revision. 2.273 + 2.274 %%% Local Variables: 2.275 %%% mode: latex 2.276 %%% TeX-master: "00book"