Skip to content
please is semver release made easy
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github chore: create FUNDING.yml Sep 27, 2019
.travis.yml build(travis): lint the commits Sep 27, 2019 chore: new version 0.10.1 [skip ci] Sep 28, 2019
LICENSE chore: license [skip ci] Aug 3, 2018
VERSION chore: new version 0.10.1 [skip ci] Sep 28, 2019
please chore: new version 0.10.1 [skip ci] Sep 28, 2019


Latest Version Travis Build Software License

please (aka php release or even npm release) is very simple Github+NPM release for PHP and/or Nodejs projects anything.

Assumes you like semantic versioning of the format <major>.<minor>.<patch>!

Actually you can release any thing not just PHP/Nodejs. Please itself is released by please.

Help Preview

Working Mechanism

  • Determine remote git repo based on local git config
  • Checkout and Update master
  • Get latest release from github api endpoint
  • Collect new commits since the latest release
  • Create a changelog (prepend to if exists), reflect that into ./ file and commit it
  • Bump the version as per semver, reflect that into ./VERSION file and commit it
    • If any of the latest commits start with feat <minor> is bumped
    • But if only you didnt explicitly pass scope already
  • If there is package.json file, bump package.json#version and commit it
  • If package.json#private is not set to true
    • If npm user not already logged in, run npm adduser
    • Run npm publish finally
  • Release the new version and tag to github
  • If there is box.json file, compile phar using box (download box.phar if required)
  • Upload the compiled phar as asset for the recent release


# Requirements:
# jq
sudo apt install jq -y

curl -sSLo ~/please
chmod +x ~/please && sudo ln -s ~/please /usr/local/bin/please


One time setup. In your .bashrc / .zshrc or the like export github token:

export GH_AUTH_TOKEN=<your token here>

Get your token from here. Make sure to set only bare minimum permission scopes for this token.

What permissions

  • repo if you want to release private repos
    • public_repo required
    • repo_deployment required

Important: Tokens are to be treated and kept as much secret as passwords.

Usage and Examples

Make sure you have already merged required commits to master branch in Github, then go to the root of any project you want to release and run:

please [Scope|Command] [Options]
please v0.9.0 | (c) Jitendra Adhikari | please is semver release made easy.

Usage: please [command|scope] [--options]

  version        Print current version of itself.
  help           Show help information and usage examples.
  major          Bumps the <major> part of semver.
  minor          Bumps the <minor> part of semver.
  -c --chlog     Forces creation of file.
  -h --help      Show help information and usage.
  -H --chash     Prepends commit hash into log.
  -o --organize  Commit types as CSV for changelog or release notes.
                 (Default: feat,fix,refactor,perf,docs,infra,chore)
  -p --public    Set scoped npm package for public access.
  -u --update    Update _please to latest version.
  -v --vfile     Forces creation of VERSION file.
  -V --version   Forces the exact version to be released.
  -y --yes       Assume yes for any confirmation.
  --before-all   Run the command before anything (very start).
  --before-npm   Run the command before releasing to npm.
  --before-push  Run the command before pushing code to remote.
  --before-vcs   Run the command before releasing to VCS.
  --before-phar  Run the command before uploading phar binary.
  --after-all    Run the command after everything finishes.
  please version                          # prints current version of itself
  please --update                         # updates please if new version available
  please --organize feat,fix,docs         # includes only features, fixes and docs
  please --vfile --chash                  # creates VERSION file, adds commit hash
  please minor --public --yes             # releases minor version without asking
  please major --vfile --chlog            # releases next major version with VERSION and CHANGELOG files
  please --vfile --chlog --version 1.5.0  # releases version 1.5.0 with VERSION and CHANGELOG files
  please --before-all 'echo {REPO}'       # before release, runs 'echo {REPO}' with REPO interpolated


  • If there is VERSION file in project root, you dont need --vfile flag.
  • If there is file in project root, you dont need --chlog flag.
  • If there is box.json file in project root, it builds and releases .phar too.
  • If no scope is given
    • If there is any feat: commit, bumps the <minor> part of semver.
    • Else bumps the <patch> part of semver.


You can take control of the work flow or execute more tasks by using the event callbacks. When the event commands are triggerred they receive all the variables defined in the then moment.

Currently please supports five events which are executed in following order:

  • before-all
  • before-npm
  • before-push
  • before-vcs
  • after-all

You can either set events as a json file in ./please.json or pass them in as option to please like so:

# run `composer test` before pushing code
# send release notification to slack after everything finishes
please --before-push "composer test" --after-all "slack 'Released {REPO}@{NEXT_VERSION}'"

The event passed in as option will have higher precedence than the one read from ./please.json


Use only single quote in the event command. Eg: please --before-all "echo 'a b c'"


Here's output of please in action, releasing 0.0.1 of itself:

$ ./please --vfile
Repository adhocore/please
Log file /tmp/PLZEXKbyF
Updating master ...
Getting latest releases ...
Current Version 0.0.0
Collecting commits ...
Bumping version ...
Releasing 0.0.1 ...
Check /tmp/PLZEXKbyF for logs

And here is colorful screenshot of please releasing v0.0.10 of phint

And here is a preview of all features of please in one release: Full Preview

Sample changelog generated by please looks like:

## [0.0.1](<repo>/releases/tag/<0.0.1>) (2018-01-01)

### Features
- **scope**: commit 1 (Author Name)
- **scope**: commit 2 (Author Name)

If you passed in --chash flag then:

## [0.0.1](<repo>/releases/tag/<0.0.1>) (2018-01-01)

### Features
- **scope**: commit 1 (Author Name) [_hash1_](<repo>/commit/<hash1>)
- **scope**: commit 2 (Author Name) [_hash2_](<repo>/commit/<hash2>)

On subsequent releases new changes are prepended such that latest commits stay at top.


If you are using zsh then please might have been already aliased to sudo. To fix this simply run

echo "alias please=/usr/local/bin/please" >> ~/.zshrc
source ~/.zshrc
You can’t perform that action at this time.