or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdconfiguration.mdindex.mdrelease-types.mdversion-bumping.md
tile.json

version-bumping.mddocs/

Version Bumping

Core version bumping functionality providing multiple operation modes including interactive prompts, explicit version specification, and full configuration control with git integration.

Capabilities

Version Bump Function

Main function for performing version bumps with multiple overloads for different use cases.

/**
 * Prompts the user for a version number and updates package.json and other files
 * @returns Promise resolving to version bump results
 */
function versionBump(): Promise<VersionBumpResults>;

/**
 * Bumps the version using a specific release type or version number
 * @param release - Version string (e.g., "1.2.3") or release type (e.g., "patch", "major")
 * @returns Promise resolving to version bump results
 */
function versionBump(release: string): Promise<VersionBumpResults>;

/**
 * Bumps the version with full configuration options
 * @param options - Complete configuration object for the version bump operation
 * @returns Promise resolving to version bump results
 */
function versionBump(options: VersionBumpOptions): Promise<VersionBumpResults>;

Usage Examples:

import { versionBump } from "bumpp";

// Interactive prompting
const result = await versionBump();

// Explicit patch bump
const result = await versionBump("patch");

// Major version bump
const result = await versionBump("major");

// Specific version
const result = await versionBump("2.1.0");

// With full configuration
const result = await versionBump({
  release: "minor",
  commit: "chore: bump version to %s",
  tag: "v%s",
  push: true,
  files: ["package.json", "src/version.ts", "README.md"]
});

Version Bump Info Function

Returns operation information without performing the actual version bump, useful for dry-runs and validation.

/**
 * Analyzes version bump operation without executing it
 * @param arg - Version string or options object
 * @returns Promise resolving to operation details
 */
function versionBumpInfo(arg: VersionBumpOptions | string = {}): Promise<Operation>;

Usage Examples:

import { versionBumpInfo } from "bumpp";

// Check what a patch bump would do
const operation = await versionBumpInfo("patch");
console.log(`Would bump from ${operation.state.currentVersion} to ${operation.state.newVersion}`);

// Dry run with options
const operation = await versionBumpInfo({
  release: "minor",
  files: ["package.json", "version.json"]
});

Operation State Management

The Operation class manages version bump state and configuration throughout the process.

class Operation {
  options: NormalizedOptions;
  readonly state: Readonly<OperationState>;
  readonly results: VersionBumpResults;
  
  static start(input: VersionBumpOptions): Promise<Operation>;
  update(newState: Partial<OperationState>): Operation;
}

interface OperationState {
  release: ReleaseType | undefined;
  currentVersionSource: string;
  currentVersion: string;
  newVersion: string;
  commitMessage: string;
  tagName: string;
  updatedFiles: string[];
  skippedFiles: string[];
}

Release Type Processing

Semantic Versioning Support

Supports all standard semantic versioning release types plus extended types for conventional commits and next releases.

Standard Release Types:

  • "major" - Breaking changes (1.0.0 → 2.0.0)
  • "minor" - New features (1.0.0 → 1.1.0)
  • "patch" - Bug fixes (1.0.0 → 1.0.1)

Prerelease Types:

  • "premajor" - Prerelease major (1.0.0 → 2.0.0-0)
  • "preminor" - Prerelease minor (1.0.0 → 1.1.0-0)
  • "prepatch" - Prerelease patch (1.0.0 → 1.0.1-0)
  • "prerelease" - Next prerelease (1.0.0-0 → 1.0.0-1)

Extended Types:

  • "next" - Smart prerelease bumping
  • "conventional" - Version based on conventional commits

Version String Processing

Direct version specification bypasses release type logic and sets the exact version.

// Direct version specification
await versionBump("3.2.1");
await versionBump("1.0.0-beta.5");
await versionBump("2.0.0-rc.1");

File Update Management

Default File Patterns

By default, bumpp updates these files when found:

  • package.json - NPM package manifest
  • package-lock.json - NPM lockfile
  • packages/**/package.json - Monorepo package manifests (when recursive mode is used)
  • jsr.json - JSR package manifest
  • jsr.jsonc - JSR package manifest with comments
  • deno.json - Deno configuration
  • deno.jsonc - Deno configuration with comments

