1. Brian Mearns
  2. hgcfg


Clone wiki

hgcfg / Config

Configuration values for the hgcfg extension




The only configuration option currently supported by the extension is hgcfg.delete_on_replace. If set, this option should be a boolean value indicating whether or not to delete the previous value when modifying a key in a config file using the hg cfg command.

The default value for this option is false, in which case lines in the modified config file will not be removed, they will be commented out by inserting a ; in front of them.

For instance, if the config file looks like this:

username = bmearns

And I issue the following command with delete_on_replace set to false (or not set at all):

$ hg cfg ui.username maytag

Then the config file will be modified to look like this:

username = maytag
;username = bmearns

However, if I had issued the same command with delete_on_replace set to true, the config file would look like this:

username = maytag

Compatibility with config extension

The delete_on_replace option should be placed in the hgcfg section of the config file, like this:

delete_on_replace = True

However, for backwards compatibility with the older config extension, if no delete_on_replace key is found in any hgcfg section, then the extension will fall back to looking in the config section (i.e., config.delete_on_replace). If the key is not found in either section, the default value is false.

Note that any occurrence of the hgcfg.delete_on_replace key will override any occurrence of the config.delete_on_replace key, even if the former is in the global scope and the latter is in the local scope. The extension will only fall back to looking in the config section if the option was not found in the hgcfg section of any file.


This extension produces output which is compatible with the built-in color extension. It comes with some default styles for various types of output, but you can change the styles in your config file. The default styles would look like this:

hgcfg.section                  =   cyan

hgcfg.file.global              =   red
hgcfg.file.global.missing      =   red 
hgcfg.file.global.writeable    =   red bold
hgcfg.file.global.readonly     =   red

hgcfg.file.user                =   yellow
hgcfg.file.user.missing        =   yellow 
hgcfg.file.user.writeable      =   yellow bold
hgcfg.file.user.readonly       =   yellow

hgcfg.file.local               =   green
hgcfg.file.local.missing       =   green 
hgcfg.file.local.writeable     =   green bold
hgcfg.file.local.readonly      =   green

hgcfg.scope.global             =   red bold
hgcfg.scope.user               =   yellow bold
hgcfg.scope.local              =   green bold

hgcfg.item.key                 =   none
hgcfg.item.sep                 =   none
hgcfg.item.value               =   none
hgcfg.item.value.selected      =   bold

hgcfg.keyname                  =   bold

Sections names

The color.hgcfg.section key is applied when printing the name of a section for the hg cfg command, for instance [ui] or [paths] or [color].

File names

All of the color.hgcfg.file.* keys refer to the printing of a file-system path for a configuration file. These are used for hg listcfgs and several variants of hg cfg (especially when the --verbose flag is given).

The styles are broken down first by the scope of the file: local, user, and global. The default coloring scheme uses red for global, yellow for user, and green for local (think of them as visual warnings: the higher the scope the more cautious you should be about editing them).

The hg cfg command stops at the scope, so it uses color.hgcfg.file.global, color.hgcfg.file.user, and color.hgcfg.file.local when printing file paths.

However, the hg listcfgs command further refines the styles by the status of the file: missing indicates that the file is not present on the filesystem, readonly is for files that are present but cannot be written by the current user, and writeable is files which are present and can be written by the current user. The default coloring scheme uses the same style for all of these (and the same for the unqualified styles used by the hg cfg command), except that writeable files are made bold to highlight that they can be edited.


Every config file is defined as having global, user, or local scope. Global means the configuration in the file is applied to all users and repositories on the system, user means it applies to all operations by the current system user, and local means it applies to operations only on the current repository.

In certain uses of the hg cfg command, the scope of a file is printed. Whenever this is done, the scope is highlighted with the appropriate one of the following styles: color.hgcfg.scope.global, color.hgcfg.scope.user, or color.hgcfg.scope.local

In the default coloring scheme, the scope styles use the same colors as the corresponding file styles described above (red, yellow, and green for global, user, and local, respectively), however the scope styles are also bold.

Configuration items

When listing configuration keys or their values, the color.hgcfg.item.* styles are used. These apply only to the hg cfg command, when querying all the items in a section, or when querying the values for a specific key (i.e., hg cfg SECTION or hg cfg SECTION.KEY).

When querying all items in section, the name of the key, a separator (i.e., =), and the value of the key are printed for each item. The styles applied to each of these pieces of data are color.hgcfg.item.key, color.hgcfg.item.sep, and color.hgcfg.item.value, respectively. For the currently active value of any given key, the value is styled with color.hgcfg.item.value.selected, but the key and separator still use the same styles.

The default color scheme does not apply any styling to any of the color.hgcfg.item.* keys, except for color.hgcfg.item.value.selected, which is styled as bold.

When querying the values for a specific key, only the value is printed for each item. This is styled with color.hgcfg.item.value or color.hgcfg.item.value.selected as appropriate.

In addition, when querying the values for a specific key using the --verbose option (e.g., hg cfg ui.username --verbose), The fully qualified keyname (e.g., ui.username) is printed prior to all the values, and is styled according to color.hgcfg.keyname. The default style for this key is simply bold.