### TypeScript Configuration File Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/configuration.md

Use this example to create a `bump.config.ts` file for detailed configuration. It covers version settings, files to update, Git operations, pre-bump setup, execution commands, and custom version logic.

```typescript
import { defineConfig } from 'bumpp'

export default defineConfig({
  // Version settings
  release: 'prompt',        // or 'major', 'minor', 'patch', etc.
  preid: 'beta',            // Prerelease identifier

  // Files to update
  files: [
    'package.json',
    'package-lock.json',
    'README.md',
    'src/version.ts'
  ],
  recursive: false,         // Bump monorepo packages

  // Git operations
  commit: 'chore: release v%s',
  tag: 'v%s',
  push: true,
  sign: false,

  // Pre-bump setup
  noGitCheck: false,        // Check git is clean
  noVerify: false,          // Run git hooks
  all: false,               // Include all files in commit

  // Execution
  execute: 'npm run build',
  install: false,
  ignoreScripts: false,

  // Behavior
  confirm: true,            // Ask before bumping
  printCommits: true,       // Show recent commits

  // Custom version function
  customVersion: (current) => {
    // Return custom version logic
    return `${current}-custom`
  }
})
```

--------------------------------

### Read Text File Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/file-system.md

Reads a text file from a specified directory and logs its path and content. Ensure 'bumpp' is installed.

```typescript
import { readTextFile } from 'bumpp'

const file = await readTextFile('README.md', process.cwd())
console.log('File path:', file.path)
console.log('File contents:', file.data)
```

--------------------------------

### JavaScript Configuration File Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/config.md

Example of a `bump.config.js` file defining files, push, and commit options.

```javascript
// bump.config.js
module.exports = {
  files: ['package.json'],
  push: true,
  commit: true,
}
```

--------------------------------

### Bumpp Operation Lifecycle Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/utility-functions.md

Illustrates the typical lifecycle of a Bumpp operation, from starting an operation and detecting versions to updating files, performing Git operations, and pushing to a remote.

```typescript
// 1. Create operation
const operation = await Operation.start(options)

// 2. Detect current version
await getCurrentVersion(operation)

// 3. Determine new version
await getNewVersion(operation, commits)

// 4. Optional: Pre-version script
await runNpmScript(NpmScript.PreVersion, operation)

// 5. Update files
await updateFiles(operation)

// 6. Optional: Version script
await runNpmScript(NpmScript.Version, operation)

// 7. Git operations
await gitCommit(operation)
await gitTag(operation)

// 8. Optional: Post-version script
await runNpmScript(NpmScript.PostVersion, operation)

// 9. Push to remote
await gitPush(operation)

// 10. Return results
return operation.results
```

--------------------------------

### JSON Configuration File Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/config.md

Example of a `bump.config.json` file specifying files, commit message, tag format, and push option.

```json
{
  "files": ["package.json", "package-lock.json"],
  "commit": "chore: bump version to %s",
  "tag": "v%s",
  "push": true
}
```

--------------------------------

### Operation.start()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/operation.md

Creates and initializes a new Operation instance from user-provided options. This is the primary way to start a version bumping operation.

```APIDOC
## Operation.start()

### Description
Creates and initializes a new operation from user options.

### Method
`public static async start(input: VersionBumpOptions): Promise<Operation>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **input** (VersionBumpOptions) - Required - Raw version bump options

### Request Example
```typescript
import { Operation } from 'bumpp'
type { VersionBumpOptions } from 'bumpp'

const options: VersionBumpOptions = {
  release: 'minor',
  files: ['package.json']
}

const operation = await Operation.start(options)
console.log('Current version:', operation.state.currentVersion)
console.log('Options:', operation.options)
```

### Response
#### Success Response (Promise<Operation>)
* **Operation** - A new initialized Operation instance

#### Response Example
(See Request Example for usage)
```

--------------------------------

### Read JSONC File Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/file-system.md

Reads a JSON or JSONC file, parses its content, and logs specific properties. Ensure 'bumpp' is installed.

```typescript
import { readJsoncFile } from 'bumpp'

const file = await readJsoncFile('package.json', process.cwd())
console.log('Name:', file.data.name)
console.log('Version:', file.data.version)

// File is parsed but not modified yet
// Use writeJsoncFile() to apply changes
```

--------------------------------

### Bumpp CLI Usage Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Illustrates the basic command structure for the Bumpp CLI, showing how to specify a release type and target files. Includes a list of available options for customization.

```bash
bumpp [release] [files...]

Options:
  --preid <id>              Prerelease ID (default: beta)
  -c, --commit [msg]        Commit message (default: true)
  -t, --tag [name]          Tag name (default: v%s)
  -p, --push                Push to remote (default: true)
  -a, --all                 Include all files (default: false)
  --sign                    Sign commits (default: false)
  --install                 Run npm install (default: false)
  -r, --recursive           Bump monorepo (default: false)
  -y, --yes                 Skip confirmation (default: false)
  -q, --quiet               Quiet output (default: false)
  --git-check               Check git clean (default: true)
  --verify                  Run git hooks (default: true)
  --ignore-scripts          Skip npm scripts (default: false)
  --print-commits           Show commits (default: true)
  --current-version <ver>   Override version
  -x, --execute <cmd>       Command to execute
  --release <type>          Release type or version
  --configFilePath <path>   Config file path
  --help                    Show help
  --version                 Show version
