ya-git-jira
v1.6.0
Published
git extensions for Jira integration. Assumes bun is installed.
Downloads
20
Readme
ya-git-jira - Yet Another Git Jira
This package installs several scripts that are written to be
usable as git
extensions, i.e. sub-commands of the git
command.
The extensions faciliate workflow when using git
for source control and jira
for issue tracking. Other similar packages exist -- thus the "yet another"
in the name.
This package will likely evolve over time to include more workflow cases.
gitj -- A test driver to use instead of git <command>
It can be useful to run these commands as if they were being invoked through
git
but using a proxy for git
than can only execute the commands in this
package.
For example, to see the available top level commands, run gitj --help
:
$ gitj help
Usage: gitj [options] [command]
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
bump [options] Bump the version number in the current branch
jira [options] Commands for working with Jira
lab [options] Commands for working with GitLab
Command hierarchy and naming conventions
The git jira
and git lab
commands are arranged in a hierarchy with a structure
and naming conventions that are indended to make it easy to navigate the existing
commands and to also make it relatively easy to decide where a new command should
go into the hierarchy. The current hierarchy is:
gitj
bump
jira
issue
list
show
start
lab
group
list
merge
active
todo
train
list
namespace
list
project
list
pipeline
list
whereami
whoami
The pattern <command> list | show
that is used for issue
will probably become
a common pattern everywhere that list
appears above. The subcommand list
implies
that multiple items are return, whereas show
implies seeing the details for a single item.
The merge
subcommands active
vs todo
are both commands that result in a list.
We might refactor them to instead be list --active
and list --todo
which would
be more consistent.
The git jira start
command might more logically be git jira issue start
but start
implies issue and it is expected to be one of the most commonly
executed commands so we elevate it the hierarchy.
git-jira-start -- Create a new topic branch for work on an issue
Usage:
$ git jira-start <issue>
Examples:
$ git jira-start BUG-0042
The command retrieves the summary line for the issue and converts it to
a suitable branch name using the kebab-case-convention. If BUG-0042 had
the summary "fix the thing" then the branch name will be BUG-0042-fix-the-thing
.
The command does not (yet) change the status of the issue.
git-bump -- Create a new branch based on the current branch
Usage:
$ git bump
This command is not specific to Jira. It simply reads the current branch name and creates a new branch with the version bumped, i.e. incremented.
Assume the current branch is BUG-0042-fix-the-thing
.
Executing the bump command once will create a new branch named BUG-0042-fix-the-thing.v1
. If you execute the bump command again it will
create a branch BUG-0042-fix-the-thing.v2
.
The git bump
command will work whatever the current branch name is.
It just checks to see if the current branch already ends with .v
<num>,
in which case it increments num but otherwise leaves the branch name as is.
If the current branch does not end with .v
<num> then it simply appends the
suffix .v1
.
Bun required
This package uses bun instead of node. You must install it before you install this package.
$ curl -fsSL https://bun.sh/install | bash
Install with any npm-compatible package manager
You can install ya-git-jira via npm
, or yarn
or pnpm
or bun
.
$ npm install -g ya-git-jira
Configuration
All configuration is via git config
settings. If your company has multiple
repositories that all using Jira issue tracking then you probably want to use
the global config by adding the --global
option to the commands below.
Jira
The git jira
comands require your Jira host
and token
. The host
is your Jira cloud service (usually yourcompany.atlassian.net
).
To create an API token follow the instructions here.
$ git config jira.host yourcompany.atlassian.net
$ git config jira.token "<long token here>"
GitLab
Likewise the git lab
comands require your GitLab host
and token
, though the default host
gitlab.com
will be sufficient
for many users. To create an API token follow the instructions here
$ git config gitlab.host gitlab.com
$ git config gitlab.token "<long token here>"
Email address
Both git lab
and git jira
also need the email address associated associated with those accounts.
Since git
itself requires an email addres via the setting user.email
, it is a reasonable default setting
that will work for many users. But if necessary, you can specify the different email addresses
using these two settings:
$ git config jira.user <email-address>
$ git config gitlab.user <email-address>