This document is a quick intro to cloning and using your Lab46 Mercurial Repository.
Term | Description |
---|---|
yourusername | Instead of writing 'yourusername', replace with your actual Lab46 username you use to log in |
This document assumes you are cloning your repository into ~/src. This is all fine and good, but an error will occur if this directory 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:~$
Next, create a new src:
lab46:~$ mkdir src 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:~$ cd src lab46:~/src$
In order to use your repository, you must first clone it:
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:~$ cd src yourpc:~/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
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:
[paths] default = http://www/hg/user/yourusername [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 lab46:~/src$
In this case, we see Mercurial has noticed a new file, .hgignore, and its status is unknown (hence the ?).
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 lab46:~/src$
Now go and check the status again:
lab46:~/src$ hg status A .hgignore 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 1 file 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.
NOTE: If you have multiple copies of a repository, you'll need to pull/update on each one to keep them all up to date, as they are each an independent copy.
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