Inspired by Lerna
A tool that optimizes the workflow around cargo workspaces with git and cargo by providing utilities to
version, publish, execute commands and more.
I made this to work on clap and other projects that rely on workspaces. But this will also work on single crates because by default every individual crate is a workspace.
cargo install cargo-workspaces
The installed tool can be called by cargo workspaces or cargo ws. Both of them point to the same.
You can use cargo ws help or cargo ws help <subcmd> anytime to understand allowed options.
The basic commands available for this tool are given below. Assuming you run them inside a cargo workspace.
Initializes a new cargo workspace in the given directory. Creates Cargo.toml if it does not exist and
fills the members with the all the crates that can be found in that directory.
``` USAGE: cargo workspaces init [PATH]
ARGS:
OPTIONS: -h, --help Print help information ```
Interactively creates a new crate in the workspace. We recommend using this instead of cargo new. All
the crates start with 0.0.0 version because the version is responsible for determining the
version.
```
USAGE:
cargo workspaces create [OPTIONS]
ARGS:
OPTIONS:
--bin Whether this is a binary crate
--edition
Lists crates in the workspace.
``` USAGE: cargo workspaces list [OPTIONS]
OPTIONS: -a, --all Show private crates that are normally hidden -h, --help Print help information --json Show information as a JSON array -l, --long Show extended information ```
Several aliases are available.
cargo ws ls implies cargo ws listcargo ws ll implies cargo ws list --longcargo ws la implies cargo ws list --allList crates that have changed since the last git tag. This is useful to see the list of crates that would be the subjects of the next version or publish command.
``` USAGE: cargo workspaces changed [OPTIONS]
OPTIONS:
-a, --all Show private crates that are normally hidden
--force
Executes an arbitrary command in each crate of the workspace.
```
USAGE:
cargo workspaces exec [OPTIONS]
ARGS:
OPTIONS:
-h, --help Print help information
--ignore
For example, if you want to run ls -l in each crate, you can simply do cargo ws exec ls -l.
Bump versions of the crates in the workspace. This command does the following:
You can influence the above steps with the flags and options for this command.
``` USAGE: cargo workspaces version [OPTIONS] [ARGS]
OPTIONS: -h, --help Print help information
VERSION ARGS:
VERSION OPTIONS:
-a, --all Also do versioning for private crates (will not be published)
--exact Specify inter dependency version numbers exactly with =
--force
GIT OPTIONS:
--allow-branch %n) [default: %n@]
-m, --message
By default, all the crates in the workspace will share a single version. But if you want the crate to have it's version be independent of the other crates, you can add the following to that crate:
toml
[package.metadata.workspaces]
independent = true
For more details, check Config section below.
Publish all the crates from the workspace in the correct order according to the dependencies. By default,
this command runs version first. If you do not want that to happen, you can supply the
--from-git option.
Note: dev-dependencies are not taken into account when building the dependency graph used to determine the proper publishing order. This is because dev-dependencies are ignored by
cargo publish- as such, a dev-dependency on a local crate (with apathattribute), should not have aversionfield.
``` USAGE: cargo workspaces publish [OPTIONS] [ARGS]
OPTIONS: -h, --help Print help information
VERSION ARGS:
VERSION OPTIONS:
-a, --all Also do versioning for private crates (will not be published)
--exact Specify inter dependency version numbers exactly with =
--force
GIT OPTIONS:
--allow-branch %n) [default: %n@]
-m, --message
PUBLISH OPTIONS:
--allow-dirty Allow dirty working directories to be published
--from-git Publish crates from the current commit without versioning
--no-verify Skip crate verification (not recommended)
--registry
Rename crates in the project. You can run this command when you might want to publish the crates with a standard prefix.
```
USAGE:
cargo workspaces rename [OPTIONS]
ARGS:
%n)
OPTIONS:
-a, --all Rename private crates too
-f, --from
There are two kind of options.
[workspace.metadata.workspaces][package.metadata.workspaces]If an option is allowed to exist in both places, it means that the value specified in the Package overrides the value specified in Workspace.
| Name | Type | Workspace | Package | Used in Commands |
| --- | --- | :---: | :---: | --- |
| allow_branch | String | Yes | No | version, publish |
| independent | bool | No | Yes | version, publish |
| no_individual_tags | bool | Yes | No | version, publish |
Here is a list of Contributors
Please see CHANGELOG.md.
MIT/X11
Report here.
Pavan Kumar Sunkara (pavan.sss1991@gmail.com)