Differences between revisions 1 and 39 (spanning 38 versions)
Revision 1 as of 2005-08-26 00:58:22
Size: 3906
Editor: waste
Comment:
Revision 39 as of 2012-11-06 15:27:31
Size: 7221
Editor: abuehl
Comment: remove link to deleted page "commit"
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
== ["Tutorial"] - making our first change == == Tutorial - Making our first Change ==
''(This page is part of the [[Tutorial]] series. Previous part is TutorialHistory, next part is TutorialShareChange)''
Line 3: Line 4:
We are inside our ''my-hello'' repository that we ["Clone"]d in TutorialClone. Carrying forward from TutorialHistory, we are inside our `my-hello` repository that we cloned in TutorialClone.
Line 5: Line 6:
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. A good Mercurial development practice is to isolate related changes in a separate [[Repository|repository]] (see also WorkingPractices). 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.
Line 7: Line 8:
Our initial silly goal is to get the "hello, world" program to print another line of output. First, we ["Clone"] our ''my-hello'' ["Repository"]. Our silly goal is to get the "hello, world" program to print another line of output. First, we create a new repository called `my-hello-new-output`, by cloning from `my-hello`, for our little project (using Mercurial 1.0):
Line 10: Line 11:
 $ cd ..
 $ hg clone my-hello my-hello-new-output
$ cd ..
$ hg clone my-hello my-hello-new-output
updating working directory
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
Line 13: Line 16:
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 (see RepositoryNaming).
Line 14: Line 18:
Once again, this 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:
Now it's time to make a change in the new repository. Let's go into the repository's [[WorkingDirectory|working directory]], which is simply our name for the directory where all the files are, and modify the source code with our favorite editor:
Line 21: Line 21:
 $ cd my-hello-new-output
 $ vi hello.c
