{"id":16838371,"url":"https://github.com/shadowspawn/forest-arborist","last_synced_at":"2025-03-17T04:33:31.257Z","repository":{"id":35024542,"uuid":"65456894","full_name":"shadowspawn/forest-arborist","owner":"shadowspawn","description":"Work with a forest of git repositories as easily as using a single repo","archived":false,"fork":false,"pushed_at":"2024-09-06T03:28:52.000Z","size":2067,"stargazers_count":18,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-27T18:06:59.282Z","etag":null,"topics":["git","hg","mercurial","subrepos"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shadowspawn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"shadowspawn"}},"created_at":"2016-08-11T09:27:20.000Z","updated_at":"2025-02-02T01:28:10.000Z","dependencies_parsed_at":"2024-01-28T07:28:18.154Z","dependency_job_id":"ca417aaf-d6ad-496a-abfd-f9230aeae937","html_url":"https://github.com/shadowspawn/forest-arborist","commit_stats":{"total_commits":929,"total_committers":4,"mean_commits":232.25,"dds":"0.18514531754574814","last_synced_commit":"1edb75a2569bb46df83b78b1157ab4c9de61a55e"},"previous_names":["johnrgee/forest-arborist"],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowspawn%2Fforest-arborist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowspawn%2Fforest-arborist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowspawn%2Fforest-arborist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowspawn%2Fforest-arborist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shadowspawn","download_url":"https://codeload.github.com/shadowspawn/forest-arborist/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243842135,"owners_count":20356610,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","hg","mercurial","subrepos"],"created_at":"2024-10-13T12:22:50.990Z","updated_at":"2025-03-17T04:33:30.918Z","avatar_url":"https://github.com/shadowspawn.png","language":"TypeScript","funding_links":["https://github.com/sponsors/shadowspawn"],"categories":[],"sub_categories":[],"readme":"# Forest Arborist\n\n[![npm version](https://img.shields.io/npm/v/@shadowspawn/forest-arborist.svg)](https://www.npmjs.com/package/@shadowspawn/forest-arborist)\n[![GitHub build](https://github.com/shadowspawn/forest-arborist/workflows/build/badge.svg)](https://github.com/shadowspawn/forest-arborist/actions?query=workflow%3Abuild+branch%3Amain)\n\n- [Forest Arborist](#forest-arborist)\n    - [Overview](#overview)\n    - [Installation](#installation)\n    - [Forest Management Commands](#forest-management-commands)\n    - [Utility Commands](#utility-commands)\n    - [Working With Branches](#working-with-branches)\n    - [Reproducing Forest State](#reproducing-forest-state)\n    - [Dependent Repository Types](#dependent-repository-types)\n    - [Manifest Files (Internals)](#manifest-files-internals)\n    - [Command-line Tab Completion](#command-line-tab-completion)\n    - [Colour Output](#colour-output)\n    - [Developing](#developing)\n\n## Overview\n\nWork with a forest of repositories as easily as using a single repo: from `fab clone`, through `fab pull` and `fab status`, to custom commands.\n\nSupports Git and Mercurial repositories. Tested on macOS, Windows, and Linux.\n\nAims to be lightweight and coexist with other tooling, rather than intrusive and opinionated. Adds a manifest file in the seed repo and a marker file at the root of the forest.\n\nMost commands can be run from anywhere in the forest.\n\nTerminology:\n\n- _forest_: a collection of repositories and their working trees\n- _root_: directory at the root of the forest\n- _manifest_: lists dependent repositories and forest configuration\n- _seed_ repository: where the manifest is stored\n\n## Installation\n\nRequires `node` and `npm`.\n\n    npm install --global @shadowspawn/forest-arborist\n    fab help\n\n## Forest Management Commands\n\nTo add `fab` to an existing forest you run `init` from the seed repo where you want the manifest to be stored.\n\n- `fab init --nested` from root repo for a nested forest\n- `fab init --sibling` from seed repo for a sibling forest, with root up one directory\n\nYou `clone` a seed repo to get the forest. This uses the manifest to find the dependent repos and forest layout.\n\n    fab clone ssh://user@host:/path\n\nIf you have more than one combination of repos you use, such as different\nplatform libraries or production vs development, you can specify a manifest name:\n\n    fab init --sibling --manifest mac\n    fab clone --manifest mac ssh://user@host:/path\n\nTo (re)install dependent repos if the manifest has changed, or install dependent repos after cloning just the seed repo:\n\n    fab install\n\n## Utility Commands\n\nTo see a compact status listing for each repo in the forest:\n\n    fab status\n\nTo pull new changesets:\n\n    fab pull\n\nThere 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](#dependent-repository-types))\n\n    fab for-each git remote -v\n    fab for-free git branch\n\nThere are two commands which run specifically `git` or `hg` commands across the forest repositories of matching type:\n\n    fab git remote -v\n    fab hg summary\n\n## Working With Branches\n\nYou can specify the starting branch when you make the clone:\n\n    fab clone --branch develop ssh://user@host:/path\n\nThere are commands to make a new branch and to switch to an existing branch:\n\n    fab make-branch feature/bells\n    fab make-branch --publish feature/working-with-others\n    fab switch trunk\n\nThe branch commands operate on the _free_ repositories, and not the _pinned_ or _locked_ repositories. (See [Dependent Repository Types](#dependent-repository-types).)\n\n## Reproducing Forest State\n\nThere are three commands for reproducing forest state:\n\n- `snapshot` produces a listing of the current forest and changesets\n- `restore` takes the current forest back to the snapshot state\n- `recreate` is like clone but takes a snapshot file\n\nExample commands:\n\n    fab snapshot --output ~/snapshot1\n    git pull\n    fab restore ~/snapshot1\n    cd ~/sandpit\n    fab recreate ~/snapshot1 myTempRepo\n\n## Dependent Repository Types\n\nSome of the repositories you work with are actively developed along with the seed repo,\nwhile some might actively track the release branch of a library, and some should stay fixed\nat a specific version.\n\nThe dependent repos can be configured in three ways:\n\n- _pinned_ to a specified changeset or tag\n- _locked_ to a specified branch\n- _free_ to follow the seed repo\n\nThe various commands operate on an appropriate subset of the repos. For example\nthe switch command only affects the _free_ repositories, the pull command affects\n_free_ and _locked_, and the status command runs on all the repos.\n\n## Manifest Files (Internals)\n\nThe manifest specifies the forest layout and the dependent repository details. The manifest file can be automatically generated by:\n\n- `fab init --nested` from root repository for a nested forest\n- `fab init --sibling` from seed repo for a sibling forest\n- `fab init --sibling --manifest name` to save a custom manifest\n\nYou can manage the manifest contents with the `manifest` command:\n\n- `fab manifest path` show path to manifest\n- `fab manifest edit` open manifest in editor\n- `fab manifest list` list dependencies from manifest\n- `fab manifest add newRepo` add entry to manifest dependencies\n- `fab manifest delete staleRepo` delete entry from manifest dependencies\n\nThe _dependencies_ map is where you might do some hand editing. The map key\nis the working directory relative to the root of the forest. The properties are:\n\n- origin: remote repo. Either absolute or relative to the seed origin.\n- repoType: \"git\" or \"hg\"\n- pinRevision: if pinned, changeset or tag\n- lockBranch: if locked, branch name\n\nExample:\n\n```json\n{\"dependencies\": {\n    \"Libs/Locked\": {\n    \"origin\": \"git@github.com:Person/Locked.git \",\n    \"repoType\": \"git\",\n    \"lockBranch\": \"trunk\"\n    },\n    \"Libs/Pinned\": {\n    \"origin\": \"git@github.com:Person/Pinned.git \",\n    \"repoType\": \"git\",\n    \"pinRevision\": \"ce12a1b401e72f7808ab3da7a696a5ab4cd364fe\"\n    },\n    \"RelativeFree\": {\n    \"origin\": \"../relative-to-seed.git\",\n    \"repoType\": \"git\"\n    }\n},\n\"rootDirectory\": \".\",\n\"seedPathFromRoot\": \".\"\n}\n```\n\nThe manifests are stored in the `.fab` folder of the seed repo.\nCustom manifests follow the template \u0026lt;custom\u0026gt;\\_manifest.json.\n\n## Command-line Tab Completion\n\nTo 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.\n(c.f. [npm completion](https://docs.npmjs.com/cli/completion))\n\n## Colour Output\n\nColour output is off by default on Windows and on by default for other platforms. You can explicitly enable or disable colour using [FORCE_COLOR](https://www.npmjs.com/package/chalk#chalksupportscolor), or disable colour using [NO_COLOR](http://no-color.org).\n\n## Developing\n\n| Branch | Build Status |\n| --- | --- |\n| develop | [![GitHub build](https://github.com/shadowspawn/forest-arborist/workflows/build/badge.svg?branch=develop)](https://github.com/shadowspawn/forest-arborist/actions?query=workflow%3Abuild+branch%3Adevelop) |\n\nQuick start:\n\n    git clone --branch develop git@github.com:shadowspawn/forest-arborist.git\n    cd forest-arborist\n    npm install\n    npm link\n    npm run test\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshadowspawn%2Fforest-arborist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshadowspawn%2Fforest-arborist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshadowspawn%2Fforest-arborist/lists"}