Using Mercurial Extensions

Expanding the basic functionality of Mercurial with optional extensions.

1. Introduction

Mercurial is designed to offer a small, safe, and easy to use command set which is powerful enough for most users. Advanced users of Mercurial can be aided with the use of Mercurial extensions. Extensions allow the integration of powerful new features directly into the Mercurial core.

<!> Features in extensions may not conform to Mercurial's usual standards for safety, reliability, and ease of use.

Built-in help on extensions is available with 'hg help extensions'. To get help about an enabled extension, run 'hg help <extension-name>'.

Note that Mercurial explicitly does not provide a stable API for extension programmers, so it is up to their respective providers/maintainers to adapt them to API changes.

2. Enabling an extension

To enable the "foo" extension, either shipped with Mercurial or in the Python search path, create an entry for it in your hgrc, like this:

[extensions]
foo =

You may also specify the full path to an extension (which may be either a .py file or a folder containing __init__.py):

[extensions]
myfeature = ~/.hgext/myfeature.py

To get an extension which is not shipped with Mercurial, just download it to any place in your filesystem. In the example above it was downloaded to ~/.hgext/. NB: On Windows, if the path refers to a directory then the trailing backwards slash must currently be omitted due to issue4187.

To explicitly disable an extension enabled in an hgrc of broader scope, prepend its path with !:

[extensions]
# disabling extension bar residing in /path/to/extension/bar.py
bar = !/path/to/extension/bar.py
# ditto, but no path was supplied for extension baz
baz = !

Extensions can often be configured further in an extension specific section in the same configuration file.

3. Extensions bundled with Mercurial

These extensions are maintained by the Mercurial project and are distributed together with Mercurial.

Name

Page

Description

acl

AclExtension

Manage commit access to parts of a repo using control lists

blackbox

BlackboxExtension

Log events to .hg/blackbox.log for post-mortem debugging

bugzilla

BugzillaExtension

Update Bugzilla entries when a bug id is referenced in a changeset

censor

CensorExtension

Erase file content at a given revision

churn

ChurnExtension

Show change statistics for mercurial operations per author

clonebundles

ClonebundlesExtension

Advertise pre-generated bundles to seed clones

color

ColorExtension

Color output for the diff, status and qseries commands

convert

ConvertExtension

Convert repositories from other SCMs into Mercurial

diff-in-diffs

DiffInDiffsExtension

Adds a new command to create the diff of two diffs

eol

EolExtension

Translate line-ending characters between working copy and repository

extdiff

ExtdiffExtension

Compare changes using external programs

factotum

FactotumExtension

HTTP authentication with factotum

fsmonitor

FsMonitorExtension

Integrates the file-monitoring program watchman with Mercurial to produce faster status results.

gpg

GpgExtension

Sign changesets and check signatures using GPG

hgcia

HgciaExtension

Send notifications to CIA

hgk

HgkExtension

Graphical repository and history browser based on gitk

highlight

HighlightExtension

Highlight syntax in the file revision view of hgweb

histedit

HisteditExtension

Edit, fold, drop changesets in the style of git rebase --interactive

keyword

KeywordExtension

Use CVS like keyword expansion in tracked files

largefiles

LargefilesExtension

Track large binary files (new in 2.0)

mq

MqExtension

Mercurial Patch Queues - manage changes as series of patches

notify

NotifyExtension

Send email to subscribed addresses to notify repository changes

pager

PagerExtension

Allows you to choose a pager

patchbomb

PatchbombExtension

Send a collection of changesets as a series of patch emails

purge

PurgeExtension

Purge all files and dirs in the repository that are not being tracked by Mercurial

rebase

RebaseExtension

Move revisions from a point to another

relink

RelinkExtension

Recreates hardlinks between repository clones

schemes

SchemesExtension

Add shortcuts to urls as url schemes

share

ShareExtension

Share repository history between multiple repos

shelve

ShelveExtension

Save and restore changes to the working directory

strip

StripExtension

Strip changesets and their descendants from history

transplant

TransplantExtension

Cherry-picking, rebasing and changeset rewriting

win32mbcs

Win32mbcsExtension

Allow to use shift_jis/big5 filenames on Windows.

zeroconf

ZeroconfExtension

Announce and browse repositories via zeroconf/bonjour

4. Extensions provided by others

These extensions are not distributed together with Mercurial. The Mercurial project provides no guarantees about these and does not maintain or test them.

4.1. Management of branches and patches

attic

AtticExtension

Easily deal with individual patches

bookbinder

bookbinder

Make bookmarks behave like a feature branch (as opposed to a label)

boundmode

BoundModeExtension

Enables a bound mode (commit command auto-pushes)

branchhead

BranchHeadExtension

Show head(s) of the branch the working directory or given revision is on