```

--------------------------------

### Write JSONC File Example (Preserving Comments)

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/file-system.md

Demonstrates modifying a JSON/JSONC file while preserving original formatting, comments, and indentation. Requires 'bumpp' to be installed.

```typescript
import { readJsoncFile, writeJsoncFile } from 'bumpp'

// Read package.json with comments
const file = await readJsoncFile('package.json', process.cwd())

// Queue up modifications (doesn't modify yet)
file.modified.push([['version'], '2.0.0'])
file.modified.push([['description'], 'New description'])

// Write back with all formatting preserved
await writeJsoncFile(file)
```

--------------------------------

### TypeScript Configuration File Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/config.md

Example of a `bump.config.ts` file using `defineConfig` to specify files, pre-release ID, commit message, and tag format.

```typescript
// bump.config.ts
import { defineConfig } from 'bumpp'

export default defineConfig({
  files: ['package.json', 'src/version.ts'],
  preid: 'beta',
  commit: 'chore: release %s',
  tag: 'v%s',
})
```

--------------------------------

### Package-lock.json Version Update Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/manifest.md

Shows the update process for both the top-level '.version' and '.packages[""].version' fields in package-lock.json.

```json
{
  "version": "1.0.0",
  "packages": {
    "": {
      "version": "1.0.0"
    }
  }
}
```

```json
{
  "version": "1.1.0",
  "packages": {
    "": {
      "version": "1.1.0"
    }
  }
}
```

--------------------------------

### Write Text File Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/file-system.md

Reads a text file, modifies its content, and writes the changes back to the file. Requires 'bumpp' to be installed.

```typescript
import { readTextFile, writeTextFile } from 'bumpp'

const file = await readTextFile('README.md', process.cwd())
file.data = file.data.replace(/v1.0.0/g, 'v1.1.0')
await writeTextFile(file)
```

--------------------------------

### Example Usage of gitTag

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/git.md

Illustrates the usage of the gitTag function in conjunction with gitCommit. This example shows setting up tag options and logging tag creation events.

```typescript
import { Operation, ProgressEvent } from 'bumpp'

const operation = await Operation.start({
  release: 'patch',
  tag: 'v%s',
  commit: 'chore: release v%s',
  progress: (progress) => {
    if (progress.event === ProgressEvent.GitTag) {
      console.log('Tagged as:', progress.tag)
    }
  }
})

// ... version bumping ...

await gitCommit(operation)
await gitTag(operation)
```

--------------------------------

### Non-Manifest File Version Update Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/manifest.md

Demonstrates global search-and-replace for version updates in files like README.md or changelogs.

```markdown
# Version 1.0.0

Current version: 1.0.0
```

```markdown
# Version 1.1.0

Current version: 1.1.0
```

--------------------------------

### CommonJS Import Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/module-exports.md

Example of importing from 'bumpp' in Node.js CommonJS environments or when TypeScript is compiled to CommonJS.

```javascript
// Node.js CommonJS or TypeScript compiled to CommonJS
const { versionBump } = require('bumpp')
```

--------------------------------

### Package.json Version Update Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/manifest.md

Illustrates how the top-level 'version' field in package.json is updated.

```json
{
  "name": "my-package",
  "version": "1.0.0"
}
```

```json
{
  "name": "my-package",
  "version": "1.1.0"
}
```

--------------------------------

### Run npm Install After Bumping

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/configuration.md

Automatically run `npm install` (or equivalent for other package managers) after the version bump process is complete.

```typescript
bumpp({ install: true })
```

--------------------------------

### Install Dependencies After Bump

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/advanced-usage.md

Automatically run 'npm install' after bumping the version by setting the 'install' option to true. This ensures dependencies are updated correctly following the version change.

```typescript
import { versionBump } from 'bumpp'

const result = await versionBump({
  release: 'minor',
  execute: 'npm run build',  // Build before commit
  install: true              // Run npm install after bumping
})
```

--------------------------------

### Start a New Operation

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/operation.md

Use `Operation.start()` to create and initialize a new operation instance with user-provided options. This method takes `VersionBumpOptions` and returns a `Promise<Operation>`.

```typescript
import { Operation } from 'bumpp'
import type { VersionBumpOptions } from 'bumpp'

const options: VersionBumpOptions = {
  release: 'minor',
  files: ['package.json']
}

const operation = await Operation.start(options)
console.log('Current version:', operation.state.currentVersion)
console.log('Options:', operation.options)
```

--------------------------------

### Tree-Shaking Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/module-exports.md

Demonstrates how unused exports like defineConfig are removed by bundlers, ensuring only necessary code is included in the bundle.

```typescript
import { versionBump } from 'bumpp'
// Only versionBump and its dependencies are included in bundle
// defineConfig, loadBumpConfig, etc. are tree-shaken away

