## page was renamed from SubpathsExtension
== projrc ==
'''This extension is not distributed with Mercurial.'''

''Author: MartinGeisler''

''Maintainer: AngelEzquerra''

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:

 1. System configuration files (''`/etc/mercurial/hgrc`'', ''`C:\mercurial\mercurial.ini`'' and friends)
 1. Project specific configuration (''`.hg/projrc`'')
 1. User configuration files (''`$HOME/.hgrc`'', ''`%HOME%\.hgrc`'', and ''`%HOME%\mercurial.ini`'')
 1. 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 ===
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.

----
''' CategoryExtensionsByOthers '''