8. Extensions¶

This chapter describes Mercurial extensions that are shipped with TortoiseHg binary packages for Windows. These external extensions are included as a convenience to users, so they can be easily enabled as soon as they are needed.

8.1. Hgfold¶

hgfold is a Mercurial extension that helps Windows users deal with filename case collisions on VFAT and NTFS.

up    - allows you to update to a revision with filename collisions
merge - allows you to merge with a changeset that would create filename collisions

The extension does not currently do anything to prevent filename collisions. See discussion on the Mercurial Wiki

Installation

To test the use of this plugin, you can specify it on the Mercurial command line like this:

hg --config "extensions.fold=" status

You may want to add it to your Mercurial.ini or a repository’s hgrc like this:

[extensions]
fold=

If you do this, you can omit the –config command-line option.

Warnings

Like all merge operations, fold.py has to change the parents of the working directory. It is still in early testing, so use with caution.

If you get an error about an unknown changeset after running hg recover try hg debugsetparents <number of tip revision>. You can find the number of the tip revision by running hg log -l 2.

8.2. Hgcr-gui¶

CodeReview management tool

• This extension allows you to manage reviews for your code in any project you like.
• It helps to keep the review management inside the mercurial.
• One can add files to the review, remove them and notify reviewr that files are ready for review.
• The reviewer can mark the code as ‘completed’ review cycle and return the message to the developer.
• The project manager can check the review status - which files are reviewd and which are not yet.
• The extension will automatically spot the files that were changed since their last review and notify about that.
• This extension uses GUI from TortoiseHg but also implements command line interface.
• Code review database is stored in .code-review file in your repository root directory as a map of file and revision when review was done.

Usage:

hg cr [OPTIONS] [FILES]

Code Review Plugin (requires Mercurial 1.3.x and TortoiseHg 0.9)

options:

-c --complete  Mark CR as complete
-r --remove    Remove files from CR list
-l --list      Print files in CR list

use "hg -v help cr" to show global options

Note

To start GUI don’t give any options.

More Details

• I’ve implemented the review around files and not changesets, because at the end, I want to be able to tell for the specific project if all the files went through code review process or not - the project status.
• Suppose you have some project that you are in charge and many developers do write code for it. And there is a group of reviewrs that review the developers code.
• Is is very difficult to keep track of changes developers do, but simple to find out what files have already been reviewd (by reviewers) and what were not.
• Using this extension, Developer can mark his files (when finished development process) as “Ready for review” and send notice to reviewer.
• Reviewer will pick up the changeset (because changesets are stored in the code review database) and perform code review (put notes inside the developer’s code).
• Afterwards Reviewr will mark the files as “Review Completed” and return the notice to the developer.
• The project manager can follow every time what is going on with his/her project.

Installation

You may want to add it to your Mercurial.ini or a repository’s hgrc like this:

[extensions]
hgcr-gui=

8.3. Perfarce¶

This extension is documented elsewhere.

8.4. HGEOL¶

The hgeol extension is the eventual successor to the win32text extension. It tries to resolve the EOLN compatibility problems in a more complete and robust fashion. Instead of documenting it here, we will link to it’s online documents which are continually evolving.

8.5. Mercurial-Keyring¶

Keyring extension uses services of the keyring library to securely save authentication passwords (HTTP/HTTPS and SMTP) using system specific password database (Gnome Keyring, KDE KWallet, OSXKeyChain, dedicated solutions for Win32 and command line).

What it does

The extension prompts for the HTTP password on the first pull/push to/from given remote repository (just like it is done by default), but saves the password (keyed by the combination of username and remote repository url) in the password database. On the next run it checks for the username in .hg/hgrc, then for suitable password in the password database, and uses those credentials if found.

Similarly, while sending emails via SMTP server which requires authorization, it prompts for the password on first use of given server, then saves it in the password database and reuses on successive runs.

In case password turns out incorrect (either because it was invalid, or because it was changed on the server) it just prompts the user again.

Installation

First, the extension must be enabled in your Mercurial.ini file as:

[extensions]
mercurial_keyring=

The most appropriate password backend should usually be picked automatically, without configuration. Still, if necessary, it can be configured using ~/keyringrc.cfg file (keyringrc.cfg in the home directory of the current user). Refer to keyring docs for more details.

Note

On Windows XP and above, your encrypted passwords are stored in the credentials subsystem using CredRead and CredWrite

Note

On Windows 2K, the encrypted passwords are stored in the system registry under HKCU\Software\Mercurial\Keyring.

Repository configuration (HTTP)

Edit repository-local .hg/hgrc and save there the remote repository path and the username, but do not save the password. For example:

[paths]
myremote = https://my.server.com/hgrepo/someproject

[auth]
myremote.schemes = http https
myremote.prefix = my.server.com/hgrepo
myremote.username = mekk

Simpler form with url-embedded name can also be used:

[paths]
bitbucket = https://User@bitbucket.org/User/project_name/

Note

If both username and password are given in .hg/hgrc, extension will use them without using the password database. If username is not given, extension will prompt for credentials every time, also without saving the password. So, in both cases, it is effectively reverting to the default behaviour.

Consult [auth] section documentation for more details.

Repository configuration (SMTP)

Edit either repository-local .hg/hgrc, or ~/.hgrc (the latter is usually preferable) and set there all standard email and smtp properties, including smtp username, but without smtp password. For example:

[email]
method = smtp
from = Joe Doe <Joe.Doe@remote.com>

[smtp]
host = smtp.gmail.com
port = 587
tls = true

Just as in case of HTTP, you must set username, but must not set password here to use the extension, in other cases it will revert to the default behaviour.

Usage

Configure the repository as above, then just pull and push (or email) You should be asked for the password only once (per every username + remote_repository_url combination).

8.6. pbranch¶

Patch Branches (pbranch) is a way to develop a series of patches for submission into a main repo. It is based on topic branches, one per patch, and is thus highly suitable for collaborative and/or long-term patch development and maintenance.

A detailed manual can be found online.

It adds a number of commands which can be listed with hg help pbranch:

pbackout       - backs out the current patch branch (undoes all its changes)
pdiff          - prints the final diff for the current or given patch branch
peditmessage   - edit the patch message
pemail         - send patches by email
pexport        - exports patches
pextdiff       - combines pdiff and extdiff
pgraph         - print an ASCII art rendering of the patch dependency graph
pmerge         - merge pending heads from dependencies into patch branches
pmessage       - print the patch message(s)
pnew           - start a new patch branch
pstatus        - print status of current (or given) patch branch
reapply        - reverts the working copy of all files touched by REV to REV

Installation

As this extension is not installed with TortoiseHg, you have to download it from http://bitbucket.org/parren/hg-pbranch. Be sure to dowload the right one according to the Mercurial version included with TortoiseHg (see the wiki page on the download site). To test the use of this plugin, you can specify it on the Mercurial command line like this:

hg --config "extensions.pbranch=C:\path\to\pbranch.py" pstatus

You may want to add it to your Mercurial.ini or a repository’s hgrc like this:

[extensions]
pbranch = C:\path\to\pbranch.py

If you do this, you can omit the –config command-line option.