@shadowspawn/forest-arborist4.1.3 • Public • Published
- Forest Arborist
Provide key operations on a loosely coupled forest of repositories. The forest repos can be nested under a main repo or siblings in a plain directory. Supports both Git and Mercurial repositories. Inspired by experience with Mercurial subrepositories. Tested on macOS, Windows, and Linux.
Aims to be lightweight and coexist with other tooling, rather than intrusive and opinionated.
Uses a manifest file in the seed repo and a marker file at the root of the forest. Allows most commands to be run from anywhere in the forest, by searching up for the root marker file.
- forest: a collection of repositories and their working trees
- root: directory at the root of the forest
- manifest: lists dependent repositories and forest configuration
- seed repository: where the manifest is stored
npm install --global @shadowspawn/forest-arborist fab help
Forest Management Commands
fab to an existing forest you run
init from the seed repo where you want the manifest to be stored.
fab init --nestedfrom root repo for a nested forest
fab init --siblingfrom seed repo for a sibling forest, with root up one directory
clone a seed repo to get the forest. This uses the manifest to find the dependent repos and forest layout.
fab clone ssh://user@host:/path
If you have more than one combination of repos you use, such as different platform libraries or production vs development, you can specify a manifest name:
fab init --sibling --manifest mac fab clone --manifest mac ssh://user@host:/path
To (re)install dependent repos if the manifest has changed, or install dependent repos after cloning just the seed repo:
To see a compact status listing for each repo in the forest:
To pull new changesets:
There are two commands which take an explicit additional command to run across the forest. A
-- is used to mark the end of the
fab options, and is optional if there are no options in the additional command. (free is explained in Dependent Repository Types)
fab for-each -- git remote -v fab for-free -- git branch
There are two commands which run specifically
hg commands across the forest repositories of matching type:
fab git -- remote -v fab hg -- summary
Working With Branches
You can specify the starting branch when you make the clone:
fab clone --branch develop ssh://user@host:/path
There are commands to make a new branch and to switch to an existing branch:
fab make-branch feature/bells fab make-branch --publish feature/working-with-others fab switch master
The branch commands operate on the free repositories, and not the pinned or locked repositories. (See Dependent Repository Types.)
Reproducing Forest State
There are three commands for reproducing forest state:
snapshotproduces a listing of the current forest and changesets
restoretakes the current forest back to the snapshot state
recreateis like clone but takes a snapshot file
fab snapshot --output ~/snapshot1 git pull fab restore ~/snapshot1 cd ~/sandpit fab recreate ~/snapshot1 myTempRepo
Dependent Repository Types
Some of the repositories you work with are actively developed along with the seed repo, while some might actively track the release branch of a library, and some should stay fixed at a specific version.
The dependent repos can be configured in three ways:
- pinned to a specified changeset or tag
- locked to a specified branch
- free to follow the seed repo
The various commands operate on an appropriate subset of the repos. For example the switch command only affects the free repositories, the pull command affects free and locked, and the status command runs on all the repos.
Manifest Files (Internals)
The manifest specifies the forest layout and the dependent repository details. The manifest file can be automatically generated by:
fab init --nestedfrom master repository for a nested forest
fab init --siblingfrom seed repo for a sibling forest
fab init --sibling --manifest nameto save a custom manifest
You can manage the manifest contents with the
fab manifestshow path to manifest
fab manifest --editopen manifest in editor
fab manifest --listlist dependencies from manifest
fab manifest --add newRepoadd entry to manifest dependencies
fab manifest --delete staleRepodelete entry from manifest dependencies
The dependencies map is where you might do some hand editing. The map key is the working directory relative to the root of the forest. The properties are:
- origin: remote repo. Either absolute or relative to the seed origin.
- repoType: "git" or "hg"
- pinRevision: if pinned, changeset or tag
- lockBranch: if locked, branch name
The manifests are stored in the
.fab folder of the seed repo.
Custom manifests follow the template <custom>_manifest.json.
Command-line Tab Completion
To install command-line tab completion, write the output of
fab completion to a suitable location to be executed, whether via your shell startup file or in a location which is read by the system. See
fab completion for installation examples.
(c.f. npm completion)
|Branch||macOS & Linux||Windows|
git clone --branch develop email@example.com:shadowspawn/forest-arborist.git cd forest-arborist npm install npm link npm run test