Differences between revisions 1 and 18 (spanning 17 versions)
Revision 1 as of 2005-08-26 00:58:22
Size: 3906
Editor: waste
Comment:
Revision 18 as of 2008-01-04 14:26:40
Size: 6126
Editor: abuehl
Comment: +cat
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
== ["Tutorial"] - making our first change == == Tutorial - making our first change ==
Line 3: Line 3:
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 ["Clone"]d in TutorialClone.
Line 7: Line 7:
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.
Line 10: Line 10:
 $ cd ..
 $ hg clone my-hello my-hello-new-output
$ cd ..
$ hg clone my-hello my-hello-new-output
Line 14: Line 14:
Once again, this command prints no output if it succeeds. In this case, the clone command prints no output if it succeeds.
Line 16: Line 16:
'''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. LyleJohnson adds: For my installation of Mercurial 0.9.4 on Mac OS X (from MacPorts), I did get one line of output, as follows.
{{{
$ hg clone my-hello my-hello-new-output
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
}}}
Line 18: Line 22:
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: '''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:
Line 21: Line 27:
 $ cd my-hello-new-output
 $ vi hello.c
$ cd my-hello-new-output
$ vi hello.c
Line 25: Line 31:
The contents of ''hello.c'' look like this: The contents of {{{hello.c}}} initially 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.

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 70:
 /*
  * 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 38: Line 74:
{{{
 #include <stdio.h>
}}}
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.

We may also examine the actual changes we have made to the file using the {{{diff}}} command:
Line 43: Line 79:
$ hg diff
diff -r 82e55d328c8c hello.c
--- a/hello.c Fri Aug 26 01:21:28 2005 -0700
+++ b/hello.c Fri Sep 30 10:27:47 2005 +0800
@@ -12,5 +12,6 @@
Line 45: Line 86:
     printf("hello, world!\n");
     return 0;
    printf("hello, world!\n");
+ printf("sure am glad I'm using Mercurial!\n");
   
return 0;
Line 50: Line 92:
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 -a option to revert all files). Just make sure you know this is what you really want.
Line 53: Line 95:
 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 61: Line 98:
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. KenMin adds: {{{revert}}} command also rename the modified file hello.c to hello.c.orig
{{{
$ hg status
? hello.c.orig
}}}
Line 63: Line 104:
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. 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 status
M hello.c
}}}

The act of creating a ChangeSet is called ["Commit"]ting it. We perform a ["Commit"] using the {{{commit}}} command:
Line 66: Line 115:
 $ hg status
 C hello.c
$ hg commit
Line 70: Line 118:
This output is terse, but it is simply telling us that ''hello.c'' has a change ready to go into a ChangeSet. This drops us into an editor, and presents us with a few cryptic lines of text.
Line 72: Line 120:
The act of creating a ChangeSet is called ["Commit"]ting it. We perform a ["Commit"] using the ''commit'' command: '''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.
Line 75: Line 123:
 $ hg commit (empty line)
HG: manifest hash 14595beb70bcfb74bf227437d70c38878421c944
HG: changed hello.c
Line 78: Line 128:
This will drop us into our editor, and present us with a few cryptic lines of text:

{{{
 <this line will be empty>
 HG: manifest hash 0d66196b08b861878228219d46258f088092286e
 HG: changed hello.c
}}}

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.
The first line is empty and the lines that follow identify the files that will go into this ChangeSet.
Line 91: Line 133:
 Express great joy at existence of Mercurial Express great joy at existence of Mercurial
HG: manifest hash 14595beb70bcfb74bf227437d70c38878421c944
HG: changed hello.c
Line 94: Line 138:
Next, we quit the editor, and (as we're coming to expect) the ''commit'' command prints no output. 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, {{{commit}}} will abort the operation, so you may change your mind before committing.
Line 96: Line 140:
But what does the ''status'' command tell us now? '''Note:''' Before committing anything into a serious project, you may want to configure a meaningful username in {{{~/.hgrc}}}; see ["QuickStart2"].

Let's see what the {{{status}}} command will tell us now?
Line 99: Line 145:
 $ hg status $ hg status
Line 102: Line 148:
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? 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.
Line 104: Line 150:
We can now examine the change history for our new work:
Line 105: Line 152:
 $ 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 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

(...)
Line 115: Line 164:
'''Note:''' The user, date, and ChangeSetID will of course vary.
Line 118: Line 169:
----
CategoryTutorial

Tutorial - making our first change

Carrying forward from TutorialHistory, 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 create a new repository called my-hello-new-output, by cloning from my-hello, for our little project.

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

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

LyleJohnson adds: For my installation of Mercurial 0.9.4 on Mac OS X (from MacPorts), I did get one line of output, as follows.

$ hg clone my-hello my-hello-new-output
2 files updated, 0 files merged, 0 files removed, 0 files unresolved

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

We may also examine the actual changes we have made to the file 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   Fri Sep 30 10:27:47 2005 +0800
@@ -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 -a option to revert all files). Just make sure you know this is what you really want.

$ hg revert hello.c

KenMin adds: revert command also rename the modified file hello.c to hello.c.orig

$ hg status
? 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 status
M hello.c

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 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, commit will abort the operation, so you may change your mind before committing.

Note: Before committing anything into a serious project, you may want to configure a meaningful username in ~/.hgrc; see ["QuickStart2"].

Let's see what the status command will 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.

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

$ 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.


CategoryTutorial

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