|
Size: 2205
Comment: Update page to state that repo version of forest is not presently functional.
|
Size: 6082
Comment: Extended, explained what I could, left places to fill where I felt lost
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #pragma section-numbers 3 |
|
| Line 12: | Line 14: |
| [[TableOfContents]] |
|
| Line 14: | Line 18: |
| The Forest extension allows operations on trees with nested Mercurial repositories, called forests. | The Forest extension allows operations on trees with nested Mercurial repositories, called forests. Those to some degree correspond to multi-project CVS/Svn/... repositories. |
| Line 16: | Line 20: |
| It provides some additional commands that apply to the forest. These commands are both standard Mercurial commands, such as 'clone' or 'status', that are applied recursively, and commands that involve a snapshot file, to represent the state of a forest at a given time. | The extension change some standard Mercurial commands - like 'clone' or 'status' - so they are applied recursively to the whole forest instead of working for the individual repository. It also defines some new commands: {{{fclone}}}, {{{fpull}}}, {{{fpush}}}, {{{fseed}}}, {{{fsnap}}}, {{{ftrees}}} and {{{fupdate}}}. |
| Line 18: | Line 23: |
| The new commands defined by the extension are: {{{fclone}}}, {{{fpull}}}, {{{fpush}}}, {{{fseed}}}, {{{fsnap}}}, {{{ftrees}}} and {{{fupdate}}} | The forest extension brings one new concept - a ''snapshot file''. This file represents state of a forest at a given time |
| Line 20: | Line 25: |
| === Configuration === | '''ToDo: detailed explanation what exactly is the snapshot file''' === Enabling the extension === |
| Line 39: | Line 47: |
| '''ToDo: does walkhg=true truly mean that .hg is NOT walked? It is crazy....''' | |
| Line 42: | Line 51: |
| To clone a forest: | Below some typical examples of how the extension can be used. |
| Line 44: | Line 53: |
| {{{hg fclone [OPTIONS] SOURCE DESTINATION}}} | ==== Creating a forest from scratch ==== |
| Line 46: | Line 55: |
| To pull/push/update all repos in the forest: | Forest is just a mercurial repository containing some other mercurial repositories. |
| Line 48: | Line 57: |
| {{{hg fpull [OPTIONS] SNAPSHOT-FILE PATH-ALIAS}}} | {{{ mkdir forestdir forestdir/subproject1 forestdir/subproject2 cd forestdir # Initialize mercurial repo for the forest itself hg init # Initialize subproject repos cd subproject1 hg init cd ../subproject2 hg init cd .. }}} |
| Line 50: | Line 70: |
| {{{hg fpush [OPTIONS] SNAPSHOT-FILE PATH-ALIAS}}} | We have a forest containing two subprojects. Of course new subprojects can be added at any time in the same way. |
| Line 52: | Line 72: |
| {{{hg fupdate [OPTIONS] (--tip | SNAPSHOT-FILE)}}} | ==== Creating a forest on top of existing repositories ==== |
| Line 54: | Line 74: |
| To take a snapshot of a forest: | Let's consider more realistic example - we want to bind as forest some already existing repositories. Then there are two options. To create the forest in new location, just initialize repository there and clone subprojects into subdirectories: |
| Line 56: | Line 78: |
| {{{hg fsnap [OPTIONS] [SNAPSHOT-FILE]}}} | {{{ mkdir forestdir cd forestdir hg init # To keep the same name (here - somelib) hg clone <some-location>/somelib # To change name hg clone <some-location>/somelib sublib }}} |
| Line 58: | Line 88: |
| To populate a forest according to a snapshot file: | Instead of cloning, one can just move the directories (this preserves working dir state). |
| Line 60: | Line 90: |
| {{{hg fseed [OPTIONS] SNAPSHOT-FILE [PATH-ALIAS]}}} | One can also build forest in existing directory. Let's say we have mercurial repositories in $HOME/someproject/subproject1 and $HOME/someproject/subproject2. Then bare |
| Line 62: | Line 93: |
| To display the status of the forest: | {{{ cd $HOME/someproject hg init }}} |
| Line 64: | Line 98: |
| {{{hg fstatus [OPTIONS]}}} | creates the forest in $HOME/someproject. |
| Line 66: | Line 100: |
| To list the roots of repositories: | ==== Cloning existing forest ==== |
| Line 68: | Line 102: |
| {{{hg ftrees [OPTIONS]}}} | To clone a forest use {{{fclone}}}. It works just as normal clone (the same URL syntaxes are recognized). For example: {{{ hg fclone /some/existing/forest new_forest # Remote syntax should work too hg fclone ssh://some.machine/some/existing/forest ./forest }}} ==== Building cloned forest on top of already cloned repositories ==== '''ToDo: describe''' (casus when I have machineA:devel/proj1, machineA:devel/proj2, machineB:devel/proj1, machineB:devel/proj2 and want to forestize devel directory) ==== Verifying status of the existing forest ==== To display the status of the forest use {{{ cd forestdir hg fstatus }}} This will display aggregated status of all subprojects (and the main forest repo itself). Note: you must issue this command while being in main forest directory, issuing it in subproject dir will bring just the status of this dir, this is some limitation of the extension. To list just the roots of repositories (forest contents), use: {{{ cd forestdir hg ftrees }}} (as above, issue it in main forest directory) ==== Pulling, pushing and updating ==== One can of course use standard pull, push, and update commands while working in individual forest subprojects, they work as usual. To pull, push and update whole forest at once, use {{{fpull}}}, {{{fpush}}} and {{{fupdate}}}. To use fpull and fpush we need a snapshot file. For the simplest case, let's create the file which points to the tips of subprojects: {{{ cd forestdir hg fsnap -t > snapshot.txt }}} (you may take a look at snapshot.txt, this is simple textual file which lists subprojects) Then you can try {{{ cd forestdir hg fpull snapshot.txt default hg fpush snapshot.txt default }}} In case of the snapshot built with -t option (pointing to tips) those commands just push or pull all forest subprojects and the main forest directory. Update can be performed similarly {{{ cd forestdir hg fupdate snapshot.txt }}} but here, when we use tips, snapshot is not necessary, altnernatively one can try {{{ cd forestdir hg fupdate --tip }}} Note: you can alias remote forests by creating aliases in top level forest mercurial repository. '''ToDo''': or maybe aliases must be defined both on top and in subdirs? And what if there is ==== Partial clone ==== Forest subproject is still normal mercurial repository. So it can be cloned as usual. {{{ hg clone forestdir/subproject1 subproject1_branch }}} ==== Using snapshots ==== '''ToDo''': some explanation what non-tip snapshots are used for, how should one operate on them etc is desperately needed. '''ToDo''': some explanation what hg fseed does is desperately needed. |
Forest Extension
This extension is not being distributed along with Mercurial.
Author: Robin FarineBR Maintainer: Simon Law <simon@akoha.org>
Download site: [http://www.terminus.org/hg/hgforest public development repository].
Note: As of 9/3/2007, the version at this repository does not load or work correctly under Mercurial 0.9.4. Simon is presently consolidating updates, and hopes to have a new version for packaging shortly. — shap
Overview
The Forest extension allows operations on trees with nested Mercurial repositories, called forests. Those to some degree correspond to multi-project CVS/Svn/... repositories.
The extension change some standard Mercurial commands - like 'clone' or 'status' - so they are applied recursively to the whole forest instead of working for the individual repository. It also defines some new commands: fclone, fpull, fpush, fseed, fsnap, ftrees and fupdate.
The forest extension brings one new concept - a snapshot file. This file represents state of a forest at a given time
ToDo: detailed explanation what exactly is the snapshot file
Enabling the extension
Configure your .hgrc to enable the extension by adding following lines:
[extensions] hgext.forest= # or, if forest.py is not in the hgext dir: # forest=/path/to/forest.py
Some additional configuration can be done using the '[forest]' stanza in your configuration file:
[forest] # will nested repositories directly under a .hg directory be skipped (0|no|false) or not (1|yes|true)?. # The default value is 0. (don't skip them) walkhg = (0|no|false|1|yes|true)
ToDo: does walkhg=true truly mean that .hg is NOT walked? It is crazy....
Usage
Below some typical examples of how the extension can be used.
1. Creating a forest from scratch
Forest is just a mercurial repository containing some other mercurial repositories.
mkdir forestdir forestdir/subproject1 forestdir/subproject2 cd forestdir # Initialize mercurial repo for the forest itself hg init # Initialize subproject repos cd subproject1 hg init cd ../subproject2 hg init cd ..
We have a forest containing two subprojects. Of course new subprojects can be added at any time in the same way.
2. Creating a forest on top of existing repositories
Let's consider more realistic example - we want to bind as forest some already existing repositories. Then there are two options. To create the forest in new location, just initialize repository there and clone subprojects into subdirectories:
mkdir forestdir cd forestdir hg init # To keep the same name (here - somelib) hg clone <some-location>/somelib # To change name hg clone <some-location>/somelib sublib
Instead of cloning, one can just move the directories (this preserves working dir state).
One can also build forest in existing directory. Let's say we have mercurial repositories in $HOME/someproject/subproject1 and $HOME/someproject/subproject2. Then bare
cd $HOME/someproject hg init
creates the forest in $HOME/someproject.
3. Cloning existing forest
To clone a forest use fclone. It works just as normal clone (the same URL syntaxes are recognized). For example:
hg fclone /some/existing/forest new_forest # Remote syntax should work too hg fclone ssh://some.machine/some/existing/forest ./forest
4. Building cloned forest on top of already cloned repositories
ToDo: describe (casus when I have machineA:devel/proj1, machineA:devel/proj2, machineB:devel/proj1, machineB:devel/proj2 and want to forestize devel directory)
5. Verifying status of the existing forest
To display the status of the forest use
cd forestdir hg fstatus
This will display aggregated status of all subprojects (and the main forest repo itself).
Note: you must issue this command while being in main forest directory, issuing it in subproject dir will bring just the status of this dir, this is some limitation of the extension.
To list just the roots of repositories (forest contents), use:
cd forestdir hg ftrees
(as above, issue it in main forest directory)
6. Pulling, pushing and updating
One can of course use standard pull, push, and update commands while working in individual forest subprojects, they work as usual.
To pull, push and update whole forest at once, use fpull, fpush and fupdate. To use fpull and fpush we need a snapshot file. For the simplest case, let's create the file which points to the tips of subprojects:
cd forestdir hg fsnap -t > snapshot.txt
(you may take a look at snapshot.txt, this is simple textual file which lists subprojects)
Then you can try
cd forestdir hg fpull snapshot.txt default hg fpush snapshot.txt default
In case of the snapshot built with -t option (pointing to tips) those commands just push or pull all forest subprojects and the main forest directory.
Update can be performed similarly
cd forestdir hg fupdate snapshot.txt
but here, when we use tips, snapshot is not necessary, altnernatively one can try
cd forestdir hg fupdate --tip
Note: you can alias remote forests by creating aliases in top level forest mercurial repository.
ToDo: or maybe aliases must be defined both on top and in subdirs? And what if there is
7. Partial clone
Forest subproject is still normal mercurial repository. So it can be cloned as usual.
hg clone forestdir/subproject1 subproject1_branch
8. Using snapshots
ToDo: some explanation what non-tip snapshots are used for, how should one operate on them etc is desperately needed.
ToDo: some explanation what hg fseed does is desperately needed.