```

--------------------------------

### Example Usage of gitCommit

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/git.md

Demonstrates how to use the gitCommit function within an Operation. It shows setting up commit options and handling progress events.

```typescript
import { Operation, ProgressEvent } from 'bumpp'

const operation = await Operation.start({
  release: 'minor',
  commit: 'chore: bump version to %s',
  progress: (progress) => {
    if (progress.event === ProgressEvent.GitCommit) {
      console.log('Committed:', progress.commit)
    }
  }
})

// ... version bumping ...

await gitCommit(operation)
```

--------------------------------

### Configuration File Setup

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/module-exports.md

Defines configuration for Bumpp using a config file, specifying files to update, commit message, and tag format.

```typescript
// bump.config.ts
import { defineConfig } from 'bumpp'
import type { VersionBumpOptions } from 'bumpp'

export default defineConfig({
  files: ['package.json', 'README.md'],
  commit: 'chore: release v%s',
  tag: 'v%s'
} satisfies VersionBumpOptions)

```

--------------------------------

### ESM Import Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/module-exports.md

Example of importing from 'bumpp' in Node.js environments with `"type": "module"` set in `package.json`.

```typescript
// Node.js with "type": "module" in package.json
import { versionBump } from 'bumpp'
```

--------------------------------

### Example Usage of gitPush

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/git.md

Shows how to use the gitPush function to send local commits and tags to the remote repository. This example includes enabling the push option and logging push events.

```typescript
import { Operation, ProgressEvent } from 'bumpp'

const operation = await Operation.start({
  release: 'minor',
  push: true,
  progress: (progress) => {
    if (progress.event === ProgressEvent.GitPush) {
      console.log('Pushed to remote')
    }
  }
})

// ... version bumping and commits ...

await gitPush(operation)
```

--------------------------------

### Programmatic Version Bumping Examples

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/configuration.md

Demonstrates programmatic usage of the `bumpp` function for setting the release type or an explicit version number.

```typescript
bumpp({ release: 'minor' })
bumpp({ release: '2.0.0' })
```

--------------------------------

### Git Tag Command Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/git.md

Shows the bash command executed by gitTag for creating an annotated tag. It includes options for the message and signing.

```bash
git tag \
  --annotate \
  --message "chore: release v1.2.3" \
  [--sign] \
  v1.2.3
```

--------------------------------

### Git Commit Command Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/git.md

Illustrates the bash command executed by gitCommit, showing optional flags for committing all files, bypassing hooks, signing, and specifying the commit message.

```bash
git commit \
  --allow-empty \
  [--all] \
  [--no-verify] \
  [--gpg-sign] \
  --message "chore: release v1.2.3" \
  [file1 file2 ...]
```

--------------------------------

### Path Resolution Examples

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/file-system.md

Illustrates how file paths are resolved relative to the current working directory (cwd) for different file system operations.

```typescript
// Resolves to /home/user/project/package.json
await readJsoncFile('package.json', '/home/user/project')
```

```typescript
// Resolves to /home/user/project/src/version.ts
await readTextFile('src/version.ts', '/home/user/project')
```

--------------------------------

### Environment-Based Configuration

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/advanced-usage.md

Configure Bumpp dynamically based on environment variables. This example sets options like 'release', 'confirm', 'push', 'sign', and 'printCommits' based on 'NODE_ENV' and 'CI' variables, and conditionally includes files.

```typescript
// bump.config.ts
import { defineConfig } from 'bumpp'
import type { VersionBumpOptions } from 'bumpp'

const isDev = process.env.NODE_ENV === 'development'
const isCI = process.env.CI === 'true'

export default defineConfig({
  // Always prompt in development
  release: isDev ? 'prompt' : 'conventional',
  
  // Skip confirmation in CI
  confirm: !isCI,
  
  // Only push from CI on main
  push: isCI && process.env.CI_COMMIT_BRANCH === 'main',
  
  // Sign commits in secure environment
  sign: !isDev && isCI,
  
  // Verbose output in development
  printCommits: isDev,
  
  files: [
    'package.json',
    'package-lock.json',
    'README.md',
    isDev && 'src/version.ts'  // Only in dev
  ].filter(Boolean)
} as VersionBumpOptions)
```

--------------------------------

### Git Push Commands Example

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/git.md

Displays the bash commands executed by gitPush: one for pushing commits and another for pushing tags if enabled.

```bash
git push                    # Push commits
git push --tags            # Push tags (if enabled)
```

--------------------------------

### CLI Arguments for Options

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/configuration.md

Configure various bumpp options like commit messages, tags, push behavior, signing, installation, monorepo mode, confirmation, and script execution via CLI flags.

```bash
# Options
bumpp --commit "chore: release %s"
bumpp --tag "v%s"
bumpp --no-push                 # Disable push
bumpp --sign                     # Sign commits
bumpp --install                 # Run npm install
bumpp --recursive               # Monorepo mode
bumpp --yes                      # Skip confirmation
bumpp --quiet                    # Suppress output
bumpp --print-commits            # Show commits
bumpp --execute "npm run build"  # Execute command
bumpp --current-version "1.0.0"  # Override version
```

--------------------------------

### TypeScript Example with Type Checking

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/module-exports.md

Demonstrates using TypeScript with bumpp, including type checking for options and results. All exported types are available via `import type` for better tree-shaking.

```typescript
import { versionBump, defineConfig } from 'bumpp'
import type { VersionBumpOptions, VersionBumpResults } from 'bumpp'

