Using Mercurial Extensions
Expanding the basic functionality of Mercurial with optional extensions.
Contents
- Introduction
- Enabling an extension
- Extensions bundled with Mercurial
-
Extensions provided by others
- Management of branches and patches
- Nested repositories (subrepositories) and multi-repository operations
- Configuration management
- Authentication, access control and logging
- Interoperability with other VCS
- Code inspection and modifications
- Specific to a hosting service
- Specific to an operating system
- Issue tracking
- Code review
- Shortcuts
- Graphical interfaces
- Unclassified
- See also
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
fsmonitor
Integrates the file-monitoring program watchman with Mercurial to produce faster status results.
purge
Purge all files and dirs in the repository that are not being tracked by Mercurial
3.1. Deprecated
/!\ These extensions are deprecated.
3.2. Experimental
/!\ These extensions are experimental.
remotefilelog
Allows clones that leave the majority of file history on the server.
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.
Note that for extensions that were hosted on bitbucket and haven't moved somewhere else, you can find an archive at https://bitbucket-archive.softwareheritage.org
4.1. Management of branches and patches
branchhead
Show head(s) of the branch the working directory or given revision is on
forest
Manage a bunch of mercurial repos as a meta repository, with snapshot support thread
hg-remotebranches
Keeps track of remote branch heads for each entry in [paths] and exposes them as tags.
importfs
Imports a set of files from a given file-system into a Mercurial repository as a changeset
lighttags
Make local tags behave like lightweight tags (shared over clone and pull, not version controlled)
rebaseif
Command that rebases only if there are no conflicts, otherwise does a merge
release
Automatize tasks to deal with release management (tag creation, archiving, ...)
send
Automatic send of bundle containing changesets missing on remote, like darcs send
shared_mq
SharedMQExtension
Allow shared repositories have same MQ queues
versions
Display the version information for Mercurial and all installed extensions.
4.2. Nested repositories (subrepositories) and multi-repository operations
all_dirs
Execute the same Mercurial command in all repositories down directory tree.
4.3. Configuration management
cedit
Command line editor for configuration files, never manually edit hgrc files again
path_pattern
Define [paths] globally in your .hgrc (as patterns), and have them known all your repositories.
reposettings
Allow repo specific configuration from central configuration files
4.4. Authentication, access control and logging
actionlog
Provides hook intended to help keep track of a remote repository's state that multiple people have access to update
defpasswd
Automatically provide credentials (username/passwords) read from a file.
excludechangesets
Exclude "bad" changesets from being re-added to a central repository
hgban
Ban specific changesets from being reintroduced to a repository after being stripped / removed.
hgssoauthentication
Allows you to use single sign-on authenticate with web servers that use NTLM or kerberos authentication.
keyring
Securely save HTTP passwords in os-specific keyring (Gnome Keyring, KWallet, OSXKeyChain, encrypted file)
serverlog
Log server-side events useful for sysadmins to diagnose what Mercurial is doing
sonichg
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
fastimport
Read a git "fast import" stream and turn it into changesets in a Mercurial repository
4.6. Code inspection and modifications
4.7. Specific to a hosting service
4.8. Specific to an operating system
win32chcp
Switches the Windows console into an encoding actually used by Mercurial on output.
win32lfn
Allow manipulating files with names longer than 260 characters on Windows.
4.9. Issue tracking
4.10. Code review
reviewassiatant
Code review tool helps you to create review requests and respond to them without leaving Visual Studio
4.11. Shortcuts
4.12. Graphical interfaces
4.13. Unclassified
Name
Page
Description
caseguard
Prevents users from adding files to a repository if that could cause a CaseFolding collision
checkfiles
Commit hook and command to check for and fix tabs and trailing whitespace
exclude
Exclude some modified files by default (e.g., config files that are always modified)
fixutf8
Fix problems on non-utf8 systems with filenames (Windows never supports utf8 filenames)
hglock-le
Allow users to inform each other in case of parallel file modification in one local repository
hgwebcachingproxy
Caching hgweb proxy, caches and serves pull requests locally, distributes load and gives good bandwidth utilization.
killbom
Remove BOM (byte-order mark) character from files with specified encodings prior to committing
pack
Pack all files involved in the give revision (if your customer does not know what a diff file is)
rsync
Keep your working directory in sync with remote files, that exist outside of the repository
rupdate
Update a remote repository to a specified revision if the remote repository is hosted via ssh
spellcheck
Interactively correct spelling errors in commit messages; also includes a hook to reject changesets with spelling errors in their commit messages
subpaths
Manage subpath remappings using a central file, distributed on clone and pull
talaria
Manage simple hierarchical trees of HTML-documents, such as web-sites, documentation, etc
tfs
Update Team Foundation Server work items when bug ids are referenced in a changeset
timestamp_mod
Automatically Saves and restores file timestamps for all files in the repository.
zipdoc
Version control zipped document formats like docx or odt as uncompressed zip archives to improve delta compression.
5. See also
WritingExtensions and PublishingExtensions for information on creating new extensions
ExtensionsDevel for core developer information about extensions