1<p align="center">
  2    <img width="150px" src="https://cdn.rawgit.com/MichaelMure/git-bug/master/misc/logo/logo-alpha-flat-bg.svg">
  3</p>
  4<h1 align="center">git-bug</h1>
  5
  6<div align="center">
  7
  8[![Backers on Open Collective](https://opencollective.com/git-bug/backers/badge.svg)](#backers)
  9[![Sponsors on Open Collective](https://opencollective.com/git-bug/sponsors/badge.svg)](#sponsors)
 10[![License: GPL v3](https://img.shields.io/badge/License-GPLv3+-blue.svg)](http://www.gnu.org/licenses/gpl-3.0)
 11[![GoDoc](https://godoc.org/github.com/MichaelMure/git-bug?status.svg)](https://godoc.org/github.com/MichaelMure/git-bug)
 12[![Go Report Card](https://goreportcard.com/badge/github.com/MichaelMure/git-bug)](https://goreportcard.com/report/github.com/MichaelMure/git-bug)
 13[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/the-git-bug/Lobby)
 14
 15</div>
 16
 17`git-bug` is a bug tracker that:
 18
 19- **is fully embedded in git**: you only need your git repository to have a bug tracker
 20- **is distributed**: use your normal git remote to collaborate, push and pull your bugs!
 21- **works offline**: in a plane or under the sea? Keep reading and writing bugs!
 22- **prevents vendor lock-in**: your usual service is down or went bad? You already have a full backup.
 23- **is fast**: listing bugs or opening them is a matter of milliseconds
 24- **doesn't pollute your project**: no files are added in your project
 25- **integrates with your tooling**: use the UI you like (CLI, terminal, web) or integrate with your existing tools through the CLI or the GraphQL API
 26- **bridges to other bug trackers**: use [bridges](#bridges) to import and export to other trackers.
 27
 28## Help needed!
 29
 30This project has grown bigger than I can handle by myself, especially with a day job. I'm looking for people to help on or maintain part of it:
 31- each bridges (go)
 32- the terminal UI (go)
 33- the web UI (Typescript/React/GraphQL)
 34
 35Individually, those pieces are not especially complex but doing everything make it hard for me to focus on the core where things get more complicated. If this is useful for you or you just want to join the fun, maybe consider it?
 36
 37## Installation
 38
 39<details><summary>Pre-compiled binaries</summary>
 40
 411. Go to the [release page](https://github.com/MichaelMure/git-bug/releases/latest) and download the appropriate binary for your system.
 422. Copy the binary anywhere in your $PATH
 433. Rename the binary to `git-bug` (or `git-bug.exe` on windows)
 44
 45That's all !
 46
 47</details>
 48
 49<details><summary>Windows packages</summary>
 50
 51* [Scoop](https://github.com/ScoopInstaller/Main/blob/master/bucket/git-bug.json)
 52  ```
 53  scoop install git-bug
 54  ```
 55
 56</details>
 57
 58<details><summary>Linux packages</summary>
 59
 60* [Archlinux (AUR)](https://aur.archlinux.org/packages/?K=git-bug)
 61* [NixOS](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/version-management/git-and-tools/git-bug/default.nix#L31)
 62
 63</details>
 64
 65<details><summary>macOS packages</summary>
 66
 67* [Homebrew](https://formulae.brew.sh/formula/git-bug)
 68  ```
 69  brew install git-bug
 70  ```
 71
 72</details>
 73
 74<details><summary>FreeBSD package/port</summary>
 75
 76Install via the package manager
 77  ```
 78  pkg install git-bug
 79  ```
 80
 81Or from the ports collection
 82  ```
 83  cd /usr/ports/devel/git-bug && make install clean
 84  ```
 85
 86</details>
 87
 88<details><summary>Compile from git (unstable)</summary>
 89
 90```shell
 91git clone git@github.com:MichaelMure/git-bug.git
 92make install
 93```
 94
 95If it's not done already, add the golang binary directory in your PATH:
 96
 97```bash
 98export PATH=$PATH:$(go env GOROOT)/bin:$(go env GOPATH)/bin
 99```
100
101</details>
102
103## Workflows
104
105There are multiple ways to use `git-bug`:
106
107<details><summary>Native workflow</summary>
108<p align="center">
109    <img src="misc/diagrams/native_workflow.png" alt="Native workflow">
110</p>
111
112This is the pure `git-bug` experience. In a similar fashion as with code, use `git bug push` and `git bug pull` to push and pull your bugs between git remotes and collaborate with your teammate. 
113
114</details>
115
116<details><summary>Bridge workflow</summary>
117<p align="center">
118    <img src="misc/diagrams/bridge_workflow.png" alt="Bridge workflow">
119</p>
120
121As `git-bug` has bridges with other bug-trackers, you can use it as your personal local remote interface. Sync with `git bug bridge pull` and `git bug bridge push`, work from your terminal, integrate into your editor, it's up to you. And it works offline !
122
123</details>
124
125<details><summary>Web UI workflow (WIP)</summary>
126<p align="center">
127    <img src="misc/diagrams/webui-workflow.png" alt="Web UI workflow">
128</p>
129
130Often, projects needs to have their bug-tracker public and accept editions from anyone facing a problem. To support this workflow, `git-bug` aims to have the web UI accept external OAuth authentication and act as a public portal. However the web UI is not up to speed for that yet. Contribution are very much welcome!
131
132</details>
133
134## CLI usage
135
136Create a new identity:
137
138```
139git bug user create
140```
141
142Create a new bug:
143
144```
145git bug add
146```
147
148Your favorite editor will open to write a title and a message.
149
150You can push your new entry to a remote:
151```
152git bug push [<remote>]
153```
154
155And pull for updates:
156```
157git bug pull [<remote>]
158```
159
160List existing bugs:
161```
162git bug ls
163```
164
165Filter and sort bugs using a [query](doc/queries.md):
166```
167git bug ls "status:open sort:edit"
168```
169
170Search for bugs by text content:
171```
172git bug ls "foo bar" baz
173```
174
175You 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](doc/md/git-bug.md).
176
177## Interactive terminal UI
178
179An interactive terminal UI is available using the command `git bug termui` to browse and edit bugs.
180
181![Termui recording](misc/termui_recording.gif)
182
183## Web UI
184
185You can launch a rich Web UI with `git bug webui`.
186
187<p align="center">
188  <img src="misc/webui1.png" alt="Web UI screenshot 1" width="880">
189</p>
190
191<p align="center">
192  <img src="misc/webui2.png" alt="Web UI screenshot 2" width="880">
193</p>
194
195This web UI is entirely packed inside the same go binary and serve static content through a localhost http server.
196
197The web UI interact with the backend through a GraphQL API. The schema is available [here](api/graphql/schema).
198
199## Bridges
200
201✅: working  🟠: partial implementation  ❌: not working
202
203### Importer implementations
204
205|                                                 | Github | Gitlab | Jira | Launchpad |
206|-------------------------------------------------|:------:|:------:|:----:|:---------:|
207| **incremental**<br/>(can import more than once) |   ✅    |   ✅    |  ✅   |     ❌     |
208| **with resume**<br/>(download only new data)    |   ✅    |   ✅    |  ✅   |     ❌     |
209| **identities**                                  |   🟠   |   🟠   |  🟠  |    🟠     |
210| **bugs**                                        |   ✅    |   ✅    |  ✅   |    🟠     |
211| **board**                                       |   ❌    |   ❌    |  ❌   |     ❌     |
212| **media/files**                                 |   ❌    |   ❌    |  ❌   |     ❌     |
213| **automated test suite**                        |   ✅    |   ✅    |  ❌   |     ❌     |
214
215### Exporter implementations
216
217|                          | Github | Gitlab | Jira | Launchpad |
218|--------------------------|:------:|:------:|:----:|:---------:|
219| **identities**           |   🟠   |   🟠   |  🟠  |    🟠     |
220| **bug**                  |   ✅    |   ✅    |  ✅   |     ❌     |
221| **board**                |   ❌    |   ❌    |  ❌   |     ❌     |
222| **automated test suite** |   ✅    |   ✅    |  ❌   |     ❌     |
223
224#### Bridge usage
225
226Interactively configure a new github bridge:
227
228```bash
229git bug bridge configure
230```
231
232Or manually:
233
234```bash
235git bug bridge configure \
236    --name=<bridge> \
237    --target=github \
238    --url=https://github.com/MichaelMure/git-bug \
239    --login=<login>
240    --token=<token>
241```
242
243Import bugs:
244
245```bash
246git bug bridge pull [<name>]
247```
248
249Export modifications:
250
251```bash
252git bug bridge push [<name>]
253```
254
255Deleting a bridge:
256
257```bash
258git bug bridge rm [<name>]
259```
260
261## Internals
262
263Interested in how it works ? Have a look at the [data model](doc/model.md) and the [internal bird-view](doc/architecture.md).
264
265Or maybe you want to [make your own distributed data-structure in git](entity/dag/example_test.go) ?
266
267See also all the [docs](doc).
268
269## Misc
270
271- [Bash, Zsh, fish, powershell completion](misc/completion)
272- [ManPages](doc/man)
273
274## Planned features
275
276The [feature matrix](doc/feature_matrix.md) gives a good overview of what is planned, without being exhaustive.
277
278Additional planned feature:
279- webUI that can be used as a public portal to accept user's input
280- inflatable raptor
281
282## Contribute
283
284PRs accepted. Drop by the [Gitter lobby](https://gitter.im/the-git-bug/Lobby) or the [Matrix room](https://matrix.to/#/#the-git-bug_Lobby:gitter.im) for a chat, look at the [feature matrix](doc/feature_matrix.md) or browse the issues to see what is worked on or discussed.
285
286```shell
287git clone git@github.com:MichaelMure/git-bug.git
288```
289
290You can now run `make` to build the project, or `make install` to install the binary in `$GOPATH/bin/`.
291
292To work on the web UI, have a look at [the dedicated Readme.](webui/Readme.md)
293
294Some tests for the CLI use golden files, if the output of CLI commands is
295changed, run the following command, then inspect the changed files in
296`commands/testdata/...` to make sure the output text is as expected:
297
298```shell
299go test ./commands -update
300```
301
302## Contributors :heart:
303
304This project exists thanks to all the people who contribute.
305<a href="https://github.com/MichaelMure/git-bug/graphs/contributors"><img src="https://opencollective.com/git-bug/contributors.svg?width=890&button=false" /></a>
306
307
308## Backers
309
310Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/git-bug#backer)]
311
312<a href="https://opencollective.com/git-bug#backers" target="_blank"><img src="https://opencollective.com/git-bug/tiers/backer.svg?width=890"></a>
313
314
315## Sponsors
316
317Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/git-bug#sponsor)]
318
319<a href="https://opencollective.com/git-bug/sponsor/0/website" target="_blank"><img src="https://opencollective.com/git-bug/tiers/sponsor/0/avatar.svg"></a>
320<a href="https://opencollective.com/git-bug/sponsor/1/website" target="_blank"><img src="https://opencollective.com/git-bug/tiers/sponsor/1/avatar.svg"></a>
321<a href="https://opencollective.com/git-bug/sponsor/2/website" target="_blank"><img src="https://opencollective.com/git-bug/tiers/sponsor/2/avatar.svg"></a>
322<a href="https://opencollective.com/git-bug/sponsor/3/website" target="_blank"><img src="https://opencollective.com/git-bug/tiers/sponsor/3/avatar.svg"></a>
323<a href="https://opencollective.com/git-bug/sponsor/4/website" target="_blank"><img src="https://opencollective.com/git-bug/tiers/sponsor/4/avatar.svg"></a>
324<a href="https://opencollective.com/git-bug/sponsor/5/website" target="_blank"><img src="https://opencollective.com/git-bug/tiers/sponsor/5/avatar.svg"></a>
325<a href="https://opencollective.com/git-bug/sponsor/6/website" target="_blank"><img src="https://opencollective.com/git-bug/tiers/sponsor/6/avatar.svg"></a>
326<a href="https://opencollective.com/git-bug/sponsor/7/website" target="_blank"><img src="https://opencollective.com/git-bug/tiers/sponsor/7/avatar.svg"></a>
327<a href="https://opencollective.com/git-bug/sponsor/8/website" target="_blank"><img src="https://opencollective.com/git-bug/tiers/sponsor/8/avatar.svg"></a>
328<a href="https://opencollective.com/git-bug/sponsor/9/website" target="_blank"><img src="https://opencollective.com/git-bug/tiers/sponsor/9/avatar.svg"></a>
329
330
331## License
332
333Unless otherwise stated, this project is released under the [GPLv3](LICENSE) or later license © Michael Muré.
334
335The git-bug logo by [Viktor Teplov](https://github.com/vandesign) is released under the [Creative Commons Attribution 4.0 International (CC BY 4.0)](misc/logo/LICENSE) license © Viktor Teplov.