git-bug: Distributed Bug Tracker Embedded in Git

What git-bug is

git-bug is a bug tracker that lives inside your git repository. Issues, comments and identities are stored as git objects, so the only infrastructure you need for a bug tracker is the repository you already have. Collaboration happens through your normal git remotes: you push and pull bugs the same way you push and pull code. Because everything is local, it works offline, and because every clone carries the full issue history, the README pitches it as a guard against vendor lock-in: if a hosted service goes down or changes direction, you already have a complete backup.

The project is aimed at developers and maintainers who want issue tracking to travel with the code, who work offline or in restricted environments, or who want a local, scriptable interface to a hosted tracker. It does not add any files to your working tree, so it does not pollute the project itself.

How git-bug works

Internally git-bug uses a layered architecture, documented in the repository's design notes. At the bottom, a repository package handles all interaction with the git repository on disk through a set of interfaces. Above it sit the entity packages: bug, which models a bug as a series of operations (create, add comment, set title and so on) that compile into a snapshot, and identity, which stores versioned user identities in their own git structure.

A cache layer sits on top of those entities and is the only path the upper layers use to read or change data. It keeps loaded bugs in memory, maintains a small pre-digested excerpt of each bug on disk and in memory so the whole set can be filtered and sorted without loading every bug, and guarantees a single in-memory instance of each bug to avoid conflicting copies. It also takes a lock file on the repository for git-bug operations; regular git commands are unaffected. This caching is why the README can claim listing or opening bugs “is a matter of milliseconds.”

The user-facing layers are the CLI (built with cobra, which also generates shell completions and man pages), an interactive terminal UI (built with gocui), a GraphQL API, a web UI whose JavaScript is compiled into the Go binary, and bridges to external trackers. The on-disk format is formally specified in a separate git-bug spec repository covering the DAG entity format, identities and the bug entity, so other tools can read or write git-bug data directly. The project even points to an example of building your own distributed data structure in git on top of its entity package.

Key features

• Fully in git: no server, database or extra files in your project; bugs are git objects in the repository.
• Distributed sync: git bug push and git bug pull exchange bugs over any git remote.
• Offline-first: read, create and edit bugs without a network connection.
• Query language: filter and sort with expressions such as status:open sort:edit, plus full-text search.
• Terminal UI: git bug termui opens an interactive browser and editor for bugs.
• Web UI: git bug webui serves a local interface for browsing, searching, commenting and editing labels and status. It doubles as a code browser with a file tree, syntax highlighting, commit history and diffs.
• GraphQL API: the web UI talks to the backend through a published GraphQL schema that other tools can use too.
• Bridges: import from and export to GitHub, GitLab, Jira and Launchpad; a feature matrix documents what each bridge supports.
• Single binary: the web UI is embedded, so distribution is one file per platform.
• Signed releases: every release ships a checksums.txt signed with keyless cosign by the release workflow.

Getting started with git-bug

The installation guide lists packages for many platforms. On macOS via Homebrew:

brew install git-bug

On Windows via scoop:

scoop install git-bug

On Arch Linux from the official repositories:

sudo pacman -S git-bug

FreeBSD (pkg install git-bug), nixpkgs, and prebuilt binaries plus deb, rpm and apk packages for Linux on several CPU architectures are also available. Verify the install with:

git bug version

Then, inside a repository, create an identity and your first bug. Your editor opens to write a title and message:

git bug user create
git bug add

Share and fetch bugs through a remote, and list what is there:

git bug push [<remote>]
git bug pull [<remote>]
git bug ls
git bug ls "status:open sort:edit"

To connect a hosted tracker, configure a bridge interactively and then sync:

git bug bridge new
git bug bridge pull [<name>]
git bug bridge push [<name>]

Commands like show, comment, open and close handle the rest, and git bug <command> --help documents each one.

Use cases

The README describes three workflows:

• Native workflow: a team uses git-bug as its only tracker, pushing and pulling bugs between remotes alongside code. This suits small teams, self-hosted git setups without a forge, or projects that want issues to be part of the repository's history.
• Bridge workflow: an individual developer uses git-bug as a local, offline front end to GitHub, GitLab, Jira or Launchpad, syncing with bridge pull and bridge push. Useful when traveling, on unreliable connections, or when you want to script triage from the terminal or an editor.
• Web UI workflow: a public portal where outside users file issues through OAuth. The README marks this as a work in progress and says the web UI is not yet ready for that role.

Other practical scenarios include keeping an archival backup of a hosted project's issues, and migrating issues between trackers through the import and export bridges.

How git-bug compares

The natural comparison is with hosted trackers such as GitHub Issues, GitLab Issues or Jira, all of which git-bug can bridge to. Hosted trackers offer polished web interfaces, notifications and permissions that come with the forge; git-bug trades some of that for offline access, local speed and no dependence on a service. The bridges mean the choice is not exclusive: you can keep a hosted tracker as the public face and use git-bug locally.

Compared with keeping issues as plain text files in the repository, git-bug stores data outside the working tree and models edits as operations with identities, which avoids merge conflicts in a shared TODO file and keeps history structured.

Things to know before adopting git-bug

• GPL license: the code is released under GPLv3 or later. Using the tool does not affect your project's license, but distributing modified versions of git-bug carries GPL obligations. The logo is separately licensed under CC BY 4.0.
• Pre-1.0 versioning: the installation guide's package links reference v0.11.0, so expect the project to still be evolving.
• Web UI as a public portal is unfinished: accepting external OAuth users is planned but not ready, per the README.
• Bridge coverage varies: check the feature matrix to see which operations each bridge supports before relying on two-way sync.
• Default branch is trunk, which matters if you build from source or link to files.
• Long-running project: the repository dates back to 2018 and is funded in part through Open Collective backers and sponsors.

Project activity

As of October 2026 the git-bug/git-bug repository has roughly 10,700 stars. It was created on July 12, 2018, is written in Go, and is licensed under GPL-3.0 (the README specifies GPLv3 or later). The project has no separate homepage; documentation lives in the repository's doc directory, and discussion happens in GitHub Discussions and a Matrix room.