@zokugun/bump-n-ship
v0.1.2
Published
Bump your project version, update files, and publish tags or PRs with ease.
Maintainers
Readme
@zokugun/bump-n-ship
Automate version bumping and release workflows. Update manifest files and publish to Git via tags or pull requests based on your project configuration.
Features
- Interactive prompts: Choose your next version interactively through a simple CLI prompt when not in CI mode.
- Manual overrides: Set an exact version or specify the increment type directly via command-line flags.
- Tagging releases: Annotate your release commit with an automatic or custom Git tag.
- Pull request releases: Branch out and push changes to a dedicated PR branch for review before merging.
- Template tokens: Supports dynamic strings in commit messages, tag names, and PR titles using variables like
{date},{index}, and{index}properties. - Prerelease handling: Easily manage prerelease identifiers and build metadata using customizable templates.
- NPM hooks: Execute your defined
preversion,version, andpostversionscripts during the release.
Installation
npm add --save-dev @zokugun/bump-n-shipRequirements
- Node.js:
v18.20or higher - Modules: ECMAScript Modules (
ESM)
Quick Start
Example 1: Basic Version Bumping
Use the bump command to update the version in your package.json and package-lock.json files without creating a Git commit.
Bumping a patch version:
# Update the current version by one patch level (e.g., 1.0.0 -> 1.0.1)
npx bump-n-ship bump --patchUsing an interactive prompt: If you do not specify an increment level, the tool prompts you to select the next version.
# Start the interactive selection process
npx bump-n-ship bumpDry run mode: Verify what the next version will be without modifying any files.
# Preview the resulting version in the console
npx bump-n-ship bump --patch --dry-runExample 2: Full Release to Git Tag
The release command automates the entire process: it bumps the version, creates a Git commit, adds a tag, and pushes changes to the remote repository.
Customizing the commit message: You can specify a custom message for the release commit instead of using the default version string.
# Release with a specific commit header
npx bump-n-ship release --patch --commit 'fix: resolve memory leak in parser'Using a manual version: Set the project to a specific version regardless of the previous state.
# Force the version to 2.0.0 and publish as a tag
npx bump-n-ship release --set-version '2.0.0'Manually edit files like CHANGELOG.md:
# After the version has been selected, pause to manually edit files like `CHANGELOG.md`
npx bump-n-ship release --all --pauseExample 3: Release via Pull Request
For projects that require code review before merging a release, use the --pr flag. This creates a dedicated release branch instead of tagging the main branch directly.
Creating a pre-release PR:
# Bump to a pre-release version and create a release branch
npx bump-n-ship release --pre --prCLI Commands
Four commands are available: bump, release, tag, and get-version.
bump
Updates the project version in configured files without creating Git commits or tags.
npx bump-n-ship bump [options]Options:
| Flag | Description |
| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| -b, --build <version> | Set build metadata |
| --ci | Disable interactive prompts; auto-detected in CI environments |
| -c, --current-version <version> | Override the current version |
| -d, --dry-run | Show what would happen without writing files |
| --ignore-scripts | Skip preversion, version npm scripts |
| -i, --increment <level> | Specify bump type: major, minor, patch, release, premajor, preminor, prepatch, prerelease |
| --major | increment the MAJOR version. |
| --minor | increment the MINOR version. |
| --patch | increment the PATCH version. |
| -p, --pause | Pause before writing files (not supported in CI) |
| --pre [label] | Set or increment pre-release label |
| -r, --release | Bump from pre-release to full release |
| -s, --set-version <version> | Manually set an exact version |
release
Bumps the version, creates a Git commit and tag (or pull request), then pushes.
npx bump-n-ship release [options]| Flag | Description |
| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| -b, --build <version> | Set build metadata |
| --ci | Disable interactive prompts; auto-detected in CI environments |
| -c, --current-version <version> | Override the current version |
| --commit <message> | Custom commit message template |
| --confirm | Prompt for confirmation before each step |
| --dirty | Continue even with uncommitted changes |
| -d, --dry-run | Show what would happen without writing files |
| --ignore-scripts | Skip preversion, version, and postversion npm scripts |
| -i, --increment <level> | Specify bump type: major, minor, patch, release, premajor, preminor, prepatch, prerelease |
| --major | increment the MAJOR version. |
| --minor | increment the MINOR version. |
| --no-verify | Skip Git hooks |
| --patch | increment the PATCH version. |
| -p, --pause | Pause before writing files (not supported in CI) |
| --pr | Release via a pull request. |
| --pre [label] | Set or increment pre-release label |
| -r, --release | Bump from pre-release to full release |
| -s, --set-version <version> | Manually set an exact version |
| --sign | GPG-sign the commit and tag |
| --tag <name> | Custom tag name template |
tag
Commits and tags the current version without bumping.
npx bump-n-ship tag [options]| Flag | Description |
| -------------------- | ------------------------------------------------------------- |
| --all | Stage all changes instead of only version files |
| --ci | Disable interactive prompts; auto-detected in CI environments |
| --commit <message> | Custom commit message template |
| --confirm | Prompt for confirmation before each step |
| --dirty | Continue even with uncommitted changes |
| -d, --dry-run | Show what would happen without writing files |
| --ignore-scripts | Skip postversion npm scripts |
| --no-verify | Skip Git hooks |
| -p, --pause | Pause before writing files (not supported in CI) |
| --sign | GPG-sign the commit and tag |
| --tag <name> | Custom tag name template |
get-version
Prints the current version from package.json.
npx bump-n-ship get-versionNo options.
Configuration
The package reads .bumpnshiprc{.json,.yaml,.yml} from the project root.
Example:
bump:
preRelease: 'beta.{index:1}'
publish:
remote: origin
sign: false
dirty: false
all: false
verify: true
tag:
name: 'v{version}'
message: '{version}'
commit:
header: 'chore: release {version}'
pullRequest:
branch: 'release/{tag}'
title: 'chore: release {tag}'
body: '{oldVersion} → {version}'Template Variables
See Template Variables for available placeholders and where they can be used.
Contributions
Contributions are most welcome. Please:
- Open issues and feature requests under the repository discussions.
- Follow the
CONTRIBUTING.md.
Donations
Support this project by becoming a financial contributor.
License
Copyright © 2026-present Baptiste Augrain
Licensed under the MIT license.
