mercurial Getting Started


See also the Mercurial Tutorial

Creating a Mercurial Repository

A Mercurial repository is simply a directory (referred to as the "working directory") containing an .hg directory with metadata about the contents of the repository. This makes Mercurial very lightweight and easy to start using. To create a new repository simply run:

$ hg init project

Where project is the name of the directory you'd like to create. This creates a project directory along with a project/.hg directory containing the repository itself.

   $ cd project
   $ echo Hello World > hello.txt
   $ hg stat
   ? hello.txt

We just created a hello.txt file in the repository and ran hg status (or stat for short) to see the current status of our repository. As you can see hello.txt is annotated with a ?, meaning Mercurial isn't yet aware of it. The add command registers this new file with Mercurial so it will be included in the next commit.

$ hg add hello.txt

Now that Mercurial is aware of a changed file you can run diff to see exactly what's changed since the last commit - in this case we're adding the full contents of hello.txt:

$ hg diff
diff -r 000000000000 hello.txt
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/hello.txt Sat Jul 23 01:38:44 2016 -0400
@@ -0,0 +1,1 @@

And once we're happy with them and ready to check in our changes we can run commit:

$ hg commit -m "Created a hello world file."

Note that we included a commit message with -m - if you don't specify -m Mercurial will launch a text editor you can enter a commit message in. This is useful if you'd like to provide a longer multi-line message.

Once you've committed your changes they no longer show up if you run hg stat since the repository is now in sync with the contents of the working directory. You can run log to see a list of commits, and -v includes additional details like the files each commit touched:

$ hg log -v
changeset:   0:b4c06cc77a42
tag:         tip
user:        Michael Diamond@Aodh <>
date:        Sat Jul 23 01:44:23 2016 -0400
files:       hello.txt
Created a hello world file.