// With type checking
const options: VersionBumpOptions = {
  release: 'minor',
  push: true
}

const results: VersionBumpResults = await versionBump(options)
```

```typescript
import type { ReleaseType, ProgressEvent } from 'bumpp'
```

--------------------------------

### Build Before Commit

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/advanced-usage.md

Integrate build steps before committing by specifying an 'execute' script. This example runs 'npm run build' and logs a success message upon completion via the 'progress' callback.

```typescript
import { versionBump } from 'bumpp'

const result = await versionBump({
  release: 'minor',
  execute: 'npm run build',  // Build before commit
  progress: (p) => {
    if (p.event === 'npm script') {
      console.log('✔ Build completed')
    }
  }
})
```

--------------------------------

### Default Bumpp Configuration Object

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/configuration.md

Illustrates the default values for various bumpp configuration options, including commit, push, tag, sign, install, and file handling.

```typescript
const bumpConfigDefaults = {
  commit: true,
  push: true,
  tag: true,
  sign: false,
  install: false,
  recursive: false,
  noVerify: false,
  confirm: true,
  ignoreScripts: false,
  all: false,
  noGitCheck: true,
  files: [],                  // Auto-detect
  configFilePath: undefined,  // Auto-detect
}
```

--------------------------------

### CLI Usage - Interactive

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Running `npx bumpp` without any arguments initiates an interactive version bumping process. The CLI will guide you through selecting the release type, confirming changes, and executing Git operations.

```APIDOC
## CLI Usage - Interactive

### Description

Running `npx bumpp` without any arguments initiates an interactive version bumping process. The CLI will guide you through selecting the release type, confirming changes, and executing Git operations.

### Command

```bash
npx bumpp
```

### Usage

Execute the command in your project's root directory. The CLI will prompt you for input.

### Example Interaction

```
? What is the next release type? (Use arrow keys)
❯ major (1.0.0 => 2.0.0)
  minor (1.0.0 => 1.1.0)
  patch (1.0.0 => 1.0.1)
  ... (other types)

? Commit message? (chore: release v2.0.0)

? Tag name? (v2.0.0)

? Push to remote? (yes/no)
```
```

--------------------------------

### Get Current Version from Manifest

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/utility-functions.md

Detects the current version number from manifest files like package.json, deno.json, or deno.jsonc. Reads JSON manifest files looking for a valid semantic version in the 'version' field. Returns immediately if version is already set.

```typescript
import { Operation, getCurrentVersion } from 'bumpp'

const operation = await Operation.start({
  files: ['package.json'],
  cwd: process.cwd()
})

await getCurrentVersion(operation)
console.log('Current version:', operation.state.currentVersion)
console.log('Source file:', operation.state.currentVersionSource)
```

--------------------------------

### Main Entry Point - versionBump()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

The `versionBump()` function is the primary entry point for programmatically bumping versions. It can be called with no arguments for interactive bumping, a specific version string, a release type, or a detailed options object for full control over the bumping process.

```APIDOC
## `versionBump()`

### Description

The `versionBump()` function is the primary entry point for programmatically bumping versions. It can be called with no arguments for interactive bumping, a specific version string, a release type, or a detailed options object for full control over the bumping process.

### Method

`versionBump(release?: string | ReleaseType, options?: VersionBumpOptions): Promise<VersionBumpResults>`

### Parameters

#### Arguments

- **release** (string | ReleaseType) - Optional - The release type (e.g., 'major', 'minor', 'patch', '2.0.0') or a specific version string to bump to.
- **options** (VersionBumpOptions) - Optional - An object to configure the bumping process, including commit messages, tags, push behavior, files to update, and more.

### Request Example

```typescript
// Bump with defaults (interactive)
const result = await versionBump()

// Bump to specific version
const result = await versionBump('2.0.0')

// Bump by release type
const result = await versionBump('minor')

// Full control
const result = await versionBump({
  release: 'minor',
  commit: 'chore: release v%s',
  tag: 'v%s',
  push: true
})
```

### Response

#### Success Response

- **VersionBumpResults** - An object containing details about the version bump operation.
  - **release** (ReleaseType) - Optional - The release type used for the bump.
  - **currentVersion** (string) - The version before the bump.
  - **newVersion** (string) - The version after the bump.
  - **commit** (string | false) - The commit message used, or false if no commit was made.
  - **tag** (string | false) - The tag name created, or false if no tag was created.
  - **updatedFiles** (string[]) - An array of files that were modified.
  - **skippedFiles** (string[]) - An array of files that were skipped.

#### Response Example

```json
{
  "release": "minor",
  "currentVersion": "1.0.0",
  "newVersion": "1.1.0",
  "commit": "chore: release v1.1.0",
  "tag": "v1.1.0",
  "updatedFiles": ["package.json"],
  "skippedFiles": []
}
```
```

--------------------------------

### main()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/INDEX.md

CLI entry point for the Bumpp command-line interface.

```APIDOC
## main()

