Initializing a new repository using Mercurial

Topics: 

I just red through the semi-official Mercurial book (http://hgbook.red-bean.com/) and didn't see in there a section describing how to initialize a new repository. It talks at length about how to use existing repositories but not quite explicitly how to start a new one. However the quick start guide does discuss it, under "Setting up a new project".

$ cd project/
$ hg init # creates .hg

The hg init command creates a blank repository that contains no files. By default it does so in the current directory, an alternate method is:

$ hg init project

This version causes the blank repository to be created in the given directory, and that directory is created if required.

As a blank repository it knows about no files. A repository is rather useless without files.. so let's look at how to add them. Assuming you have some existing files copy them into the repository directory.

$ hg add            # add those 'unknown' files
$ hg commit # commit all changes, edit changelog entry

The first does a recursive walk of the directory tree to record the existence of all the files. The second puts them into the repository control, and along the way you'll be thrown into your $EDITOR to explain what you're doing.

It's possible to have mercurial ignore certain files in your directory tree, such as if there are build results or other flotsam lying around which shouldn't be checked in. The .hgignore files lets you instruct mercurial what files to ignore.

Now let's test this new repository. One is the hg status command, which can be executed immediately after the hg add command to see that the status is a bunch of new files, then again after the hg commit to see that there are no files left to commit as they'd already been committed.

Another test is to make a copy of the repository.

$ cd ../
$ hg clone project project-copy
updating working directory
1459 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ ls
project project-copy

This makes a duplicate of the repository, the second is named "project-copy". At this point both are identical and further clones can be made of either one.

Another test is to use ssh to access a repository. In my case the repository is being set up within my dreamhost account and I want to make a duplicate of the repository on my local system. The local system is a desktop running Ubuntu, but I also have other local systems running Mac OS X and I run a CentOS server to house my websites. All these systems have ssh available.

$ hg clone ssh://user [at] domain [dot] com/path/to/project

You may be asked for a password but that's all which is required to retrieve the repository over ssh.

extvideo: