@ws-conventional-version-roller/version

(`ws-roller version`) Version command

The roller Version command, bump version of packages changed since the last release

Internal Dependencies

@ws-conventional-version-roller/core

Installation

# install globally
npm install -g @ws-conventional-version-roller/cli
# then use it (see usage below)
ws-roller version

# OR use npx
npx ws-roller version

Usage

ws-roller version 1.0.1 # explicit
ws-roller version patch # semver keyword
ws-roller version       # select from prompt(s)

When run, this command does the following:

Identifies packages that have been updated since the previous tagged release.
Prompts for a new version.
Modifies package metadata to reflect new release, running appropriate lifecycle scripts in root and per-package.
Commits those changes and tags the commit.
Pushes to the git remote.

Positionals

semver `bump`

ws-roller version [major | minor | patch | premajor | preminor | prepatch | prerelease]
# uses the next semantic version(s) value and this skips `Select a new version for...` prompt

When this positional parameter is passed, ws-roller version will skip the version selection prompt and increment the version by that keyword. You must still use the --yes flag to avoid all prompts.

Prerelease

If you have any packages with a prerelease version number (e.g. 2.0.0-beta.3) and you run ws-roller version with and a non-prerelease bump (major, minor, or patch), it will publish those previously pre-released packages as well as the packages that have changed since the last release.

For projects using conventional commits, use the following flags for prerelease management:

--conventional-prerelease: release current changes as prerelease versions.
--conventional-graduate: graduate prerelease versioned packages to stable versions.

Running ws-roller version --conventional-commits without the above flags will release current changes as prerelease only if the version is already in prerelease.

Options

@ws-roller/version

`--allow-branch <glob>`

A whitelist of globs that match git branches where ws-roller version is enabled. It is easiest (and recommended) to configure in roller.json, but it is possible to pass as a CLI option as well.

{
  "command": {
    "version": {
      "allowBranch": "main"
    }
  }
}

With the configuration above, the ws-roller version will fail when run from any branch other than main. It is considered a best-practice to limit ws-roller version to the primary branch alone.

{
  "command": {
    "version": {
      "allowBranch": ["main", "feature/*"]
    }
  }
}

With the preceding configuration, ws-roller version will be allowed in any branch prefixed with feature/. Please be aware that generating git tags in feature branches is fraught with potential errors as the branches are merged into the primary branch. If the tags are "detached" from their original context (perhaps through a squash merge or a conflicted merge commit), future ws-roller version executions will have difficulty determining the correct "diff since last release."

It is always possible to override this "durable" config on the command-line. Please use with caution.

ws-roller version --allow-branch hotfix/oops-fix-the-thing

`--amend`

ws-roller version --amend
# commit message is retained, and `git push` is skipped.

When run with this flag, ws-roller version will perform all changes on the current commit, instead of adding a new one. This is useful during Continuous integration (CI) to reduce the number of commits in the project's history.

In order to prevent unintended overwrites, this command will skip git push (i.e., it implies --no-push).

`--changelog-preset`

ws-roller version --conventional-commits --changelog-preset angular-bitbucket

By default, the changelog preset is set to angular. In some cases you might want to change either use a another preset or a custom one.

Presets are names of built-in or installable configuration for conventional changelog. Presets may be passed as the full name of the package, or the auto-expanded suffix (e.g., angular is expanded to conventional-changelog-angular).

This option is can also be specified in roller.json configuration:

{
  "changelogPreset": "angular"
}

If the preset exports a builder function (e.g. conventional-changelog-conventionalcommits), you can specify the preset configuration too:

{
  "changelogPreset": {
    "name": "conventionalcommits",
    "issueUrlFormat": "{{host}}/{{owner}}/{{repository}}/issues/{{id}}"
  }
}

`--conventional-commits`

ws-roller version --conventional-commits

When run with this flag, ws-roller version will use the Conventional Commits Specification to determine the version bump and generate CHANGELOG.md files.

Passing --no-changelog will disable the generation (or updating) of CHANGELOG.md files.

`--conventional-graduate`

ws-roller version --conventional-commits --conventional-graduate=package-2,package-4

# force all prerelease packages to be graduated
ws-roller version --conventional-commits --conventional-graduate

When run with this flag, ws-roller version will graduate the specified packages (comma-separated) or all packages using *. This command works regardless of whether the current HEAD has been released, similar to --force-publish, except that any non-prerelease packages are ignored. If changes are present for packages that are not specified (if specifying packages), or for packages that are not in prerelease, those packages will be versioned as they normally would using --conventional-commits.

"Graduating" a package means bumping to the non-prerelease variant of a prerelease version, eg. package-1@1.0.0-alpha.0 => package-1@1.0.0.

NOTE: when specifying packages, dependents of specified packages will be released, but will not be graduated.

`--conventional-prerelease`

ws-roller version --conventional-commits --conventional-prerelease=package-2,package-4