### Description
CLI entry point for the Bumpp command-line interface. Parses arguments and executes the version bumping process.

### Method
(Not specified, typically invoked from the command line)

### Parameters
#### Path Parameters
(Not applicable)

#### Query Parameters
(Not applicable)

#### Request Body
(Not applicable)

### Request Example
```bash
npx bumpp patch
```

### Response
(Not specified, typically exits with a status code)
#### Success Response
(Not specified)

#### Response Example
(Not specified)
```

--------------------------------

### main()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/cli.md

The main entry point for the CLI. It parses arguments, checks git status, calls versionBump(), and handles errors.

```APIDOC
## main()

### Description
The main entry point for the CLI. This is called by the `bumpp` binary and handles argument parsing, error handling, and orchestrating the version bump process.

### Method
async

### Signature
`export async function main(): Promise<void>`

### Parameters
None

### Returns
`Promise<void>` — Resolves when the CLI process is complete; exits on success or error

### Details
1. Parses command-line arguments
2. Optionally checks git working tree status (unless `--all` or `--git-check=false`)
3. Calls `versionBump()` with parsed options
4. Handles all errors and exits with appropriate code

### Exit Codes
- `0` — Success
- `1` — Fatal error
- `9` — Invalid argument

### Error Handling
Uncaught exceptions and unhandled rejections are caught and logged to stderr. If `DEBUG` or `NODE_ENV=development` is set, full stack traces are shown.

### Example
```typescript
import { main } from 'bumpp/cli'

main().catch(() => {
  // Already handled by main()
})
```
```

--------------------------------

### Main Entry Point - Bump with Defaults

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Use the `versionBump` function with no arguments to perform an interactive bump using default settings.

```typescript
import { versionBump } from 'bumpp'

// Bump with defaults (interactive)
const result = await versionBump()
```

--------------------------------

### Main Entry Point - Full Control

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Provide a configuration object to `versionBump` for fine-grained control over release type, commit messages, tagging, and pushing.

```typescript
// Full control
const result = await versionBump({
  release: 'minor',
  commit: 'chore: release v%s',
  tag: 'v%s',
  push: true
})
```

--------------------------------

### Main Entry Point - Bump to Specific Version

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Call `versionBump` with a specific version string to bump to that exact version.

```typescript
// Bump to specific version
const result = await versionBump('2.0.0')
```

--------------------------------

### Main Entry Point - Bump by Release Type

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Use `versionBump` with a release type string (e.g., 'minor') to perform a semantically versioned bump.

```typescript
// Bump by release type
const result = await versionBump('minor')
```

--------------------------------

### CLI Usage - With Options

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

You can combine release type specification with various flags and options to customize the bumping process directly from the command line, overriding configuration file settings.

```APIDOC
## CLI Usage - With Options

### Description

You can combine release type specification with various flags and options to customize the bumping process directly from the command line, overriding configuration file settings.

### Command

```bash
npx bumpp [release-type | version] [options]
```

### Options

- `--commit <message>`: Set a custom commit message. Use `%s` for the version.
- `--no-commit`: Disable commit creation.
- `--tag <tag>`: Set a custom tag name. Use `%s` for the version.
- `--no-tag`: Disable tag creation.
- `--push`: Push commits and tags to the remote repository.
- `--no-push`: Disable pushing to the remote repository.
- `--files <files...>`: Specify files to update.
- `--no-confirm`: Skip user confirmation prompts.
- `--quiet`: Enable quiet mode with minimal output.
- `--recursive`: Enable monorepo support.
- `--preid <id>`: Specify the pre-release identifier (e.g., `alpha`, `beta`).

### Usage

Append options as flags after the release type or version argument.

### Example

```bash
# Bump minor version, disable push, and disable commit
npx bumpp minor --no-push --no-commit

# Bump to version 1.2.3, enable push, and use a custom tag
npx bumpp 1.2.3 --push --tag "release-v%s"

# Bump patch version with a specific pre-release id
npx bumpp patch --preid beta
```
```

--------------------------------

### Version Detection Only

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Use `versionBumpInfo` to get information about a potential version bump without modifying any files. This is useful for previewing changes or in automated workflows.

```typescript
// Get version info without making changes
const op = await versionBumpInfo('minor')

console.log('Would bump:', op.state.currentVersion, '->', op.state.newVersion)
console.log('Files affected:', op.options.files)
```

--------------------------------

### CLI Usage - Interactive

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Run `npx bumpp` without arguments for an interactive version bumping process.

```bash
# Interactive
npx bumpp
```

--------------------------------

### CLI Arguments for Files and Configuration

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/configuration.md

Specify target files for bumping and provide a custom configuration file path using CLI flags.

```bash
# Files
bumpp --files package.json README.md

# Config
bumpp --configFilePath ./custom.config.ts
```

--------------------------------

### Get JSON Output for Version Bump

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/advanced-usage.md

Obtain structured JSON output from a version bump operation, suitable for consumption by other tools or scripts. This bypasses interactive prompts and direct console logging.

```typescript
import { versionBump } from 'bumpp'

