Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kevinoid/git-branch-is
Assert that the name of the current branch of a git repository has a particular value.
https://github.com/kevinoid/git-branch-is
cli git nodejs
Last synced: 6 days ago
JSON representation
Assert that the name of the current branch of a git repository has a particular value.
- Host: GitHub
- URL: https://github.com/kevinoid/git-branch-is
- Owner: kevinoid
- License: mit
- Created: 2016-02-16T02:04:58.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2024-11-02T19:29:09.000Z (about 2 months ago)
- Last Synced: 2024-12-15T17:05:23.738Z (13 days ago)
- Topics: cli, git, nodejs
- Language: JavaScript
- Size: 1.05 MB
- Stars: 96
- Watchers: 2
- Forks: 9
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
`git-branch-is`
===============
[](https://github.com/kevinoid/git-branch-is/actions?query=branch%3Amain)
[](https://app.codecov.io/gh/kevinoid/git-branch-is/branch/main)
[](https://libraries.io/npm/git-branch-is)
[](https://www.npmjs.com/package/git-branch-is)
[](https://www.npmjs.com/package/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](https://docs.npmjs.com/cli/version) in `package.json`:
```json
{
"name": "super-cool-package",
"version": "1.2.3",
"scripts": {
"preversion": "git-branch-is release && echo Preversion checks passed."
}
}
```
## Installation
[This package](https://www.npmjs.com/package/browserify) can be installed
using [npm](https://www.npmjs.com/), either globally or locally, by running:
```sh
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]
Options:
-C run as if started in
--git-arg additional argument to git (can be repeated) (default: [])
--git-dir set the path to the repository
--git-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 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:
```js
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`:
```js
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:
```js
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](https://kevinoid.github.io/git-branch-is/api).
## Rationale
What's the value of this command over scripting with `git` directly? Good
question. The [Introductory Example](#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.
## Contributing
Contributions are appreciated. Contributors agree to abide by the [Contributor
Covenant Code of
Conduct](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html).
If this is your first time contributing to a Free and Open Source Software
project, consider reading [How to Contribute to Open
Source](https://opensource.guide/how-to-contribute/)
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](LICENSE.txt).
See the [summary at TLDRLegal](https://tldrlegal.com/license/mit-license).