ProjrcExtension - Mercurial

projrc

This extension is not distributed with Mercurial.

Repository: http://bitbucket.org/aragost/projrc

Overview

This extension makes Mercurial look for and parse .hg/projrc for additional configuration settings. The file is transferred on clone and on pull (but never on push), after confirmation by the user, from a list of servers that must be configured by the user. For security reasons the user must also select which projrc configuration settings will be transferred (i.e. no settings are transferred from any servers by default). The user can also configure the extension to automatically accept all changes to the .hg/projrc file.

This is useful for centralized setups where you want to distribute configuration settings to all repositories with a minimum amount of setup. In particular, it can be used to implement the second part of the SubrepoRemappingPlan.

Load Order

The settings in the .hg/projrc file are meant to be used as additional system settings, which means that the extension tries to load them after the system settings but before the user settings. In particular, the system files are loaded in the following order:

System configuration files (/etc/mercurial/hgrc, C:\mercurial\mercurial.ini and friends)
Project specific configuration (.hg/projrc)
User configuration files ($HOME/.hgrc, %HOME%\.hgrc, and %HOME%\mercurial.ini)
Repository specific configuration (.hg/hgrc)

This is so that users can disable extensions loaded in the .hg/projrc file.

Caveats

While you can enable extensions in the .hg/projrc file, you cannot disable extensions with it. This is because Mercurial enables the extensions loaded from the normal configuration files before projrc gets a chance to load the .hg/projrc file.

Configuration

Configure your .hgrc to enable the extension by adding the following lines:

[extensions]
projrc = path/to/projrc/projrc.py

You must enable the extension on the client and on the server machines, unless you are accessing the server repository through a shared drive (in which case there is no server).

Enabling the extension will make mercurial look for and parse any projrc file found in a repository's .hg folder. However, it will not make mercurial transfer that file when cloning or updating it when pulling from a server that has a projrc file (and which has the extension enabled).

For security reasons the user must explicitly whitelist the repositories from which they want to get the projrc file, and they must also select which configuration keys they get from the remote projrc files. (This is necessary to prevent a malicious user from creating a projrc file that enables hooks or extensions that may execute arbitrary code on the user's local machine.)

Thus, in order to actually enable the transfer of projrc files you must configure it to select the servers and the configuration keys that will be received from those servers. This configuration is done by adding a "[projrc]" section to one of the relevant hgrc files on your machine. In that "[projrc]" section you can setup the extension via the following configuration keys: servers, confirm, include, exclude and updateonincoming.

For example:

[projrc]
servers = http://mycentralserver/*, localhost
include = *
confirm = False

For more examples see the "Configuration Examples" section below.

servers:

The "projrc.servers" setting lets you control from which servers the projrc file will be pulled. This setting is a comma separated list of glob patterns matching the server names of the servers that the projrc file will be pulled from.

Unless the "projrc.servers" key is set, the projrc file will not be pulled from any server.

To pull the projrc file from all servers, you can set the "projrc.servers" key to "*" (without the quotes).

To pull the projrc file from any repo hosted on server "http://example.com", set the "projrc.servers" key to "http://example.com/*" (without the quotes). Note the trailing "*"!

Note that the server pattern matcher considers forward and backward slashes as different characters.

The patterns in the server list are "expanded" using the local mercurial "paths" configuration. That is, before matching them against the pull or clone source, they will be compared to the repository "paths" that are defined in the "[paths]" section of the local hgrc files (such as default , default-push, or any other such path). If they match, the pull source will be matched against the corresponding path, not against the actual path name.

The path name expansion is useful if you want to allow the transfer of projrc files from clones of clones. Simply add "default" to your server list and the extension will always update the projrc file when pulling from the default repository source. (Note that currently you will not get the projrc file when cloning. Instead you'll get it when you first pull into the clone. This is a known issue.)

There is an additional "special server" that you can add to your server list, which is "localhost". If you add localhost to the server list, you will always get the projrc file when cloning or pulling from any local repo (where a "local repo" is one that is on the local machine, whether it is accessed directly through the file system or through http, https or ssh access to the localhost)

include:

The "projrc.include" configuration key lets you control which sections and which keys will be accepted from the remote projrc files. The "projrc.include" key is a comma separated list of glob patterns that match the section or key names that will be included. Keys names must be specified with their section name followed by a '.' followed by the key name (e.g. "diff.git").

To allow all sections and all keys you can set the "projrc.include" key to "*" (without the quotes).

Using globs it would be possible to receive all the authorization keys for the bitbucket.com server, for example, by adding "auth.bitbucket.com.*" to the projrc.include configuration key.

exclude:

The "projrc.exclude" setting is similar to the "projrc.include" setting but it has the opposite effect. It sets an "exclude list" of settings that will not be transferred from the common projrc files.

The exclude list has the same syntax as the include list. If an exclusion list is set but the inclusion list is empty or not set all non excluded keys will be included.

If both an include and an exclude lists are set, and a key matches both the include and the exclude list, priority is given to the most explicit key match, in the following order:

full key, exact matches are considered the most explicit (e.g. "ui.merge");
pattern (glob) matches are considered next (e.g. "auth.bitbucket.com.*"), with the longest matching pattern being the most explicit;
section level matches (e.g. "ui");
global ("*") matches.

If a key matches both an include and an exclude (glob) pattern of the same length, the key is included (i.e. inclusion takes precedence over exclusion).

confirm:

This configuration setting controls whether the user must confirm the transfer of new projr settings. This happens when the user clones a repository that has a .hg/projrc file or when he pulls from a repository that has a .hg/projrc that is different from his local copy of that file.

Valid values are:

True or always : Always ask for confirmation (this is the default).
first : Ask for confirmation when the projrc file is transferred for the first time (e.g. on clone).
False or never: Never ask for confirmation (accept all projrc changes).

Note that if this key is not set, the user will have to confirm all changes (i.e. always is the default setting). Also note that in addition to True and always you can use any value that mercurial considers True (i.e. 1, yes and on). Idem for False (i.e. you can also use 0, no and off).

Set this key to "False" if you want to automatically accept all changes to the project configuration.

Set this key to "first" if you want to only ask for confirmation when you clone a repo that has a projrc file, or when you pull for the first time from a repo to which a projrc file has been is added.

Note that if you do not confirm the transfer of the new projrc file you will be prompted again when you next pull from the same source (i.e. the extension does not remember your previous answer to the confirmation prompt).

updateonincoming:

This configuration setting controls whether the user will be able to update the local .hg/projrc when it runs the mercurial incoming command.

Valid values are:

False or never : Show whether the remote projrc file has changed, but do not update (nor ask to update) the local projrc file (this is the default).
prompt : Look for changes to the projrc file. If there are changes _always_ show a confirmation prompt asking the user to confirm that it wants to update its local projrc file.
auto : Look for changes to the projrc file. Use the value of the "projrc.confirm" configuration key to determine whether to show a confirmation dialog or not before updating the local projrc file.

Configuration Examples

The following are several configuration examples that will show how to configure this extension.

Pay especial attention to configuration #3 below , which is probably the most useful base configuration on a typical corporate environment:

1. Accept all project configurations from all servers, without confirmation:

The least safe configuration for this extension is one that accepts all project settings from all servers without any confirmation prompt:

[projrc]
servers = *
include = *
confirm = False

2. Accept all project configurations from a central repository server:

Note that with this configuration clones of local clones will _not_ get the projrc file!

[projrc]
servers = http://mycentralserver/*
include = *
confirm = False

3. Accept all project configurations from a central repo and from local repositories:

This is probably the most useful base configuration of this extension. It ensures that you'll only get the projrc file from a central server (e.g. your company's mercurial server) but that you will also propagate it to clones of local clones.

[projrc]
servers = http://mycentralserver/*, localhost
include = *
confirm = False

4. Accept all project configurations from a central repo and from local repositories, but prompt to accept configuration changes:

This is a safer variation of the previous configuration. The difference is that the user will get a confirmation prompt whenever the projrc file changes.

[projrc]
servers = http://mycentralserver/*, localhost
include = *

You can also configure the incoming command to prompt for changes by adding:

updateonincoming = prompt

5. Accept all project configurations from a central repo and from local repositories, but prompt the first time that a projrc file is detected:

This configuration is not as safe as #4, but is a safer than #3.

[projrc]
servers = http://mycentralserver/*, localhost
include = *
confirm = first

6. Accept all project configurations from the default pull sources:

This makes sure that the projrc file is transferred when pulling from the default path, which is usually the one that we cloned from. Note that you won't get the projrc file when cloning. You'll get it when pulling for the first time.

[projrc]
servers = default
include = *
confirm = False

7. Accept all project configurations except the [hooks] section from the default pull sources:

[projrc]
servers = default
exclude = hooks
confirm = False

8. Only get the commit hook from the project configuration file, from the central repository, but prompt to accept configuration changes:

[projrc]
servers = http://mycentralserver/*
include = hooks.commit

Security

This extension is safe by default, since no configuration settings from any .hg/projrc files will be transferred from any server unless the user explicitly configures the projrc.servers and the projrc.include or the projrc.exclude keys in one of their hgrc configuration files.

In addition, the user will always be prompted to confirm any changes to their local copies of the .hg/projrc files unless they change the projrc.confirm setting.

However, if the user sets these configuration settings locally, mercurial will pull these .hg/projrc files. A malicious (or erroneous) .hg/projrc file could configure a hook which could execute any arbitrary code on the local machine. Thus it is recommended to only enable the transfer of remote configurations from trusted locations.

Caveats

CategoryExtensionsByOthers