cedit

CeditExtension

Command line editor for configuration files, never manually edit hgrc files again

changelog

ChangelogExtension

Auto-generate commit message from changelog entry

commits

CommitsExtension

Commit modified files as multiple changesets at once

committer

CommitterExtension

Record the committer when you are not the author of a changeset.

collapse

CollapseExtension

Collapse consecutive changesets into one

easycommit

EasycommitExtension

Command-line GUI for committing changes

easymerge

EasymergeExtension

Command-line GUI for merging

editcommitmsgs

EditcommitmsgsExtension

Change commit messages for all applied mq patches in one go

evolve

EvolveExtension

History rewriting with second-order version control

exportfiles

hgexportfiles

Export all files changed in a revision or revision range to a directory.

foreign

ForeignExtension

Interactively register or delete foreign/unknown files

forest

ForestExtension

Manage a bunch of mercurial repos as a meta repository, with snapshot support thread

flow

FlowExtension

Support for the generalized Driessen's model

hg-remotebranches

hg-remotebranches

Keeps track of remote branch heads for each entry in [paths] and exposes them as tags.

histpush

HistpushExtension

Record locally which revisions have been pushed

importfs

ImportfsExtension

Imports a set of files from a given file-system into a Mercurial repository as a changeset

lighttags

LightTagsExtension

Make local tags behave like lightweight tags (shared over clone and pull, not version controlled)

mbox

MboxExtension

Import patches from unix mailboxes in MQ

mergediff

MergediffExtension

Show only the changes introduced by a merge

mergeutil

MergeUtilExtension

Useful utilities for merging branches

mqcollab

MqCollabExtension

Manage patches in several parallel queues when working with others

mutable-branches

MutableBranches

Rename named branches

nearest

NearestExtension

Display the nearest tag from a given changeset

localbranch

LocalbranchExtension

Create clones inside your working directory

lock

LockExtension

Take locks on resources

patience

PatienceExtension

Generate diffs using Bram Cohen's patience diff algorithm

pbranch

PatchBranchExtension

Collaborative and/or long-term patch development and maintenance

quiet-hg-branch

quiet-hg-branch

Suppress the "did you want a bookmark?" hint for hg branch

rebaseif

RebaseIfExtension

Command that rebases only if there are no conflicts, otherwise does a merge

release

ReleaseExtension

Automatize tasks to deal with release management (tag creation, archiving, ...)

remotenames

remotenames

Track remote bookmarks and branches

send

SendExtension

Automatic send of bundle containing changesets missing on remote, like darcs send

shared_mq

SharedMQExtension

Allow shared repositories have same MQ queues

sync

SyncExtension

Perform pull, update/merge and push in a single click

tasks

TasksExtension

Manage tasks as collections of contiguous changesets

versions

VersionsExtension

Display the version information for Mercurial and all installed extensions.

4.2. Nested repositories (subrepositories)

guestrepo

GuestrepoExtension

Handle nested repositories

hgmod

HgModExtension

Yet another way working with subrepos

hgnested

HgNestedExtension

Manage nested repositories

hg-subtree

HgSubtree

A way to work with subrepositories by storing them inside the repository

multirepo

MultirepoExtension

Allow commands to affect multiple repositories simultaneously

onsub

OnsubExtension

Recursively execute a command in each subrepository

4.3. Configuration management

config

ConfigExtensionCommandLine

Manage config files via command line only

config

ConfigExtension

Manage hgrc files via dialogs and command line

configexpress

ConfigExpressExtension

monitor and enforce client configuration from a server

dynamic_username

DynamicUsernameExtension

Set your username per directory tree.

projrc

ProjrcExtension

Parse project specific config from .hg/projrc

rcpath

RcpathExtension

Displays Mercurial configuration file paths and names

reposettings

ReposettingsExtension

Allow repo specific configuration from central configuration files

4.4. Authentication, access control and logging

actionlog

ActionLogExtension

Provides hook intended to help keep track of a remote repository's state that multiple people have access to update

commitsigs

CommitsigsExtension

Embed GnuPG and OpenSSL signatures directly into changesets

defpasswd

DefpasswdExtension

Automatically provide credentials (username/passwords) read from a file.

excludechangesets

ExcludeChangesetsExtension

Exclude "bad" changesets from being re-added to a central repository

hgban

BanChangesetsExtension

Ban specific changesets from being reintroduced to a repository after being stripped / removed.

hg-kerberos

hg-kerberos

Kerberos authentication extension by Henrik Stuart

hgssoauthentication

hgssoauthentication

Allows you to use single sign-on authenticate with web servers that use NTLM or kerberos authentication.

kerberos

KerberosExtension

Kerberos Authentication over HTTP support

keyring

