`git-branch-is`

Assert that the name of the current branch of a git repository has a particular value.

Introductory Example

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 in package.json:

{
  "name": "super-cool-package",
  "version": "1.2.3",
  "scripts": {
    "preversion": "git-branch-is release && echo Preversion checks passed."
  }
}

Installation

This package can be installed using npm, either globally or locally, by running:

npm install git-branch-is

Command Usage

The command options are intended to be similar to git and are documented in the --help output:

Usage: git-branch-is [options] <branch name>

Options:

  -h, --help         output usage information
  -C <path>          run as if started in <path>
  --git-arg <arg>    additional argument to git (can be repeated)
  --git-dir <dir>    set the path to the repository
  --git-path <path>  set the path to the git binary
  -i, --ignore-case  compare/match branch name case-insensitively
  -q, --quiet        suppress warning message if branch differs
  -r, --regex        match <branch name> as a regular expression
  -v, --verbose      print a message if the branch matches
  -V, --version      output the version number

Additional Command Examples

Regular Expression Matching

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).

Case-Insensitive Matching

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

API Usage

To use the API with a callback function:

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 a Promise:

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:

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); }
);

API Docs

To use this module as a library, see the API Documentation.

Rationale

What's the value of this command over scripting with git directly? Good question. The Introductory Example could instead be approximated with the following:

{
  "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.

Contributing

Contributions are welcome and very much appreciated! Please add tests to cover any changes and ensure npm test passes.

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.

License

This package is available under the terms of the MIT License.

Dzivenu / git-branch-is