Deps Extension

This extension is not distributed with Mercurial.

Author: Aleix Conchillo Flaque, Martin Vejnár

• Repository: http://bitbucket.org/avakar/hgdeps

• Unstable: http://bitbucket.org/avakar/hgdeps-trunk

Overview

This extension is useful when a repository might depend on some versioned external dependencies: other repositories (Mercurial, CVS, Subversion…), files not handled by a SCM tool, etc.

Configuration

To enable this extension, add this to your global .hgrc file (or to your repository .hg/hgrc file):

[extensions]
hgext.deps =
# or, if deps.py is not in the hgext dir:
# deps = /path/to/deps.py

Setting dependencies locations

Before you start using a dependency, you have to define an alias for it. An alias is a symbolic name, which will uniquely identify the dependency. When creating an alias, you'll specify the type of dependency (currenly 'hg' or 'cmd', the former is used for dependencies that are Mercurial repositories, the latter for everything else) and the source URL (or a shell command in case of 'cmd' dependencies).

An alias is created using 'hg depalias' command. As an example, let’s say that our repository depends on two external libraries managed by different SCM tools: ‘libfoo’ managed by Mercurial and ‘libbar’ managed by CVS.

$ hg depalias -t hg libfoo http://path/to/libfoo
$ hg depalias -t cmd libbar "cvs -z3 -d:pserver:anonymous@cvs.server.org:/sources/bar co -r $rev -d $dest bar"

Two aliases have been defined, one for each library, and also the sources where the libraries can be obtained were specified. For 'cmd' dependencies, $rev and $dest are placeholders, which will be replaced during update by the revision number and the full path to the destination directory. You can omit '-t hg' parameter since it is the default.

If you need to change the source location or type of the repository anytime in the future (because the URL of the external repository changed, for example), simply run the command again with new parameters.

Aliases are recorded in .hgdeps file. If the file didn't exist before you ran 'hg depalias', it is automatically created and marked for adding. You should commit the changes after you're finished.

You can list all defined aliases with 'hg depaliases' and remove them with 'hg deprmalias'.

Adding dependencies

Once the location of dependencies is defined, you can use 'hg dep' command to set the revision and destination directory for the dependency. The command will not record anything to .hgdeps, it will merely move the dependency around in your working copy.

$ hg dep libfoo path/to/foo 697673321305

The above line will, if necessary, pull the repository from the remote location up to revision 697673321305. It will then update it to that revision and move the dependency to the specified destination directory. For mercurial repositories, you can use a named tag in place of the hexadecimal changeset identifier.

While not recording anything permanently, the 'hg dep' command will record dependency's location and revision into .hg/depsmanifest file. The list of dependencies and their state is therefore always known and can be retrieved by 'hg depstatus' command.

$ hg depst
A libfoo path/to/foo 697673321305

The 'hg depstatus' command works similarly to 'hg status'. The 'A' at the beginning of the line signifies, that in the parent changeset, the dependency was not assigned to any directory (but now it is).

Committing dependency lists

A particular state of dependencies (i.e. their revision and location) is called a dependency list. Once you've moved the dependencies to their proper place, updated your code to use them and committed your changes, you can associate this last commit with the current dependency list. For that purpose, use 'hg depcommit' command.

$ hg depci

The dependency list will by recorded in .hgdeps file and automatically committed. Remember that the dependency list is associated with the previous revision. Think of the command the same way you think of 'hg tag'.

You can safely run 'hg depci' after every commit. The command will do nothing if there was no change to the dependency list.

Updating dependencies

If you update your working copy to an older revision or you've just pulled a fresh copy from a remote repository, your dependencies will be out of sync. The 'hg depupdate' command will search the .hgdeps file and update all dependencies according to the appropriate dependency list, as if by using the 'hg dep' command.

$ hg depup

If, for some reason, you wish to apply a dependency list associated with a different revision, specify the name of this revision as a parameter to 'hg depupdate'.

Status of the dependencies

The 'hg depstatus' command was already mentioned. It will display the changes to the dependency list between the last revision and the current working copy. The status codes are similar to those used by 'hg status': 'A' for new dependencies, 'R' for removed ones, 'M' for dependencies that were updated to a different revision or moved to another destination directory.

$ hg -v depst
  libfoo path/to/libfoo 697673321305
$ hg dep libfoo path/to/foo d47d5b850da1
$ hg depst
M libfoo path/to/libfoo d47d5b850da1 (path/to/libfoo 697673321305)
$ hg depci
$ hg -v depst
  libfoo path/to/libfoo d47d5b850da1

Note, that in case of 'cmd' dependencies, if you update the dependency to another revision without using 'hg dep' command, neither 'hg depstatus' nor 'hg depcommit' will detect this change. For 'hg' dependencies, current revision is detected correctly.

Removing dependencies

Commands 'hg depremove' and 'hg deppurge' will remove a dependency from your working copy. If you run 'hg depstatus', this dependency will be marked with 'R'. The difference between the two commands is that 'hg deppurge' will physically erase the dependency directory from your harddisk, whereas 'hg depremove' will only move it to .hg/deps directory, from where it can be quickly retrieved by 'hg dep' command (without a need for pull from source).

Format of .hgdeps file

The .hgdeps file is a text file consisting of several sections. Each section represents one dependency list and is named after the changeset it is associated with. There is also a special section called 'aliases', in which alias definitions are stored. Otherwise the format is pretty self-explanatory.

[aliases]
libfoo hg http://path/to/libfoo
libbar cmd "cvs -z3 -d:pserver:anonymous@cvs.server.org:/sources/bar co -r $rev -d $dest bar"

[c1d2ab11121e30a80d4703969b81d3db8be4ac0d]
6976733213056a95ab3395fb4663c10987606814 libfoo path/to/foo

[7220338eb0ac16d61ac78d42e87199fd989ca8d4]
d47d5b850da19ed30d417c197b96014c0be35517 libfoo path/to/foo

---

CategoryExtensionsByOthers