@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-installenvironment variable set - Force reading commit message from a local file with
--file <filename>option
Small print
Author: Gleb Bahmutov <[email protected]> © 2017
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.