@legion-workspace/cli
v0.1.1
Published
Polyrepo helper tool to manage multiple repositories at once
Downloads
66
Readme
Legion CLI
Legion workspace speeds up multi-repository workflows. Compared to monorepos, Legion fully embraces a poly-repository environment. It significantly reduces the overhead of handling multiple repositories and allows for a more streamlined workflow.
Legion is specifically designed for NPM packaged projects. Legion currently relies on NPM Workspace for linking (Yarn support to come).
NB! Currently, legion
does not yet calculate the dependency graph for the workspace, so it will not recursively version up affected packages. Therefore, NPM package versioning and publishing should still be done manually.
Table of contents
Installation
npm install -g @legion-workspace/cli
Setup
1. Set up .legionrc.js
Define your repositories in .legionrc.js
in the root of your workspace
module.exports = {
repositories: [
// Microservice applications in apps/
{
url: "[email protected]:example-org-name/example-microservice-name.git",
branch: "main",
path: "apps/microservice-service"
},
// Shared package libraries in packages/
{
url: "[email protected]:example-org-name/example-package-name.git",
branch: "main",
path: "packages/package-name",
}
]
}
| Property | Description |
|---|---|
| url
| URL of the git repository |
| branch
| This is the branch that the repository will be checked out to when you run legion init
and legion reset
. This is usually main
. |
| path
| Relative path to the repository. |
2. Set up package.json
In the workspace root: npm init
This will create a package.json
file in the root of your workspace. It is mainly used to define the "workspace" paths for npm linking by NPM Workspaces.
3. Clone repositories
legion init
This will clone the repositories defined in .legionrc.js
into the directories defined in the path
properties.
Commands
| Command | Description |
|---|---|
| help
| Shows a list of all commands. |
| add
| Runs git add
in all the repositories. Simple alias of legion run 'git add'
|
| check [-a]
| Checks the compatibility of dependencies compared to the local packages. Incompatible packages are unlinked, compatible packages are linked. If the package is red, it will be unlinked. If it is green or orange, it will be linked. |
| checkout
| Runs git checkout
in all the repositories. Simple alias of legion run 'git checkout'
|
| commit
| Runs git commit
in repositories with staged, unstaged and/or tracked changes. |
| init
| Initialises repositories defined in .legionrc.js
, populates "workspaces"
and runs npm i
in the root of the workspace. |
| link
| Refreshes the workspace root package.json
"workspaces"
value. |
| list
| Lists the projects. |
| pull
| Runs git pull
in all the repositories. |
| push
| Runs git push
in all the repositories which are ahead of the base branch at least with one commit. |
| reset
| Discards all changes (staged, unstaged and untracked) and resets to the latest base branch. |
| run '<command>'
| Runs the command in all repositories. Notice the upticks. |
| status
| Quick overview of the changed repositories. It will show you any repositories that are ahead of the base branch or that have uncommited changes. |
| switch <branch-name>
| Switches to the branch in all repositories. |
| upgrade <package-name>
| Upgrades the package in all repositories. Runs npm i package-name@<version>
in all repositories dependent on the package. The <version>
will match the value in the local workspace, but it will pull it from the remote registry. |
Usage
Starting a new feature branch
Implementing a feature is symmetric to git
commands. A workflow example:
legion reset
makes sure we have the latest changes and are on the base branchlegion checkout -b new-branch-name
creates a new branch in all repositories- Implement the required changes
- Commit the changes:
legion add .
andlegion commit -m "Implement feature"
- Push the changes of the affected repositories:
legion push
Publishing the packages
legion
does not yet support a way to automatically publish all affected packages.
It is currently expected that you version and publish the packages manually with npm version
and npm publish
in the affected repositories.
Upgrading packages
Once the packages are upgraded with npm version major/minor/patch
and published with npm publish
, use:
legion upgrade @org-name/package-name
This will update the version in all repositories that use the package to the version that is currently on your local machine.
Use:
legion check
To check that all your repositories use the compatible package version. If not, they will show up either yellow or red with the required version numbers defined.
You can then use
legion add .
legion commit -m "Upgrade package"
legion push
To push the changes to all services.
Deploying services
It is expected that you use your own deployment flow to deploy the services. legion
does not restrict you to using a specific deployment flow and will not do so in the future.
Roadmap and issues
In no particular order
- [ ] Support for
-a
inlegion commit -am "Commit message"
. When-a
is detected,git commit
will run in repositories that have unstaged changes, too. - [ ] Show unpushed commits in
legion status
- [ ]
legion prune
or similar to clean up unused branches and old merged branches. - [ ]
legion pull
should not fail when remote is not tracked or when remote is already merged/deleted - [ ]
legion push
should not push branch which has been deleted in remote - [ ] Migrate code to TypeScript for better code scaling
- [ ]
legion reset
should show the changes that are going to be discarded and ask the user for confirmation before continuing - [ ]
legion snap
should create a snapshot of the current state of the workspace. This includes the branch state, stashed and unstanshed changes