# force all changed packages to be prereleased
ws-roller version --conventional-commits --conventional-prerelease

When run with this flag, ws-roller version will release with prerelease versions the specified packages (comma-separated) or all packages using *. Releases all unreleased changes as pre(patch/minor/major/release) by prefixing the version recommendation from conventional-commits with pre, eg. if present changes include a feature commit, the recommended bump will be minor, so this flag will result in a preminor release. If changes are present for packages that are not specified (if specifying packages), or for packages that are already in prerelease, those packages will be versioned as they normally would using --conventional-commits.

`--changelog-header-message <msg>`

Add a custom message at the top of your "changelog.md" which is located in the root of your project. This option only works when using --conventional-commits and will only impact your project root "changelog.md".

ws-roller version --changelog-header-message "My Custom Header Message"

`--changelog-version-message <msg>`

Add a custom message as a prefix to your new version in your "changelog.md" which is located in the root of your project. This option only works when using --conventional-commits and will only impact your project root "changelog.md".

ws-roller version --changelog-version-message "My Great New Version Message"

`--create-release <type>`

ws-roller version --conventional-commits --create-release github
ws-roller version --conventional-commits --create-release gitlab

When run with this flag, ws-roller version will create an official GitHub or GitLab release based on the changed packages. Requires --conventional-commits to be passed so that changelogs can be generated.

To authenticate with GitHub, the following environment variables can be defined.

GH_TOKEN (required) - Your GitHub authentication token (under Settings > Developer settings > Personal access tokens).
GHE_API_URL - When using GitHub Enterprise, an absolute URL to the API.
GHE_VERSION - When using GitHub Enterprise, the currently installed GHE version. Supports the following versions.

To authenticate with GitLab, the following environment variables can be defined.

