README.md

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 "main", 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:
  -C <path>           run as if started in <path>
  --git-arg <arg>     additional argument to git (can be repeated) (default: [])
  --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
  -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 <branch name> as a regular expression
  -v, --verbose       print a message if the branch matches
  -V, --version       output the version number
  -h, --help          output usage information

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 "main" 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 "main" does not match "^release/".
$ echo $?
1

Inverted/Negated Matching

To check that the current branch is not main, use -I, --invert-match, or --not (all functionally equivalent, use whichever you prefer):

$ git-branch-is --not main
Error: Current branch is "main".
$ echo $?
1

API Usage

To use the API with a callback function:

const gitBranchIs = require('git-branch-is');
gitBranchIs('main', function(err, result) {
  if (err) console.error(err);
  else console.log(result ? 'On main' : 'Not on main');
});

Alternatively, if a callback is not provided, gitBranchIs will return a Promise:

const gitBranchIs = require('git-branch-is');
gitBranchIs('main').then(
  function(result) { console.log(result ? 'On main' : 'Not on main'); },
  function(err) { console.error(err); }
);

Additionally, instead of a string, a checking function can be passed to perform arbitrary checking against the branch name:

const gitBranchIs = require('git-branch-is');
gitBranchIs(function(branchName) { /^main$/.test(branchName); }).then(
  function(result) { console.log(result ? 'On main' : 'Not on main'); },
  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 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.

License

This project is available under the terms of the MIT License. See the summary at TLDRLegal.