const result = await versionBump({
  release: 'minor',
  confirm: false
})

// Output JSON for consumption by other tools
console.log(JSON.stringify({
  success: true,
  from: result.currentVersion,
  to: result.newVersion,
  release: result.release,
  commit: result.commit,
  tag: result.tag,
  updatedFiles: result.updatedFiles,
  skippedFiles: result.skippedFiles,
  timestamp: new Date().toISOString()
}, null, 2))
```

--------------------------------

### Get Operation Results

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/operation.md

Access the final results of a version bumping operation using the `results` getter. This transforms the internal state into a user-facing format, indicating whether commit and tag actions were performed.

```typescript
const operation = await versionBumpInfo('minor')
const results = operation.results
console.log('Bumped:', results.currentVersion, '->', results.newVersion)
console.log('Files to update:', results.updatedFiles.length)
```

--------------------------------

### loadBumpConfig()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/INDEX.md

Loads configuration from a file.

```APIDOC
## loadBumpConfig()

### Description
Loads configuration from a file, typically `bump.config.ts` or `package.json`.

### Method
(Not specified, likely a function call in a JavaScript/TypeScript environment)

### Parameters
#### Path Parameters
(Not applicable)

#### Query Parameters
- **cwd** (string) - Optional - The current working directory to search for the config file.

#### Request Body
(Not applicable)

### Request Example
```javascript
import { loadBumpConfig } from 'bumpp';

const config = await loadBumpConfig({ cwd: './' });
```

### Response
#### Success Response
- **config** (VersionBumpOptions) - The loaded configuration object.

#### Response Example
```json
{
  "files": ["package.json"],
  "commit": true,
  "tag": true
}
```
```

--------------------------------

### Main CLI Entry Point

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/cli.md

The main function orchestrates the CLI process, handling argument parsing, git status checks, and version bumping. It's the entry point called by the bumpp binary.

```typescript
export async function main(): Promise<void>
```

```typescript
import { main } from 'bumpp/cli'

main().catch(() => {
  // Already handled by main()
})
```

--------------------------------

### Recommended Import Paths

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/module-exports.md

Imports core Bumpp functionalities like versionBump and defineConfig from the main export.

```typescript
import { versionBump, defineConfig } from 'bumpp'
import type { VersionBumpOptions } from 'bumpp'

```

--------------------------------

### versionBump()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/INDEX.md

Main API function to bump the version. It takes configuration options and performs the version update.

```APIDOC
## versionBump()

### Description
Main API function to bump the version. It takes configuration options and performs the version update.

### Method
(Not specified, likely a function call in a JavaScript/TypeScript environment)

### Parameters
#### Path Parameters
(Not applicable)

#### Query Parameters
(Not applicable)

#### Request Body
- **options** (VersionBumpOptions) - Optional - Configuration options for version bumping.

### Request Example
```javascript
import { versionBump } from 'bumpp';

await versionBump({
  // configuration options here
});
```

### Response
#### Success Response
- **results** (VersionBumpResults) - The results of the version bumping operation.

#### Response Example
```json
{
  "oldVersion": "1.0.0",
  "newVersion": "1.1.0"
}
```
```

--------------------------------

### CLI Usage - With Options

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Use command-line flags to override configuration, such as disabling push or commit for `npx bumpp`.

```bash
# With options
npx bumpp minor --push=false --no-commit
```

--------------------------------

### CLI Usage - Specific Version

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Provide a target version string to `npx bumpp <version>` to bump to that exact version.

```bash
# Specific version
npx bumpp 2.0.0
```

--------------------------------

### versionBump()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/version-bump.md

Prompts the user for the version number to bump to. This is the simplest way to use the versionBump function, relying on interactive prompts for user input.

```APIDOC
## versionBump()

### Description
Prompts user for version number with no arguments.

### Method
`export async function versionBump(): Promise<VersionBumpResults>`

### Parameters
None

### Returns
`Promise<VersionBumpResults>` — Information about the version bump operation

### Example
```typescript
import { versionBump } from 'bumpp'

const result = await versionBump()
console.log(`Bumped from ${result.currentVersion} to ${result.newVersion}`)
```
```

--------------------------------

### Configuration Loading - defineConfig()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

The `defineConfig()` function is used within your `bump.config.*` file to define and type-check your version bumping configuration. It helps ensure that your configuration options are valid and correctly structured.

```APIDOC
## `defineConfig()`

### Description

The `defineConfig()` function is used within your `bump.config.*` file to define and type-check your version bumping configuration. It helps ensure that your configuration options are valid and correctly structured.

### Method

`defineConfig(options: VersionBumpOptions): VersionBumpOptions`

### Parameters

#### Arguments

- **options** (VersionBumpOptions) - Required - An object containing the configuration options for bumpp.

### Request Example

```typescript
// bump.config.ts
import { defineConfig } from 'bumpp'

export default defineConfig({
  commit: 'chore: release v%s',
  tag: 'v%s',
  push: true,
  files: ['package.json', 'README.md']
})
```

### Response

#### Success Response

- **VersionBumpOptions** - The configuration object, validated and typed.

#### Response Example

