🧩 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:

# 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.

Install the base package

pip install gibr

or if you use uv

uv tool install gibr

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.

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

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.

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

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

• init
• alias
• issues
• create

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.

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.

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

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

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"
    },
    ...
]

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

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)

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.

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.

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

See the Roadmap for upcoming features and plans.

See the Contributing guidelines if you would like to contribute.

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!