branch-remover
Version:
A small application for quickly removing unnecessary branches from GitHub.
214 lines (127 loc) • 6.24 kB
Markdown
# branch-remover
[](https://www.npmjs.com/package/branch-remover)
[](https://travis-ci.com/sfm-tools/branch-remover)
[](https://coveralls.io/github/sfm-tools/branch-remover?branch=master)
[](https://www.npmjs.com/package/branch-remover)
The easiest way to remove unneeded branches in your GitHub repos.
## Install
```bash
npm install --global branch-remover
```
## Usage
**:warning: Disclaimer: Using this tool, you are aware that you may lose important data and fully accept responsibility for this.**
**:warning: Always carefully check your options and always test program execution with the `--test` option.**
```bash
branch-remover --github.owner %owner% --github.repo %repo% --github.token %token% --ignore "^(master|main)$"
```
Use your access options instead `%owner%`, `%repo%`, and `%token%`.
`%owner%` and `%repo%` you can found in URL of your repository:
```
https://github.com/sfm-tools/branch-remover
^^^^^^^^ ^^^^^^^^^^^^^^
owner repo
```
For `%token%` check the following page:
https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token
You can also use a separate JSON file with access parameters. For example:
**my-project.json**
```json
{
"owner": "%GITHUB USERNAME OR ORG NAME HERE%",
"repo": "%GITHUB REPOSITORY NAME HERE%",
"token": "%YOUR GITHUB TOKEN HERE%"
}
```
You can specify the path to this file using the `github.auth` parameter:
```bash
branch-remover --github.auth ./my-project.json --ignore "^(master|main)$"
```
## Options
### --after
Allows specifying a shell command to execute after the branch is removed.
You can use the `{branch}` marker to get the name of the removed branch.
The following example shows a command that writes the name of the removed branch to a file:
```bash
branch-remover --github.auth ./my-project.json --after echo "{branch} >> ./removed-branches.log"
```
### --before
Allows specifying a shell command that will be executed before removing a branch.
You can use the `{branch}` marker to get the name of the removed branch.
If the result of the command execution is the string `"0"` or `"false"`, then removing will be prevented.
The following example shows creating a backup of a branch before removing:
```bash
branch-remover --github.auth ./my-project.json --before "git -c credential.helper= -c core.quotepath=false -c log.showSignature=false fetch origin {branch}:{branch} --recurse-submodules=no"
```
### --cache
Allows specifying caching options. Caching is implemented in the file system.
You can specify the file path and cache time-to-live.
```bash
branch-remover --github.auth ./my-project.json --cache "./.branch-remover.cache timeout=600"
```
`./.branch-remover.cache` - is the default path to the cache file. It is optional to specify it.
`timeout` - time-to-live time in seconds. Default: `0` - without caching.
The following example shows caching enabled for 7 days (7 days * 24 hours * 60 minutes * 60 seconds = 604800 seconds):
```bash
branch-remover --github.auth ./my-project.json --cache "timeout=604800"
```
### --config
Path to custom js-file containing branch processing parameters.
[Simple example config file](/examples/config.js).
### --debug
Enables the display of debugging information.
### --details
Enables the display of detailed information about each branch.
By default, detailed information is only displayed for branches that will be removed.
### --github.auth
The path to the JSON file that contains the repository access parameters.
Required only for provider "github", when the access parameters are not specified separately.
### --github.owner
Username or organization name on GitHub. For example: `sfm-tools`.
Required only for provider "github", when `--github.auth` is not specified.
### --github.repo
Repository name on GitHub. For example: `branch-remover`.
Required only for provider "github", when `--github.auth` is not specified.
### --github.token
GitHub access token - https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token
Required only for provider "github", when `--github.auth` is not specified.
### --help
Displays help information.
You can see additional information for each individual option:
`branch-remover --help %parameterName%`.
For example:
* `branch-remover --help help`
* `branch-remover --help github.auth`
### --ignore
A regex pattern that allows specifying branches to ignore.
For example, ignore `master` and `main` branches:
```bash
branch-remover --github.auth ./my-project.json --ignore "^(master|main)$"
```
### --merged
Allows specifying the time elapsed since the merge.
For example: `2 years` (or `2y`), `6 months`, `5 days` (or `5d`), `2 hours` (or `2h`), `30 minutes` (or `30m`), etc.
Default: `all` (all merged branches).
**NOTE:** Please use quotation marks if the option value contains a space. For example:
```bash
branch-remover --github.auth ./my-project.json --merged "2 months"
```
### --provider
Specifies the provider name. Expected values: `github` (default).
### --quiet
The presence of this option disables the confirmation request to remove branches.
**Matching branches will be removed immediately. Be careful when using this option!**
### --stale
Allows specifying the time after which the unmerged branch can be considered obsolete since the last update.
This option is similar to `--merged`.
### --test
Test mode, automatic removing branches is disabled.
Use this option to **test your configuration**.
### --version
Displays the version number of the application.
### --yes
The default answer to a delete confirmation is YES (default - NO).
Does not work with `--quiet`.
## License
MIT