KeyringExtension

Securely save HTTP passwords in os-specific keyring (Gnome Keyring, KWallet, OSXKeyChain, encrypted file)

nopush

NoPushExtension

Prohibits pushes from predefined local repository directories

pushlog

MozillaPushlogExtension

Tracks who pushed what to a repository

serverlog

ServerlogExtension

Log server-side events useful for sysadmins to diagnose what Mercurial is doing

sonichg

SonicHgExtension

Record pushlog data, web interfaces to view pushlog & shortlog with slider, advanced search for pushlog, new file log page, full side-by-side diffs, regex filter, commit syntax warning and more!

4.5. Interoperability with other VCS

cvscommit

CvscommitExtension

Push changesets to CVS

fastimport

FastImportExtension

Read a git "fast import" stream and turn it into changesets in a Mercurial repository

hg-git

HgGit

Push to and pull from a Git server

hgsubversion

HgSubversion

Use Mercurial as a Subversion client

perfarce

PerfarceExtension

Allow Hg to pull from and push to a Perforce depot

4.6. Specific to a hosting service

bitbucketize

BitBucketizeExtension

Create, modify, or delete BitBucket clone from command line

hg-github

HgGithubExtension

Allow mirroring Mercurial repositories in Bitbucket to Github

4.7. Specific to an operating system

tpager

TpagerExtension

Mercurial pager with color support on Windows

win32chcp

Win32ChCpExtension

Switches the Windows console into an encoding actually used by Mercurial on output.

win32lfn

Win32LongFileNamesExtension

Allow manipulating files with names longer than 260 characters on Windows.

wincolor

WinColorExtension

Support colors on Windows consoles.

4.8. Unclassified

Name

Page

Description

activity

ActivityExtension

Create an image representing the activity of the repository

all_dirs

AllDirsExtension

Execute the same Mercurial command in all repositories down directory tree.

allpaths

AllPathsExtension

Run commands like push on multiple paths

artemis

ArtemisExtension

Simple and light-weight issue tracker

automv

AutomvExtension

Automatically detect file renames

autopager

AutopagerExtension

Invoke pager when output is longer than one screen

b

bExtension

Distributed bug tracker based off the lightweight task manager t

bfiles

BfilesExtension

Handle large binary files

bigfiles

BigfilesExtension

Support versions of big files with storage outside hg repo

buglink

BugLinkExtension

Allow to link changesets and Issue IDs

bugtracker

BugtrackerExtension

A tiny distributed bugtracking extension for Mercurial

bundleclone

BundleCloneExtension

Clone using pre-generated bundles

casefold

CaseFoldExtension

Successful unjams case-folding conflicts

caseguard

CaseGuardExtension

Prevents users from adding files to a repository if that could cause a CaseFolding collision

casestop

CasestopExtension

Stops case-folding conflicts on commit

chart

ChartExtension

Display activity graphs (see also ActivityExtension and ChurnExtension)

checkfiles

CheckFilesExtension

Commit hook and command to check for and fix tabs and trailing whitespace

checkmeta

CheckMetaExtension

Enforces configurable file characteristics like file encoding.

cifiles

CifilesExtension

Print the names of all checked-in files

cloc

ClocExtension

Count lines of source code

codesmell

CodesmellExtension

Ask before committing "smelly" changes

contains

ContainsExtension

Test whether a changset is contained in a branch

crecord

CrecordExtension

Select graphically which files/hunk/lines to commit

cutehg

CuteHgExtension

A growing set of easy to install and use dialogs for mercurial commands

deps

DepsExtension

Create and manage versioned repository dependencies

digest

DigestExtension

Create and use small digest files for outgoing/bundle

dotlog

DotLogExtension

Yet Another DOT grapher

dynapath

dynapath

Dynamically rewrite paths to use local mirrors based on current local IP.

exclude

ExcludeExtension

Exclude some modified files by default (e.g., config files that are always modified)

filereview

FileReviewExtension

Perform code review for any project using mercurial

fixcase

FixcaseExtension

Fix problems where an external tool has changed the case of a filename

fixrenames

FixrenamesExtension

Replay old history to add rename information

fixutf8

FixUtf8Extension

Fix problems on non-utf8 systems with filenames (Windows never supports utf8 filenames)

ftp

FTPExtension

Manage uploaded snapshots on FTP server

graphviz

GraphvizExtension

Generate DOT language source to visualize changeset tree

group

GroupExtension

Allow to visually regroup a set of changesets

grepfile

GrepfileExtension

Search files for a regular expression

hgbb

BitbucketExtension

Several helpers for working with bitbucket.org repositories

hgexternals

HgExternals

Pull external repositories into a Mercurial repository

hgext.markdown

MarkdownExtension

Markdown Extension for hgweb

