hg-diff a graphical user interface to compare mercurial revisions
Introduction
Mercurial is a great tool for version control. There is even a graphical user interface in the distribution that is called with the command "hg view which can be used to browse different revisions in a repository. But it displays only the raw output of "hg diff" when you compare versions of files which is the common unified diff format. This format contains only the lines in the file that have changed but not the file as a whole.
There are alternatives when you want to compare two files, that are all based on the good old diff command but display the differences in a graphical way. One of these programs is tkdiff. It displays both versions side by side and has the differences marked by coloring.
With the "extdiff" command in mercurial you can call an external graphical diff viewer, for example kompare (part of kdesdk), but you have to start this command from the command line.
hg-diff fills the gap here as it allows the usage of graphical diff viewers for mercurial that are started by a graphical user interface.
Prerequisites
In order to use hg-diff you should have installed at least one of the following diff viewer programs:
and at least one of the following file viewer programs:
You should have the Graph log configured by adding:
[extensions] hgext.graphlog =
to your ~/.hgrc file.
You should have extdiff configured by adding:
[extensions] hgext.extdiff =
to your ~/.hgrc file.
Elements of the GUI
Here is a picture of the application:
The main window consists of 5 main parts that are from top to bottom:
- The menu
- The repository selector
- The revision selection and command part
- The file display
- The status line
The menu
The menu bar contains two items, the "File" and the "Help" menu. Both are described below.
The File Menu
This is how the file menu looks like when it is opened:
The "File" menu consists of these parts:
Open Repository
This menu item opens a file dialog that is used to select a new mercurial repository. If you select a directory within a mercurial repository that is fine. hg-diff will find the repository root directory. If the selected directory contains no mercurial repository, an error message is displayed and the repository that was used before remains unchanged.
close all started programs
If this option is chosen, all programs that were started by hg-diff and are still running are terminated. This may be useful when too many of these programs fill your desktop.
default diff program
Here you can select the external program that is used to display differences between files. Currently hg-diff supports tkdiff, gvimdiff (gvim), kompare and meld. Note that hg-diff checks at start if these programs are installed and offers only the programs that it found.
default viewer programs
Here you can select the external programs that is used to display single files. This program is called for files that were added or removed or for files in the working copy that are unknown to the repository. Currently hg-diff supports gview (gvim), gedit and kwrite. hg-diff checks at the start if these programs are installed and offers only the programs found.
quit
This quits the program. Diff and file-viewer programs started by hg-diff and still running are terminated, too.
The repository selector
This part of GUI shows the path of the currently selected repository. The repository path can be edited directly or, if the "browse" button is pressed, a file selection dialog is opened to select a new directory. If you select a directory within a mercurial repository that is fine. hg-diff will find the repository root directory. If the selected directory contains no mercurial repository, an error message is displayed and the repository that was used before remains unchanged. The repository entry field changes to it's old value in this case.
The revision selection and command part
This part of the GUI is used to select the two revisions that are to be compared and to set options on what information is displayed.
The revision selection entries
The first two lines show both revisions with their short revision number and the first line of the log message. In each line, the revision can be changed by entering a decimal number or an empty string to the entry field. The program checks if the number is a valid revision number and replaces it with the revision number and the first line of the corresponding log message. If you enter an empty string this selects the working copy and the text is replaced with the string "working copy".
If you click on the arrow on the right side, a list of all revisions is displayed where you can select a revision with a simple mouse-click.
The command and display options part
In this area you find buttons for certain commands and check boxes for display options.
The +rev and -rev buttons
The buttons "+rev" and "-rev" offer another possibility to select revisions. "+rev" goes forward with the first and second revision. If a branch is encountered a dialog window opens where you have to specify with part of the branch you want to go. "-rev" goes backward with the first and second revision. This may also open a dialog window if a branch is encountered.
The re-scan button
This button reloads all the revision data from mercurial. You have to click this button if you applied changes to your repository (like "hg commit" or "hg qnew") while hg-diff was running.
The couple selection box
This selection box is used to couple the selected first with the selected second revision that the first one is always the parent of the second one. In this case, the entry field for the first revision is disabled. In most cases you want to compare a revision with it's parent revision so "couple" is selected as a default.
The revision history selection box
The selection box "rev log" is used to display a history of all revisions. This simply is the output of the "hg glog" command. It displays a list of all revisions with tags, user, date and summary along a simple ascii representation of the revision branches at the left side of the window.
The full log selection box
The selection box "full log" is used to display the full log message of the currently selected second revision. This information is displayed in a new window that opens when "full log" is activated.
The full diff selection box
This selection box diff" changes the way the difference viewer program is called. When "full diff" is off, the difference viewer program is called once for each file you click on. If "full diff" is on, the difference viewer program is called for all changed files at once. Programs like kompare and meld are capable of displaying these differences between file-trees. For the programs tkdiff and gvimdiff, which cannot do this, the selection box is set to the state "off" and disabled.
The file display
The file display shows the output of the "hg status" command. Each line has a flags as a first character followed by a space and the name of the file. These are the codes of the flags:
- M
- modified
- A
- added
- R
- removed
- C
- clean
- !
- missing (deleted by non-hg command, but still tracked)
- ?
- not tracked
- I
- ignored
When "full diff" is off (see above), a double-click on a single line opens the diff viewer or file viewer program for that file. If "full diff" is on, a double-click on any file opens the diff-viewer program for all files.
The status line
This is the small area on the bottom of the main window. Usually, it is empty, but help and error messages may be displayed here. If you move, for example, the mouse over the file window, a short help message on the file window is displayed here.
Command line options
hg-diff has these command line options:
| --version | show program's version number and exit |
| -h, --help | show this help message and exit |
| --summary | graphical diff for mercurial |
| --dry-run | do not execute commands, just show them |
| -v, --verbose | show executed external commands |
| -R REPOSITORY, --repository=REPOSITORY | |
| specify the REPOSITORY to use. You need this option if the mercurial repository is not in the current working directory. | |
| -r REVISION, --rev=REVISION | |
| specify the REVISION against the comparision is done. If two --rev options are given, compare these two revisions. | |
| -c REVISION, --changes=REVISION | |
| show that changes that REVISION did. | |
| -q, --quick | directly show all changes by running the default GUI diff viewer "tkdiff" on the files. After starting the external programs, hg-diff terminates. It's own GUI is not started. If you want this to be done only for a specific list of files add them after the command, otherwise all modified files are shown. |
| -p DIFFPROGRAM, --program=DIFFPROGRAM | |
| Does the same as "-q" but calls DIFFPROGRAM to show the changes. These are the known programs: "tkdiff", "gvimdiff", "kompare", "meld". | |
Screenshots of the external programs
Here are screenshots from the external programs called by hg-diff:
tkdiff with a single file:
gvimdiff with a single file:
kompare with a single file:
meld with a single file:
display of a single file with gvim:
display of a single file with gedit:
display of a single file with kwrite:
