Diff for "ProjrcExtension"

projrc

This extension is not distributed with Mercurial.

Author: MartinGeisler

Download site: 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 loads them after the system settings but before the user settings. In particular, the system files are load in the following order:

1. System configuration files (/etc/mercurial/hgrc, C:\mercurial\mercurial.ini and friends)

2. Project specific configuration (.hg/projrc)

3. User configuration files ($HOME/.hgrc, %HOME%\.hgrc, and %HOME%\mercurial.ini)

4. 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 loads the .hg/projrc file.

Configuration

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

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

Enabling the extension will make mercurial look for and parse any projrc file found on a repository .hg folder. However, it will not make mercurial transfer that file when cloning or update it when pulling from a server that has a projrc file.

For security reasons the user must explicitly whitelist the repositories from which it wants to get the projrc file, and it must also select which configuration keys it must get from the remote projrc files. This is necessary to avoid allowing a malicious user to create a projrc file that enables hooks or extensions that may execute arbitrary code on the user's local machine.

this file when is not enough to get the .your .hgrc to enable the extension by adding following lines:

in order to actually enable the extension you must configure it to select the servers and the configuration keys that must be received from those servers. This is done by adding a "[projrc]" section to one of the hgrc files on your machine (i.e. to one of your mercurial system configuration files, to your user configuration files or to your repository specific configuration file). In that "[projrc]" section configuring the following configuration keys: servers, confirm, include and exclude.

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 must be pulled. This setting is a comma separated list of glob patterns matching the server names of the servers that the projrc file must 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 match 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 on 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 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 must 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 must 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 opposity effect. It sets an "exclude list" of settings that must 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)

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).

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 = *

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 no server unless the user explicitly configures the projrc.servers and the projrc.include or the projrc.exclude keys in one of its local.

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

However, if the user sets these configuration settings locally, mercurial will get 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

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 loads the .hg/projrc file.

CategoryExtensionsByOthers