TutorialFirstChange

Tutorial - making our first change

We are inside our my-hello repository that we ["Clone"]d in TutorialClone.

It is good ["Mercurial"] development practice to isolate each change in a separate ["Repository"]. This prevents unrelated code from getting mixed up, and makes it easier to test individual chunks of work one by one. Let's start out by following that model.

Our silly goal is to get the "hello, world" program to print another line of output. First, we ["Clone"] our my-hello ["Repository"].

$ cd ..
$ hg clone my-hello my-hello-new-output

In this case, the clone command prints no output if it succeeds.

Note: Notice that we have given our new ["Repository"] a descriptive name, basically identifying the purpose of the ["Repository"]. Since making a ["Clone"] of a ["Repository"] in ["Mercurial"] is cheap, we will quickly accumulate many slightly different repositories. If we do not give these repositories descriptive names, we will rapidly lose the ability to tell them apart.

Now it's time to make a change in the new repository. Let's go into the WorkingDirectory, which is simply our name for the directory where all the files are, and modify the source code with our favorite editor:

$ cd my-hello-new-output
$ vi hello.c

The contents of hello.c initially look like this:

/*
 * hello.c
 *
 * Placed in the public domain by Bryan O'Sullivan
 *
 * This program is not covered by patents in the United States or other
 * countries.
 */

#include <stdio.h>

int main(int argc, char **argv)
{
        printf("hello, world!\n");
        return 0;
}

Let's edit main so that it prints an extra line of output:

(...)

int main(int argc, char **argv)
{
        printf("hello, world!\n");
        printf("sure am glad I'm using Mercurial!\n");
        return 0;
}

Once we're done, we quit out of our favorite editor, and we're done. That's it. The edit is now ready for us to create a ChangeSet.

But what if we're been interrupted, and we've forgotten what changes are going to make it into the ChangeSet once we create it? For this, we use the status command.

$ hg status
M hello.c

The output is terse, but it is simply telling us that hello.c has been modified, so a change ready to go into a ChangeSet.

The act of creating a ChangeSet is called ["Commit"]ting it. We perform a ["Commit"] using the commit command:

$ hg commit

This drops us into an editor, and presents us with a few cryptic lines of text.

Note: The default editor is vi. This can be changed using the EDITOR or HGEDITOR environment variables. Also, the manifest hash might be different, depending on how you typed and saved the file.

(empty line)
HG: manifest hash 14595beb70bcfb74bf227437d70c38878421c944
HG: changed hello.c

The first line is empty and the lines that follow identify the files that will go into this ChangeSet.

To ["Commit"] the ChangeSet, we must describe the reason for it. This is usually called a ChangeSet comment. Let's type something like this:

Express great joy at existence of Mercurial
HG: manifest hash 14595beb70bcfb74bf227437d70c38878421c944
HG: changed hello.c

Next, we quit the editor, and, if all went well, the commit command prints no output.

But what does the status command tell us now?

$ hg status

Nothing! Our change has been ["Commit"]ted to a ChangeSet, so there's no modified file in need of a commit. Our ["Tip"] now matches our working directory contents. Does that mean our new commit will show up in the change history?

$ hg log
changeset:   2:a58809af174d
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:26:28 2005 -0700
summary:     Express great joy at existence of Mercurial

(...)

There it is! We've ["Commit"]ted a ChangeSet.

Note: The user, date, and ChangeSetID will of course vary.

As we discussed in TutorialClone, the new ChangeSet only exists in this repository. This is a critical part of the way ["Mercurial"] works.

To share changes, we must continue to TutorialShareChange.