hgremap extension

This extension lets you define a set of "source", version controlled files or folders that will be "mapped" (i.e. copied) into some other non version controlled "target" files or folders.

The mapping occurs when hg update is run. By default files will only by mapped if the target files or folder do not already exist. However, it is possible to configure the extension to overwrite existing files as well.

A primary use case for this extension is to make it easier to version control configuration files. It is normally not a good idea to track configuration files, particularly if their contents may change from one repository or one user to the other. A common solution to this problem is to commit a "template" file (with a different filename) instead, and let the user copy that template file to the actual configuration file location. This extension automates that process.


.hgremap file

In order to use this extension you must enable it and then create an .hgremap file, which must be placed at the root of your repository. Each line in the .hgremap file configures one mapping. Each mapping has 3 fields, TARGET, SOURCE and ACTION, separated by "|". That is:


TARGET and SOURCE are file or folder paths. TARGET Folder paths must end with a slash (i.e. "/" or "\")

Valid actions are: copy, move, delete Actions can have modifyiers. There is currently a single valid modifier: overwrite

ACTIONS are optional. The default action is "copy"

For example:

empty_folder/ target_folder/ | test_folder_source target_file_1.txt | source_files\source_file_in_hg.txt

Additional settings

You can customize the behavior of the extension by setting the following configuration keys on the [hgremap] section of your mercurial config files:

  • overwrite:
  • false: The default. Do not overwrite existing target files.
  • prompt: Ask for confirmation before overwriting existing files
  • true: Automatically overwrite existing files

  • continue_if_error: If True, ignore all errors. If False, any error will abort the current operation (update or commit)

  • remapback: If True, changes to the target files will be automatically copied back into the source files before any commit operation.

Basic usage

Once the extension is enabled, the .hgremap file is configured and (optionally) the hremap configuration set, everything should be automatic. Files should be automatically mapped during updates and (depending on the configuration) mapped back before commits.

You can also execute the remap the remapback operations at any time through the hg remap and hg remapback commands.