Mercurial > hgbook
comparison en/tour.tex @ 91:7524d52d9577
More tour progress.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu, 12 Oct 2006 16:01:40 -0700 |
parents | d351032c189c |
children | 72d207927dc4 |
comparison
equal
deleted
inserted
replaced
90:9d0432dc167a | 91:7524d52d9577 |
---|---|
143 private to Mercurial. Every other file and directory in the | 143 private to Mercurial. Every other file and directory in the |
144 repository is yours to do with as you please. | 144 repository is yours to do with as you please. |
145 | 145 |
146 To introduce a little terminology, the \dirname{.hg} directory is the | 146 To introduce a little terminology, the \dirname{.hg} directory is the |
147 ``real'' repository, and all of the files and directories that coexist | 147 ``real'' repository, and all of the files and directories that coexist |
148 with it are said to live in the ``working directory''. An easy way to | 148 with it are said to live in the \emph{working directory}. An easy way |
149 remember the distinction is that the \emph{repository} contains the | 149 to remember the distinction is that the \emph{repository} contains the |
150 \emph{history} of your project, while the \emph{working directory} | 150 \emph{history} of your project, while the \emph{working directory} |
151 contains a \emph{snapshot} of your project at a particular point in | 151 contains a \emph{snapshot} of your project at a particular point in |
152 history. | 152 history. |
153 | 153 |
154 \section{A tour through history} | 154 \section{A tour through history} |
215 the hexadecimal identifier. | 215 the hexadecimal identifier. |
216 | 216 |
217 \subsection{Viewing specific revisions} | 217 \subsection{Viewing specific revisions} |
218 | 218 |
219 To narrow the output of \hgcmd{log} down to a single revision, use the | 219 To narrow the output of \hgcmd{log} down to a single revision, use the |
220 \hgopt{log}{-r} option. You can use either a revision number or a | 220 \hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a |
221 long-form changeset identifier, and you can provide as many revisions | 221 revision number or a long-form changeset identifier, and you can |
222 as you want. | 222 provide as many revisions as you want. \interaction{tour.log-r} |
223 \interaction{tour.log-r} | |
224 | 223 |
225 If you want to see the history of several revisions without having to | 224 If you want to see the history of several revisions without having to |
226 list each one, you can use \emph{range notation}; this lets you | 225 list each one, you can use \emph{range notation}; this lets you |
227 express the idea ``I want all revisions between $a$ and $b$, | 226 express the idea ``I want all revisions between $a$ and $b$, |
228 inclusive''. | 227 inclusive''. |
229 \interaction{tour.log.range} | 228 \interaction{tour.log.range} |
230 Mercurial also honours the order in which you specify revisions, so | 229 Mercurial also honours the order in which you specify revisions, so |
231 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} | 230 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} |
232 prints $4,3,2$. | 231 prints $4,3,2$. |
233 | 232 |
233 \subsection{More detailed information} | |
234 | |
235 While the summary information printed by \hgcmd{log} is useful if you | |
236 already know what you're looking for, you may need to see a complete | |
237 description of the change, or a list of the files changed, if you're | |
238 trying to decide whether a changeset is the one you're looking for. | |
239 The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) | |
240 option gives you this extra detail. | |
241 \interaction{tour.log-v} | |
242 | |
243 If you want to see both the description and content of a change, add | |
244 the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays | |
245 the content of a change as a \emph{unified diff} (if you've never seen | |
246 a unified diff before, see section~\ref{sec:mq:patch} for an overview). | |
247 \interaction{tour.log-vp} | |
248 | |
249 \section{All about command options} | |
250 | |
251 Let's take a brief break from exploring Mercurial commands to discuss | |
252 a pattern in the way that they work; you may find this useful to keep | |
253 in mind as we continiue our tour. | |
254 | |
255 Mercurial has a consistent and straightforward approach to dealing | |
256 with the options that you can pass to commands. It follows the | |
257 conventions for options that are common to modern Linux and Unix | |
258 systems. | |
259 \begin{itemize} | |
260 \item Every option has a long name. For example, as we've already | |
261 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. | |
262 \item Most options have short names, too. Instead of | |
263 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that | |
264 some options don't have short names is that the options in question | |
265 are rarely used.) | |
266 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), | |
267 while short options start with one (e.g.~\hgopt{log}{-r}). | |
268 \item Option naming and usage is consistent across commands. For | |
269 example, every command that lets you specify a changeset~ID or | |
270 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} | |
271 arguments. | |
272 \end{itemize} | |
273 In the examples throughout this book, I use short options instead of | |
274 long. This just reflects my own preference, so don't read anything | |
275 significant into it. | |
276 | |
277 Most commands that print output of some kind will print more output | |
278 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less | |
279 when passed \hggopt{-q} (or \hggopt{--quiet}). | |
280 | |
281 \section{Making and reviewing changes} | |
282 | |
283 Now that we have a grasp of viewing history in Mercurial, let's take a | |
284 look at making some changes and examining them. | |
285 | |
286 The first thing we'll do is isolate our experiment in a repository of | |
287 its own. We use the \hgcmd{clone} command, but we don't need to | |
288 clone a copy of the remote repository. Since we already have a copy | |
289 of it locally, we can just clone that instead. This is much faster | |
290 than cloning over the network, and cloning a local repository uses | |
291 less disk space in most cases, too. | |
292 \interaction{tour.reclone} | |
293 As an aside, it's often good practice to keep a ``pristine'' copy of a | |
294 remote repository around, which you can then make temporary clones of | |
295 to create sandboxes for each task you want to work on. This lets you | |
296 work on multiple tasks in parallel, each isolated from the others | |
297 until it's complete and you're ready to integrate it back. Because | |
298 local clones are so cheap, there's almost no overhead to cloning and | |
299 destroying repositories whenever you want. | |
300 | |
301 In our \dirname{my-hello} repository, we have a file | |
302 \filename{hello.c} that contains the classic ``hello, world'' program. | |
303 Let's use the ancient and venerable \command{sed} command to edit this | |
304 file so that it prints a second line of output. (I'm only using | |
305 \command{sed} to do this because it's easy to write a scripted example | |
306 this way. Since you're not under the same constraint, you probably | |
307 won't want to use \command{sed}; simply use your preferred text editor to | |
308 do the same thing.) | |
309 \interaction{tour.sed} | |
310 | |
311 Mercurial's \hgcmd{status} command will tell us what Mercurial knows | |
312 about the files in the repository. | |
313 \interaction{tour.status} | |
314 The \hgcmd{status} command prints no output for some files, but a line | |
315 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell | |
316 it to, \hgcmd{status} will not print any output for files that have | |
317 not been modified. | |
318 | |
319 The ``\texttt{M}'' indicates that Mercurial has noticed that we | |
320 modified \filename{hello.c}. Notice that we didn't need to | |
321 \emph{inform} Mercurial that we were going to modify the file before | |
322 we started, or that we had modified the file after we were done; it | |
323 was able to figure this out itself. | |
324 | |
325 It's a little bit helpful to know that we've modified | |
326 \filename{hello.c}, but we might prefer to know exactly \emph{what} | |
327 changes we've made to it. To do this, we use the \hgcmd{diff} | |
328 command. | |
329 \interaction{tour.diff} | |
330 | |
331 \section{Recording changes in a new changeset} | |
332 | |
333 We can modify files, build and test our changes, and use | |
334 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're | |
335 satisfied with what we've done and arrive at a natural stopping point | |
336 where we want to record our work in a new changeset. | |
337 | |
338 The \hgcmd{commit} command lets us create a new changeset; we'll | |
339 usually refer to this as ``making a commit'' or ``committing''. | |
340 | |
341 \subsection{Writing a commit message} | |
342 | |
343 When we commit a change, Mercurial drops us into a text editor, to | |
344 enter a message that will describe the modifications we've made in | |
345 this changeset. This is called the \emph{commit message}. It will be | |
346 a record for readers of what we did and why, and it will be printed by | |
347 \hgcmd{log} after we've finished committing. | |
348 \interaction{tour.commit} | |
349 | |
350 The editor that the \hgcmd{commit} command drops us into will contain | |
351 an empty line, followed by a number of lines starting with | |
352 ``\texttt{HG:}''. | |
353 \begin{codesample2} | |
354 \emph{empty line} | |
355 HG: changed hello.c | |
356 \end{codesample2} | |
357 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses | |
358 them only to tell us which files it's recording changes to. Modifying | |
359 or deleting these lines has no effect. | |
360 | |
361 \subsection{Writing a good commit message} | |
362 | |
363 Since \hgcmd{log} only prints the first line of a commit message by | |
364 default, it's best to write a commit message whose first line stands | |
365 alone. Here's a real example of a commit message that \emph{doesn't} | |
366 follow this guideline, and hence has a summary that is not readable. | |
367 \begin{codesample2} | |
368 changeset: 73:584af0e231be | |
369 user: Censored Person <censored.person@example.org> | |
370 date: Tue Sep 26 21:37:07 2006 -0700 | |
371 summary: include buildmeister/commondefs. Add an exports and install | |
372 \end{codesample2} | |
373 | |
374 As far as the remainder of the contents of the commit message are | |
375 concerned, there are no hard-and-fast rules. Mercurial itself doesn't | |
376 interpret or care about the contents of the commit message, though | |
377 your project may have policies that dictate a certain kind of | |
378 formatting. | |
379 | |
380 My personal preference is for short, but informative, commit messages | |
381 that tell me something that I can't figure out with a quick glance at | |
382 the output of \hgcmdargs{log}{--patch}. | |
383 | |
384 \subsection{Aborting a commit} | |
385 | |
386 If you decide that you don't want to commit while in the middle of | |
387 editing a commit message, simply exit from your editor without saving | |
388 the file that it's editing. This will cause nothing to happen to | |
389 either the repository or the working directory. | |
390 | |
391 If we run the \hgcmd{commit} command without any arguments, it records | |
392 all of the changes we've made, as reported by \hgcmd{status} and | |
393 \hgcmd{diff}. | |
394 | |
395 \subsection{Admiring our new handywork} | |
396 | |
397 Once we've finished the commit, we can use the \hgcmd{tip} command to | |
398 display the changeset we just created. This command produces output | |
399 that is identical to \hgcmd{log}, but it only displays the newest | |
400 revision in the repository. | |
401 \interaction{tour.tip} | |
402 We refer to the newest revision in the repository as the tip revision, | |
403 or simply the tip. | |
404 | |
405 \section{Sharing changes} | |
406 | |
407 We mentioned earlier that repositories in Mercurial are | |
408 self-contained. This means that the changeset we just created exists | |
409 only in our \dirname{my-hello} repository. Let's look at a few ways | |
410 that we can propagate this change into other repositories. | |
411 | |
412 \subsection{Pulling changes from another repository} | |
413 \label{sec:tour:pull} | |
414 | |
415 To get started, let's clone our original \dirname{hello} repository, | |
416 which does not contain the change we just committed. We'll call our | |
417 temporary repository \dirname{hello-pull}. | |
418 \interaction{tour.clone-pull} | |
419 | |
420 We'll use the \hgcmd{pull} command to bring changes from | |
421 \dirname{my-hello} into \dirname{hello-pull}. However, blindly | |
422 pulling unknown changes into a repository is a somewhat scary | |
423 prospect. Mercurial provides the \hgcmd{incoming} command to tell us | |
424 what changes the \hgcmd{pull} command \emph{would} pull into the | |
425 repository, without actually pulling the changes in. | |
426 \interaction{tour.incoming} | |
427 (Of course, someone could cause more changesets to appear in the | |
428 repository that we ran \hgcmd{incoming} in, before we get a chance to | |
429 \hgcmd{pull} the changes, so that we could end up pulling changes that we | |
430 didn't expect.) | |
431 | |
432 Bringing changes into a repository is a simple matter of running the | |
433 \hgcmd{pull} command, and telling it which repository to pull from. | |
434 \interaction{tour.pull} | |
435 As you can see from the before-and-after output of \hgcmd{tip}, we | |
436 have successfully pulled changes into our repository. There remains | |
437 one step before we can work with those changes. | |
438 | |
439 \section{Updating the working directory} | |
440 | |
441 We have so far glossed over the relatioship between a repository and | |
442 its working directory. The \hgcmd{pull} command that we ran in | |
443 section~\ref{sec:tour:pull} brought changes into the repository, but | |
444 if we check, there's no sign of those changes in the working | |
445 directory. This is because \hgcmd{pull} does not (by default) touch | |
446 the working directory. Instead, we use the \hgcmd{update} command to | |
447 do this. | |
448 \interaction{tour.update} | |
449 | |
450 It might seem a bit strange that \hgcmd{pull} doesn't update the | |
451 working directory automatically. There's actually a good reason for | |
452 this: you can use \hgcmd{update} to update the working directory to | |
453 the state it was in at \emph{any revision} in the history of the | |
454 repository. If you had the working directory updated to an old | |
455 revision---to hunt down the origin of a bug, say---and ran a | |
456 \hgcmd{pull} which automatically updated the working directory to a | |
457 new revision, you might not be terribly happy. | |
458 | |
459 However, since pull-then-update is such a common thing to do, | |
460 Mercurial lets you combine the two by passing the \hgopt{pull}{-u} | |
461 option to \hgcmd{pull}. | |
462 \begin{codesample2} | |
463 hg pull -u | |
464 \end{codesample2} | |
465 | |
466 To find out what revision the working directory is at, use the | |
467 \hgcmd{parents} command. | |
468 \interaction{tour.parents} | |
469 To update the working directory to a particular revision, give a | |
470 revision number or changeset~ID to the \hgcmd{update} command. | |
471 \interaction{tour.older} | |
472 If you omit an explicit revision, \hgcmd{update} will update to the | |
473 tip revision. | |
474 | |
234 %%% Local Variables: | 475 %%% Local Variables: |
235 %%% mode: latex | 476 %%% mode: latex |
236 %%% TeX-master: "00book" | 477 %%% TeX-master: "00book" |
237 %%% End: | 478 %%% End: |