git-bug: A Distributed, Offline-First Bug Tracker for Git

git-bug is a specialized bug tracking system that lives directly inside your git repository. It transforms your version control system into a fully functional issue tracker without requiring a centralized server.

🚀 Core Value Proposition

Instead of relying on proprietary cloud platforms external services, git-bug offers a decentralized approach.

---

🛠 Architecture & Workflow

The system operates as a distributed graph of entities. Mathematically, the bug state can be viewed as a Directed Acyclic Graph (DAG) where each update is a node $\mathcal{N}$ and edges $\mathcal{E}$ represent the causal history: $\text{State} = \bigcup (\mathcal{N}, \mathcal{E})$

Installation

For a comprehensive walkthrough, including source compilation and verification, please refer to the INSTALLATION.md file.

Collaboration Patterns

• Git-Native: Much like managing source code, use git bug push and git bug pull to exchange bug reports with teammates via git remotes.
• Bridge-Based: Use git-bug as a local proxy for other services. Sync via git bug bridge pull and git bug bridge push to maintain a local workflow while updating external trackers.
• Web Portal (WIP): The goal is to allow the Web UI to function as a public-facing portal utilizing OAuth for external contributions.

---

💻 Usage Guide

Command Line Interface (CLI)

The CLI provides direct access to all bug-tracking functions:

• Identity: git bug user create (Set up your profile)
• Creation: git bug add (Opens your default editor for title/description)
• Synchronization:
  • git bug push [ remote ]
  • git bug pull [ remote ]
• Discovery:
  • List all: git bug ls
  • Filter/Sort: git bug ls " status:open sort:edit "
  • Text Search: git bug ls " foo bar " baz
• Management: Use show, comment, open, or close to modify entries.

Tip: Need more help? Run git bug <command> --help or consult the official documentation.

Interactive Terminal UI (TUI)

Launch the TUI with git bug termui. This provides a rich environment to:

1. Browse, filter, and search issues.
2. Edit labels, statuses, and titles.
3. Bonus: It acts as a code browser, featuring a file tree, commit history, diffs, and syntax highlighting.

Web Interface

The Web UI is embedded within the Go binary and runs via a local HTTP server. It communicates with the backend using a GraphQL API.

---

🌉 Bridges

git-bug can interface with several major platforms: GitHub, GitLab, Jira, and Launchpad.

Bridge Management Commands:

• Interactive Setup: git bug bridge new
• Manual Setup:

  git bug bridge new \
    --name=my-bridge \
    --target=github \
    --url=https://github.com/user/repo \
    --login=myuser \
    --token=mytoken
  

• Syncing: git bug bridge pull [ name ] $\rightarrow$ git bug bridge push [ name ]
• Removal: git bug bridge rm [ name ]

---

⚙️ Internals & Technicals

For those interested in the "how," the on-disk format is strictly defined in the git-bug spec. This covers the DAG entity format, identities, and bug entities. This is essential for anyone building compatible tools or implementing the protocol in another language.

Additional Resources:

• Shell completions available for Bash, Zsh, fish, and powershell.
• Comprehensive ManPages included.

Roadmap

• Public-facing Web UI portal for external input.
• Inflatable raptor.
• Refer to the feature matrix for a full list of planned capabilities.

---

🤝 Contributing & Community

We welcome Pull Requests! To get started:

1. Read CONTRIBUTING.md to set up your dev environment.
2. Build the project and execute the test suite.
3. Join the conversation in our Matrix room.

Contributors ❤️ This project is a community effort.

Support the Project:

• [Become a backer or sponsor on Open Collective]
• 
• 

Licensing:

• Software: Released under GPLv3 or later © Michael Muré.
• Logo: Created by Viktor Teplov, released under CC BY 4.0.