$ cd my-hello-new-output
$ vi hello.c
Line 24: Line 24:
The contents of `hello.c` initially look like this:
Line 25: Line 26:
The contents of ''hello.c'' look like this: {{{#!cplusplus numbers=off
/*
 * 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:

{{{#!cplusplus numbers=off
(...)

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|changeset]].

But what if we're 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.
Line 28: Line 61:
 /*
  * 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.
  */
$ hg status
M hello.c
Line 37: Line 64:
The output is terse, but prefix `M` is simply telling us that `hello.c` has been modified, so our change is ready to go into a changeset.

Instead of the long-winded `hg status` we can alternatively just type `hg st`, as Mercurial allows us to abbreviate commands as long as the entered character sequence is not ambiguous.
Line 39: Line 69:
 #include <stdio.h> $ hg st
M hello.c
Line 41: Line 72:
We may also examine the actual changes we have made to the files using the `diff` command:
Line 43: Line 75:
$ hg diff
diff -r 82e55d328c8c hello.c
--- a/hello.c Fri Aug 26 01:21:28 2005 -0700
+++ b/hello.c Mon May 05 00:27:56 2008 +0200
@@ -12,5 +12,6 @@
Line 45: Line 82:
     printf("hello, world!\n");
     return 0;
    printf("hello, world!\n");
+ printf("sure am glad I'm using Mercurial!\n");
   
return 0;
Line 49: Line 87:

Let's edit ''main'' so that it prints an extra line of output:
<!> In case we wish to discard our changes and start over, we may use the `revert` command to restore `hello.c` to its unmodified state (or use the `--all` option to revert all files). Just make sure you know this is what you really want (see [[Revert]]).
Line 53: Line 90:
 int main(int argc, char **argv)
 {
     printf("hello, world!\n");
     printf("sure am glad I'm using Mercurial!\n");
     return 0;
 }
$ hg revert hello.c
Line 60: Line 92:
`revert` renames the modified file `hello.c` to `hello.c.orig` and restores `hello.c` to its unmodified state.
Line 61: Line 94:
Once we're done, we quit out of ''vi'' (or our editor of choice) 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.
`status` now lists `hello.c.orig` as not tracked (prefix "?").
Line 66: Line 97:
 $ hg status
 C hello.c
$ hg st
? hello.c.orig
Line 69: Line 100:

This output is terse, but it is simply telling us that ''hello.c'' has 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:
If we change our mind again and want to reuse the modification we have made, we just remove the unmodified state of `hello.c` and rename the modified `hello.c.orig` to `hello.c`
Line 75: Line 103:
 $ hg commit $ rm hello.c
$ mv hello.c.orig hello.c
$ hg st
M hello.c
Line 77: Line 108:

This will drop us into our editor, and present us with a few cryptic lines of text:
The act of creating a changeset is called committing it. We perform a commit using the `commit` command. The `commit` command has a nice short alias: `ci` ("check in"), so we can use that:
Line 81: Line 111:
 <this line will be empty>
 HG: manifest hash 0d66196b08b861878228219d46258f088092286e
 HG: changed hello.c
$ hg ci
Line 85: Line 113:
This drops us into an editor, and presents us with a few cryptic lines of text.
Line 86: Line 115:
The first line is empty, the second contains a big long hash, 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:
''Note:'' The default editor is `vi`. This can be changed using the `EDITOR` or [[HGEDITOR]] environment variables.
Line 91: Line 118:
 Express great joy at existence of Mercurial HG: Enter commit message. Lines beginning with 'HG:' are removed.
HG: --
HG: user: mpm@selenic.com
HG: branch 'default'
HG: changed hello.c
Line 93: Line 124:
The first line is empty and the lines that follow identify the user, branch name and the files that will go into this changeset.
Line 94: Line 126:
Next, we quit the editor, and (as we're coming to expect) the ''commit'' command prints no output. The default branch name is "default" (see NamedBranches). The default value for "user" is taken from the {{{~/.hgrc}}} configuration file from value "username" of section "ui" (see [[http://www.selenic.com/mercurial/hgrc.5.html#ui|hgrc(5)]]). Alternatively, it can also be specified on the command line with option -u (see `hg help ci` or [[http://www.selenic.com/mercurial/hg.1.html#commit|hg.1.html#commit]]).
Line 96: Line 128:
But what does the ''status'' command tell us now? To commit the changeset, we must describe the reason for it (see ChangeSetComments). Let's type something like this:
Line 99: Line 131:
 $ hg status Express great joy at existence of Mercurial
HG: Enter commit message. Lines beginning with 'HG:' are removed.
HG: --
HG: user: mpm@selenic.com
HG: branch 'default'
HG: changed hello.c
Line 101: Line 138:
Next, we save the text and quit the editor, and, if all goes well, the `commit` command will exit and prints no output.
Line 102: Line 140:
Nothing! Our change has been ["Commit"]ted to a ChangeSet, so our ["Tip"] now matches our working directory contents. Does that mean our new commit will show up in the change history? <!> If you quit the editor without saving the text or enter no text, `commit` will abort the operation, so you may change your mind before committing.

Let's see what the {{{status}}} command will tell us now?
Line 105: Line 145:
 $ hg log
 changeset: 3:da99cce05957f7a62b74d345fd55365dc33109f0
 tag: tip
 user: bos@camp4.serpentine.com
 date: Wed Jun 29 12:58:37 2005
 summary: Express great joy at existence of Mercurial
$ hg st
Line 112: Line 147:
Nothing! Our change has been committed to a changeset, so there's no modified file in need of a commit. Our [[Tip|tip]] now matches our working directory contents.
Line 113: Line 149:
There it is! We've ["Commit"]ted a ChangeSet. The [[Parent|parents]] command shows us that our repository's working directory is now synced (see [[Update]]) to the newly committed changeset (here we have only one parent revision, which is always the case after a commit. We will see two parents in TutorialMerge):
Line 115: Line 151:
As we discussed in TutorialClone, the new ChangeSet only exists in this repository. This is a critical part of the way ["Mercurial"] works. {{{
$ hg par
changeset: 2:86794f718fb1
tag: tip
user: mpm@selenic.com
date: Mon May 05 01:20:46 2008 +0200
summary: Express great joy at existence of Mercurial
}}}
There it is! We've committed a new changeset.

We can now examine the change history for our new work:

{{{
$ hg log
changeset: 2:86794f718fb1
tag: tip
user: mpm@selenic.com
date: Mon May 05 01:20:46 2008 +0200
summary: Express great joy at existence of Mercurial

(...)
}}}
''Note:'' The user, date, and [[ChangeSetID|changeset ID]] 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.
Line 118: Line 178:

----
CategoryTutorial

Tutorial - Making our first Change

(This page is part of the Tutorial series. Previous part is TutorialHistory, next part is TutorialShareChange)

Carrying forward from TutorialHistory, we are inside our my-hello repository that we cloned in TutorialClone.

A good Mercurial development practice is to isolate related changes in a separate repository (see also WorkingPractices). 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 create a new repository called my-hello-new-output, by cloning from my-hello, for our little project (using Mercurial 1.0):

$ cd ..
$ hg clone my-hello my-hello-new-output
updating working directory
2 files updated, 0 files merged, 0 files removed, 0 files unresolved

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 (see RepositoryNaming).

Now it's time to make a change in the new repository. Let's go into the repository's working directory, 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 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 prefix M is simply telling us that hello.c has been modified, so our change is ready to go into a changeset.

Instead of the long-winded hg status we can alternatively just type hg st, as Mercurial allows us to abbreviate commands as long as the entered character sequence is not ambiguous.

$ hg st
M hello.c

We may also examine the actual changes we have made to the files using the diff command:

$ hg diff
diff -r 82e55d328c8c hello.c
--- a/hello.c   Fri Aug 26 01:21:28 2005 -0700
+++ b/hello.c   Mon May 05 00:27:56 2008 +0200
@@ -12,5 +12,6 @@
 int main(int argc, char **argv)
 {
        printf("hello, world!\n");
+       printf("sure am glad I'm using Mercurial!\n");
        return 0;
 }

<!> In case we wish to discard our changes and start over, we may use the revert command to restore hello.c to its unmodified state (or use the --all option to revert all files). Just make sure you know this is what you really want (see Revert).

$ hg revert hello.c

revert renames the modified file hello.c to hello.c.orig and restores hello.c to its unmodified state.

status now lists hello.c.orig as not tracked (prefix "?").

$ hg st
? hello.c.orig

If we change our mind again and want to reuse the modification we have made, we just remove the unmodified state of hello.c and rename the modified hello.c.orig to hello.c

$ rm hello.c
$ mv hello.c.orig hello.c
$ hg st
M hello.c

The act of creating a changeset is called committing it. We perform a commit using the commit command. The commit command has a nice short alias: ci ("check in"), so we can use that:

$ hg ci

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.

HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: --
HG: user: mpm@selenic.com
HG: branch 'default'
HG: changed hello.c

The first line is empty and the lines that follow identify the user, branch name and the files that will go into this changeset.

The default branch name is "default" (see NamedBranches). The default value for "user" is taken from the ~/.hgrc configuration file from value "username" of section "ui" (see hgrc(5)). Alternatively, it can also be specified on the command line with option -u (see hg help ci or hg.1.html#commit).

To commit the changeset, we must describe the reason for it (see ChangeSetComments). Let's type something like this:

Express great joy at existence of Mercurial
HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: --
HG: user: mpm@selenic.com
HG: branch 'default'
HG: changed hello.c

Next, we save the text and quit the editor, and, if all goes well, the commit command will exit and prints no output.

<!> If you quit the editor without saving the text or enter no text, commit will abort the operation, so you may change your mind before committing.

Let's see what the status command will tell us now?

$ hg st

Nothing! Our change has been committed to a changeset, so there's no modified file in need of a commit. Our tip now matches our working directory contents.

The parents command shows us that our repository's working directory is now synced (see Update) to the newly committed changeset (here we have only one parent revision, which is always the case after a commit. We will see two parents in TutorialMerge):

$ hg par
changeset:   2:86794f718fb1
tag:         tip
user:        mpm@selenic.com
date:        Mon May 05 01:20:46 2008 +0200
summary:     Express great joy at existence of Mercurial

There it is! We've committed a new changeset.

We can now examine the change history for our new work:

$ hg log
changeset:   2:86794f718fb1
tag:         tip
user:        mpm@selenic.com
date:        Mon May 05 01:20:46 2008 +0200
summary:     Express great joy at existence of Mercurial

(...)

Note: The user, date, and changeset ID 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.


CategoryTutorial

TutorialFirstChange (last edited 2013-02-23 03:48:44 by mpm)