Perhaps by now you're wondering how Mercurial knows what changes have been made in your code. How does it figure out what got edited? There's a category of software programs called "diff tools", or "diff utilities", named after the original: a program on Unix systems from a very long time ago. Diff tools are able to compare two text files (which are presumably somewhat similar) and point out what changed from one file to the other.

All version control systems use some form of diff tool, and Mercurial is no different.

TortoiseHg includes a visual diff tool called KDiff3. You can use this tool to compare any two similar files, but the most popular use for it will be to compare a file that you've changed with the latest version in the repository to see how it's different from the last commit. (Or any earlier commit.)

In this tutorial, we'll take a few minutes to explore the diff tool. To set things up, go to your repository and make a change of some sort to a file without committing the change right away. We'll use the diff tool to show the changes that were made to the file.

Once you've made some changes (the file will now have a red exclamation icon overlaid on it, instead of the green check icon that indicates nothing has changed) right-click on it and choose TortoiseHg > Visual Diff.

This opens KDiff3, preconfigured to compare your edits to the file against the last version you committed, so that you can see the changes that you made. See the screenshot below:


I'm not going to go into a ton of details on this tool. It has quite a few features, and we just don't have time to look at everything here, but feel free to explore. For now, I'll just cover the most important features.

What you see on the left side is the last version that was committed to the repository. On the right is the current state of the file. You can tell all of this by looking at the text just just about the actual files. The one on the left says Design.txt@4:1c36d072982a and the one on the right says Design.txt. (The number after the @ sign is the revision.) Note that there are browse buttons next to each of those, so you could diff any files that you have, regardless of whether they're under version control or not.

You can see from the red bar on the right side that KDiff3 has detected three changes across the file. The green bar indicates where these changes are in the original file, and the blue bar indicates where these changes are in the new file.

What you can hopefully see by doing your own diff is that the diff tool is great at picking out every little change that was made and displaying them to you. My third change is the easiest to see: I added a new line. My first change is a bit tougher: I turned the word "amet" into "metta world peace". You can see that it highlights the additions in blue on the right side. The middle change was the most subtle: I added a single character randomly to the text. The diff tool found it and highlighted it, making it easy to see.

And by the way, you can use the little up and down arrows at the top of the screen to move from one change to the next. (The current change is highlighted in a tan/brown color.) This is especially useful in a long file where the changes are spread out.

Using Diff At Commit Time

Before finishing up here, I should point out that you can also open the diff tool when you're doing a commit. In fact, you might use diff in this way more often than the first way I described. This is a great time to pull the diff tool out, because it makes it easy to pay careful attention to the changes you're dumping into the repository. That way you don't commit any changes that you didn't mean to. To do this, on the Commit dialog, right-click on the file of interest and choose Diff to Parent: