How to manage code with Mercurial
The Mercurial project offers excellent resources for those who are new to using it and/or any other distributed source control management tool.
For quick instructions on how to jump right in and begin using Mercurial, take a look at their QuickStart guide. If that's too fast, then the tutorial would be a good choice. Finally, a detailed walkthrough of using Mercurial can be found in the online book Mercurial: The Definitive Guide.
Installing Mercurial: Download and install Mercurial from their site (http://mercurial.selenic.com/). Create the file mercurial.ini in your user root folder (e.g. c:\Users\John\mercurial.ini) with the following lines:
[ui] username=John Doe <firstname.lastname@example.org>
Quick help: To get a quick list of the hg commands, do
hgFor a more complete list, do
hg --helpFor all the options, do
hg -v help
To get help for a particular command, do 'hg help <command>'. For example,
hg help commit
First time sync of a project: Open a command prompt window, 'cd' into the directory where the project root folder will be created (e.g. 'cd c:\Users\John\Projects\Frc\2010'), clone a project from the server. For example,
hg clone http://proj.titanrobotics.net/hg/Frc/2010/code hg clone http://proj.titanrobotics.net/hg/Frc/2010/docs hg clone http://proj.titanrobotics.net/hg/Frc/2010/tools
where Frc/2010/code is one of the projects hosted on this server (This will create the local folder c:\Users\John\Projects\Frc\2010\code).
For a list of all the projects on this server, please visit http://proj.titanrobotics.net/hg
Working on the code: You can 'cd' into any directories under the project, create and edit any project files or create sub-directories and files.
Add a new file to the project: After creating a new file, add it to you local mercurial repository by
hg add newfile.cpp
Remove a file from the project: For example,
hg remove obsolete.cpp
Abandon changes to a file: If you changed a file but do not want to commit that change among other changes, you can remove that file from the change set by
hg revert robot.cpp
Do not track a file anymore: This marks the file so it will no longer be tracked as part of the project. It is similar to remove except that it will not delete the file from your computer and will retain its change history in the project. You can also undo the forget by doing an add.
hg revert robot.cpp
List new changes from the server before pulling: Sometimes it is useful to check what changes were pushed to the server by others before pulling them down by
List local changes before pushing: To show the local changesets that have not been pushed onto the server by
Show server path: To show where the changed files will be pushed to by
Examine the changes to a file: Before you commit the changes, you may examine the changes by
hg diff robot.cpp
Commit the changes to your local repository: For example,
hg commitMake sure you enter a concise description of your changes to let people know what they are about.
Sync your committed changes to the server: For example,
hg pushYou will need to provide your user name and password to commit the changes to the server.
Examine the status of all the files in your project: For example,
Examine the status of all the files in the sub-folder lib: For example,
hg status lib
Examine the change history: For example,
hg logIf you want to see the change history of a particular file, do
hg log robot.cpp
Sync changes from the server: For example,
hg pullNote that this will only pull the latest changes from the server to your local repository but it doesn't update your project files.
Update the project files from your local repository: After pulling the latest changes from the server, you need to update your project files by
hg updateIf you have private changes that have not been committed and want to discard them, do this instead.
hg update -CIf you have private changes that have not been committed and want to merge with the changes you pull from the server, do this instead.
Peer Sync Operations
One of the strengths of Mercurial is the ability to do peer sync. This means that you can sync changes with your peer instead of with the server. In other words, it doesn't require a server which means you don't need Internet connectivity that is often not available in competition. Everybody has a complete copy of the repository. This is especially useful during competition where team members may make changes after each match and wish to revert to a previous version if the change doesn't work. It is also useful to share the changes with other team members. One way to make peer sync operations simple is to create a repository on a USB flash drive and treat it as your server. Then you can push changes to the USB flash drive repository and pass it around to other members who can pull changes from it. Here are the steps to create and use a USB flash drive repository.
- Insert a USB flash drive to your laptop.
- Create the necessary folder structure of the project on the USB flash drive (e.g. d:\Frc\2010).
- 'cd' into the directory where the project root folder will be created. For example,
- Clone the project from the server. For example,
hg clone http://proj.titanrobotics.net/hg/Frc/2010/codeOr you can clone it from your laptop directly. For example,
hg clone c:\Users\John\Projects\Frc\2010\code
- When this is done, you have a complete copy of the project repository on the USB flash drive.
- In the repository of your laptop, modify the mercurial project configuration (e.g. c:\Users\John\Projects\Frc\2010\code\.hg\hgrc) to add the following line to the [path] section. For example,
[path] FlashDrive = d:\Frc\2010\code
- After you commit your changes to your laptop's repository, you can now push the changes to the flash drive by
hg push FlashDrive
- If you pass on the flash drive to your team member. The flash drive may show up with a different drive letter on her laptop (e.g. e:). She needs to add the corresponding line in her project configuration file (e.g. c:\Users\Jane\Projects\Frc\2010\code\.hg\hgrc). For example,
FlashDrive = e:\Frc\2010\code
- Now she can pull your changes from the flash drive by
cd c:\Users\Jane\Projects\Frc\2010\code hg pull FlashDrive
- Then she can update her files by
- Alternatively, you can also explicitly specify the path of the remote repository such as
hg pull d:\Frc\2010\code or hg push http://proj.titanrobotics.net/hg/Frc/2010/code