Assert that the name of the current branch of a git repository has a particular value.
npm install git-branch-isgit-branch-is
===============
Assert that the name of the current branch of a git repository has a particular value.
To check that the current branch is named release and print an error if not,
run the following command:
``
$ git-branch-is release
Error: Current branch is "master", not "release".
$ echo $?
1
This can be useful as part of a preversion
script:
`json`
{
"name": "super-cool-package",
"version": "1.2.3",
"scripts": {
"preversion": "git-branch-is release && echo Preversion checks passed."
}
}
This package can be installed
using npm, either globally or locally, by running:
`sh`
npm install git-branch-is
The command options are intended to be similar to git and are documented in--help
the output:
`
Usage: git-branch-is [options]
Options:
-C
--git-arg
--git-dir
--git-path
-i, --ignore-case compare/match branch name case-insensitively
-I, --invert-match inverts/negates comparison
--not inverts/negates comparison (same as --invert-match)
-q, --quiet suppress warning message if branch differs
-r, --regex match
-v, --verbose print a message if the branch matches
-V, --version output the version number
-h, --help output usage information
`
To check that the current branch starts with release/ using a regular
expression:
`
$ git-branch-is -r "^release/"
Error: Current branch "master" does not match "^release/".
$ echo $?
1
Note: Be careful to quote patterns to avoid shell expansion or special
handling (e.g. POSIX shells expand * and cmd.exe treats ^ specially).
To check that the current branch starts with release/ case-insensitively
using a regular expression:
`
$ git-branch-is -i -r "^release/"
Error: Current branch "master" does not match "^release/".
$ echo $?
1
To check that the current branch is not master, use -I, --invert-match,--not
or (all functionally equivalent, use whichever you prefer):
`
$ git-branch-is --not master
Error: Current branch is "master".
$ echo $?
1
To use the API with a callback function:
`js`
var gitBranchIs = require('git-branch-is');
gitBranchIs('master', function(err, result) {
if (err) console.error(err);
else console.log(result ? 'On master' : 'Not on master');
});
Alternatively, if a callback is not provided, gitBranchIs will return aPromise:
`js`
var gitBranchIs = require('git-branch-is');
gitBranchIs('master').then(
function(result) { console.log(result ? 'On master' : 'Not on master'); },
function(err) { console.error(err); }
);
Additionally, instead of a string, a checking function can be passed to
perform arbitrary checking against the branch name:
`js`
var gitBranchIs = require('git-branch-is');
gitBranchIs(function(branchName) { /^master$/.test(branchName); }).then(
function(result) { console.log(result ? 'On master' : 'Not on master'); },
function(err) { console.error(err); }
);
To use this module as a library, see the API
Documentation.
What's the value of this command over scripting with git directly? Good
question. The Introductory Example could instead be
approximated with the following:
`json`
{
"name": "super-cool-package",
"version": "1.2.3",
"scripts": {
"preversion": "if [ \"$(git symbolic-ref HEAD)\" = release ] ; then echo Preversion checks passed. ; else echo Error: Not on branch release. ; exit 1 ; fi"
}
}
For packages which are only targeting POSIX systems, this may be a preferable
solution. However, it doesn't work on systems which don't support the POSIX
shell language (e.g. Windows, which runs scripts in cmd.exe`). To support
these systems it is necessary to either introduce a dependency on Bash, to
use this script, or code up something else.
Contributions are appreciated. Contributors agree to abide by the Contributor
Covenant Code of
Conduct.
If this is your first time contributing to a Free and Open Source Software
project, consider reading How to Contribute to Open
Source
in the Open Source Guides.
If the desired change is large, complex, backwards-incompatible, can have
significantly differing implementations, or may not be in scope for this
project, opening an issue before writing the code can avoid frustration and
save a lot of time and effort.
This project is available under the terms of the MIT License.
See the summary at TLDRLegal.