|
Size: 3813
Comment:
|
Size: 6989
Comment: The page now describes the improved deps extension.
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 5: | Line 5: |
| ''Author: Aleix Conchillo Flaque'' | ''Author: Aleix Conchillo Flaque, Martin Vejnár'' |
| Line 7: | Line 7: |
| Download site: http://hg.hacks-galore.org/aleix/hgdeps | Download site: http://ratatanek.cz/hg/hgdeps |
| Line 11: | Line 11: |
| 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 or some other dependencies. | 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. |
| Line 24: | Line 25: |
| In order to define external dependencies, you need to add a section [deps] in your repository .hg/hgrc file (or in the global .hgrc) where you will define how to find them. 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. {{{ [deps] aliases = libfoo, libbar alias.libfoo = /path/to/libfoo alias.libbar = :pserver:anonymous@cvs.server.org:/sources/bar alias.libbar.command = cvs -z3 -d$source co -r $rev -d $dest bar |
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" |
| Line 32: | Line 39: |
| Two aliases have been defined, one for each library, and also the sources where the libraries can be obtained. ‘libbar’ has two options: the library location and the CVS command to use in order to get the library. For ‘libfoo’ only a path to the Mercurial repository has been specified. $rev, $source, and $dest are substitution placeholders and will be explained later. | 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'. |
| Line 36: | Line 59: |
| Once the location of the depedencies have been defined, dependency lists can be created. A depedency list has an associated name. Following the example above, two depedency lists will be created, one for version 0.9.1 of our repository and another for version 1.0. 0.9.1 and 1.0 will be used as the name of the lists.{{{ $ hg deps -a libfoo -r 3a9b061bada1 -d lib/foo 0.9.1 $ hg deps -a libbar -r v0r7_8 -d lib/bar 0.9.1 |
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. |
| Line 40: | Line 71: |
| $ hg deps -a libfoo -r f24139319bdb -d lib/foo 1.0 $ hg deps -a libbar -r v0r8_0 -d lib/bar 1.0 |
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 |
| Line 44: | Line 93: |
| The .hgdeps file will look like this: {{{ [1.0] f24139319bdb libfoo lib/foo v0r8_0 libbar lib/bar |
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'. |
| Line 49: | Line 97: |
| [0.9.1] 3a9b061bada1 libfoo lib/foo v0r7_8 libbar lib/bar |
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 |
| Line 54: | Line 111: |
| A dependency is defined by three fields: a revision name, the alias of the external dependency and a destination directory. The alias must be one of the aliases defined in the [deps] section (see above). The revision name will be substituted for the placeholder $rev also seen before. For Mercurial, the revision name will just be a Mercurial revision of the external repository. Finally, the destination directory will be substituted for $dest. | 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'. |
| Line 56: | Line 115: |
| === Cloning dependencies === | === Status of the dependencies === |
| Line 58: | Line 117: |
| Now that dependency lists are created, the next step is to download (clone) them. So, if we want the dependencies for 1.0, we just type:{{{ $ hg depsclone 1.0 |
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 |
| Line 62: | Line 134: |
| Note, that if you create the dependencies sometime after your project has started, you will probably have some already defined tags. So, if you add dependencies for an old version and someone wants to obtain that version and its dependencies, she will need to obtain the dependencies first and then update to the old version, that is:{{{ $ hg clone http://hg.server.com/project $ hg depsclone 0.9.1 $ hg update 0.9.1 |
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 |
| Line 67: | Line 167: |
This is the same as if you create Mercurial tags for old revisions, the ''.hgtags'' will only exist in newer versions, as well as the ''.hgdeps'' file.{{{ # This is a common error $ hg clone -r 0.9.1 http://hg.server.com/project $ hg depsclone 0.9.1 <----- fails: .hgdeps did not exist in 0.9.1 }}} |
Deps Extension
This extension is not distributed with Mercurial.
Author: Aleix Conchillo Flaque, Martin Vejnár
Download site: http://ratatanek.cz/hg/hgdeps
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