Since this is Sally’s first time using Mercurial on her desktop machine, she first sets up her .hgrc file.

[ui]
username = Sally <sally@futilisoft.com>

Now Sally needs to set up her own repository instance.

~ sally$ hg clone http://server.futilisoft.com:8000/ ./lottery
no changes found
updating to branch default
0 files updated, 0 files merged, 0 files removed, 0 files unresolved

~ sally$ cd lottery

lottery sally$ ls -al
total 0
drwxr-xr-x   3 sally  staff  102 May 17 08:00 .
drwxr-xr-x  19 sally  staff  646 May 17 08:00 ..
drwxr-xr-x   8 sally  staff  272 May 17 08:00 .hg

Hmmm. Harry was supposed to commit the initial code, but there’s nothing here.

But Harry did commit his changes! Why aren’t they here? Ah, he forgot to push. Sally screams at Harry loudly enough to be heard six time zones away.

lottery harry$ hg push
pushing to http://server.futilisoft.com:8000/
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 1 changes to 1 files

Now Sally can pull.

lottery sally$ hg pull
pulling from http://server.futilisoft.com:8000/
requesting all changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
(run 'hg update' to get a working copy)

The developers of Mercurial have done a great job on ease of use, including little prompts like the one I highlighted above. Mercurial is the friendliest DVCS around.

Now that she has pulled, Sally should have the code, right?

lottery sally$ ls -al
total 0
drwxr-xr-x   3 sally  staff  102 May 17 08:00 .
drwxr-xr-x  20 sally  staff  680 May 17 08:06 ..
drwxr-xr-x  12 sally  staff  408 May 17 08:06 .hg

Hmmm. Still not there. Ah, maybe she needs to hg update the working copy.

lottery sally$ hg update
1 files updated, 0 files merged, 0 files removed, 0 files unresolved

lottery sally$ ls -al
total 8
drwxr-xr-x   4 sally  staff  136 May 17 08:07 .
drwxr-xr-x  20 sally  staff  680 May 17 08:06 ..
drwxr-xr-x  12 sally  staff  408 May 17 08:07 .hg
-rw-r--r--   1 sally  staff  555 May 17 08:07 lottery.c

Now that she has the initial code they had previously discussed, Sally is happy as a dead pig in the sunshine. She wants to check the log to see the details.

lottery sally$ hg log
changeset:   0:1f8baa59f5a4
tag:         tip
user:        Harry <harry@futilisoft.com>
date:        Tue May 17 07:58:36 2011 -0500
summary:     initial implementation

Note the way Mercurial describes this commit: 0:1f8baa59f5a4. At the lowest level, a Mercurial version ID is a SHA-1 hash, usually displayed in hex with only its first 12 characters. This is the part after the colon. Before the colon is a friendlier version number, one which starts at zero and increases by one with each new version. This is more intuitive, but these version numbers are valid only in one repository instance.

When Sally decides to take a look at the code, she immediately finds something that makes her nervous as a chicken on a conveyor belt. The program expects the red ball number to be the first argument, followed by the other five. But in the actual lottery, the five white numbers are always drawn and shown first. She worries this will be confusing for users so she decides to fix it. Fortunately it is only necessary to modify a few lines of main().

    if (argc != 7)
    {
        fprintf(stderr, "Usage: %s (5 white balls) power_ball\n", argv[0]);
        return -1;
    }

    int power_ball = atoi(argv[6]);

    int white_balls[5];
    for (int i=0; i<5; i++)
    {
        white_balls[i] = atoi(argv[1+i]);
    }

Now she uses the status operation to see the pending changes.

lottery sally$ hg status
M lottery.c

No surprise there. Mercurial knows that lottery.c has been modified. She wants to double-check by reviewing the actual changes.

lottery sally$ hg diff
diff -r 1f8baa59f5a4 lottery.c
--- a/lottery.c Tue May 17 07:58:36 2011 -0500
+++ b/lottery.c Tue May 17 08:09:58 2011 -0500
@@ -11,16 +11,16 @@
 {
     if (argc != 7)
     {
-        fprintf(stderr, "Usage: %s power_ball (5 white balls)\n", argv[0]);
+        fprintf(stderr, "Usage: %s (5 white balls) power_ball\n", argv[0]);
         return -1;
     }
 
-    int power_ball = atoi(argv[1]);
+    int power_ball = atoi(argv[6]);
 
     int white_balls[5];
     for (int i=0; i<5; i++)
     {
-        white_balls[i] = atoi(argv[2+i]);
+        white_balls[i] = atoi(argv[1+i]);
     }
 
     int result = calculate_result(white_balls, power_ball);

Ain’t that the bee’s knees!?!