GL_TOKEN (required) - Your GitLab authentication token (under User Settings > Access Tokens).
GL_API_URL - An absolute URL to the API, including the version. (Default: https://gitlab.com/api/v4)

NOTE: When using this option, you cannot pass --no-changelog.

`--exact`

ws-roller version --exact

When run with this flag, ws-roller version will specify updated dependencies in updated packages exactly (with no punctuation), instead of as semver compatible (with a ^).

For more information, see the package.json dependencies documentation.

`--force-publish`

ws-roller version --force-publish=package-2,package-4

# force all packages to be versioned
ws-roller version --force-publish

When run with this flag, ws-roller version will force publish the specified packages (comma-separated) or all packages using *.

This will skip the ws-roller changed check for changed packages and forces a package that didn't have a git diff change to be updated.

`--git-dry-run`

Displays the git command that would be performed without actually executing it, however please note that it will still create all the changelogs. This could be helpful for troubleshooting and also to see changelog changes without commiting them to Git.

Note: it will still create the changelogs (when enabled), so it could be useful to see what gets created (however, make sure to discard the changes and roll back your version in roller.json once you're done)

$ ws-runner run watch --git-dry-run

`--git-remote <name>`

ws-roller version --git-remote upstream

When run with this flag, ws-roller version will push the git changes to the specified remote instead of origin.

`--ignore-changes`

Ignore changes in files matched by glob(s) when detecting changed packages.

ws-roller version --ignore-changes '**/*.md' '**/__tests__/**'

This option is best specified as root roller.json configuration, both to avoid premature shell evaluation of the globs and to share the config with ws-roller diff and ws-roller changed:

{
  "ignoreChanges": ["**/__fixtures__/**", "**/__tests__/**", "**/*.md"]
}

Pass --no-ignore-changes to disable any existing durable configuration.

In the following cases, a package will always be published, regardless of this option:

The latest release of the package is a prerelease version (i.e. 1.0.0-alpha, 1.0.0–0.3.7, etc.).

One or more linked dependencies of the package have changed.

`--ignore-scripts`

When passed, this flag will disable running lifecycle scripts during ws-roller version.

`--include-merged-tags`

ws-roller version --include-merged-tags

Include tags from merged branches when detecting changed packages.

`--message <msg>`

This option is aliased to -m for parity with git commit.

ws-roller version -m "chore(release): publish %s"
# commit message = "chore(release): publish v1.0.0"

ws-roller version -m "chore(release): publish %v"
# commit message = "chore(release): publish 1.0.0"

# When versioning packages independently, no placeholders are replaced
ws-roller version -m "chore(release): publish"
# commit message = "chore(release): publish
#
# - package-1@3.0.1
# - package-2@1.5.4"

When run with this flag, ws-roller version will use the provided message when committing the version updates for publication. Useful for integrating ws-roller into projects that expect commit messages to adhere to certain guidelines, such as projects which use commitizen and/or semantic-release.

If the message contains %s, it will be replaced with the new global version version number prefixed with a "v". If the message contains %v, it will be replaced with the new global version version number without the leading "v". Note that this placeholder interpolation only applies when using the default "fixed" versioning mode, as there is no "global" version to interpolate when versioning independently.

This can be configured in roller.json, as well:

{
  "command": {
    "version": {
      "message": "chore(release): publish %s"
    }
  }
}

`--no-changelog`

ws-roller version --conventional-commits --no-changelog

When using conventional-commits, do not generate any CHANGELOG.md files.

NOTE: When using this option, you cannot pass --create-release.

`--no-commit-hooks`

By default, ws-roller version will allow git commit hooks to run when committing version changes. Pass --no-commit-hooks to disable this behavior.

This option is analogous to the npm version option --commit-hooks, just inverted.

`--no-git-tag-version`

By default, ws-roller version will commit changes to package.json files and tag the release. Pass --no-git-tag-version to disable the behavior.

This option is analogous to the npm version option --git-tag-version, just inverted.

`--no-granular-pathspec`

By default, ws-roller version will git add only the leaf package manifests (and possibly changelogs) that have changed during the versioning process. This yields the equivalent of git add -- packages/*/package.json, but tailored to exactly what changed.

If you know you need different behavior, you'll understand: Pass --no-granular-pathspec to make the git command literally git add -- .. By opting into this pathspec, you MUST HAVE ALL SECRETS AND BUILD OUTPUT PROPERLY IGNORED, OR IT WILL BE COMMITTED AND PUSHED.

This option makes the most sense configured in roller.json, as you really don't want to mess it up:

{
  "version": "independent",
  "granularPathspec": false
}

The root-level configuration is intentional, as this also covers the identically-named option in ws-roller publish.

`--no-private`

By default, ws-roller version will include private packages when choosing versions, making commits, and tagging releases. Pass --no-private to disable this behavior.

Note that this option does not exclude private scoped packages, only those with a "private": true field in their package.json file.

`--no-push`

By default, ws-roller version will push the committed and tagged changes to the configured git remote. Pass --no-push to disable this behavior.

`--preid`

ws-roller version prerelease
# uses the next semantic prerelease version, e.g.
# 1.0.0 => 1.0.1-alpha.0

ws-roller version prepatch --preid next
# uses the next semantic prerelease version with a specific prerelease identifier, e.g.
# 1.0.0 => 1.0.1-next.0

When run with this flag, ws-roller version will increment premajor, preminor, prepatch, or prerelease semver bumps using the specified prerelease identifier.

`--signoff-git-commit`

Adds the --signoff flag to the git commit done by lerna version when executed.

Note: This is different from --sign-git-commit which is about gpg signatures.

`--sign-git-commit`

This option is analogous to the npm version option of the same name.

`--sign-git-tag`

This option is analogous to the npm version option of the same name.

`--force-git-tag`

This option replaces any existing tag instead of failing.

`--tag-version-prefix`

This option allows to provide custom prefix instead of the default one: v.

Keep in mind that currently you have to supply it twice: for version command and for publish command:

# locally
ws-roller version --tag-version-prefix=''
# on ci
ws-roller publish from-git --tag-version-prefix=''

`--yes`

ws-roller version --yes
# skips `Are you sure you want to publish these packages?`

When run with this flag, ws-roller version will skip all confirmation prompts. Useful in Continuous integration (CI) to automatically answer the publish confirmation prompt.

Lifecycle Scripts

// preversion:  Run BEFORE bumping the package version.
// version:     Run AFTER bumping the package version, but BEFORE commit.
// postversion: Run AFTER bumping the package version, and AFTER commit.

ws-roller will run npm lifecycle scripts during ws-roller version in the following order:

Detect changed packages, choose version bump(s)
Run preversion lifecycle in root
For each changed package, in topological order (all dependencies before dependents):
1. Run preversion lifecycle
2. Update version in package.json
3. Run version lifecycle
Run version lifecycle in root
Add changed files to index, if enabled
Create commit and tag(s), if enabled
For each changed package, in lexical order (alphabetical according to directory structure):
1. Run postversion lifecycle
Run postversion lifecycle in root
Push commit and tag(s) to remote, if enabled
Create release, if enabled

Files

README.md

Latest commit

History

README.md

File metadata and controls

@ws-conventional-version-roller/version

(ws-roller version) Version command

Internal Dependencies

Installation

Usage

Positionals

semver bump

Prerelease

Options

--allow-branch <glob>

--amend

--changelog-preset

--conventional-commits

--conventional-graduate

--conventional-prerelease

--changelog-header-message <msg>

--changelog-version-message <msg>

--create-release <type>

--exact

--force-publish

--git-dry-run

--git-remote <name>

--ignore-changes

--ignore-scripts

--include-merged-tags

--message <msg>

--no-changelog

--no-commit-hooks

--no-git-tag-version

--no-granular-pathspec

--no-private

--no-push

--preid

--signoff-git-commit

--sign-git-commit

--sign-git-tag

--force-git-tag

--tag-version-prefix

--yes