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 https://github.com/MichaelMure/git-bug.git
 92cd git-bug
 93make install
 94```
 95
 96If it's not done already, add the golang binary directory in your PATH:
 97
 98```bash
 99export PATH=$PATH:$(go env GOROOT)/bin:$(go env GOPATH)/bin
100```
101
102</details>
103
104## Workflows
105
106There are multiple ways to use `git-bug`:
107
108<details><summary>Native workflow</summary>
109<p align="center">
110    <img src="misc/diagrams/native_workflow.png" alt="Native workflow">
111</p>
112
113This 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. 
114
115</details>
116
117<details><summary>Bridge workflow</summary>
118<p align="center">
119    <img src="misc/diagrams/bridge_workflow.png" alt="Bridge workflow">
120</p>
121
122As `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 !
123
124</details>
125
126<details><summary>Web UI workflow (WIP)</summary>
127<p align="center">
128    <img src="misc/diagrams/webui-workflow.png" alt="Web UI workflow">
129</p>
130
131Often, 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!
132
133</details>
134
135## CLI usage
136
137Create a new identity:
138
139```
140git bug user create
141```
142
143Create a new bug:
144
145```
146git bug add
147```
148
149Your favorite editor will open to write a title and a message.
150
151You can push your new entry to a remote:
152```
153git bug push [<remote>]
154```
155
156And pull for updates:
157```
158git bug pull [<remote>]
159```
160
161List existing bugs:
162```
163git bug ls
164```
165
166Filter and sort bugs using a [query](doc/queries.md):
167```
168git bug ls "status:open sort:edit"
169```
170
171Search for bugs by text content:
172```
173git bug ls "foo bar" baz
174```
175
176You 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).
177
178## Interactive terminal UI
179
180An interactive terminal UI is available using the command `git bug termui` to browse and edit bugs.
181
182![Termui recording](misc/termui_recording.gif)
183
184## Web UI
185
186You can launch a rich Web UI with `git bug webui`.
187
188<p align="center">
189  <img src="misc/webui1.png" alt="Web UI screenshot 1" width="880">
190</p>
191
192<p align="center">
193  <img src="misc/webui2.png" alt="Web UI screenshot 2" width="880">
194</p>
195
196This web UI is entirely packed inside the same go binary and serve static content through a localhost http server.
197
198The web UI interact with the backend through a GraphQL API. The schema is available [here](api/graphql/schema).
199
200## Bridges
201
202✅: working  🟠: partial implementation  ❌: not working
203
204### Importer implementations
205
206|                                                 | Github | Gitlab | Jira | Launchpad |
207|-------------------------------------------------|:------:|:------:|:----:|:---------:|
208| **incremental**<br/>(can import more than once) |   ✅    |   ✅    |  ✅   |     ❌     |
209| **with resume**<br/>(download only new data)    |   ✅    |   ✅    |  ✅   |     ❌     |
210| **identities**                                  |   🟠   |   🟠   |  🟠  |    🟠     |
211| **bugs**                                        |   ✅    |   ✅    |  ✅   |    🟠     |
212| **board**                                       |   ❌    |   ❌    |  ❌   |     ❌     |
213| **media/files**                                 |   ❌    |   ❌    |  ❌   |     ❌     |
214| **automated test suite**                        |   ✅    |   ✅    |  ❌   |     ❌     |
215
216### Exporter implementations
217
218|                          | Github | Gitlab | Jira | Launchpad |
219|--------------------------|:------:|:------:|:----:|:---------:|
220| **identities**           |   🟠   |   🟠   |  🟠  |    🟠     |
221| **bug**                  |   ✅    |   ✅    |  ✅   |     ❌     |
222| **board**                |   ❌    |   ❌    |  ❌   |     ❌     |
223| **automated test suite** |   ✅    |   ✅    |  ❌   |     ❌     |
224
225#### Bridge usage
226
227Interactively configure a new github bridge:
228
229```bash
230git bug bridge new
231```
232
233Or manually:
234
235```bash
236git bug bridge new \
237    --name=<bridge> \
238    --target=github \
239    --url=https://github.com/MichaelMure/git-bug \
240    --login=<login> \
241    --token=<token>
242```
243
244Import bugs:
245
246```bash
247git bug bridge pull [<name>]
248```
249
250Export modifications:
251
252```bash
253git bug bridge push [<name>]
254```
255
256Deleting a bridge:
257
258```bash
259git bug bridge rm [<name>]
260```
261
262## Internals
263
264Interested in how it works ? Have a look at the [data model](doc/model.md) and the [internal bird-view](doc/architecture.md).
265
266Or maybe you want to [make your own distributed data-structure in git](entity/dag/example_test.go) ?
267
268See also all the [docs](doc).
269
270## Misc
271
272- [Bash, Zsh, fish, powershell completion](misc/completion)
273- [ManPages](doc/man)
274
275## Planned features
276
277The [feature matrix](doc/feature_matrix.md) gives a good overview of what is planned, without being exhaustive.
278
279Additional planned feature:
280- webUI that can be used as a public portal to accept user's input
281- inflatable raptor
282
283## Contribute
284
285PRs 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.
286
287```shell
288git clone git@github.com:MichaelMure/git-bug.git
289```
290
291You can now run `make` to build the project, or `make install` to install the binary in `$GOPATH/bin/`.
292
293To work on the web UI, have a look at [the dedicated Readme.](webui/Readme.md)
294
295Some tests for the CLI use golden files, if the output of CLI commands is
296changed, run the following command, then inspect the changed files in
297`commands/testdata/...` to make sure the output text is as expected:
298
299```shell
300go test ./commands -update
301```
302
303## Contributors :heart:
304
305This project exists thanks to all the people who contribute.
306<a href="https://github.com/MichaelMure/git-bug/graphs/contributors"><img src="https://opencollective.com/git-bug/contributors.svg?width=890&button=false" /></a>
307
308
309## Backers
310
311Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/git-bug#backer)]
312
313<a href="https://opencollective.com/git-bug#backers" target="_blank"><img src="https://opencollective.com/git-bug/tiers/backer.svg?width=890"></a>
314
315
316## Sponsors
317
318Support 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)]
319
320<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>
321<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>
322<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>
323<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>
324<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>
325<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>
326<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>
327<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>
328<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>
329<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>
330
331
332## License
333
334Unless otherwise stated, this project is released under the [GPLv3](LICENSE) or later license © Michael Muré.
335
336The 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.