Mercurial Path Pattern Extension
Project description
Don’t repeat yourself defining [paths] over many repositories, specify the general rule once in ~/.hgrc.
Path Pattern is a Mercurial extension used to define default remote path aliases. You may find it helpful if you maintain consistently layed out repository trees on a few machines.
Path Pattern mostly works behind the courtains, making standard commands like hg pull, hg push, and hg incoming aware of extra paths. Still, it implements some commands, in particular hg cloneto «path-alias» (clone to remote address specified by short name).
1 Using path patterns
Install the extension as described below.
1.1 Simple example
Write in your ~/.hgrc:
[extensions] mercurial_path_pattern = [path_pattern] lagrange.local = ~/devel/{repo} lagrange.remote = ssh://johny@lagrange.mekk.net/sources/{repo} bbssh.local = ~/devel/public/{below} bbssh.remote = ssh://hg@bitbucket.org/Johny/{below:/=-}
Imagine ~/devel/personal/blog/drafts and ~/devel/public/pymods/acme are both some mercurial repositories. Then:
cd ~/devel/personal/blog/drafts hg push lagrange # Works, pushes to ssh://johny@lagrange.mekk.net/sources/personal/blog/drafts cd ~/devel/public/pymods/acme hg pull lagrange # Works, pulls from ssh://johny@lagrange.mekk.net/sources/public/pymods/acme hg pull bbssh # Works too, pulls from ssh://hg@bitbucket.org/Johny/pymods-acme
This works in spite of the fact, that those repos lack .hg/hgrc.
For two repositories that’s not very useful, but once you have hundred of them, managing individual .hg/hgrc becomes a hassle (imagine changing lagrange.mekk.net to lagrange.mekk.com everywhere, or maybe adding second remote alias for the new development machine).
1.2 Overriding repository-level paths
By default path patterns have lower priority than per-repository paths, so in case you define lagrange path on repository level, it won’t be overwritten by pattern. You can augment it by adding .enforce:
[path_pattern] lagrange.local = ~/devel/{repo} lagrange.remote = ssh://johny@lagrange.mekk.net/sources/{repo} lagrange.enforce = true
With such config pattern wins against any path from .hg/hgrc (usually it is not recommended but can be handy if you have some broken paths scattered around repositories).
1.3 Reusing the same alias
To (re)use the same alias in a few different locations, use .alias:
[path_pattern] production.local = ~/devel/{repo} production.remote = ssh://www-owner@www.mekk.net/public/{repo} experiment.local = ~/experiments/{repo} experiment.remote = ssh://www-owner@beta.mekk.net/public/{repo} experiment.alias = production
Definitions above let you hg push production not only in ~/devel/website/blog but also in ~/experiments/website/qagame. Whether this is a good idea, is up to you.
2 Clone-supporting commands
2.1 Using cloneto
The cloneto command makes it easier to clone repository to remote url:
hg cloneto lagrange # Equivalent to # hg clone . ssh://johny@lagrange.mekk.net/sources/pymodules/acme # but noticeably shorter
which works both for normal paths and paths derived from patterns, but is especially handy with patterns. In particular, it makes it possible to push newly created repository, for example:
cd ~/devel/libs hg init xyz cd xyz hg cloneto lagrange # Works, creates soures/libs/xyz on johny@lagrange.mekk.net
2.2 Instead of clonefrom
There is no clonefrom command (at least for now), but it is not really needed. The following works (imagine libs/zzz exists on lagrange.mekk.net, but is not yet cloned here):
cd ~/devel/libs hg init zzz cd zzz hg pull lagrange
3 Testing pattern configuration
The standard:
hg paths
command lists paths defined for current repository, after pattern expansion. Use it (in a few different repositories) to verify whether your patterns generate proper paths.
The:
hg list_path_patterns
command prints all patterns found in configuration. Use it to detect typos causing some patterns to be ignored and to check the final result of configuration processing.
4 Pattern syntax
Patterns are defined in [path_pattern] section of mercurial configuration file (typically they are kept in ~/.hgrc, but feel free to define them system-wide).
You may have as many patterns as you like. Example:
[path_pattern] lagrange.local = ~/devel/{repo} lagrange.remote = ssh://johny@lagrange.mekk.net/sources/{repo} euler.local = ~/devel/{repo} euler.remote = ssh://johny@euler.mekk.net/devel/{repo:/=.}/hg wrk.local = ~/work/{what} wrk.remote = https://tim@devel-department.local/{what:/=__:\=__} ugly.local = ~/(topic)/sources/{subpath}/repo ugly.remote = ssh://hg{topic}@devel.local/{topic}/{subpath} cfg.local = ~/.config/upstart cfg.remote = ssh://hgrepos@central.com/configs/riemann/upstart cfg2.local = ~/.local/share/applications cfg2.remote = ssh://hgrepos@central.com/configs/riemann/applications cfg2.alias = cfg
Every pattern is defined by the pair of keys - «alias».local and «alias».remote - or, less frequently, by set of three keys «prefix».local, «prefix».remote, and «prefix».alias (where «prefix» is anything unique).
While processing patterns, the extension matches current repository root path against local pattern, and if it matches, extracts parts marked with markers and fills remote part with them to calculate proper path to use.
The .local part should specify absolute repository path (~ and ~user are allowed). Some part(s) of the path may be replaced with {brace} or (paren) markers:
{brace} matches everything aggressively (to the very end, unless some fixed text follows it),
(paren) is limited to single path item and does not cross / or \\ characters).
Those parts will be extracted from local repository path and available for use in remote path being defined.
Markers are optional, if no marker is used (see cfg above), rule applies to exactly one repository. This may make sense (over defining path in given repo .hg/hgrc) if you prefer to centralize your paths.
The .remote part defines appropriate remote address. This is typical Mercurial remote path, but {marker}’s can be used to refer to values extracted from local path: {sth} is replaced with whatever matched {sth} or (sth) present in local path.
Simple modifications are supported – {sth:x=y} means take whatever was extracted as sth and replace any x with y. This is mostly used to replace / with some other character (in particular {below:/=-} handles BitBucket convention, replacing slashes with minuses).
Replacements can be chained if necessary – {sth:x=y,v=z} means take whatever was extracted as sth, replace any x with y, then replace any v with z, then use the final result.
For example, with definitions above, if you happen to work in repository ~/devel/python/libs/webby, the extension will:
Find that lagrange.local matches and that {repo} is python/libs/webby. Filling lagrange.remote with that value generates ssh://johny@lagrange.mekk.net/sources/python/libs/webby, so finally it will create path alias lagrange=ssh://johny@lagrange.mekk.net/sources/python/libs/webby
Discover that euler.local also matches, and {repo} is again python/libs/webby. After replacing /-s with .-s, that brings alias euler=ssh://johny@euler.mekk.net/devel/python.libs.webby/hg
Ignore remaining patterns as they do not match.
If .alias is defined, value of this item serves as path alias. Otherwise pattern prefix is used as alias. So, with definitions above:
You may issue hg pull lagrange or hg push euler in ~/devel/snippets/js.
You may issue hg push cfg in both ~/.config/upstart and ~/.local/share/applications (in the latter thanks to .alias).
5 Pattern priority
It is possible to write patterns so they conflict (more than one definition of some path exists). While not frequent, such approach has sometimes it’s uses.
Path aliases have the following priority:
enforced patterns (patterns with .enforce set),
per repo aliases (standard [paths] defined in .hg/hgrc),
non-enforced patterns.
So, for example, with:
[path_pattern] acme.local = ~/devel/{repo} acme.remote = ssh://johny@apps.mekk.net/code/{repo} acme.enforce = true acme-alt.local = ~/devel/libs/{repo} acme-alt.remote = ssh://johny@libs.mekk.net/{repo} acme-alt.alias = acme
(both patterns define the same alias acme) executing hg push acme in ~/devel/libs/calc will push to ssh://johny@apps.mekk.net/code/libs/calc as enforced pattern wins over non-enforced one. The same will happen even if acme is defined in per-repository .hg/hgrc (among standard [paths]).
If more than one pattern of the same strength matches, extension tries it’s best to pick one with more specific local path, for example if we drop acme.enforce from the example above (or if we add acme-alt.enforce), executing hg push acme in ~/devel/libs/calc will push to ssh://johny@libs.mekk.net/calc as more specific pattern wins.
6 Tips and tricks
6.1 default as path pattern
You can define default via path pattern if you wish:
[path_pattern] default_hobby.local = ~/hobby/{repo} default_hobby.remote = ssh://hg@bitbucket.org/Johny/{below:/=-} default_hobby.alias = default default_wrk.local = ~/work/{what} default_wrk.remote = https://tim@devel-department.local/{what} default_wrk.alias = default
(here in ~/hobby I push to bitbucket by default, but in ~/work to department server).
6.2 Special treatment of specific repositories
It happens that some repository (or a few) does not match the general rule. In such a case, one can simply overwrite given alias on repository level, or use pattern priority.
My real example is Keyring Extension repository. While I generally use - as path separator (so Path Pattern is located at /Mekk/mercurial-path_pattern and Dynamic Username at /Mekk/mercurial-dynamic_username), keyring repo predates this convention and is named /Mekk/mercurial_keyring. So I solve this by:
[path_pattern] # By default bitbucket mirrors my dir structure replacing / with - bbssh.local = ~/devel/{below} bbssh.remote = ssh://hg@bitbucket.org/Mekk/{below:/=-} # … but there are overrides bbssh_keyring.local = ~/devel/mercurial/keyring bbssh_keyring.remote = ssh://hg@bitbucket.org/Mekk/mercurial_keyring bbssh_keyring.alias = bbssh
Of course I could achieve the same by defining bbssh among [paths] in ~/devel/mercurial/keyring/.hg/hgrc, but pattern technique have some advantages:
as I share and sync snippet of my ~/.hgrc between machines, this definition automatically propagates everywhere, and I don’t need to remember about adding path to new clone,
it leaves all paths in one place where I can review them all and fix if necessary,
it can be expanded to whole subtree if necessary.
6.3 Keeping non-standard remote paths as patterns
The same trick can be used for maintaining list of remotes. For example here is my way to have hg pull official handy in various tracked repositories:
[path_pattern] official_hgstable.local = ~/tracked/hg-stable official_hgstable.remote = http://selenic.com/repo/hg-stable official_hgstable.alias = official official_thg.local = ~/tracked/tortoise-hg official_thg.remote = http://bitbucket.org/tortoisehg/thg/ official_thg.alias = official # …
Again, of course I could enter those paths directly inside .hg/hgrc, but definitions above can be synced between machines and survive if I discard repo in charge for some time.
7 Installation
7.1 Linux/Unix (from PyPI)
If you have working pip or easy_install:
pip install --user mercurial_path_pattern
or maybe:
sudo pip install mercurial_path_pattern
(or use easy_install instead of pip). Then activate by:
[extensions] mercurial_path_pattern =
To upgrade, repeat the same command with --upgrade option, for example:
pip install --user --upgrade mercurial_path_pattern
7.2 Linux/Unix (from source)
If you don’t have pip, or wish to follow development more closely:
clone both this repository and mercurial_extension_utils and put them in the same directory, for example:
cd ~/sources hg clone https://bitbucket.org/Mekk/mercurial-extension_utils/ hg clone https://bitbucket.org/Mekk/mercurial-path_pattern/
update to newest tags,
activate by:
[extensions] mercurial_path_pattern = ~/sources/mercurial-path_pattern/mercurial_path_pattern.py
To upgrade, pull and update.
Note that directory names matter. See mercurial_extension_utils for longer description of this kind of installation.
7.3 Windows
If you have any Python installed, you may install with pip:
pip install mercurial_path_pattern
Still, as Mercurial (whether taken from TortoiseHg, or own package) uses it’s own bundled Python, you must activate by specifying the path:
[extensions] mercurial_path_pattern = C:/Python27/Lib/site-packages/mercurial_path_pattern.py ;; Or wherever pip installed it
To upgrade to new version:
pip --upgrade mercurial_path_pattern
If you don’t have any Python, clone repositories:
cd c:\hgplugins hg clone https://bitbucket.org/Mekk/mercurial-extension_utils/ hg clone https://bitbucket.org/Mekk/mercurial-path_pattern/
update to tagged versions and activate by path:
[extensions] mercurial_path_pattern = C:/hgplugins/mercurial-path_pattern/mercurial_path_pattern.py ;; Or wherever you cloned
See mercurial_extension_utils documentation for more details on Windows installation.
9 History
See HISTORY.txt
10 Development, bug reports, enhancement suggestions
Development is tracked on BitBucket, see http://bitbucket.org/Mekk/mercurial-path_pattern/
Use BitBucket issue tracker for bug reports and enhancement suggestions.
11 Additional notes
Information about this extension is also available on Mercurial Wiki: http://mercurial.selenic.com/wiki/PathPatternExtension
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for mercurial_path_pattern-1.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | dcc845f6a5fce6628e512c6a478de8525d6d75b2affe30181d92a5a7893c72e7 |
|
MD5 | 87f528ad43644ae9aa52f49ce0ba7688 |
|
BLAKE2b-256 | b83a35d75e5cd52a89cd6b8d659effe48772010f6b692b28a03053cd71630c72 |