======Lab46 Mercurial Repository====== 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 | =====Avoiding an unnecessary error===== 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. =====Cloning Locally (on Lab46)===== 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$ =====Cloning Remotely (Home Computer)===== 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$ =====Restoring original src contents===== 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. =====Customizing your Settings===== 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 [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** =====Ignoring Files===== 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. =====Checking for changes===== 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 **?**). =====Adding a file for tracking===== 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 **A**dd. =====Committing changes to the repository===== 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$ =====Pushing changes to the repository===== 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. =====Pulling changes from a repository===== 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. =====Other===== 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**