```json
{
  "commit": "chore: release v%s",
  "tag": "v%s",
  "push": true,
  "files": ["package.json", "README.md"]
}
```
```

--------------------------------

### Pre-Release Workflow

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

Manage pre-release versions by setting `release: 'prerelease'` and specifying a `preid` like 'alpha'. Push is often disabled to allow local review.

```typescript
await versionBump({
  release: 'prerelease',
  preid: 'alpha',
  push: false,  // Keep local until ready
})
```

--------------------------------

### versionBump(options)

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/version-bump.md

Provides full control over the version bumping process by accepting a configuration object. This allows customization of commit messages, tags, files to update, and more.

```APIDOC
## versionBump(options)

### Description
Bumps version with full control over all options.

### Method
`export async function versionBump(options: VersionBumpOptions): Promise<VersionBumpResults>`

### Parameters
#### Request Body
- **options** (VersionBumpOptions) - Required - Configuration object controlling version bump behavior
  - **release** (string) - Optional - Release version or type
  - **commit** (string) - Optional - Commit message format
  - **tag** (string) - Optional - Tag name format
  - **push** (boolean) - Optional - Whether to push changes to remote
  - **files** (string[]) - Optional - List of files to update
  - **confirm** (boolean) - Optional - Whether to confirm changes interactively
  - **progress** (function) - Optional - Callback function for progress updates

### Returns
`Promise<VersionBumpResults>` — Information about the version bump operation

### Example
```typescript
import { versionBump } from 'bumpp'

const result = await versionBump({
  release: 'minor',
  commit: 'chore: bump version to %s',
  tag: 'v%s',
  push: true,
  files: ['package.json', 'README.md'],
  confirm: true,
  progress: (progress) => {
    console.log(`[${progress.event}] from ${progress.currentVersion} to ${progress.newVersion}`)
  }
})

console.log('Updated files:', result.updatedFiles)
console.log('Skipped files:', result.skippedFiles)
console.log('Commit:', result.commit)
console.log('Tag:', result.tag)
```
```

--------------------------------

### Public API Functions

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/README.md

The main entry point for the Bumpp library provides functions for version bumping and retrieving bump information. It also includes utilities for configuration management and type definitions.

```APIDOC
## Public API

### Description
Provides functions to programmatically bump versions, retrieve information about the bump operation, and manage configuration.

### Functions
- `versionBump(releaseType?: ReleaseType | string, files?: string[], options?: BumpOptions)`: Initiates the version bumping process.
- `versionBumpInfo(options?: BumpOptions)`: Retrieves information about the current bump operation state.
- `defineConfig(config: BumpConfig)`: Defines the configuration for Bumpp.
- `loadBumpConfig(options?: LoadBumpConfigOptions)`: Loads the Bumpp configuration.

### Types
- `VersionBumpProgress`: Information passed to the progress callback during a version bump.
- `VersionBumpResults`: Results of a version bump operation.
- `NpmScript`: Represents an npm script name.
- `ProgressEvent`: Describes the event that just occurred during progress.
- `ReleaseType`: Defines the type of release (e.g., 'major', 'minor', 'patch').
- `BumpOptions`: Options for configuring the version bump operation.
- `BumpConfig`: Configuration object for Bumpp.
- `LoadBumpConfigOptions`: Options for loading the bump configuration.

### Example
```typescript
import { versionBump } from 'bumpp'

try {
  await versionBump('minor')
} catch (error) {
  console.error('Version bump failed:', error.message)
}
```
```

--------------------------------

### Read Version from package.json

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/manifest.md

Demonstrates how to read the version from a package.json file using bumpp's utility functions. Ensure the file exists in the specified directory.

```typescript
import { readJsoncFile, isManifest } from 'bumpp'

const file = await readJsoncFile('package.json', process.cwd())

if (isManifest(file.data)) {
  console.log('Current version:', file.data.version)
}
```

--------------------------------

### parseArgs()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/cli.md

Parses command-line arguments and loads configuration for the bumpp CLI.

```APIDOC
## parseArgs()

### Description
Parses command-line arguments and loads configuration.

### Method
async

### Signature
`export async function parseArgs(): Promise<ParsedArgs>`

### Parameters
None (uses `process.argv`)

### Returns
`Promise<ParsedArgs>` — Parsed CLI arguments and loaded configuration

### ParsedArgs Type
```typescript
interface ParsedArgs {
  help?: boolean
  version?: boolean
  quiet?: boolean
  options: VersionBumpOptions
}
```

| Field | Type | Description |
|-------|------|-------------|
| help | boolean | True if `--help` was passed |
| version | boolean | True if `--version` was passed |
| quiet | boolean | True if `--quiet` was passed |
| options | VersionBumpOptions | Fully resolved bump configuration |

### Argument Parsing Rules

1. First positional argument (after flags) is checked: if it's a valid release type or version, it's treated as `release`
2. Remaining positional arguments are treated as `files`
3. Configuration file is loaded (auto-detected or from `--configFilePath`)
4. CLI arguments override config file values, which override defaults

