DOCSEARCHbyAlgolia
Submit Docs

bump Ruby Gem

repository·master·Indexed 41 days ago

https://github.com/gregorym/bump

A Ruby gem to automate version bumping for gems and chef-cookbooks. It supports major, minor, patch, and pre-release increments, and can automatically handle git commits, tagging, bundling, and CHANGELOG.md updates via a CLI, Rake tasks, or a Ruby API.

Tokens
2.4K
Snippets
9
Records
12
Agent score
50%

What's inside bump

  1. Use the bump CLI to manage versions

    master

    The bump command provides a CLI for inspecting and incrementing project versions. By default, it handles version bumping, running bundle, and committing changes to git.

    Version Inspection

    • Show current version: bump current (e.g., returns 0.1.2)
    • Show next version: bump show-next [type] (e.g., bump show-next patch returns 0.1.3)
    • Show version file path: bump file (e.g., returns lib/foo/version.rb)

    Version Bumping

    Use the following commands to increment the version:

    • bump major
    • bump minor
    • bump patch
    • bump pre (for pre-releases)
    bump current
bump patch
bump show-next patch
bump file

  3. Use bump with Rake tasks

    master

    You can integrate bump into your Rakefile by requiring bump/tasks. This allows you to run versioning tasks via rake.

    Available Rake Tasks

    • rake bump:current — Display current version.
    • rake bump:show-next [INCREMENT=type] — Display next version (e.g., INCREMENT=minor).
    • rake bump:file — Display version file path.
    • rake bump:major, rake bump:minor, rake bump:patch, rake bump:pre — Perform the bump with default settings (commit, tag, and bundle).

    Task Configuration via Rake

    You can set global defaults in your Rakefile:

    require "bump/tasks"

# Bump.tag_by_default = false
# Bump.replace_in_default = ["Readme.md"]
# Bump.changelog = true
# Bump.changelog = :editor

    Task Options

    Pass options as environment variables:

    # Commit, but don't tag or run bundle
rake bump:patch TAG=false BUNDLE=false

# Tag with a specific prefix
rake bump:patch TAG=true TAG_PREFIX=v-

# Don't commit or tag
rake bump:patch COMMIT=false TAG=false

# Custom commit message
rake bump:minor COMMIT_MESSAGE="release it"
    # Rakefile
