15 Jan 2012

Writing complex software (or even simple programs) often requires many revisions. It's useful to be able to track those revisions for many reasons, including:

• looking back to find the revision that introduced a bug
• managing competing changes from several collaborators
• managing different versions of the source code
• just as a general history of changes/features added

Numerous version control systems have been created to help track revision information. We'll be covering version control concepts using Mercurial, a distributed version control system.

### Agenda

1. Create an account at Bitbucket, which provides free hosting of mercurial repositories. If you want, you can use this to post all of your homework for the semester.

2. Install Mercurial. On Windows, the easiest way is to use TortoiseHg, which comes with a merge program and other utilities. On Linux, it's probably even easier, but depends on which distribution you're using. On a Mac, we can figure something out (I haven't use it there before).

3. Set up Mercurial. Create a file called mercurial.ini in your home directory (or called .hgrc on non-Windows systems). You can use this to define basic preferences. Here's a template:

[ui]
username = Your Name <yourname@youremail.com>
merge = kdiff3

[extensions]
fetch =


About your home directory: on Windows 7, this is C:\Users\yourname, which is also listed in the %USERPROFILE% environment variable. When you start a command prompt, you'll usually start in your home directory.

4. Clone this example repository for us to play with, by executing the hg clone command in a shell:

hg clone https://bitbucket.org/jlepak/185-example

• Make a few edits on an existing file, and create a new file (put your name in the filename).
• Run hg status to see which files you've changed.
• Notice the ? lines, which indicate new files that haven't been set to be tracked yet. Use hg add to add all newly created files.
• Run hg diff to see the lines you've changed.
• If there are files in the directory that shouldn't be tracked, add them to a file named .hgignore in the root of the repository. For example, since you probably don't want to track the .class files created when you compile Java source, you could add the lines:

syntax: glob
*.class

• When you're satisfied with your changes, run hg commit to commit them, and give an informative message.

• Run hg outgoing to see which changes you have ready to post to the public server.
• Run hg incoming to see which changes are waiting on the public server for you to download.
• If there are incoming changes, run hg fetch to get the changes, merge the changes with your own if necessary, and update your working directory to the latest version.
• After fetching the latest changes, post your changes by running hg push.
• Run hg log to view a log of all changes made so far.
• (Only if you're using TortoiseHg): run thg to launch a graphical browser.
• Run hg help for a summary of all these commands and a few more.

### Homework (HW3)

Due in either 1 or 2 weeks, depending on how much we cover in class (I'll decide at end of class).

1. Create a repository on Bitbucket (log in before following the link). Call it 185-hw, since you'll be doing this week's homework in it. Check the box to make it private, so that if you put later assignments in it you won't have to worry about others copying your work.

Once it's created, click on the Admin tab, select Access management, and add me (username jlepak) with write access. This will allow me to read and optionally write updates to your repository.

2. Create a folder called hw3 in the root of the repository. Put all of your work for this assignment in that folder.

3. Browse or search Bitbucket to find examples of 3 repositories containing projects related to a topic you're interested in. For each, describe the project (just a sentence or two is OK), say what the primary programming language used is, and determine how many commits have been made. Put all the information in a file called project-links.txt. Run hg commit to commit your progress so far, if you haven't already.

4. We've used the dir command and the cd command in class already, and the week 1 agenda lists a few others. Find 3 more commands that could be useful (by searching online, or asking your friends), describe them, and give an example of how they're used. Put your answers in a file called command-examples.txt. Run hg commit to commit your progress so far, if you haven't already.

5. After you are done, run hg push to post your work (you don't need to worry about fetching/merging first, since you're not collaborating with anyone). Email me at jal2016@email.vccs.edu to let me know that you're done, and tell be your Bitbucket username to make sure I know how to find your repository.

### Readings

• Hg Init. The "Ground up Mercurial" chapter provides a good detailed introduction, with a focus on usage in Windows. The other chapters (optional) give even more detaiil.

• Understanding Mercurial. This discusses details of how repositories are structured.

• If you'd like to browse to find some material that might be more to your liking, see this list of beginner's guides.