Mercurial Source Control

Nordic Storm uses the Mercurial version control system to allow many programmers to write code on different computers and merge changes together easily and safely.  Our Mercurial repositories are hosted on Bitbucket, who has graciously donated an educational license for us to use. Following are instructions for getting set up to use Mercurial, and basic instructions on how to do the most common operations with the code.

Getting Started with Mercurial

The simplest way to get started if you are using Windows, is to use an excellent free application named TortoiseHg to run all of your Mercurial commands. The TortoiseHg installer contains everything you need to get started.  Simply download the latest version of TortoiseHg that matches your operating system and install it.

You will also need to create a user account with your source control host (in our case it is Bitbucket) and get added to your team repository. Talk to the person who administers the repository to get this done.

Cloning a Repository

If you have TortoiseHg installed, and your account has been granted access to the repository, you are ready to get a copy of the repository brought down to your machine so you can work on the code.  Mercurial calls this "Cloning" the repository.  Run the TortoiseHg Workbench on your machine and use the File | Clone Repository... menu to begin this process.

  • Source: The path to the repository which will be given to you by your repository administrator.
  • Destination: The local directory where you want to create the local copy of the repository.

For example for our 2013 repository we entered the following

  • Source: https://{yourBitbucketUserId}@bitbucket.org/lorenh/nordicstorm2013
  • Destination: C:\FRC\NordicStorm2013

After this operation completes you will have the entire repository local on your machine and can begin working on the code.

Working on the code

There's really nothing special to do here, just open the project in NetBeans and work like you always did. When you get your code working to a spot where you want to save it you will Commit it to your local repository.  You can Commit your changes as often as you want, but none of your changes will be able to be shared with your teammates until you Push your changes up to the shared repository, and they Pull them into their local repository, then Update them into their own local working folder.

Commit local changes

Once you have finished with your changes to the code, open up the TortoiseHg workbench(or whatever program you use), and find your working directory. This contains all of the changes you have made since the last version of the code that you updated to. Find where you can commit the code, in TortoiseHg, it's in the middle on the left. Type in a description of what you did, and press the "commit" button. This saves your changes locally as the next step in the production timeline. In order for the rest of the users to see it; however, you have to push your local repository.

Push Changes

Once you have finished all of your changes and committed them, you want the rest of the repository users to be able to see them and work off of them. In TortoiseHg, there is a toolbar at the top, one of the buttons is the "push" button. This button will replace the cloud repository with a copy of your local one which includes all the changes you made. Press the button and enter your password to send your changes to the cloud.

Pull Changes

When you start working, you want to make sure you have the latest version of the repository; find the button to "pull incoming changes" and select it. Your workbench will now replace your local repository with a copy of the one in the cloud. NOTE: It will NOT replace your local directory, that is, all of the changes you have made and committed since the last time you pulled, unless you choose to completely clear your local directory.

Update Changes

Sometimes, in the course of developing your code, you may decide that you want to roll-back some changes you made. To do this in TortoiseHg, choose the version of the code that you want to go back to, right-click on it, and select "update." This will load that code as the current version, and shift all of the versions since then into a separate branch, so you can go forward again to the most recent one.

Merging

This is one of the most useful and complicated parts of a mercurial repository. If you need to accept changes in two different commits, for example, if two people are working at the same time, there is a tool in TortoiseHg to combine the changes. First, load all of the changes onto one computer, so that you have multiple branches--One for each thing you want to combine. Then, right-click the branch that is in the cloud and not only in the local repository and select "merge with local." TortoiseHg will then attempt to merge the two branches by choosing the things that are different and deciding what the final result should be. If the changes are in different parts of the program, this will go cleanly and automatically after you press the merge button, but if the changes were all made on the same parts of the code, you will be asked to manually choose which version or versions you want to keep in the final.