Ver-Bump: Bash-Powered Version Bumping Mastery


A fully automated handy CLI utility that takes care of releasing GitHub software projects, written in 100% pure bash.

Highlights šŸ“¦šŸš€

It does several things that are typically required for releasing a Git repository:

  • Create a release branch from your current branch (should be a feature or develop branch, following the Git branch-based workflow, and tags the release
  • Enforces Semantic Versioning specification
  • Avoid potential mistakes associated with manual releases, such as forgetting a step
  • Create and update a changelog file automatically
  • Pushes release to a remote
  • Leaves merging the release branch to the development branch to the user

Release Steps šŸ‘£

The command ver-bump will execute the following steps:

Verify + Prepare Release

  • Verify some commits exist
  • Selects a semantic version number for the release branch & tag
  • Increments / suggests a semantic version number for the release and its tag
    • Checks to see a tagged release with the chosen version already exists

Create Release

  • Bump version number in package.json
  • Write
  • Create release branch
  • Commit changes to files made by this script
  • Create a Git tag
  • Push release branch + tag to remote

Release Steps: In detail šŸ”Ž

Verify + Prepare ReleaseProcess user argumentsCheck and store CLI arguments supplied by user for later processing.
Check commitsVerify some commits exist for release.
Determine Release VersionIf <package.json> doesn't exist, warn + exit. 

If -v option is specified, set version from that.

Or, grab from version from package.json.

Suggest incremented version number in the form of MAJOR.MINOR.PATCH (incrementing PATCH), as per Semver 2.0.0.

Give the user the option to modify/confirm suggested version bump.
Check branch existEnsure a release branch with the chosen version number doesn't already exist, if so exit.
Check tag existsEnsure a tag with the chosen version number doesn't exist, and exit if it does.
Create ReleaseBump version numberUpdate semantic version number in package.json + stages changes.
Generate changelogCommits since the last release are automatically added to, as well as new commit messages for files modified by this script itself. Stages changes for commit action later.
Create release branchCreate a branch with the name release-MAJOR.MINOR.PATCH and switch to it (following the Git branch-based workflow).
Commit changed filesCommits changes to package.json and` (staged in the previous steps) to the release branch.
Create Git tagCreate a Git tag referencing the new release version.
PushOptionally, push the release branch to origin.


In order to use ver-bump you need:

  • To host your project code in a Git repository
  • Have Git installed in your environment
  • Have npm and node installed


Install the script globally via npm, and use it in any local Git repository to release your project:

$ npm install -g ver-bump



  • Make sure you have package.json file in your project and it contains a "version": "x.x.x" parameter
  • You have done some work and have some existing commits
  • You have the ability to push to your Git remote via the Git CLI


$ ver-bump [-v <version no.>] [-m <release message>] [-j <file1>] [-j <file2>].. [-n] [-p] [-b] [-h]


-v <version number>     Specify a manual version number
-m <release message>    Custom release message
-f <filename.json>      Update version number inside JSON files.
                            * For multiple files, add a separate -f option for each one,
                            * For example:
                              ./ -f src/plugin/package.json -f composer.json
-p <repository alias>   Push commits to remote repository, eg `-p Origin`
-n                      Turns off automatic commit
                            * You may want to do that yourself, for example.
-b                      Don't create automatic `release-<version>` branch.
-c                      Disable updating automatically with new commits
                        since last release tag.
-l                      Pause enabled for amending
-h                      Show help message.


This example assumes that a package.json contains version: "1.0.0", and the user is working in the branch to be released with pre-existing un-released commits.

This will create a new Git branch called release-1.0.1 and a Git tag named v1.0.1:


Current version read from <package.json> file: 1.0.0

Enter a new version number or press <enter> to use [1.0.1]: <pressed enter>


āœ… Updated file <package.json> from 1.0.0 -> 1.0.1

āœ… Updated [] file

Make adjustments to [] if required now. Press <enter> to continue.

Creating new release branch...

āœ… Switched to branch 'release-1.0.1'
M package.json


āœ… [release-1.0.1 ace8b1e] Updated package.json, Updated, Bumped 1.0.0 ā€“> 1.0.1
2 files changed, 9 insertions(+), 1 deletion(-)

āœ… Added GIT tag

Push tags to <origin>? [N/y]: n


āœ… Bumped 1.0.0 ā€“> 1.0.1

šŸ Done!
$ ver-bump

After checking out the changes in the branch and confirming them, test the release, and push the release branch to your remote if you didn't choose to push it automatically. Alternatively, use $ ver-bump -p origin to bypass the prompt and push the release branch anyway to the remote automatically.

If your code checks out, then open a Pull Request to merge the release branch into your develop or main branch.

You can merge the release branch into your development branch or main branch like this, without fast-forwarding so that the branch topology is preseved as you're merging in a release branch that hasn't diverged (apart from new changes to and package.json) and you want to ensure it's clearly evident when reading the history that a merge was performed, as opposed to a fast-forward merge, where new commits performed by the merge will become descendents of the last commit before the merge.

A release branch shouldn't normally diverge from the branch it was created during the time ver-bump is operating, so a non-fastforward should be possible instead of a normal merge, which would simply looks like a new commit was made to the main or development branch.

$ git checkout develop # Switch to development branch from the new release branch

$ git merge --no-ff release-1.0.1 # Merge the new release branch to your development branch


This project uses bats to test the functionality of ver-bump.

To run the tests, first install the pre-requisites:


$ npm run tests:install


$ npm run tests:install:windows

And finally, run the test suite:

$ npm run tests:run


 āœ“ can run script
 āœ“ process-arguments: -h: display help message
 āœ“ process-arguments: -v: fail when not supplying version
 āœ“ process-arguments: -v x.x.x: succeed when supplying version
 āœ“ process-arguments: -m: fail when not supplying release note
 āœ“ process-arguments: -m <note>: succeed when supplying release note
 āœ“ process-arguments: -f: fail when not supplying filenames
 āœ“ process-arguments: -f <filename.json>: succeed with multiple filenames
 āœ“ process-arguments: -p: fail when not supplying push destination
 āœ“ process-arguments: -p <repo destination>: succeed when supplying a destination
 āœ“ process-arguments: -n: set flag to prevent committing at the end
 āœ“ process-arguments: -b: set flag to disable creating a release branch
 āœ“ process-arguments: -c: set flag to disable creating/updating
 āœ“ process-arguments: -l: set flag to enable pausing after is created
 āœ“ process-arguments: fail on not-existing argument
 āœ“ set-v-suggest: increments version
 āœ“ set-v-suggest: fails to increments non SemVer version
 āœ“ process-version: fail on entering non-SemVer input
 āœ“ process-version: patch of the version from json file should be bumped +1
 āœ“ do-packagefile-bump: can bump version in package.json + lock file
 āœ“ bump-json-files: can bump version in a json file
 āœ“ bump-json-files: can fail bumping a json file when a version already exists in file
 āœ“ bump-json-files: can fail bumping a json file when no version found inside it
 āœ“ check-branch-notexist: can detect branch DOES exist
 āœ“ check-branch-notexist: can confirm branch DOES'NT exist
 āœ“ do-branch: can create a release branch
 āœ“ do-tag: create a tag
 āœ“ check-tag-exists: check doesn't exist
 āœ“ check-tag-exists: check it exists
 āœ“ do-changelog: can create a

30 tests, 0 failures


I'd love you to contribute to @jv-k/ver-bump, pull requests are welcome for submitting issues and bugs!

Download Details:

Author: jv-k
Source Code: 
License: MIT license.

#bash #git #package #automation #changelog 

Ver-Bump: Bash-Powered Version Bumping Mastery
1.40 GEEK