2 A tour of Mercurial: the basics
6 This document is a modified version originally known as "Distributed
7 revision control with Mercurial" and originally authored by Bryan
8 O’Sullivan. The original document was obtained from
9 <http://hgbook.red-bean.com/>.
11 Copyright © 2006, 2007 Bryan O’Sullivan.
13 This material may be distributed only subject to the terms and
14 conditions set forth in version 1.0 of the Open Publication
15 License. Please refer to Appendix D for the license text.
17 As this is a modified version, the name of Bryan O'Sullivan is used
18 only to properly credit him with the original text. The appearance of
19 his name here explicitly does not assert or imply his endorsement of
20 this modified document.
22 Portions Copyright © 2007 Carl Worth.
24 Changes made by Carl include the following:
27 * Convert from HTML to markdown source syntax
28 * Eliminate all content except Chapter 2 and Appendix D
29 * Eliminate line numbers from examples
31 ### 2.1 Installing Mercurial on your system
33 Prebuilt binary packages of Mercurial are available for every popular
34 operating system. These make it easy to start using Mercurial on your
39 Because each Linux distribution has its own packaging tools, policies,
40 and rate of development, it’s difficult to give a comprehensive set of
41 instructions on how to install Mercurial binaries. The version of
42 Mercurial that you will end up with can vary depending on how active
43 the person is who maintains the package for your distribution.
45 To keep things simple, I will focus on installing Mercurial from the
46 command line under the most popular Linux distributions. Most of these
47 distributions provide graphical package managers that will let you
48 install Mercurial with a single click; the package name to look for is
53 apt-get install mercurial
67 * Ubuntu Ubuntu’s Mercurial package is based on Debian’s. To install
68 it, run the following command.
70 apt-get install mercurial
72 The Ubuntu package for Mercurial tends to lag behind the Debian
73 version by a considerable time margin (at the time of writing, seven
74 months), which in some cases will mean that on Ubuntu, you may run
75 into problems that have since been fixed in the Debian package.
83 Lee Cantey publishes an installer of Mercurial for Mac OS X at
84 [http://mercurial.berkwood.com][6]. This package works on both
85 Intel- and Power-based Macs. Before you can use it, you must install a
86 compatible version of Universal MacPython [[BI][7]]. This is easy to
87 do; simply follow the instructions on Lee’s site.
91 Lee Cantey also publishes an installer of Mercurial for Windows at
92 [http://mercurial.berkwood.com][6]. This package has no external
93 dependencies; it “just works”.
95 Note: The Windows version of Mercurial does not automatically convert
96 line endings between Windows and Unix styles. If you want to share
97 work with Unix users, you must do a little additional configuration
98 work. XXX Flesh this out.
100 ### 2.2 Getting started
102 To begin, we’ll use the “hg version” command to find out whether
103 Mercurial is actually installed properly. The actual version
104 information that it prints isn’t so important; it’s whether it prints
105 anything at all that we care about.
108 Mercurial Distributed SCM (version 2937d0dbfab0)
110 Copyright (C) 2005, 2006 Matt Mackall <mpm@selenic.com>
111 This is free software; see the source for copying conditions. There is NO
112 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
114 #### 2.2.1 Built-in help
116 Mercurial provides a built-in help system. This is invaluable for
117 those times when you find yourself stuck trying to remember how to run
118 a command. If you are completely stuck, simply run “hg help”; it will
119 print a brief list of commands, along with a description of what each
120 does. If you ask for help on a specific command (as below), it prints
121 more detailed information.
124 hg init [-e CMD] [--remotecmd CMD] [DEST]
126 create a new repository in the given directory
128 Initialize a new repository in the given directory. If the given
129 directory does not exist, it is created.
131 If no directory is given, the current directory is used.
133 It is possible to specify an ssh:// URL as the destination.
134 Look at the help text for the pull command for important details
139 -e --ssh specify ssh command to use
140 --remotecmd specify hg command to run on the remote side
142 use "hg -v help init" to show global options
144 For a more impressive level of detail (which you won’t usually need)
145 run “hg help -v”. The -v option is short for --verbose, and tells
146 Mercurial to print more information than it usually would.
148 ### 2.3 Working with a repository
150 In Mercurial, everything happens inside a repository. The repository
151 for a project contains all of the files that “belong to” that project,
152 along with a historical record of the project’s files.
154 There’s nothing particularly magical about a repository; it is simply
155 a directory tree in your filesystem that Mercurial treats as
156 special. You can rename or delete a repository any time you like,
157 using either the command line or your file browser.
159 #### 2.3.1 Making a local copy of a repository
161 Copying a repository is just a little bit special. While you could use
162 a normal file copying command to make a copy of a repository, it’s
163 best to use a built-in command that Mercurial provides. This command
164 is called “hg clone”, because it creates an identical copy of an
167 $ hg clone http://hg.serpentine.com/tutorial/hello
168 destination directory: hello
169 requesting all changes
173 added 5 changesets with 5 changes to 2 files
174 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
176 If our clone succeeded, we should now have a local directory called
177 hello. This directory will contain some files.
181 drwxrwxr-x 3 bos bos 4096 Jun 17 18:05 hello
185 These files have the same contents and history in our repository as
186 they do in the repository we cloned.
188 Every Mercurial repository is complete, self-contained, and
189 independent. It contains its own private copy of a project’s files and
190 history. A cloned repository remembers the location of the repository
191 it was cloned from, but it does not communicate with that repository,
192 or any other, unless you tell it to.
194 What this means for now is that we’re free to experiment with our
195 repository, safe in the knowledge that it’s a private “sandbox” that
196 won’t affect anyone else.
198 #### 2.3.2 What’s in a repository?
200 When we take a more detailed look inside a repository, we can see that
201 it contains a directory named .hg. This is where Mercurial keeps all
202 of its metadata for the repository.
206 . .. .hg Makefile hello.c
208 The contents of the .hg directory and its subdirectories are private
209 to Mercurial. Every other file and directory in the repository is
210 yours to do with as you please.
212 To introduce a little terminology, the .hg directory is the “real”
213 repository, and all of the files and directories that coexist with it
214 are said to live in the working directory. An easy way to remember the
215 distinction is that the repository contains the history of your
216 project, while the working directory contains a snapshot of your
217 project at a particular point in history.
219 ### 2.4 A tour through history
221 One of the first things we might want to do with a new, unfamiliar
222 repository is understand its history. The “hg log” command gives us a
226 changeset: 4:b57f9a090b62
228 user: Bryan O'Sullivan <bos@serpentine.com>
229 date: Tue Sep 06 15:43:07 2005 -0700
230 summary: Trim comments.
232 changeset: 3:ff5d7b70a2a9
233 user: Bryan O'Sullivan <bos@serpentine.com>
234 date: Tue Sep 06 13:15:58 2005 -0700
235 summary: Get make to generate the final binary from a .o file.
237 changeset: 2:057d3c2d823c
238 user: Bryan O'Sullivan <bos@serpentine.com>
239 date: Tue Sep 06 13:15:43 2005 -0700
240 summary: Introduce a typo into hello.c.
242 changeset: 1:82e55d328c8c
243 user: mpm@selenic.com
244 date: Fri Aug 26 01:21:28 2005 -0700
245 summary: Create a makefile
247 changeset: 0:0a04b987be5a
248 user: mpm@selenic.com
249 date: Fri Aug 26 01:20:50 2005 -0700
250 summary: Create a standard "hello, world" program
253 By default, this command prints a brief paragraph of output for each
254 change to the project that was recorded. In Mercurial terminology, we
255 call each of these recorded events a changeset, because it can contain
256 a record of changes to several files.
258 The fields in a record of output from “hg log” are as follows.
260 * changeset This field has the format of a number, followed by a
261 colon, followed by a hexadecimal string. These are identifiers for
262 the changeset. There are two identifiers because the number is
263 shorter and easier to type than the hex string.
264 * user The identity of the person who created the changeset. This is
265 a free-form field, but it most often contains a person’s name and
267 * date The date and time on which the changeset was created, and the
268 timezone in which it was created. (The date and time are local to
269 that timezone; they display what time and date it was for the
270 person who created the changeset.)
271 * summary The first line of the text message that the creator of the
272 changeset entered to describe the changeset.
274 The default output printed by “hg log” is purely a summary; it is
275 missing a lot of detail.
277 Figure [2.1][8] provides a graphical representation of the history of
278 the hello repository, to make it a little easier to see which
279 direction history is “flowing” in. We’ll be returning to this figure
280 several times in this chapter and the chapter that follows.
287 Graphical history of the hello repository
291 #### 2.4.1 Changesets, revisions, and talking to other people
293 As English is a notoriously sloppy language, and computer science has
294 a hallowed history of terminological confusion (why use one term when
295 four will do?), revision control has a variety of words and phrases
296 that mean the same thing. If you are talking about Mercurial history
297 with other people, you will find that the word “changeset” is often
298 compressed to “change” or (when written) “cset”, and sometimes a
299 changeset is referred to as a “revision” or a “rev”.
301 While it doesn’t matter what word you use to refer to the concept of
302 “a changeset”, the identifier that you use to refer to “a specific
303 changeset” is of great importance. Recall that the changeset field in
304 the output from “hg log” identifies a changeset using both a number
305 and a hexadecimal string.
307 * The revision number is only valid in that repository,
308 * while the hex string is the permanent, unchanging identifier that
309 will always identify that exact changeset in every copy of the
312 This distinction is important. If you send someone an email talking
313 about “revision 33”, there’s a high likelihood that their revision 33
314 will not be the same as yours. The reason for this is that a revision
315 number depends on the order in which changes arrived in a repository,
316 and there is no guarantee that the same changes will happen in the
317 same order in different repositories. Three changes a,b,c can easily
318 appear in one repository as 0,1,2, while in another as 1,0,2.
320 Mercurial uses revision numbers purely as a convenient shorthand. If
321 you need to discuss a changeset with someone, or make a record of a
322 changeset for some other reason (for example, in a bug report), use
323 the hexadecimal identifier.
325 #### 2.4.2 Viewing specific revisions
327 To narrow the output of “hg log” down to a single revision, use the -r
328 (or --rev) option. You can use either a revision number or a long-form
329 changeset identifier, and you can provide as many revisions as you
333 changeset: 3:ff5d7b70a2a9
334 user: Bryan O'Sullivan <bos@serpentine.com>
335 date: Tue Sep 06 13:15:58 2005 -0700
336 summary: Get make to generate the final binary from a .o file.
338 $ hg log -r ff5d7b70a2a9
339 changeset: 3:ff5d7b70a2a9
340 user: Bryan O'Sullivan <bos@serpentine.com>
341 date: Tue Sep 06 13:15:58 2005 -0700
342 summary: Get make to generate the final binary from a .o file.
345 changeset: 1:82e55d328c8c
346 user: mpm@selenic.com
347 date: Fri Aug 26 01:21:28 2005 -0700
348 summary: Create a makefile
350 changeset: 4:b57f9a090b62
352 user: Bryan O'Sullivan <bos@serpentine.com>
353 date: Tue Sep 06 15:43:07 2005 -0700
354 summary: Trim comments.
357 If you want to see the history of several revisions without having to
358 list each one, you can use range notation; this lets you express the
359 idea “I want all revisions between a and b, inclusive”.
362 changeset: 2:057d3c2d823c
363 user: Bryan O'Sullivan <bos@serpentine.com>
364 date: Tue Sep 06 13:15:43 2005 -0700
365 summary: Introduce a typo into hello.c.
367 changeset: 3:ff5d7b70a2a9
368 user: Bryan O'Sullivan <bos@serpentine.com>
369 date: Tue Sep 06 13:15:58 2005 -0700
370 summary: Get make to generate the final binary from a .o file.
372 changeset: 4:b57f9a090b62
374 user: Bryan O'Sullivan <bos@serpentine.com>
375 date: Tue Sep 06 15:43:07 2005 -0700
376 summary: Trim comments.
379 Mercurial also honours the order in which you specify revisions, so
380 “hg log -r 2:4” prints 2,3,4 while “hg log -r 4:2” prints 4,3,2.
382 #### 2.4.3 More detailed information
384 While the summary information printed by “hg log” is useful if you
385 already know what you’re looking for, you may need to see a complete
386 description of the change, or a list of the files changed, if you’re
387 trying to decide whether a changeset is the one you’re looking
388 for. The “hg log” command’s -v (or --verbose) option gives you this
392 changeset: 3:ff5d7b70a2a9
393 user: Bryan O'Sullivan <bos@serpentine.com>
394 date: Tue Sep 06 13:15:58 2005 -0700
397 Get make to generate the final binary from a .o file.
401 If you want to see both the description and content of a change, add
402 the -p (or --patch) option. This displays the content of a change as a
403 unified diff (if you’ve never seen a unified diff before, see
404 section [12.4][10] for an overview).
407 changeset: 2:057d3c2d823c
408 user: Bryan O'Sullivan <bos@serpentine.com>
409 date: Tue Sep 06 13:15:43 2005 -0700
412 Introduce a typo into hello.c.
415 diff -r 82e55d328c8c -r 057d3c2d823c hello.c
416 --- a/hello.c Fri Aug 26 01:21:28 2005 -0700
417 +++ b/hello.c Tue Sep 06 13:15:43 2005 -0700
420 int main(int argc, char ⋆⋆argv)
422 - printf("hello, world!∖n");
423 + printf("hello, world!∖");
428 ### 2.5 All about command options
430 Let’s take a brief break from exploring Mercurial commands to discuss
431 a pattern in the way that they work; you may find this useful to keep
432 in mind as we continue our tour.
434 Mercurial has a consistent and straightforward approach to dealing
435 with the options that you can pass to commands. It follows the
436 conventions for options that are common to modern Linux and Unix
439 * Every option has a long name. For example, as we’ve already seen,
440 the “hg log” command accepts a --rev option.
441 * Most options have short names, too. Instead of --rev, we can use
442 -r. (The reason that some options don’t have short names is that
443 the options in question are rarely used.)
444 * Long options start with two dashes (e.g. --rev), while short
445 options start with one (e.g. -r).
446 * Option naming and usage is consistent across commands. For
447 example, every command that lets you specify a changeset ID or
448 revision number accepts both -r and --rev arguments.
450 In the examples throughout this book, I use short options instead of
451 long. This just reflects my own preference, so don’t read anything
454 Most commands that print output of some kind will print more output
455 when passed a -v (or --verbose) option, and less when passed -q (or
458 ### 2.6 Making and reviewing changes
460 Now that we have a grasp of viewing history in Mercurial, let’s take a
461 look at making some changes and examining them.
463 The first thing we’ll do is isolate our experiment in a repository of
464 its own. We use the “hg clone” command, but we don’t need to clone a
465 copy of the remote repository. Since we already have a copy of it
466 locally, we can just clone that instead. This is much faster than
467 cloning over the network, and cloning a local repository uses less
468 disk space in most cases, too.
471 $ hg clone hello my-hello
472 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
475 As an aside, it’s often good practice to keep a “pristine” copy of a
476 remote repository around, which you can then make temporary clones of
477 to create sandboxes for each task you want to work on. This lets you
478 work on multiple tasks in parallel, each isolated from the others
479 until it’s complete and you’re ready to integrate it back. Because
480 local clones are so cheap, there’s almost no overhead to cloning and
481 destroying repositories whenever you want.
483 In our my-hello repository, we have a file hello.c that contains the
484 classic “hello, world” program. Let’s use the ancient and venerable
485 sed command to edit this file so that it prints a second line of
486 output. (I’m only using sed to do this because it’s easy to write a
487 scripted example this way. Since you’re not under the same constraint,
488 you probably won’t want to use sed; simply use your preferred text
489 editor to do the same thing.)
491 $ sed -i '/printf/a∖∖tprintf("hello again!∖∖n");' hello.c
493 Mercurial’s “hg status” command will tell us what Mercurial knows
494 about the files in the repository.
501 The “hg status” command prints no output for some files, but a line
502 starting with “M” for hello.c. Unless you tell it to, “hg status” will
503 not print any output for files that have not been modified.
505 The “M” indicates that Mercurial has noticed that we modified
506 hello.c. We didn’t need to inform Mercurial that we were going to
507 modify the file before we started, or that we had modified the file
508 after we were done; it was able to figure this out itself.
510 It’s a little bit helpful to know that we’ve modified hello.c, but we
511 might prefer to know exactly what changes we’ve made to it. To do
512 this, we use the “hg diff” command.
515 diff -r b57f9a090b62 hello.c
516 --- a/hello.c Tue Sep 06 15:43:07 2005 -0700
517 +++ b/hello.c Sun Jun 17 18:05:50 2007 +0000
518 @@ -8,5 +8,6 @@ int main(int argc, char ⋆⋆argv)
519 int main(int argc, char ⋆⋆argv)
521 printf("hello, world!∖");
522 + printf("hello again!∖n");
526 ### 2.7 Recording changes in a new changeset
528 We can modify files, build and test our changes, and use “hg status”
529 and “hg diff” to review our changes, until we’re satisfied with what
530 we’ve done and arrive at a natural stopping point where we want to
531 record our work in a new changeset.
533 The “hg commit” command lets us create a new changeset; we’ll usually
534 refer to this as “making a commit” or “committing”.
536 #### 2.7.1 Setting up a username
538 When you try to run “hg commit” for the first time, it is not
539 guaranteed to succeed. Mercurial records your name and address with
540 each change that you commit, so that you and others will later be able
541 to tell who made each change. Mercurial tries to automatically figure
542 out a sensible username to commit the change with. It will attempt
543 each of the following methods, in order:
545 1. If you specify a -u option to the “hg commit” command on the
546 command line, followed by a username, this is always given the
548 2. If you have set the HGUSER environment variable, this is checked next.
549 3. If you create a file in your home directory called .hgrc, with a
550 username entry, that will be used next. To see what the contents
551 of this file should look like, refer to section [2.7.1][11]
553 4. If you have set the EMAIL environment variable, this will be used
555 5. Mercurial will query your system to find out your local user name
556 and host name, and construct a username from these
557 components. Since this often results in a username that is not
558 very useful, it will print a warning if it has to do this.
560 If all of these mechanisms fail, Mercurial will fail, printing an
561 error message. In this case, it will not let you commit until you set
564 You should think of the HGUSER environment variable and the -u option
565 to the “hg commit” command as ways to override Mercurial’s default
566 selection of username. For normal use, the simplest and most robust
567 way to set a username for yourself is by creating a .hgrc file; see
570 ##### Creating a Mercurial configuration file
572 To set a user name, use your favourite editor to create a file called
573 .hgrc in your home directory. Mercurial will use this file to look up
574 your personalised configuration settings. The initial contents of your
575 .hgrc should look like this.
577 # This is a Mercurial configuration file.
579 username = Firstname Lastname <email.address@domain.net>
581 The “[ui]” line begins a section of the config file, so you can read
582 the “username = ...” line as meaning “set the value of the username
583 item in the ui section”. A section continues until a new section
584 begins, or the end of the file. Mercurial ignores empty lines and
585 treats any text from “#” to the end of a line as a comment.
587 ##### Choosing a user name
589 You can use any text you like as the value of the username config
590 item, since this information is for reading by other people, but for
591 interpreting by Mercurial. The convention that most people follow is
592 to use their name and email address, as in the example above.
594 Note: Mercurial’s built-in web server obfuscates email addresses, to
595 make it more difficult for the email harvesting tools that spammers
596 use. This reduces the likelihood that you’ll start receiving more junk
597 email if you publish a Mercurial repository on the web.
599 #### 2.7.2 Writing a commit message
601 When we commit a change, Mercurial drops us into a text editor, to
602 enter a message that will describe the modifications we’ve made in
603 this changeset. This is called the commit message. It will be a record
604 for readers of what we did and why, and it will be printed by “hg log”
605 after we’ve finished committing.
609 The editor that the “hg commit” command drops us into will contain an
610 empty line, followed by a number of lines starting with “HG:”.
615 Mercurial ignores the lines that start with “HG:”; it uses them only
616 to tell us which files it’s recording changes to. Modifying or
617 deleting these lines has no effect.
619 #### 2.7.3 Writing a good commit message
621 Since “hg log” only prints the first line of a commit message by
622 default, it’s best to write a commit message whose first line stands
623 alone. Here’s a real example of a commit message that doesn’t follow
624 this guideline, and hence has a summary that is not readable.
626 changeset: 73:584af0e231be
627 user: Censored Person <censored.person@example.org>
628 date: Tue Sep 26 21:37:07 2006 -0700
629 summary: include buildmeister/commondefs. Add an exports and install
631 As far as the remainder of the contents of the commit message are
632 concerned, there are no hard-and-fast rules. Mercurial itself doesn’t
633 interpret or care about the contents of the commit message, though
634 your project may have policies that dictate a certain kind of
637 My personal preference is for short, but informative, commit messages
638 that tell me something that I can’t figure out with a quick glance at
639 the output of “hg log --patch”.
641 #### 2.7.4 Aborting a commit
643 If you decide that you don’t want to commit while in the middle of
644 editing a commit message, simply exit from your editor without saving
645 the file that it’s editing. This will cause nothing to happen to
646 either the repository or the working directory.
648 If we run the “hg commit” command without any arguments, it records
649 all of the changes we’ve made, as reported by “hg status” and “hg
652 #### 2.7.5 Admiring our new handiwork
654 Once we’ve finished the commit, we can use the “hg tip” command to
655 display the changeset we just created. This command produces output
656 that is identical to “hg log”, but it only displays the newest
657 revision in the repository.
660 changeset: 5:fa1321bf0c80
662 user: Bryan O'Sullivan <bos@serpentine.com>
663 date: Sun Jun 17 18:05:50 2007 +0000
666 Added an extra line of output
669 diff -r b57f9a090b62 -r fa1321bf0c80 hello.c
670 --- a/hello.c Tue Sep 06 15:43:07 2005 -0700
671 +++ b/hello.c Sun Jun 17 18:05:50 2007 +0000
672 @@ -8,5 +8,6 @@ int main(int argc, char ⋆⋆argv)
673 int main(int argc, char ⋆⋆argv)
675 printf("hello, world!∖");
676 + printf("hello again!∖n");
681 We refer to the newest revision in the repository as the tip revision,
684 ### 2.8 Sharing changes
686 We mentioned earlier that repositories in Mercurial are
687 self-contained. This means that the changeset we just created exists
688 only in our my-hello repository. Let’s look at a few ways that we can
689 propagate this change into other repositories.
691 #### 2.8.1 Pulling changes from another repository
693 To get started, let’s clone our original hello repository, which does
694 not contain the change we just committed. We’ll call our temporary
695 repository hello-pull.
698 $ hg clone hello hello-pull
699 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
701 We’ll use the “hg pull” command to bring changes from my-hello into
702 hello-pull. However, blindly pulling unknown changes into a repository
703 is a somewhat scary prospect. Mercurial provides the “hg incoming”
704 command to tell us what changes the “hg pull” command would pull into
705 the repository, without actually pulling the changes in.
708 $ hg incoming ../my-hello
709 comparing with ../my-hello
710 searching for changes
711 changeset: 5:fa1321bf0c80
713 user: Bryan O'Sullivan <bos@serpentine.com>
714 date: Sun Jun 17 18:05:50 2007 +0000
715 summary: Added an extra line of output
718 (Of course, someone could cause more changesets to appear in the
719 repository that we ran “hg incoming” in, before we get a chance to “hg
720 pull” the changes, so that we could end up pulling changes that we
723 Bringing changes into a repository is a simple matter of running the
724 “hg pull” command, and telling it which repository to pull from.
727 changeset: 4:b57f9a090b62
729 user: Bryan O'Sullivan <bos@serpentine.com>
730 date: Tue Sep 06 15:43:07 2005 -0700
731 summary: Trim comments.
733 $ hg pull ../my-hello
734 pulling from ../my-hello
735 searching for changes
739 added 1 changesets with 1 changes to 1 files
740 (run 'hg update' to get a working copy)
742 changeset: 5:fa1321bf0c80
744 user: Bryan O'Sullivan <bos@serpentine.com>
745 date: Sun Jun 17 18:05:50 2007 +0000
746 summary: Added an extra line of output
749 As you can see from the before-and-after output of “hg tip”, we have
750 successfully pulled changes into our repository. There remains one
751 step before we can see these changes in the working directory.
753 #### 2.8.2 Updating the working directory
755 We have so far glossed over the relationship between a repository and
756 its working directory. The “hg pull” command that we ran in
757 section [2.8.1][12] brought changes into the repository, but if we
758 check, there’s no sign of those changes in the working directory. This
759 is because “hg pull” does not (by default) touch the working
760 directory. Instead, we use the “hg update” command to do this.
762 $ grep printf hello.c
763 printf("hello, world!∖");
765 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
766 $ grep printf hello.c
767 printf("hello, world!∖");
768 printf("hello again!∖n");
770 It might seem a bit strange that “hg pull” doesn’t update the working
771 directory automatically. There’s actually a good reason for this: you
772 can use “hg update” to update the working directory to the state it
773 was in at any revision in the history of the repository. If you had
774 the working directory updated to an old revision—to hunt down the
775 origin of a bug, say—and ran a “hg pull” which automatically updated
776 the working directory to a new revision, you might not be terribly
779 However, since pull-then-update is such a common thing to do,
780 Mercurial lets you combine the two by passing the -u option to “hg
785 If you look back at the output of “hg pull” in section [2.8.1][12]
786 when we ran it without -u, you can see that it printed a helpful
787 reminder that we’d have to take an explicit step to update the working
790 (run 'hg update' to get a working copy)
792 To find out what revision the working directory is at, use the “hg
796 changeset: 5:fa1321bf0c80
798 user: Bryan O'Sullivan <bos@serpentine.com>
799 date: Sun Jun 17 18:05:50 2007 +0000
800 summary: Added an extra line of output
803 If you look back at figure [2.1][8], you’ll see arrows connecting each
804 changeset. The node that the arrow leads from in each case is a
805 parent, and the node that the arrow leads to is its child. The working
806 directory has a parent in just the same way; this is the changeset
807 that the working directory currently contains.
809 To update the working directory to a particular revision, give a
810 revision number or changeset ID to the “hg update” command.
813 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
815 changeset: 2:057d3c2d823c
816 user: Bryan O'Sullivan <bos@serpentine.com>
817 date: Tue Sep 06 13:15:43 2005 -0700
818 summary: Introduce a typo into hello.c.
821 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
823 If you omit an explicit revision, “hg update” will update to the tip
824 revision, as shown by the second call to “hg update” in the example
827 #### 2.8.3 Pushing changes to another repository
829 Mercurial lets us push changes to another repository, from the
830 repository we’re currently visiting. As with the example of “hg pull”
831 above, we’ll create a temporary repository to push our changes into.
834 $ hg clone hello hello-push
835 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
837 The “hg outgoing” command tells us what changes would be pushed into
841 $ hg outgoing ../hello-push
842 comparing with ../hello-push
843 searching for changes
844 changeset: 5:fa1321bf0c80
846 user: Bryan O'Sullivan <bos@serpentine.com>
847 date: Sun Jun 17 18:05:50 2007 +0000
848 summary: Added an extra line of output
851 And the “hg push” command does the actual push.
853 $ hg push ../hello-push
854 pushing to ../hello-push
855 searching for changes
859 added 1 changesets with 1 changes to 1 files
861 As with “hg pull”, the “hg push” command does not update the working
862 directory in the repository that it’s pushing changes into. (Unlike
863 “hg pull”, “hg push” does not provide a -u option that updates the
864 other repository’s working directory.)
866 What happens if we try to pull or push changes and the receiving
867 repository already has those changes? Nothing too exciting.
869 $ hg push ../hello-push
870 pushing to ../hello-push
871 searching for changes
874 #### 2.8.4 Sharing changes over a network
876 The commands we have covered in the previous few sections are not
877 limited to working with local repositories. Each works in exactly the
878 same fashion over a network connection; simply pass in a URL instead
881 $ hg outgoing http://hg.serpentine.com/tutorial/hello
882 comparing with http://hg.serpentine.com/tutorial/hello
883 searching for changes
884 changeset: 5:fa1321bf0c80
886 user: Bryan O'Sullivan <bos@serpentine.com>
887 date: Sun Jun 17 18:05:50 2007 +0000
888 summary: Added an extra line of output
891 In this example, we can see what changes we could push to the remote
892 repository, but the repository is understandably not set up to let
893 anonymous users push to it.
895 $ hg push http://hg.serpentine.com/tutorial/hello
896 pushing to http://hg.serpentine.com/tutorial/hello
897 searching for changes
900 [1]: http://hgbook.red-bean.com/hgbookch3.html
901 [2]: http://hgbook.red-bean.com/hgbookch1.html
902 [3]: http://hgbook.red-bean.com/hgbookch1.html#tailhgbookch1.html
903 [4]: #tailhgbookch2.html
904 [5]: http://hgbook.red-bean.com/hgbook.html#hgbookch2.html
905 [6]: http://mercurial.berkwood.com/
906 [7]: http://hgbook.red-bean.com/hgbookli4.html#Xweb:macpython
908 [9]: hgbookch2_files/tour-history.png
909 [10]: http://hgbook.red-bean.com/hgbookch12.html#x16-27100012.4
912 [13]: http://hgbook.red-bean.com/hgbookch2.html
915 Open Publication License
917 Version 1.0, 8 June 1999
919 ### D.1 Requirements on both unmodified and modified versions
921 The Open Publication works may be reproduced and distributed in whole
922 or in part, in any medium physical or electronic, provided that the
923 terms of this license are adhered to, and that this license or an
924 incorporation of it by reference (with any options elected by the
925 author(s) and/or publisher) is displayed in the reproduction.
927 Proper form for an incorporation by reference is as follows:
929 Copyright (c) year by author’s name or designee. This material may be
930 distributed only subject to the terms and conditions set forth in the
931 Open Publication License, vx.y or later (the latest version is
932 presently available at
933 [http://www.opencontent.org/openpub/][http://www.opencontent.org/openpub/]).
935 The reference must be immediately followed with any options elected by
936 the author(s) and/or publisher of the document (see section D.6).
938 Commercial redistribution of Open Publication-licensed material is
941 Any publication in standard (paper) book form shall require the
942 citation of the original publisher and author. The publisher and
943 author’s names shall appear on all outer surfaces of the book. On all
944 outer surfaces of the book the original publisher’s name shall be as
945 large as the title of the work and cited as possessive with respect to
950 The copyright to each Open Publication is owned by its author(s) or
953 ### D.3 Scope of license
955 The following license terms apply to all Open Publication works,
956 unless otherwise explicitly stated in the document.
958 Mere aggregation of Open Publication works or a portion of an Open
959 Publication work with other works or programs on the same media shall
960 not cause this license to apply to those other works. The aggregate
961 work shall contain a notice specifying the inclusion of the Open
962 Publication material and appropriate copyright notice.
964 Severability. If any part of this license is found to be unenforceable
965 in any jurisdiction, the remaining portions of the license remain in
968 No warranty. Open Publication works are licensed and provided “as is”
969 without warranty of any kind, express or implied, including, but not
970 limited to, the implied warranties of merchantability and fitness for
971 a particular purpose or a warranty of non-infringement.
973 ### D.4 Requirements on modified works
975 All modified versions of documents covered by this license, including
976 translations, anthologies, compilations and partial documents, must
977 meet the following requirements:
979 1. The modified version must be labeled as such.
980 2. The person making the modifications must be identified and the
982 3. Acknowledgement of the original author and publisher if
983 applicable must be retained according to normal academic citation
985 4. The location of the original unmodified document must be identified.
986 5. The original author’s (or authors’) name(s) may not be used to
987 assert or imply endorsement of the resulting document without the
988 original author’s (or authors’) permission.
990 ### D.5 Good-practice recommendations
992 In addition to the requirements of this license, it is requested from
993 and strongly recommended of redistributors that:
995 1. If you are distributing Open Publication works on hardcopy or
996 CD-ROM, you provide email notification to the authors of your
997 intent to redistribute at least thirty days before your
998 manuscript or media freeze, to give the authors time to provide
999 updated documents. This notification should describe
1000 modifications, if any, made to the document.
1001 2. All substantive modifications (including deletions) be either
1002 clearly marked up in the document or else described in an
1003 attachment to the document.
1004 3. Finally, while it is not mandatory under this license, it is
1005 considered good form to offer a free copy of any hardcopy and
1006 CD-ROM expression of an Open Publication-licensed work to its
1009 ### D.6 License options
1011 The author(s) and/or publisher of an Open Publication-licensed
1012 document may elect certain options by appending language to the
1013 reference to or copy of the license. These options are considered part
1014 of the license instance and must be included with the license (or its
1015 incorporation by reference) in derived works.
1017 1. To prohibit distribution of substantively modified versions
1018 without the explicit permission of the author(s). “Substantive
1019 modification” is defined as a change to the semantic content of
1020 the document, and excludes mere changes in format or
1021 typographical corrections.
1023 To accomplish this, add the phrase “Distribution of substantively
1024 modified versions of this document is prohibited without the
1025 explicit permission of the copyright holder.” to the license
1028 2. To prohibit any publication of this work or derivative works in
1029 whole or in part in standard (paper) book form for commercial
1030 purposes is prohibited unless prior permission is obtained from
1031 the copyright holder.
1033 To accomplish this, add the phrase “Distribution of the work or
1034 derivative of the work in any standard (paper) book form is
1035 prohibited unless prior permission is obtained from the copyright
1036 holder.” to the license reference or copy.