git-jira-branch

KO | EN

gitlite — search

#python #hacktoberfest #react #typescript #android #rust #deep-learning #linux #nodejs #cli #awesome-list #security #pytorch #openai

git-jira-branch

(★ 18)

Manage branches for your Jira tickets

git-jira-branch Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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

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

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

- [Usage](#Usage)
  - [Pick a Jira ticket interactively](#PickaJiraticketinteractively)
  - [Create a new branch from your current `HEAD`](#CreateanewbranchfromyourcurrentHEAD)
  - [Create a new branch based on some other revision](#Createanewbranchbasedonsomeotherrevision)
  - [Reset an already existing branch](#Resetanalreadyexistingbranch)
  - [Open tickets in your browser](#Openticketsinyourbrowser)
  - [Show ticket info on your terminal](#Showticketinfoonyourterminal)
  - [Attach GitHub PR links to the current branch ticket](#AttachGitHubPRlinkstothecurrentbranchticket)
  - [List branches associated with jira tickets](#Listbranchesassociatedwithjiratickets)
  - [`wizard` mode](#wizardmode)
- [Setup](#Setup)
  - [Install](#Install)
- [Configuration](#Configuration)
    - [For Jira Cloud](#ForJiraCloud)
    - [For Jira Data Center](#ForJiraDataCenter)
  - [Setup shell completions](#Setupshellcompletions)
- [Development](#Development)
  - [Run E2E tests against local sources](#RunE2Etestsagainstlocalsources)
  - [Write release notes with Changesets](#WritereleasenoteswithChangesets)
- [Contributors](#Contributors)
- [Technologies used](#Technologiesused)
- [License](#License)

## <a name='Usage'></a>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](https://github.com/Effect-TS/cli) used, all options must be passed
before the jira ticket key argument.

### <a name='PickaJiraticketinteractively'></a>Pick a Jira ticket interactively

For `create`, `switch`, and `delete`, the Jira ticket key is optional. If you
leave it out, git-jira-branch opens an interactive ticket picker that searches
Jira as you type and includes matching local branches.

```bash
git-jira-branch create
git-jira-branch switch
git-jira-branch delete
```

The picker lets you search with a full key like `MYAPP-1234` or, when
`JIRA_KEY_PREFIX` is configured, just the issue number. It also makes branch
state visible: `create` shows whether a branch already exists, while `switch`
and `delete` only allow tickets that have an associated local branch.

### <a name='CreateanewbranchfromyourcurrentHEAD'></a>Create a new branch from your current `HEAD`

Using the default JIRA_KEY_PREFIX

```bash
git-jira-branch create 1324
```

Or fully specified:

```bash
git-jira-branch create MYAPP-1234
```

### <a name='Createanewbranchbasedonsomeotherrevision'></a>Create a new branch based on some other revision

To create a new branch based on your `master` branch:

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

### <a name='Resetanalreadyexistingbranch'></a>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`)

```bash
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.

```bash
git-jira-branch switch MYAPP-1234
```

### <a name='Openticketsinyourbrowser'></a>Open tickets in your browser

1. For the current branch:
   ```bash
   $ git jira-branch open
   > Opening ticket url 'https://gcjb.atlassian.net/browse/GCJB-164' in your default browser...
   ```
2. For a given ticket:
   ```bash
   $ git jira-branch open GCJB-1234
   > Opening ticket url 'https://gcjb.atlassian.net/browse/GCJB-1234' in your default browser...
   ```

### <a name='Showticketinfoonyourterminal'></a>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.

```bash
$ git jira-branch info
```

Will create output like this:

> <ins>**GCJB-1** - Ticket summary</ins>
> <ins>**Task** | **Status**: To Do | **Creator**: Alexander Pankoff | **Assignee**: Alexander Pankoff</ins>
>
> Long lines in the description of the ticket are wrapped to fit a line width of 
> 80 characters to make it easier to read.

### <a name='AttachGitHubPRlinkstothecurrentbranchticket'></a>Attach GitHub PR links to the current branch ticket

The `link-pr` command resolves the Jira ticket from the current branch, or uses
an explicit Jira key if provided, detects the GitHub repository from your git
remotes, finds pull requests in that repository whose head branch contains the
Jira key, and adds missing Jira remote links for those pull requests.

It prefers a GitHub `upstream` remote, then `origin`, and otherwise uses the
first GitHub remote. You can override that with `--remote <name>` or bypass
remote detection entirely with `--repo <owner/repo>`. Supported remote formats
include SSH (`git@github.com:...`, `ssh://git@github.com/...`) and HTTPS
(`https://github.com/...`).

By default, `link-pr` scans the newest `500` pull requests. Override that with
`--scan-limit` or `LINK_PR_SCAN_LIMIT`, or use `all` to scan full history. The
search currently scans pull requests across all GitHub PR states and matches on
the head branch name.

```bash
$ git jira-branch link-pr
> Linked 1, skipped 1.
> linked #42 https://github.com/my-org/my-repo/pull/42
> skipped #40 https://github.com/my-org/my-repo/pull/40
```

```bash
$ git jira-branch link-pr FOOX-1234
```

Examples:

```bash
git-jira-branch link-pr --scan-limit 1000 FOOX-1234
git-jira-branch link-pr --scan-limit all FOOX-1234
git-jira-branch link-pr --remote upstream FOOX-1234
git-jira-branch link-pr --repo my-org/my-repo FOOX-1234
git-jira-branch link-pr --provider github FOOX-1234
```

### <a name='Listbranchesassociatedwithjiratickets'></a>List branches associated with jira tickets

```bash
$ 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
```

### <a name='wizardmode'></a>`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.

```bash
git-jira-branch --wizard
```

## <a name='Setup'></a>Setup

### <a name='Install'></a>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`.

```bash
npm i -g git-jira-branch
```

### <a name='Configuration'></a>Configuration

#### <a name='ForJiraCloud'></a>For Jira Cloud

1. Create a Jira API Token [See Jira
   Docs](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
1. 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`:
   ```bash
   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"
   ```

#### <a name='ForJiraDataCenter'></a>For Jira Data Center

**Note: this project is tested against a Jira Cloud instance. Jira Data Center
support is best effort: it is not covered by the E2E test suite and has not
been tested by the author.**

1. Create a Jira PAT (Personal Access Token) [See Jira
   Docs](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html)
1. 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`:
   ```bash
   export JIRA_PAT="YOUR_PERSONAL_ACCESS_TOKEN"
   export JIRA_API_URL="https://jira.mycompany.com"
   export JIRA_KEY_PREFIX="MYAPP"
   ```

For `link-pr` only, set one GitHub token:

```bash
export GITHUB_TOKEN="YOUR_GITHUB_TOKEN"
# or
export GH_TOKEN="YOUR_GITHUB_TOKEN"
```

If both are present, `GITHUB_TOKEN` takes precedence.

Optional default scan window for `link-pr`:

```bash
export LINK_PR_SCAN_LIMIT="500"
```

`LINK_PR_SCAN_LIMIT` must be a positive integer. It only affects `link-pr` and
can be overridden per invocation with `--scan-limit`.

### <a name='Setupshellcompletions'></a>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:

```bash
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`:

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

## <a name='Development'></a>Development

### <a name='RunE2Etestsagainstlocalsources'></a>Run E2E tests against local sources

Running `pnpm e2e-test` locally type-checks, rebuilds the CLI, and then executes
the freshly built binary (`node dist/main.js`) against the fixtures, so no extra
setup is required.

In CI you can call `pnpm e2e-test:ci`, which defaults to
`GIT_JB_BIN=git-jira-branch` unless you override the variable before invoking
the command. This lets you choose whether the suite exercises the published
package or a specific binary path.

### <a name='WritereleasenoteswithChangesets'></a>Write release notes with Changesets

Commits should be atomic and have clear, descriptive messages; no type or scope
prefix is required. Versions and changelogs are controlled explicitly with
[Changesets](https://github.com/changesets/changesets), not inferred from commit
messages. Pull requests are rebase-merged so their individual commits remain in
the project history.

Every pull request that should change the published package needs a changeset:

```bash
pnpm changeset
```

Choose `patch`, `minor`, or `major`, then write a concise note for end users.
The note is copied into `CHANGELOG.md` and the GitHub release, so describe the
user-visible outcome rather than the implementation or commit mechanics. Commit
the generated `.changeset/*.md` file alongside the change. Documentation,
tests, CI changes, and internal refactors that do not affect the published
package do not need a changeset.

After changesets reach `master`, the release workflow collects them in the
`Release package updates` pull request. Merging that pull request publishes the
new version to npm and creates the corresponding GitHub release automatically.

## <a name='Contributors'></a>Contributors

- Alexander Pankoff ([@ccntrq](https://github.com/ccntrq))
- Jakob Friedrich ([@jakobtfr](https://github.com/jakobtfr))
- Taylor Falk ([@taytayp](https://github.com/taytayp) [@tfalkarkea](https://github.com/tfalkarkea))

## <a name='Technologiesused'></a>Technologies used

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

| Package | Usage |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [effect](https://github.com/Effect-TS/effect) | The core effect system and runtime. |
| [@effect/cli](https://github.com/Effect-TS/cli) | Command line handling and option parsing. The `wizard` mode and `--completions` option are automatically provided by this lib. |
| [@effect/platform](https://github.com/Effect-TS/platform) | For its http client. |
| [@effect/platform-node](https://github.com/Effect-TS/platform) | 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`](https://vitest.dev). The testsuite can be run using `pnpm test`.

## <a name='License'></a>License

The code in this repository is licensed under the [MIT License](/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](/assets/gjb-logo.svg).

git-jira-branch

git-jira-branch Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

git-jira-branch

git-jira-branch Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README