git-bug: A Distributed Bug Tracker Embedded in Your Git Repository

Distributed Bug Tracking Without a Hosted Service

Conventional bug trackers, including GitHub Issues and GitLab Issues, store data on a central server. When the server is unavailable, developers cannot read or file bugs. git-bug takes a different approach: it stores all bug data inside the git repository itself, in a separate ref namespace that does not pollute working tree files.

This means a clone of the repository includes all its bugs. Collaborating is the same operation as collaborating on code: `git bug push [<remote>]` sends bugs to a remote, and `git bug pull [<remote>]` fetches updates. No additional service is required. The README lists five properties: fully integrated in git, distributed, offline-capable, free from vendor lock-in, and fast.

The project also supports bridging, which is a different workflow: using git-bug as a local interface to a hosted tracker, synchronising bugs with GitHub, GitLab, Jira, or Launchpad via the bridge commands.

How git-bug Stores Bugs Inside the Repository

git-bug stores bugs and identities in separate ref namespaces: `refs/bugs/` and `refs/identities/`. These refs are not part of the working tree and are not visible in `git status` or `git log` by default. The README states that no files are added to the project.

Each bug is a directed acyclic graph (DAG) of operations stored as git objects. The entity format and the identity format are formally specified in a spec document in the repository. The README links to the data model and architecture documentation in `doc/design/`.

Creating a new identity is a prerequisite before filing bugs:

git bug user create

After that, creating a bug opens the configured editor to enter a title and message:

git bug add

This design has an implication for garbage collection: `git gc` will collect the bug objects unless the refs are preserved. The cleanup Makefile targets (`clean-local-bugs`, `clean-remote-bugs`) use `git update-ref -d` and `git push origin -d` to remove local and remote bug refs.

CLI, Terminal UI, and Web UI

git-bug provides three interfaces. The CLI covers creation, display, and modification of bugs from the shell:

git bug ls

List filtering and sorting use a query syntax:

git bug ls "status:open sort:edit"

Text search across bug content:

git bug ls "foo bar" baz

The `show`, `comment`, `open`, and `close` commands display and modify individual bugs. The full command documentation is in `doc/md/git-bug.md`.

The terminal UI launches with `git bug termui`. It is an interactive text interface for browsing and editing bugs without leaving the terminal.

The web UI launches with `git bug webui`. The README describes it as a rich interface for browsing, searching, filtering, opening, commenting, and editing bugs. It also works as a code browser with a file tree, syntax-highlighted files, commit history, and diffs. The web UI is packaged inside the same Go binary and served by a local HTTP server, communicating with the backend through a GraphQL API.

Bridges: Synchronising with GitHub, GitLab, Jira, and Launchpad

The bridge workflow lets teams use git-bug as a local interface to a hosted tracker. Configure a bridge interactively:

git bug bridge new

Or with explicit flags:

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

The bridge pull and push commands synchronise bugs:

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

Delete a bridge configuration:

git bug bridge rm [<name>]

The README links to a feature matrix that shows which bridge operations are supported for each tracker. Not all bridges support all operations; the matrix is the authoritative source for which capabilities are available per platform.

Shell Completions, Man Pages, and GraphQL API

git-bug ships shell completions for Bash, Zsh, fish, and PowerShell in `misc/completion/`. Man pages are in `doc/man/`. Both are generated from the CLI definitions and are included in the repository.

The web UI communicates with the backend through a GraphQL API. The schema is referenced from the README and available in the repository. This API can be used for programmatic access to bugs from external tools without going through the CLI.

The `go.mod` file shows that the project uses Go 1.26.0 and imports a full set of dependencies including gqlgen for GraphQL, gocui for the terminal UI, bleve for full-text search, and go-git for the git operations. The build requires building the web UI first with `pnpm` before running `go build`.

Limitations and When git-bug Does Not Fit

The web UI public portal mode is explicitly described as a planned but incomplete feature. The README states: "the web UI aims to accept external OAuth authentication and act as a public portal. However the web UI is not up to speed for that yet." Teams that need a publicly accessible issue tracker for open-source contributors cannot currently use git-bug's web UI for that purpose.

The GPL-3.0 licence applies to the binary and the source. Programmes that link against git-bug as a library must comply with GPL-3.0 terms. The README notes that the logo has a separate Creative Commons Attribution 4.0 licence, credited to Viktor Teplov.

For teams fully committed to GitHub or GitLab Issues, the bridge workflow adds synchronisation overhead. Bugs created on the remote must be pulled before they appear locally, and local changes must be pushed to appear on the hosted tracker. The bridge feature matrix documents which operations sync bidirectionally for each supported target.

The project uses blevesearch/bleve for full-text indexing of bug content, visible in the `go.mod` dependencies. This index powers the text search in `git bug ls "foo bar"` and is stored locally.

LinearB, GitLab Issues, and GitHub Issues are alternatives for teams who do not need offline access. GitHub Issues in particular is tightly integrated with pull requests and code review workflows in ways that git-bug does not replicate. The most recent stable release was v0.11.0 on 2026-09-22, following v0.10.1 and v0.10.0 in May 2025. The gap between those two release clusters shows that the project has longer development cycles rather than frequent minor releases. The last push to the repository was on 2026-09-28.

Editorial conclusion

git-bug is the right tool for teams or individuals who want a portable bug tracker that travels with the repository, works offline, and can synchronise with GitHub or GitLab without committing to those platforms as the primary store. The CLI, terminal UI, and web UI give multiple access paths depending on the workflow. It is not the right fit for projects that need a publicly accessible, always-on issue tracker for external contributors, because the web UI is explicitly marked as work-in-progress for public portal use. The GPL-3.0 licence applies to the compiled binary and the source; check whether that is compatible with your deployment context before building a tool on top of git-bug.

Frequently asked questions

Official sources

1. git-bug/git-bug on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases