Getting started with Mercurial and TortoiseHG Workbench

A version control system should be easy to use, at least when you just need to perform basic tasks.

This is why I like Mercurial. It's powerful yet easy. And TortoiseHG is an excellent client app. It's got the same GUI in Linux, MacOS and Windows. This is a brief tutorial:


We are going to use the TortoiseHG Workbench. So let’s open up the workbench now. If it’s the first time we open the workbench we must tell  TortoiseHG what is our username. Open the settings window through the “File” menu. Select “Commit” on the left hand side and introduce some username on the right.

Now we need to create a repository. That can be done through the “New Repository” in the “File” menu. We just need to indicate the folder. It can contain source code already.

tortoise_ready_to_commitThe “commit view”, is where pending changes (uncommitted) can be seen. To display this view click on the green tick button on the top. From this view we can see changed files and their contents.
If there has been changes while this view was displayed, we need to refresh (blue circle button in the middle of the screen) in order to
see them.
Finally, the commit needs a comment that goes into the comment area. Text from previous comments can be retrieved in case we want to reuse the same comment. See the “Copy message” dropdown right on top of the comment area. Once the commit comment is introduced we just need to click on the “Commit” button on the right hand side.
If we need to commit the change into a new branch, we can do that clicking on the label “Branch: default” right on top of the comment area.


From the "commit view" it's also possible to track new files. This is one way we can add existing source files into the repository or files that we create later. Using the right mouse button over the pink file

(unversioned file) pops over the menu with the option to add. The same menu also gives the choice to discard changes made on the selected file (the “Revert” menu item). Another useful item in the menu is the “File History” of each file, which opens up in a new window. That window shows only commits where the selected file was changed.

tortoise_enabling_filter_barThe second most common operation we do with TortoiseHG is searching for commits. The “filter bar” must be enabled for that. Then we can write any word that we want to search for in the commits comments. The filter bar also admits filter commands. For example to search for commits made by user with name John write “user(‘john’)” on the filter bar.

Version control and TDD

I use the VCS to keep track of my TDD flow. It serves as documentation for others and saves me time when I want to jump back to a previous state. I usually commit on red (test failing), on green (test passing) and eventually on refactor. To be efficient with that, I don’t worry much about the commit comment. I prefix the comment with “red:”, “green” or “refactor:”. In red, I copy the name of the test as part of the commit comment. On green I don’t need to add anything. On refactor, sometimes I add the name of refactor used (i.e “refactor: extract method”).

tortoise_filtering_commitsPeople coming from CVS or Mercurial are used to commit only when the code compiles and tests pass, because a  commit affects the  other teammates. The biggest advantage of DVCS over centralized systems is that our commits don’t affect others. So now a commit is just a snapshot of the code. And we should take as many snapshots as needed. Doing this properly we will never find ourselves struggling to come back to a previous state where everything was working. We can just discard the changes (revert) and continue from the last safe point. This technique is explained in detail in the Agile Record Magazine, issue 9, page18

  • Tuppence Farthing

    Great quick Tutorial. However, I believe, in the first sentence of your last paragraph, you meant to use two examples of centralized VCS such as CVS and SVN. Mercurial is not a cVCS but a DVCS as you obviously know.

  • Carlos Ble

    Thanks for the correction, you are right 🙂