This document is a quick intro to cloning and using your Lab46 Mercurial Repository.

NOTE: New accounts will not have a ~/src directory, thereby obsoleting this step. If you do not currently have a ~/src subdirectory, you may proceed to the next step.

This document assumes you are cloning your repository into ~/src. This is all fine and good, but an error will occur if this directory exists and is not empty.

So, we are going to employ a quick workaround. If you are performing these instructions on a home machine and you do not have a src directory, or the directory you plan to clone to is empty, you do not need to perform this step.

First up, move the existing src out of the way:

lab46:~$ mv src src.bak
lab46:~$ 

Proceed with the instructions.

In order to use your repository, you must first clone it:

lab46:~$ hg clone http://www/hg/user/yourusername ~/src
http authorization required
realm: Lab46/LAIR Mercurial Repository (Authorization Required)
user: yourusername
password:
no changes found
updating to branch default
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
lab46:~$ 

Perform this step ONLY if you wish to access your lab46 repository from your home computer (ie if you want a local copy, and are not using an SSH client to access your data). For most of you, this step is not necessary, and you should skip it.

In order to use your repository, you must first clone it. Note that this is only for additional copies of the repository you wish to work with, in addition to the “local” copy we cloned above on lab46.

If you're using a command-line interface on your remote machine:

yourpc:~$ hg clone http://lab46.corning-cc.edu/hg/user/yourusername ~/src
http authorization required
realm: Lab46/LAIR Mercurial Repository (Authorization Required)
user: yourusername
password:
no changes found
updating to branch default
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
yourpc:~$ 

If you are making use of some graphical front-end to hg, such as TortoiseHg, the URL you want is:

http://lab46.corning-cc.edu/hg/user/yourusername

Having finished the chicken-and-egg file management aspect of bootstrapping our repository activities, we need to remember to change back into our src directory before continuing:

lab46:~$ cd src
lab46:~/src$ 

If you did that initial step to avoid encountering errors, you'll also want to perform this step to complete the process.

If you didn't perform the workaround, this step also is not necessary.

Move the contents of src.bak into src (note that we are already in src as per the last step):

