5 releases
0.1.9 | Mar 22, 2021 |
---|---|
0.1.8 | Mar 16, 2021 |
#651 in Configuration
32KB
601 lines
gh-labels-cli
A tool for managing your GitHub labels.
Use-cases
I personally use the CLI for creating a standard set of labels when initializing a new repository on GitHub. I've created custom alias for gh
that uses gh-labels-cli
to create a repository and run the CLI for bulk label creation:
$ gh alias set -s new 'gh repo create $1; cd $1; gh labels update --purge'
- Adding alias for new: gh repo create $1; cd $1; gh labels update --purge
✓ Changed alias new from !gh repo create $1; cd $1; gh labels update to !gh repo create $1; cd $1; gh labels update --purge
Note: for this to work you need a label definition file inside the configuration directory. See here for more information.
Installation
As for now, gh-labels-cli
can only be installed through cargo
:
$ cargo install gh-labels-cli --locked
A homebrew tab and AUR packages are in the works :)
Usage
The CLI can be used as either standalone by directly invoking it via the gh-labels
binary or you can register aliases for the official GitHub CLI (gh
) to integrate gh-labels-cli
into it.
To register the aliases, run gh-labels integration install
.
The CLI needs a personal access token with appropiate public_repo
or repo
scope, depending on whether you want it to work on private repositories as well. The token can be passed to the CLI using a CLI argument or via the environment variable GH_LABELS_TOKEN
.
Note: Some poeple may wish to re-use a singleton token across multiple CLIs. The CLIs I've stumbled across often use the
GITHUB_TOKEN
environment variable. This is also supported. The order in which the token is tried to be read from isCLI argument
>GH_LABELS_TOKEN
>GITHUB_TOKEN
.
The CLI operates on repositories. Those can either be directly supplied via an argument in the form owner/repo
or by running the CLI inside of an existing git repository with an upstream named origin
pointing to github.com
.
For more information, take a closer look at the help.
I know use the gh new <repo-name>
alias to create a new repository instead of gh repo create
.
Commands
Config
Used to query the configuration file path, content or to edit the configuration inside your terminal.
Integration
Used to install and uninstall the labels
alias for the gh
CLI.
Api
Commands related to actual GitHub API calls.
Create
Creates a single label inside a repository with the given values.
Update
Bulk-create labels and update existing ones inside of repositories. You have to supply a label definition file for the command to work. The file can be supplied via the -f,--file
argument or by putting the file inside the directory returned via the gh-labels config --path
. The file has to be named labels.json
when using the second option.
Label definitions file
A label definitions file is a file that you write containing all the labels you want to apply to a repository. It's a JSON file with the following format:
{
"labels": [
{
"name": "type: bug",
"color": "431232",
"description": "A programming error"
}
]
}
Note: The description field is optional.
My own label definition file can be found here.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Dependencies
~33–52MB
~1M SLoC