gibr

🧩 A smarter CLI for creating Git branches.

gibr connects your Git workflow to your issue tracker — instantly creating consistent, descriptive branches. Fully configurable, and ready for any tracker or team setup.

Currently supporting integration with:

Usage

# 1️⃣ List open issues
$ gibr issues
|   Issue | Type   | Title                                 | Assignee   |
|---------|--------|---------------------------------------|------------|
|     123 | issue  | Add support for OAuth2 / login (beta) | ytreister  |
|      97 | issue  | Add support for gitlab                |            |

# 2️⃣ Decide which issue to work
$ gibr 123
Generating branch name for issue #123: Add support for OAuth2 / login (beta)
Branch name: ytreister/issue/123/add-support-for-oauth2-login-beta
✅  Created branch 'ytreister/issue/123/add-support-for-oauth2-login-beta' from main.
✅  Checked out branch: ytreister/issue/123/add-support-for-oauth2-login-beta
✅  Pushed branch 'ytreister/issue/123/add-support-for-oauth2-login-beta' to origin.

🚀 Quick start

Installation

Install the base package

pip install gibr

or if you use uv

uv tool install gibr

🧩 Optional dependencies

gibr supports multiple issue trackers, but you only need to install the dependencies for the ones you actually use.

Each tracker’s client library is an optional extra.

Tracker	Extra name	Install command
GitHub	github	pip install "gibr[github]" or uv tool install --with github gibr
GitLab	gitlab	pip install "gibr[gitlab]" or uv tool install --with gitlab gibr
Jira	jira	pip install "gibr[jira]" or uv tool install --with jira gibr
Azure	azure	pip install "gibr[azure]" or uv tool install --with azure gibr
Linear	built-in	N/A
Monday.dev	built-in	N/A
YouTrack	built-in	N/A

Note: You can also install multiple trackers at once, for example:

pip install "gibr[github,jira]"

or if you use uv

uv tool install --with github --with jira gibr

Initial setup

Run gibr init to set up your configuration interactively. This will create a .gibrconfig file in your project root with the correct format for your chosen issue tracker.

.gibrconfig defaults

Your .gibrconfig will be generated with defaults for branch_name_format and push. You can set push = False if you do not want to push your branch to origin by default. You can modify the branch name format as well, see Branch naming convention.

Defaults:

[DEFAULT]
branch_name_format = {issue}-{title}
push = True

Setup git aliases commands (optional)

Run gibr alias to set up git alias commands for your conveinence. This essentially allows you to extend the git CLI with gibr commands. See alias command for more details

Commands

• init
• alias
• issues
• create

init

gibr includes an init command to help you create your .gibrconfig file. See the following usage example:

$ gibr init
Welcome to gibr setup! Let’s get you started 🚀

Which issue tracker do you use?
1. AzureDevOps
2. GitHub
3. GitLab
4. Jira
5. Linear
6. Monday.dev
7. YouTrack
8. Forgejo (coming soon)

Select a number (1, 2, 3, 4, 5, 6, 7, 8) [1]: 2

GitHub selected.

GitHub repository (e.g. user/repo): ytreister/gibr
Environment variable for your GitHub token [GITHUB_TOKEN]:
🎉  Found GitHub token in environment (GITHUB_TOKEN)
.gibrconfig already exists. Overwrite? [y/N]: y
✅  Created .gibrconfig with GitHub settings
You're all set! Try: `gibr issues`

ℹ️  Customize your `.gibrconfig`:
  - Customize branch name format: set `branch_name_format` (default: "{issue}-{title}")
  - Disable automatic push: set `push = False` to prevent pushing

💡Note: .gibrconfig will expand envionmental variables, and you can define your variables in a .env.

alias

gibr includes a built-in helper that writes git aliases into your global ~/.gitconfig for you. Run:

gibr alias

This adds aliases such as git create so that instead of using the gibr CLI directly, you can use an extended version of git:

git create 123

The above command is equivalent to using the CLI as follows: gibr 123 or gibr create 123.

Global flag order

When using the alias version of the commands, the global flags (--verbose) must appear after the command. This is a limitation of the git aliases.

# ✅ gibr CLI (flags before)
gibr --verbose create 123

# ✅ git alias (flags after)
git create 123 --verbose

# ❌ wrong: flags after gibr CLI
gibr create 123 --verbose

# ❌ wrong: flags before the alias
git --verbose create 123

issues

Run gibr issues (or git issues) to view open issues in the issue tracker you have configured

JSON format

You can pass in a flag to change output format to JSON:

$gibr issues --json
[
    {
        "id": "FOO-314",
        "title": "establish a large-limit API key",
        "assignee": "ngoldman",
        "type": "issue"
    },
    ...
]

create

Run gibr 123 (or gibr create 123 or git create 123) to create a branch for the cooresponding issue number.

Branch naming convention

gibr uses the branch_name_format from your .gibrconfig to determine the format for the branch. You can use the following placeholders:

• {issuetype}
• {issue}
• {title}
• {assignee} (Note: If issue does not have an assignee and your branch name format contains assignee, you will not be able to create the branch)

Special cases: Jira, Linear and YouTrack

For Jira, you can specify a project_key in your configuration:

[jira]
project_key=FOO

For YouTrack, you can specify a project in your configuration:

[youtrack]
project=FOO

and for linear you can specify a team:

[linear]
team=FOO

If you do this, you can choose to either specify the entire issue id or just the numerical portion (i.e. FOO-123 or 123

# List issues
$ gibr issues
| Issue   | Type    | Title       | Assignee   |
|---------|---------|-------------|------------|
| FOO-3   | Subtask | Subtask 2.1 | ytreister  |
| FOO-2   | Story   | Task 2      |            |
# Create branch for FOO-3
$ gibr 3
Generating branch name for issue FOO-3: Subtask 2.1
Branch name: FOO-3-subtask-2-1
✅  Created branch 'FOO-3-subtask-2-1' from main.
✅  Checked out branch: FOO-3-subtask-2-1
✅  Pushed branch 'FOO-3-subtask-2-1' to origin.

Special case: Azure

Azure DevOps allows teams to customize their work item states based on their workflow. By default, this integration assumes the following states represent closed/completed work items:

• Done
• Removed
• Closed If your Azure DevOps project uses different state names or a custom workflow, you can configure the closed_states parameter to match your setup.

[azure]
closed_states=['Done', 'Removed', 'Closed']

Work items matching any of the configured closed_states will be excluded from the list of active issues.

Optional flags

• --verbose — enable debug-level logging for a command

Roadmap

See the Roadmap for upcoming features and plans.

Opensource contributions

See the Contributing guidelines if you would like to contribute.

💬 Feedback welcome!

Found a bug or have a feature request? Open an issue or start a discussion. If you find it useful, consider starring ⭐️ the repo — it really helps visibility!