hgflowdock

FlowdockExtension

Send notifications to flowdock.com

hglist

hglist

An ls command for Mercurial

hglock-le

HgLockLEExtension

Allow users to inform each other in case of parallel file modification in one local repository

hgopenurl

HgOpenURLExtension

Quickly show repository URLs in the browser

hgreview

HgReviewExtension

Upload / refresh and fetch patches from rietveld codereview instances

hgsftp

hgsftp

Use Mercurial over SFTP

hgsite

HgSiteExtension

Serve a web site straight out of a Mercurial repository

hgsql

hgsqlExtension

Allow server multi-mastering by using a MySQL backend.

hgview

hgview

Tool for visually navigating a repository history and comparing multiple revisions

hg-textauth

hg-textauth

Plaintext file authentication

hgtrac

HgTracExtension

Mercurial/Trac Integration Hook (pre/post hooks for Trac/Mercurial)

hgwebcachingproxy

hgwebcachingproxy

Caching hgweb proxy, caches and serves pull requests locally, distributes load and gives good bandwidth utilization.

hgxmpp

HgJabberExtension

Mercurial Jabber Notification Hook (pre/post hooks for Jabber/Mercurial)

hotfiles

HotFilesExtension

Designates the files the most susceptible to contain issues

info

InfoExtension

Display basic information about a repository

infocalypse

Infocalypse

Share code efficiently, decentrally, anonymous and encrypted over Freenet

killbom

KillBomExtension

Remove BOM (byte-order mark) character from files with specified encodings prior to committing

makewritable

MakewritableExtension

Interactively removes read-only flags from files

moinport

MoinportExtension

Fetch changes from MoinMoin Wiki

narrowhg

narrowhg

Download only part of the history, see NarrowClonePlan

pack

mercurial-pack-extension

Pack all files involved in the give revision (if your customer does not know what a diff file is)

path_pattern

PathPatternExtension

Define [paths] globally in your .hgrc, and have them known all your repositories.

paste

PasteExtension

Paste changes to pastebin

pastebin

PastebinExtension

Paste changes to public and private pastebins

prompt

PromptExtension

Put information about the current repository into a shell prompt

publishall

PublishAllExtension

Publish to all your set repositories (ie: paths)

punchcard

PunchcardExtension

Generate a "punch card" graph of your commit habits

reviewboard

ReviewboardExtension

Post changesets for review to a Review Board server

qct

QctExtension

Provide access to the Qct commit tool

qtimes

QtimesExtension

Save or restore modification times of files affected by patch queue

qup

QupExtension

Move MQ patches to top of unapplied part of series

rdiff

RdiffExtension

Allow diff to work against remote repositories

remotefilelog

RemotefilelogExtension

Allows clones that leave the majority of file history on the server.

reviewassiatant

CodeReviewExtension

Code review tool helps you to create review requests and respond to them without leaving Visual Studio

rsync

RemoteSyncExtension

Keep your working directory in sync with remote files, that exist outside of the repository

rupdate

RemoteUpdateExtension

Update a remote repository to a specified revision if the remote repository is hosted via ssh

snap

SnapExtension

Version (big) file snapshots with storage outside a Mercurial repository

socks_proxy

socks_proxy

SOCKS proxy support

softrebase

SoftRebaseExtension

Turn possibly complicated rebase calls into multiple simpler ones

spellcheck

SpellcheckExtension

Interactively correct spelling errors in commit messages; also includes a hook to reject changesets with spelling errors in their commit messages

subpaths

SubpathsExtension

Manage subpath remappings using a central file, distributed on clone and pull

talaria

TalariaExtension

Manage simple hierarchical trees of HTML-documents, such as web-sites, documentation, etc

terse-status

terse-status

Makes 'hg status' show ? foo/ when all files inside foo are untracked

textful

TextfulExtension

Convert binary file to text or handle character encoding when displaying

tfs

TfsExtension

Update Team Foundation Server work items when bug ids are referenced in a changeset

timestamp

TimestampExtension

Saves and restores file timestamps

timestamp_mod

TimestampModExtension

Automatically Saves and restores file timestamps for all files in the repository.

timetracker

timetracker

Tracks the time spent on a project

untouch

UntouchExtension

Save or restore modification times of files

update_version

UpdateVersionExtension

Automatically update version numbers in code while tagging.

webuserdir

WebUserDirExtension

Host users' repositories under /~username/ on hgwebdir

zipdoc

ZipdocExtension

Version control zipped document formats like docx or odt as uncompressed zip archives to improve delta compression.

5. See also


CategoryBundledExtension CategoryExtensionsByOthers

French, Japanese, German

UsingExtensions (last edited 2018-01-22 20:18:50 by MarioCastelánCastro)