git-bug/README.md

git-bug

git-bug is a bug tracker that:

• fully embed in git: you only need your git repository to have a bug tracker
• is distributed: use your normal git remote to collaborate, push and pull your bugs !
• works offline: in a plane or under the sea ? keep reading and writing bugs
• prevent vendor locking: your usual service is down or went bad ? you already have a full backup
• is fast: listing bugs or opening them is a matter of milliseconds
• doesn't pollute your project: no files are added in your project
• integrate with your tooling: use the UI you like (CLI, terminal, web) or integrate with your existing tools through the CLI or the GraphQL API
• bridge with other bug trackers: bridges exist to import and export to other trackers.

🚧 This is now more than a proof of concept, but still not fully stable. Expect dragons and unfinished business. 🚧

Install

Pre-compiled binaries

1. Go to the release page and download the appropriate binary for your system.
2. Copy the binary anywhere in your PATH
3. Rename the binary to git-bug (or git-bug.exe on windows)

That's all !

Linux packages

• Archlinux (AUR)

go get (unstable)

go get -u github.com/MichaelMure/git-bug

If it's not done already, add golang binary directory in your PATH:

export PATH=$PATH:$(go env GOROOT)/bin:$(go env GOPATH)/bin

CLI usage

Create a new identity:

git bug user create

Create a new bug:

git bug add

Your favorite editor will open to write a title and a message.

You can push your new entry to a remote:

git bug push [<remote>]

And pull for updates:

git bug pull [<remote>]

List existing bugs:

git bug ls

Filter and sort bugs using a query:

git bug ls "status:open sort:edit"

You can now use commands like show, comment, open or close to display and modify bugs. For more details about each command, you can run git bug <command> --help or read the command's documentation.

Interactive terminal UI

An interactive terminal UI is available using the command git bug termui to browse and edit bugs.

Web UI (status: WIP)

You can launch a rich Web UI with git bug webui.

This web UI is entirely packed inside the same go binary and serve static content through a localhost http server.

The web UI interact with the backend through a GraphQL API. The schema is available here.

Bridges

Importer implementations

	Github	Gitlab	Launchpad
incremental (can import more than once)	✔️	✔️	❌
with resume (download only new data)	❌	❌	❌
identities	✔️	✔️	✔️
identities update	❌	❌	❌
bug	✔️	✔️	✔️
comments	✔️	✔️	✔️
comment editions	✔️	❌	❌
labels	✔️	✔️	❌
status	✔️	✔️	❌
title edition	✔️	✔️	❌
media/files	❌	❌	❌
automated test suite	✔️	✔️	❌

Exporter implementations

	Github	Gitlab	Launchpad
bug	✔️	✔️	❌
comments	✔️	✔️	❌
comment editions	✔️	✔️	❌
labels	✔️	✔️	❌
status	✔️	✔️	❌
title edition	✔️	✔️	❌
automated test suite	✔️	✔️	❌

Bridge usage

Interactively configure a new github bridge:

git bug bridge configure

Or manually:

git bug bridge configure \
    --name=mybridge \
    --target=github \
    --url=https://github.com/michaelmure/git-bug \
    --token=$TOKEN

Import bugs:

git bug bridge pull [<name>]

Export modifications:

git bug bridge push [<name>]

Deleting a bridge:

git bug bridge rm [<name>]

Internals

Interested by how it works ? Have a look at the data model and the internal bird-view.

Misc

• Bash completion
• Zsh completion
• PowerShell completion
• ManPages

Planned features

• media embedding
• more bridges
• extendable data model to support arbitrary bug tracker
• inflatable raptor

Contribute

PRs accepted. Drop by the Gitter lobby for a chat or browse the issues to see what is worked on or discussed.

Developers unfamiliar with Go may try to clone the repository using "git clone". Instead, one should use:

go get -u github.com/MichaelMure/git-bug

The git repository will then be available:

# Note that $GOPATH defaults to $HOME/go
$ cd $GOPATH/src/github.com/MichaelMure/git-bug/

You can now run make to build the project, or make install to install the binary in $GOPATH/bin/.

To work on the web UI, have a look at the dedicated Readme.

Contributors ❤️

This project exists thanks to all the people who contribute.

Backers

Thank you to all our backers! 🙏 [Become a backer]

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

License

Unless otherwise stated, this project is released under the GPLv3 or later license © Michael Muré.

The git-bug logo by Viktor Teplov is released under the Creative Commons Attribution 4.0 International (CC BY 4.0) license © Viktor Teplov.