lab46:~/src$ mv ~/src.bak/* ~/src/
lab46:~/src$ 

And, assuming there were no hidden files in ~/src.bak/, it should now be empty and we can remove it:

lab46:~/src$ rmdir ~/src.bak
lab46:~/src$ 

If you got an error to the tune of “directory not empty”, there is still something there and you may want to investigate that. However, the current state of ~/src.bak will not impact our efforts here, so successful or not, we can proceed to the next step.

Mercurial uses a .hg located at the base of your repository to store important information. Most of it you will not have any need to directly look at (but you should take care to preserve that data as it manages how your repository works).

There is one file you may want to edit- .hg/hgrc

lab46:~/src$ nano .hg/hgrc

It is a text file, and by default, probably looks as follows:

[paths]                                                                                   
default = http://www/hg/user/yourusername

To make your life a little easier, we may wish to make a few changes (ADD/APPEND the following information):

[web]
push_ssl = False
allow_push = *

[ui]
username = Firstname Lastname <yourusername@lab46.corning-cc.edu>

[auth]
lab46.prefix = http://www/hg/user/yourusername
lab46.username = yourusername
lab46.schemes = http

There are other settings and changes you can make, but this is probably the minimum you'll want to do in order to avoid more complicated command invocations when interacting with your repository.

Obviously, if you are accessing your repository from a home or computer that is on a network foreign to the LAIR, be sure to substitute www with lab46.corning-cc.edu

Just as it is important to track changes to files, we also want the ability to ignore certain files. Mercurial provides a facility for this, and it is a set of patterns located in a file called .hgignore, located in the base of your repository (not in .hg, but a sibling file).

Until you learn a better text editor, you may make use of the nano text editor. Don't worry, we'll aim to learn something more elegant and effective-to-use before too long. In this instance, you can create/edit this file with the following command:

lab46~/src$ nano .hgignore

Here are some initial settings you may wish to put in your .hgignore file:

syntax: glob                                                                              

*.swp
*.pyc
*.o
*~

Basically, any file located in this directory and subdirectory beneath will be ignored when it comes to Mercurial looking for changes.

Why would this be useful? Well, for one we don't wish to track temporary files that might be created by a text editor, that contain no useful information. Also, we really have no need to track object and compiled files- it is the text and source files that are most valuable to us.

Let's assume you created that .hgignore file from the section above. This is a great file to track in Mercurial, so we will use it as an example.

First up, I introduce to you the command hg status. Go ahead and run it while residing in your repository directory:

lab46:~/src$ hg status
? .hgignore
? Makefile
lab46:~/src$ 

In this case, we see Mercurial has noticed a new file, .hgignore, and its status is unknown (hence the ?), it will also pick up on any other files you have located in this directory.

As I said, we want to track this file, so we need to tell Mercurial to pay regular attention to it. We do that with the hg add command (note that we only have to add files to the repository once):

lab46:~/src$ hg add
adding .hgignore
adding Makefile
lab46:~/src$ 

Now go and check the status again:

lab46:~/src$ hg status
A .hgignore
A Makefile
lab46:~/src$ 

You should see that the original “?” status of the file has been altered to “A”. That is *A* as in Add.

In order for Mercurial to work its magic, we need to get the changes committed to the repository. For us, this will be a two-step process- we need to commit any changes, and then push them to the LAIR repository.

You will want to commit changes fairly regularly. A commit represents a “changeset” in Mercurial terminology, or a snapshot/revision of files. The more often you commit, the more precise the collection of changes you will have access to (and, generally, the safer your files will be to corruption or loss).

To commit, we specify that as a command, and provide a reason:

lab46:~/src$ hg commit -m "Created .hgignore file"
lab46:~/src$ 

With Mercurial, when you clone the repository, you now have a NEW repository. So there's the original one you copied, and the one you just copied (2). The more you clone, the more repositories you have. This creates a local/remote situation. Your local copy IS a real repository, that you can add and commit to.

But in order to ensure a level of redundancy, safety, and in the case of group projects, collaboration, you need to synchronize any local changes with the remote repository. To do that, we issue a push command:

lab46:~/src$ hg push
http authorization required
realm: Lab46/LAIR Mercurial Repository (Authorization Required)
user: yourusername
password: 
pushing to http://www/user/yourusername
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 1 change to 2 files
lab46:~/src$ 

You generally want to push once you have finished a commit.

It would be good to get in the habit of doing this regularly.

If we are in a group setting, we'll regularly be making transactions with the repository- you'll be commiting and pushing changes, and so will others.

In order for you to receive changes commit/pushed by others, you need to occasionally do a pull/update. First up, we do a pull:

lab46:~/src$ hg pull
http authorization required
realm: Lab46/LAIR Mercurial Repository (Authorization Required)
user: yourusername
password: 
pulling from http://www/hg/user/yourusername
searching for changes
adding changesets
adding manifests
adding file changes
added 3 changesets with 10 changes to 7 files
lab46:~/src$ 

Notice here in this example, 3 new commit transactions are coming down the pipe, encompassing 10 separate tracked changes across 7 files in the repository.

Now, listing and poking around the repository will show no changes. That's because while we've received changes, we have yet to apply them to the repository. To do that, an update is in order:

lab46:~/src$ hg update
10 files updated, 0 files merged, 0 files removed, 0 files unresolved
lab46:~/src$ 

The changes are now visible in your copy of the repository.

There are other actions or situations you may encounter while using Mercurial. Conflicts, branches, heads, the need to merge, and even pulling out old versions. But for now, get used to the basics.

Mercurial has a help screen, that can be accessed by issuing the command: hg help

Should you be required to utilize Bitbucket, it is possible to clone your Bitbucket repository on Lab46. This will allow you to commit files to your Bitbucket repository without the use of tools such as TortoiseHg.

First, clone your repository.

hg clone https://yourusername@bitbucket.org/yourusername/cscs1320s14

cd into the repository directory that it just made

cd cscs1320s14

Now, edit the hgrc file (located in .hg)

nano .hg/hgrc

The [paths] should already be there. Add the following info, replacing the correct information.

[paths]
default = https://yourusername@bitbucket.org/yourusername/cscs1320s14
[auth]
bb.prefix = https://bitbucket.org/yourusername/
bb.username = yourusername
[ui]
username = Firstname Lastname <mybitbucketemailaddress@whatever.com>
verbose = True

Save the file.

To add your files you wish to commit, run

hg add

This adds the files to the repostiory, afterwards you can use

hg commit -m "Your commit message"

to commit the files, and then run

hg push

to push it to Bitbucket