<> == 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|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. 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: {{{ $ cd my-hello-new-output $ vi hello.c }}} 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 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. {{{ $ 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 [[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]]). 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|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 [[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. To share changes, we must continue to TutorialShareChange. ---- CategoryTutorial