Basic Usage

This guide covers the essential commands and workflows for using bumpx in your daily development.

Version Bumping

The core functionality of bumpx is version bumping across your project files.

Simple Version Bumps

Bump the version in your current directory:

# Patch version bump (1.0.0 → 1.0.1)
bumpx patch

# Minor version bump (1.0.0 → 1.1.0)
bumpx minor

# Major version bump (1.0.0 → 2.0.0)
bumpx major

Prerelease Versions

Create prerelease versions for testing:

# Create a prerelease version (1.0.0 → 1.0.1-alpha.0)
bumpx prerelease

# Specify custom prerelease identifier
bumpx prerelease --preid beta  # → 1.0.1-beta.0

# Prerelease bumps
bumpx premajor --preid rc      # → 2.0.0-rc.0
bumpx preminor --preid alpha   # → 1.1.0-alpha.0
bumpx prepatch --preid beta    # → 1.0.1-beta.0

Specific Version

Set an exact version:

# Set specific version
bumpx 2.1.0

# Set prerelease version
bumpx 2.1.0-beta.3

Interactive Mode

Use interactive mode to choose your version:

# Interactive version selection
bumpx prompt

# Shows recent commits for context
bumpx prompt --print-commits

File Operations

Target Specific Files

By default, bumpx looks for package.json in your current directory. You can specify different files:

# Update specific files
bumpx patch --files package.json,package-lock.json

# Update multiple package.json files
bumpx minor --files packages/*/package.json

# Include non-JSON files (searches for version patterns)
bumpx patch --files VERSION.txt,README.md

Workspace & Recursive Updates

bumpx includes automatic workspace detection and recursive updates enabled by default:

# Update all workspace packages (automatic detection, recursive by default)
bumpx patch

# Explicitly disable recursive mode
bumpx patch --no-recursive

# Show what would be updated without making changes
bumpx patch --dry-run --verbose

Current Version Override

When working with multiple packages that should share the same version:

# Set a common starting version for all files (recursive is default)
bumpx patch --current-version 1.2.3

# Useful for monorepos with synchronized versions
bumpx minor --current-version 2.0.0

Git Integration

Automatic Git Operations

Commit and tag your version bumps automatically:

# Default behavior: automatic commit, tag, and push
bumpx patch

# Override default behavior to disable specific operations
bumpx minor --no-push

# Create signed commit and tag
bumpx major --sign

# Disable all git operations
bumpx patch --no-commit --no-tag --no-push

Custom Commit Messages

Customize your commit and tag messages:

# Custom commit message (use %s for version)
bumpx patch --commit-message "chore: bump version to %s"

# Custom tag message
bumpx minor --tag-message "Release v%s"

Skip Git Checks

Bypass git status checks when needed:

# Skip git status check (allows dirty working directory)
bumpx patch --no-git-check

# Skip git hooks
bumpx minor --no-verify

Advanced Options

Progress Tracking

Monitor the bump process in detail:

# Show detailed progress
bumpx patch --verbose

# Show recent commits for context
bumpx minor --print-commits

# Combination of both
bumpx major --verbose --print-commits

Dry Run

Preview changes without making them:

# See what would be changed
bumpx patch --dry-run

# Dry run with git operations
bumpx minor --dry-run --commit --tag

Post-Bump Scripts

Run custom commands after version bump:

# Run scripts after bump (git operations still happen by default)
bumpx patch --execute "bun run build"

# Multiple commands
bumpx minor --execute "bun run build && bun run test"

# Install dependencies after bump
bumpx patch --install

Common Workflows

Development Release

Quick patch for bug fixes:

bumpx patch  # All git operations enabled by default

Feature Release

Release with documentation update:

bumpx minor --execute "bun run build:docs"

Major Release

Comprehensive major version release:

# Interactive selection with full workflow
bumpx prompt --print-commits --sign --execute "bun run build"

Prerelease Testing

Create prerelease for testing:

# Alpha release
bumpx prerelease --preid alpha

# Beta release with no push
bumpx prerelease --preid beta --no-push

Monorepo Management

Update all packages in a monorepo with automatic workspace detection:

# Synchronized version across all packages (recursive is default)
bumpx patch --current-version 1.0.0

# Independent versioning (each package bumps from its current version)
bumpx patch

Configuration

Global Configuration

Set default options in your shell profile:

# Add to ~/.zshrc or ~/.bashrc
alias bump-patch='bumpx patch --commit --tag'
alias bump-minor='bumpx minor --commit --tag --push'
alias bump-major='bumpx major --prompt --print-commits --commit --tag --push'

Project Configuration

Create a configuration file in your project. bumpx supports multiple formats:

TypeScript configuration:

// bumpx.config.ts
export default {
  commit: true,
  tag: true,
  push: false,
  sign: true,
  message: 'chore: release v%s',
  tagMessage: 'Release v%s'
}

JavaScript configuration:

// bumpx.config.js
module.exports = {
  commit: true,
  tag: true,
  push: false,
  sign: true,
  message: 'chore: release v%s',
  tagMessage: 'Release v%s'
}

Package.json configuration:

{
  "name": "my-project",
  "bumpx": {
    "commit": true,
    "tag": true,
    "push": false,
    "sign": true,
    "message": "chore: release v%s",
    "tagMessage": "Release v%s"
  }
}

Error Handling

Common Issues

Dirty working directory:

# Allow dirty working directory
bumpx patch --no-git-check

# Or commit changes first
git add . && git commit -m "work in progress"
bumpx patch --commit

No package.json found:

# Specify files explicitly
bumpx patch --files ./package.json

# Or check current directory
ls -la package.json

Git authentication issues:

# Ensure git credentials are set up
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# For signed commits
git config --global user.signingkey YOUR_KEY_ID

Troubleshooting

Enable verbose mode to see detailed operations:

# Verbose output shows each step
bumpx patch --verbose

# Check git status manually
git status
git log --oneline -5

Next Steps

• Configuration Guide - Set up default options and aliases
• Version Bumping Features - Explore semantic versioning capabilities
• Git Integration - Learn about Git workflow automation
• Monorepo Support - Manage multiple packages
• Advanced Usage - Cross-platform considerations