@cypress/commit-message-install

NPM install a package by name taken from the last commit message

Install

Requires Node version 6 or above.

npm install --save-dev @cypress/commit-message-install
yarn add -D @cypress/commit-message-install

or globally

npm i -g @cypress/commit-message-install
yarn global @cypress/commit-message-install

Node version

We are trying to use the same minimum version of Node as Cypress

Use

Install NPM package from commit message

Imagine you have a CI build that installs NPM dependencies, but you also want to override one or more dependencies and test by creating a commit. Instead of changing package.json you can make a commit message with embedded JSON block describing custom installation. Then use this CLI tool to install based on the commit message.

Example CI file command

- npm i -g @cypress/commit-message-install
- commit-message-install

If commit message is this

this will install package debug and chalk and while
installing them will set environment variable FOO to "bar".
The install will happen on all platforms

    ```json
    {
        "platform": "*",
        "architecture": "x64",
        "packages": "debug,chalk"
    }
    ```

Happy installation

note platform can be * or specific one like darwin (from Node os.platform()) or a list of several platforms like darwin,linux. architecture is usually 64 bit x64 as returned by os.arch().

Specific commit

You can install using commit message from a specific commit (not the current one)

$ $(npm bin)/commit-message-install --sha f81a00

Alternative command

You can specify a command to run if commit message has no JSON block. For example you can install default dependency

$ $(npm bin)/commit-message-install --else "npm install foo-bar"

Run or skip command based on platform

If the commit message allows a specific platform, you can run any command, while setting environment variables from the commit message. For example if th commit message embeds the following JSON block

{
    "platform": "win32",
    "env": {
        "FOO": "bar"
    }
}

and the CI has command run-if echo Foo is \\$FOO, then on Windows CI it will print Foo is bar and on other platforms it will skip this step.

In general, if you use commit-message-install on the CI, then you should use run-if command as well! For example, here are CircleCI steps that install default dependencies, but then run conditional steps

steps:
  - checkout
  - run: npm install
  - run: $(npm bin)/commit-message-install
  - run: $(npm bin)/run-if $(npm bin)/cypress version
  - run: DEBUG=cypress:cli $(npm bin)/run-if $(npm bin)/cypress verify

Set GitHub commit status

Very useful to notify other projects asynchronously via GitHub commit states.

$(npm bin)/set-status --label "context label" --state success --description "short message"

State can be "error", "pending", "failure" or "success". --label is optional, if not set, then the platform and the package name will be used.

Has commit message

You can use script has-message to check if the last or a specific commit has JSON commit information block

$(npm bin)/has-message
$(npm bin)/has-message --sha f81a00

If there is a message in the commit's body the script will exit with code 0. Otherwise it will exit with code 1.

See commit-message-install-example repo for an example. Here is CircleCI halting if there is no commit message JSON

# install tool locally
- run: npm install @cypress/commit-message-install
- run: |
    if ! $(npm bin)/has-message; then
        echo Stopping early, no commit message
        circleci-agent step halt
    else
        echo All good, found commit message JSON
    fi

# install tool globally using Yarn
- run: yarn global @cypress/commit-message-install
- run: |
    if ! has-message; then
        echo Stopping early, no commit message
        circleci-agent step halt
    else
        echo All good, found commit message JSON
    fi

API

getJsonFromGit

Extracts JSON block from the current Git message text

const {getJsonFromGit} = require('@cypress/commit-message-install')
getJsonFromGit()
    .then(json => {
        // {platform: 'win32', packages: 'foo', branch: 'test-branch'}
    })

If there is no valid JSON object in the message, resolves with undefined.

getInstallJson

You can form good Json object to be included in markdown json block in the body of the commit message using provided function

const {getInstallJson} = require('@cypress/commit-message-install')
// package(s), env, platform, branch name (optional)
const json = getInstallJson('foo',
    {foo: 42}, 'linux', 'test-branch', 'b7ccfd8')
// returns an object
    // {
    //   platform: "linux",
    //   env: {foo: 42},
    //   packages: "foo",
    //   branch: "test-branch",
    //   commit: "b7ccfd8"
    // }

You can pass individual package name like debug or several as a single string debug chalk or a list ['debug', 'chalk']

You can pass for platform either individual os.platform() or a "*"" for all, and even several platforms like win32,linux or linux|darwin.

npmInstall

After getting JSON from a commit message you can install dependencies

const {getInstallJson, npmInstall} = require('@cypress/commit-message-install')
getInstallJson()
  .then(npmInstall)

Debugging

• Run this tool with DEBUG=commit-message-install environment variable set
• Force reading commit message from a local file with --file <filename> option

Small print

Author: Gleb Bahmutov <[e-mail]> © 2017

• @bahmutov
• glebbahmutov.com
• blog

License: MIT - do anything with the code, but don't blame me if it does not work.

Support: if you find any problems with this module, email / tweet / open issue on Github

MIT License

Copyright (c) 2017 Cypress.io

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.