Git-bug keeps bug tracking inside the Git repository itself

Git-bug solves a specific problem: your project's bug tracker depends on a centralized service (GitHub Issues, Jira, GitLab) that requires a constant connection and locks your data into a proprietary format. The tool, written in Go and distributed under GPLv3, embeds the entire bug tracker inside the Git repository, using the same object and DAG mechanisms that already version your code. Today it has 10,100 stars and 323 forks on GitHub, with 2,691 commits accumulated in the project's history.

How storage works

Unlike plugins that save issues in .md files inside the repo (cluttering the code history), git-bug stores each bug, comment, and edit as native Git objects, separate from the code branches. In practice, this means two things: no extra file appears in your working tree, and the tracker travels along with any clone, fork, or mirror of the repository with no extra setup. According to the project, listing or opening bugs is an operation in the millisecond range, because there's no network round trip involved unless you explicitly ask for one.

The on-disk format is formally specified in what the project calls the "git-bug spec," covering the DAG entity model, user identities, and the bug structure itself. It's documentation aimed at anyone who wants to write an alternative implementation or a tool that reads git-bug data directly, without going through the official binary.

The native workflow, on the command line

Basic usage follows the vocabulary any dev already knows from Git. Creating an identity:

git bug user create

Opening a bug (the editor configured in your Git opens for title and description):

git bug add

Syncing with a remote, exactly as you would with git push/git pull:

git bug push [<remote>]
git bug pull [<remote>]

Listing and filtering using its own query syntax:

git bug ls "status:open sort:edit"

Searching by text content:

git bug ls "foo bar" baz

From there, commands like show, comment, open, and close cover the normal lifecycle of an issue. For those who'd rather not memorize flags, there's an interactive terminal interface (git bug termui) and a local Web UI (git bug webui), served by a Go binary that also exposes a GraphQL API and acts as a code browser, with a file tree, syntax highlighting, commit history, and diffs.

Sync without a central server

What sets git-bug apart from a simple versioned notes file is its distributed model: each bug is an object that can be created, edited, and merged by multiple people across different local copies, with conflict resolution inherited from Git itself. This removes the need to be online to open, comment on, or close a bug, a scenario the README itself literally describes as "on a plane or underwater." For distributed teams working in regions with unstable connectivity, or in air-gapped environments due to security policy, this removes the need to maintain replicas or caches of a third-party service just to keep logging problems.

The other side effect is automatic backup: since bug data travels through the same Git remotes that already host the code, any full clone of the repository is already a complete copy of the issue history. If the hosting service goes down or changes its policy tomorrow, the data is already everywhere the code has been cloned, with no migration needed.

Bridges to GitHub, GitLab, Jira, and Launchpad

For teams that aren't going to abandon GitHub Issues or Jira overnight, git-bug offers import and export bridges. Interactive setup:

git bug bridge new

Or explicit, pointing to a project on GitHub:

git bug bridge new --name=<bridge> --target=github \
  --url=https://github.com/git-bug/git-bug \
  --login=<login> --token=<token>

With the bridge configured, git bug bridge pull brings issues from the external service into the local repository, and git bug bridge push sends back the edits made offline. The project maintains a "feature matrix" documenting what each bridge supports today, since GitHub, GitLab, Jira, and Launchpad have different data models and not every feature (labels, assignees, milestones) maps 1:1 between them. It's worth checking that matrix before adopting a specific bridge in production, because feature parity varies by service.

What's not ready yet

The README itself classifies the Web UI as "work in progress" for the public portal scenario, that is, accepting issues and comments from external users authenticated via OAuth without requiring them to clone the repository and install the binary. Today the Web UI works well as a local interface for anyone who already has the repo cloned, but it still doesn't replace a portal open to the public the way GitHub Issues does natively. This matters for anyone thinking about using git-bug as the tracker for an open source project with many external contributors: the native workflow requires each person to have the repository and the binary installed, which is natural for those who already contribute code, but adds extra friction for someone who just wants to report a bug.

When it makes sense to consider

The most direct use case is a team that already works mostly through the CLI and wants to eliminate one more dependency on an external service, or a project that needs to work in disconnected environments by default (embedded development, field systems, contexts with an air-gap policy). For teams that rely on rich PM integrations (dashboards, automations, SLAs), Jira or GitHub Issues still cover more ground; git-bug offsets this with bridges, but bidirectional sync requires maintenance and isn't as seamless as using the native platform directly.

The project accepts contributions and maintains a room on Matrix for technical discussion, in addition to the issues and discussions in the repository itself on GitHub, where the list of planned features (including the Web UI's public portal) is open for anyone who wants to pick up one of these efforts.