### Example
```typescript
import { parseArgs } from 'bumpp/cli'

const parsed = await parseArgs()
console.log('Help:', parsed.help)
console.log('Version:', parsed.version)
console.log('Release:', parsed.options.release)
console.log('Files:', parsed.options.files)
```
```

--------------------------------

### VersionBumpOptions Interface

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/types.md

Configuration object for the `versionBump()` function. Customize release type, commit/tag behavior, file updates, and more.

```typescript
export interface VersionBumpOptions {
  release?: string
  currentVersion?: string
  preid?: string
  commit?: boolean | string
  tag?: boolean | string
  sign?: boolean
  push?: boolean
  install?: boolean
  all?: boolean
  noGitCheck?: boolean
  confirm?: boolean
  noVerify?: boolean
  files?: string[]
  cwd?: string
  interface?: boolean | InterfaceOptions
  ignoreScripts?: boolean
  progress?: (progress: VersionBumpProgress) => void
  execute?: string | ((config: Operation) => void | PromiseLike<void>)
  recursive?: boolean
  printCommits?: boolean
  configFilePath?: string
  customVersion?: (currentVersion: string, semver: typeof _semver) => Promise<string | void> | string | void
}
```

--------------------------------

### Enable GPG/SSH Signing for Commits and Tags

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/configuration.md

Sign commits and tags using your configured GPG or SSH key. Requires prior Git configuration for signing.

```typescript
bumpp({ sign: true })
```

--------------------------------

### checkGitStatus()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/cli.md

Verifies that the git working directory is clean before proceeding with a version bump.

```APIDOC
## checkGitStatus()

### Description
Verifies that the git working directory is clean.

### Method
async

### Signature
`export async function checkGitStatus(): Promise<void>`

### Parameters
None

### Returns
`Promise<void>` — Resolves if working tree is clean; throws if not

### Throws
`Error` with message containing `git status --porcelain` output if working directory has uncommitted changes

### Details
Runs `git status --porcelain` and throws an error if any output is produced, indicating a non-empty working directory.

### Example
```typescript
import { checkGitStatus } from 'bumpp/cli'

try {
  await checkGitStatus()
  console.log('Git working tree is clean')
} catch (error) {
  console.error('Git has uncommitted changes:', error.message)
}
```
```

--------------------------------

### Parse CLI Arguments and Load Configuration

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/cli.md

Parses command-line arguments from `process.argv` and loads configuration, applying specific rules for argument precedence. Returns parsed arguments and resolved options.

```typescript
export async function parseArgs(): Promise<ParsedArgs>
```

```typescript
import { parseArgs } from 'bumpp/cli'

const parsed = await parseArgs()
console.log('Help:', parsed.help)
console.log('Version:', parsed.version)
console.log('Release:', parsed.options.release)
console.log('Files:', parsed.options.files)
```

--------------------------------

### All Release Types Constant

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/release-type.md

An array containing all possible release type strings, including standard, prerelease, 'next', and 'conventional'.

```typescript
export const releaseTypes: ReleaseType[] = [
  'premajor',
  'preminor',
  'prepatch',
  'prerelease',
  'major',
  'minor',
  'patch',
  'next',
  'conventional'
]
```

--------------------------------

### runNpmScript()

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/INDEX.md

Runs an npm lifecycle script.

```APIDOC
## runNpmScript()

### Description
Runs an npm lifecycle script (e.g., 'prepublish', 'postversion') as defined in `package.json`.

### Method
(Not specified, likely a function call in a JavaScript/TypeScript environment)

### Parameters
#### Path Parameters
(Not applicable)

#### Query Parameters
(Not applicable)

#### Request Body
- **script** (NpmScript) - The name of the npm script to run.
- **options** (object) - Optional - Configuration options.
  - **cwd** (string) - The current working directory.

### Request Example
```javascript
import { runNpmScript } from 'bumpp/utility-functions';

await runNpmScript('postversion', { cwd: './' });
```

### Response
#### Success Response
(No explicit return value, indicates success by not throwing an error)

#### Response Example
(Not applicable)
```

--------------------------------

### Programmatic File Updates Configuration

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/configuration.md

Demonstrates configuring `bumpp` to update specific files, including glob patterns for directories and manifest files.

```typescript
bumpp({
  files: [
    'package.json',
    'README.md',
    'src/version.ts',
    'docs/**/*.md'
  ]
})
```

--------------------------------

### Load Configuration with loadBumpConfig

Source: https://github.com/antfu-collective/bumpp/blob/main/_autodocs/api-reference/config.md

Load configuration from a file, merging it with overrides and defaults. This function automatically searches for configuration files in the specified directory.

```typescript
export async function loadBumpConfig(
  overrides?: Partial<VersionBumpOptions>,
  cwd = process.cwd(),
): Promise<VersionBumpOptions>
```

```typescript
import { loadBumpConfig } from 'bumpp'

// Load config from current directory with CLI overrides
const config = await loadBumpConfig({
  release: 'minor',
  push: false
})

// Load config from specific directory
const config2 = await loadBumpConfig({}, '/path/to/project')

// Load custom config file
const config3 = await loadBumpConfig({
  configFilePath: './custom-config.ts'
})
```