Custom File Updates

Specify additional files to update with the version number:

await versionBump({
  release: "patch",
  files: [
    "package.json",
    "src/version.ts",     // Custom version file
    "README.md",          // Documentation
    "docker-compose.yml", // Docker configuration
    "chart/Chart.yaml"    // Helm chart
  ]
});

Smart File Processing

bumpp intelligently handles different file types:

  • JSON files: Updates version field
  • Other files: Performs global string replacement of old version with new version

Git Integration

Commit Creation

Automatic git commit creation with customizable messages:

await versionBump({
  release: "patch",
  commit: true,                    // Default: "release v{version}"
  commit: "chore: bump to %s",     // Custom format with placeholder
  commit: "Version bump to 1.2.3", // Explicit message
});

Tag Creation

Git tag creation with flexible formatting:

await versionBump({
  release: "minor",
  tag: true,           // Default: "v{version}"
  tag: "release-%s",   // Custom format
  tag: "v1.2.0",       // Explicit tag name
});

Signing Support

Sign commits and tags with configured GPG/SSH keys:

await versionBump({
  release: "patch",
  commit: true,
  tag: true,
  sign: true  // Signs both commit and tag
});

Push Operations

Automatic pushing of commits and tags to remote repository:

await versionBump({
  release: "patch",
  commit: true,
  tag: true,
  push: true  // Pushes commit and tag
});

Monorepo Support

Recursive Bumping

Enable recursive version bumping across multiple packages in a monorepo:

await versionBump({
  release: "patch",
  recursive: true  // Finds and updates all package.json files
});

When recursive: true, bumpp:

  1. Searches for all package.json files in subdirectories
  2. Updates each package's version
  3. Creates a single commit with all changes
  4. Applies consistent tagging and pushing

Monorepo Considerations

  • Works only when files option is not explicitly set
  • Respects .gitignore patterns when searching for packages
  • Maintains consistent versioning across all packages
  • Creates unified commit messages referencing all updated packages

Custom Execution Hooks

Pre-commit Execution

Execute custom commands or functions before committing:

// String command
await versionBump({
  release: "patch",
  execute: "npm run build && npm test"
});

// Function execution
await versionBump({
  release: "patch",
  execute: async (operation) => {
    console.log(`Building version ${operation.state.newVersion}`);
    await runBuild();
    await runTests();
  }
});

NPM Script Integration

Automatic execution of NPM lifecycle scripts:

  • preversion - Runs before version change
  • version - Runs after version change, before commit
  • postversion - Runs after commit and tag creation
await versionBump({
  release: "patch",
  ignoreScripts: false  // Default: run lifecycle scripts
});

Progress Tracking

Progress Callbacks

Monitor version bump progress with custom callbacks:

await versionBump({
  release: "patch",
  progress: (progress) => {
    switch (progress.event) {
      case "file updated":
        console.log(`Updated ${progress.updatedFiles.slice(-1)[0]}`);
        break;
      case "git commit":
        console.log("Created git commit");
        break;
      case "git tag":
        console.log("Created git tag");
        break;
      case "git push":
        console.log("Pushed to remote");
        break;
    }
  }
});

Progress Events

Available progress events:

  • "file updated" - A file was successfully updated
  • "file skipped" - A file was skipped (no changes needed)
  • "git commit" - Git commit was created
  • "git tag" - Git tag was created
  • "git push" - Changes were pushed to remote
  • "npm script" - NPM lifecycle script was executed

Error Handling

Common Error Scenarios

bumpp handles various error conditions:

  • Dirty working directory: Prevents operation unless noGitCheck: true
  • No git repository: Disables git operations automatically
  • Invalid version strings: Validates version format before processing
  • File permission errors: Reports which files couldn't be updated
  • Git operation failures: Provides detailed error messages for commit/tag/push failures

Error Recovery

try {
  const result = await versionBump("patch");
  console.log(`Successfully bumped to ${result.newVersion}`);
} catch (error) {
  console.error("Version bump failed:", error.message);
  // Operation is atomic - no partial updates on failure
}