Using TortoiseHg (Windows)

TortoiseHg is an easy to use GUI for Mercurial. With TortoiseHg you can use Mercurial without having to type in commands on the command line. After installing TortoiseHg it sits in the context menu of Windows Explorer. Just rightclick inside a random folder and you'll find it there. This guide tells you how to use the basics of TortoiseHg. We'll cover cloning a repository, setting who you are, cloning, pulling, committing and pushing. Basically everyting you need to get started! Each section first states the Hg command and then explains how you can do the same via the TortoiseHg GUI.

For this part we assume that you've configured TortoiseHg correctly.

Clone

$ hg clone http://hg.openttdcoop.org/<project_name>

Clone makes a copy of a remote repository on your local system so that you can work on it.

  • First, browse to a folder in which you want to create a subfolder for the project. Then rightclick, choose TortoiseHg from the context menu and pick Clone a Repository. A dialog appears.
  • After Source Path, fill in the ssh:// address to the project's repository:
  • After Destination Path you can type the name of a folder in which the project should be cloned. Leave empty to automatically create a folder named <project_name> in the folder you opened the clone dialog from.
  • Click the Clone button in the top left corner.
  • If you've set a password for your private ssh key, a dialog pops up asking for it.
  • Wait for the operation to finish and close the dialog. You have now successfully cloned the project's repository.

You only need to do this once for every repository you want to work on.

Pull

$ hg pull -u

Pull gets the latest files from the remote repository. The -u modifier makes it update your local files at the same time so that these are in sync with the remote repository as well. You should pull every time you start working on something new and always before you push changes to the remote repository. That way differences between your local copy (the changes you made) and the remote repository are discovered and resolved. In some cases you might need to merge differences manually, but those are mostly resolved automatically.

  • Browse to the folder that contains the cloned repository.
  • Rightclick > TortoiseHg > Synchronize....
  • Click the little arrow right of the Pull button and select Update to new tip (this preference is remembered).
  • Click Pull.
  • If you've set a password for your private ssh key, a dialog pops up asking for it.
  • Wait for the operation to finish and close the dialog. You have now successfully pulled changes from the remote repository (if any).

Add and Commit

$ hg add -n
$ hg add FILE1 [FILE2 [...]]
$ hg commit -m "Type: commit message"

If you've added new files to the repository's folder structure, you'll need to run the add command to actually add them to the repository as well before committing. If there are no new files (only changed files) you can commit straight away. Both can be done from the Commit dialog.

  • Browse to the folder that contains the cloned repository.
  • Rightclick > HG Commit...
  • If there are new to add, select them from the left pane and click Add in the toolbar at the top of the window.
  • All changes you are about to commit are shown in the right pane.
  • Type a useful commit message in the large upper textarea.
  • When you're happy with what you're about to commit and the commit message, click the Commit button in the upper toolbar.
  • You have now successfully committed your changes, but only to your local repository, yet...

Pull-Merge-Push

$ hg pull -u
[possible merge]
$ hg push https://<user>:<pw>@push.openttdcoop.org/<project>

You can save the push url below the pull url:
in .hg/hgrc:
[paths]
default = http://hg.openttdcoop.org/<project>
default-push = https://<user>:<password>@push.openttdcoop.org/<project>

After committing it's time to add the changes to the remote repository as well. Before doing that, you have to pull to see if others have added things to the repository in the time you were working on it yourself. Possibly you need to merge something if you've been working on the same thing as someone else. These occasions are rare though if you use the "assigned to" bit of the issue tracker properly. After pulling (and possibly merging) you can push the changes back to the remote repository.

  • Browse to the folder that contains the cloned repository.
  • Rightclick > TortoiseHg > Synchronize....
  • Click Pull.
  • If you've set a password for your private ssh key, a dialog pops up asking for it.
  • Wait for the operation to finish. If there's something to merge you'll be notified of that and the k3diff dialog will open up. Perform the merge manually in that case.
  • Click Push.
  • If you've set a password for your private ssh key, a dialog pops up asking for it.
  • Wait for the operation to finish and close the dialog. You have now successfully pushed the changes to the remote repository.

Next: Setting up a Compile Environment »