git-jira-branch - Manage branches for your Jira tickets

Creates feature branches based on your Jira tickets type and description.

$ git jira-branch create MYAPP-1234
> Successfully created branch: 'feat/MYAPP-1234-sluggified-description-used-as-branchname'

• Usage
  • Create a new branch from your current HEAD
  • Create a new branch based on some other revision
  • Reset an already existing branch
  • Open tickets in your browser
  • Show ticket info on your terminal
  • List branches associated with jira tickets
  • wizard mode
• Setup
  • Install
  • Configuration
    • For Jira Cloud
    • For Jira Data Center
  • Setup shell completions
• Technologies used
• License

Usage

Since this command starts with git- all commands can be run via git-jira-branch or as a git subcommand with git jira-branch.

Due to a limitation in the awesome cli library used, all options must be passed before the jira ticket key argument.

Create a new branch from your current HEAD

Using the default JIRA_KEY_PREFIX

git-jira-branch create 1324

Or fully specified:

git-jira-branch create MYAPP-1234

Create a new branch based on some other revision

To create a new branch based on your master branch:

git-jira-branch create -b master MYAPP-1234

Reset an already existing branch

Pass the -r|--reset flag to reset an already existing branch to the current HEAD or the specified base revision (with -b)

git-jira-branch create -r MYAPP-1234

Switch to an already existing branch that is associated with a Jira ticket

To switch to an already existing branch that is associated with a Jira ticket you can use the switch command.

git-jira-branch switch MYAPP-1234

Open tickets in your browser

1. For the current branch:

   $ git jira-branch open
   > Opening ticket url 'https://gcjb.atlassian.net/browse/GCJB-164' in your default browser...

2. For a given ticket:

   $ git jira-branch open GCJB-1234
   > Opening ticket url 'https://gcjb.atlassian.net/browse/GCJB-1234' in your default browser...

Show ticket info on your terminal

The info command shows the information for ticket nicely rendered for consumtpion in the terminal.

By default info is show for the ticket associated with the current branch. Alternatively a ticket key can be passed as an argument to show info for that ticket.

$ git jira-branch info

Will create output like this:

GCJB-1 - Ticket summary
Task | Status: To Do | Creator: Alexander Pankoff | Assignee: Alexander Pankoff

Long lines in the description of the ticket are wrapped to fit a line width of
80 characters to make it easier to read.

List branches associated with jira tickets

$ git jira-branch list
> * feat/GCJB-1-e2e-test-ticket-with-a-fancy-summary
>   feat/GCJB-2-another-ticket-that-looks-like-its-associated-with-a-jira-ticket

wizard mode

Use the --wizard option to enter wizard mode. This will prompt you for the Jira ticket key and additional options and build the appropriate command line for you.

git-jira-branch --wizard

Setup

Install

The cli can be installed from npm. It assumes you have git installed on your system and the git command to be available on your $PATH.

npm i -g git-jira-branch

Configuration

For Jira Cloud

1. Create a Jira API Token See Jira Docs
2. Add the created API Token, your login email, the base url of your Jira instance and optionally a default Jira key prefix to your environment. For example in your .bashrc or .zshrc:

   export JIRA_USER_EMAIL="YOUR_JIRA_LOGIN_EMAIL"
   export JIRA_API_TOKEN="YOUR_API_TOKEN"
   export JIRA_API_URL="https://jira.mycompany.com"
   export JIRA_KEY_PREFIX="MYAPP"

For Jira Data Center

1. Create a Jira PAT (Personal Access Token) See Jira Docs
2. Add the created Jira PAT, the base url of your Jira instance and optionally a default Jira key prefix to your environment. For example in your .bashrc or .zshrc:

   export JIRA_PAT="YOUR_PERSONAL_ACCESS_TOKEN"
   export JIRA_API_URL="https://jira.mycompany.com"
   export JIRA_KEY_PREFIX="MYAPP"

Setup shell completions

The cli can generate shell completion scripts for bash,zsh and fish. To generate and print the script for your shell run:

git-jira-branch --completions (bash|zsh|fish)

To install the completions for your shell, run the above command and pipe the output to a file and source it in your shell config.

E.g. for bash:

git-jira-branch --completions bash > ~/.git-jira-branch-bash-completions
echo "source \$HOME/.git-jira-branch-bash-completions" >> ~/.bashrc
source ~/.bashrc

Technologies used

This project was started as an excuse to explore the Effect ecosystem and was written with only @effect/* packages as it's runtime dependencies. It uses:

Package	Usage
effect	The core effect system and runtime.
@effect/cli	Command line handling and option parsing. The wizard mode and --completions option are automatically provided by this lib.
@effect/platform	For its http client.
@effect/platform-node	For its shell command executor.

It uses the Jira API to fetch the details for a ticket and calls out directly to git for branch creation.

Tests were written using vitest. The testsuite can be run using pnpm test.

License

The code in this repository is licensed under the MIT License. Please note that the MIT License applies only to the code in this repository and not to any other assets, especially not the Logo.