require "bump/tasks"

  4. Use the Bump Ruby API

    master

    For programmatic access, use the Bump::Bump class.

    MethodReturn Value / Description
    Bump::Bump.currentReturns current version string (e.g., `

  5. Supported version file locations

    master

    The bump gem automatically detects version strings in the following locations:

    • VERSION file containing 1.2.3
    • gemspec file with gem.version = "1.2.3" or Gem::Specification.new "gem-name", "1.2.3" do ...
    • lib/**/version.rb file with VERSION = "1.2.3"
    • metadata.rb file with version "1.2.3"
    • lib/**/*.rb files containing VERSION = "1.2.3"

  6. Configure bump CLI options

    master

    You can customize the behavior of the bump command using various flags:

    OptionDescription
    --no-commitDo not commit changes after bumping.
    --tagAdd a git tag (e.g., v1.2.3). Requires git repository and --no-commit must NOT be used.
    --tag-prefix [PREFIX]Change the git tag prefix (e.g., --tag-prefix v- results in v-1.2.3). Use "" for no prefix.
    --no-bundleDo not run the bundle command after bumping.
    --replace-in [FILE]Bump the version string in additional files (e.g., Readme.md).
    --commit-message [MSG] or -m [MSG]Append additional information to the default commit message.
    --changelogUpdates CHANGELOG.md. Requires a heading (starting with ##) containing the previous version and a heading above it (e.g., ### Next).
    --edit-changelogUpdates CHANGELOG.md and opens it in your $EDITOR (or vi) to wait for you to finish before continuing.
    bump patch --tag --tag-prefix v-
bump patch --no-commit
bump patch --replace-in Readme.md
bump patch -m "Something extra"
EDITOR="subl -n -w" bump patch --edit-changelog

  7. Configure Bump defaults and global settings

    master

    You can configure global behavior for the Bump module using its class attributes. These settings influence the Bump.defaults hash used during run.

    Global Attributes:

    • Bump.tag_by_default: Boolean. If true, creates a git tag during the bump.
    • Bump.replace_in_default: Array of file paths. Files where the version string should also be replaced.
    • Bump.changelog: Boolean or :editor. If true, updates CHANGELOG.md. If :editor, it opens the changelog in your $EDITOR after updating.
    Bump.tag_by_default = true
Bump.replace_in_default = ['config/settings.yml']
Bump.changelog = :editor

  8. Get the current version or next version

    master

    Use these methods to inspect versioning state without performing a write operation.

    • Bump.current: Returns the current version string (e.g., '1.0.0').
    • Bump.next_version(increment, current = Bump.current): Calculates what the next version would be given an increment ('major', 'minor', 'patch', or 'pre').
    • Bump.file: Returns the path to the file where the version is currently defined.
    current_v = Bump.current
next_v = Bump.next_version('minor')
version_file = Bump.file

  9. Run version bumping with Bump.run

    master

    The Bump.run method is the primary entrypoint for performing version increments or setting specific versions. It automatically detects version files (like VERSION, *.gemspec, or lib/**/version.rb) and handles file updates, git commits, and changelog updates based on the provided options.

    Available bump commands:

    • major, minor, patch: Increments the version part.
    • pre: Cycles through pre-release identifiers (alpha, beta, rc).
    • set: Sets the version to a specific value (requires options[:version]).
    • current: Returns the current version string.
    • show-next: Returns the version that would result from the next increment.
    • file: Returns the path to the detected version file.

    Error Handling: If an operation fails, run returns an array containing an error message string and a non-zero exit code (e.g., ["Invalid option.", 1]).

    # Example: Bumping to the next minor version
result, status = Bump.run('minor', commit: true, changelog: true)

# Example: Setting a specific version
result, status = Bump.run('set', version: '1.2.3')

  10. Configure bump CLI options for commits, tags, and changelogs

    master

    When running a version bump, you can use several flags to control the automation process, such as git commits, tagging, and changelog management.

    Git and Bundling

    • --no-commit: Prevents the tool from making a git commit.
    • --tag: Creates a git tag based on the new version (only works if a commit is being made).
    • --tag-prefix TAG_PREFIX: Adds a prefix to the git tag (e.g., --tag-prefix v results in v1.0.0).
    • --commit-message [MSG], -m [MSG]: Customizes the commit message. The default is '<tag> MSG'. You can use %<tag> as a placeholder, for example: --commit-message 'chore: %<tag> bump version'.
    • --no-bundle: Prevents the tool from running bundle.

    Changelog and File Management

    • --replace-in FILE: In addition to the version file, also replace the old version string with the new version in the specified FILE.
    • --changelog: Automatically updates CHANGELOG.md.
    • --edit-changelog: Opens the changelog in your $EDITOR (e.g., nano or subl) for manual editing before the commit is finalized.

    Output

    • --value-only: Suppresses all descriptive text in the output, returning only the version value.
    bump patch --tag --tag-prefix v --commit-message 'chore: %<tag> bump version'
bump minor --changelog --edit-changelog
bump patch --replace-in config/version.rb

  11. Bump error classes

    master

    The following error classes are raised by Bump when operations fail or inputs are invalid:

    • Bump::InvalidIncrementError: The requested increment (e.g., 'major') is not recognized.
    • Bump::InvalidOptionError: The requested bump command (e.g., 'set') is not recognized.
    • Bump::InvalidVersionError: The provided version string is invalid.
    • Bump::UnfoundVersionError: No version file could be detected in the project.
    • Bump::UnfoundVersionFileError: A version file was found but it does not contain a valid version.
    • Bump::TooManyVersionFilesError: Multiple files matching version patterns were found, causing ambiguity.
    • Bump::RakeArgumentsDeprecatedError: (Internal/Legacy) related to Rake integration.

  12. Use the bump CLI to manage gem versions

    master

    The bump CLI tool is used to increment, set, or preview gem versions. It supports various increment types (major, minor, patch, pre) and can automate git commits, tagging, and changelog updates.

    Basic Commands

    CommandDescription
    bump currentShow the current version of your gem
    bump show-next INCREMENTShow what the next version will be (use pre, patch, minor, or major)
    bump fileShow the path to the version file
    bump preIncrease the prerelease version (e.g., 1.0.0-alpha $\rightarrow$ 1.0.0-beta)
    bump patchIncrease the patch version (e.g., 1.0.0 $\rightarrow$ 1.0.1)
    bump minorIncrease the minor version (e.g., 1.0.0 $\rightarrow$ 1.1.0)
    bump majorIncrease the major version (e.g., 1.0.0 $\rightarrow$ 2.0.0)
    bump set VERSIONSet the version number to a specific value (e.g., bump set 1.2.3)
    bump patch
bump show-next minor
bump set 2.0.0