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[](https://travis-ci.com/MichaelMure/git-bug)
9[](#backers)
10[](#sponsors)
11[](http://www.gnu.org/licenses/gpl-3.0)
12[](https://godoc.org/github.com/MichaelMure/git-bug)
13[](https://goreportcard.com/report/github.com/MichaelMure/git-bug)
14[](https://gitter.im/the-git-bug/Lobby)
15
16</div>
17
18`git-bug` is a bug tracker that:
19
20- **is fully embedded in git**: you only need your git repository to have a bug tracker
21- **is distributed**: use your normal git remote to collaborate, push and pull your bugs!
22- **works offline**: in a plane or under the sea? Keep reading and writing bugs!
23- **prevents vendor lock-in**: your usual service is down or went bad? You already have a full backup.
24- **is fast**: listing bugs or opening them is a matter of milliseconds
25- **doesn't pollute your project**: no files are added in your project
26- **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
27- **bridges to other bug trackers**: use [bridges](#bridges) to import and export to other trackers.
28
29:construction: This is now more than a proof of concept, but still not fully stable. Expect dragons and unfinished business. :construction:
30
31## Installation
32
33<details><summary>Pre-compiled binaries</summary>
34
351. Go to the [release page](https://github.com/MichaelMure/git-bug/releases/latest) and download the appropriate binary for your system.
362. Copy the binary anywhere in your $PATH
373. Rename the binary to `git-bug` (or `git-bug.exe` on windows)
38
39That's all !
40
41</details>
42
43<details><summary>Linux packages</summary>
44
45* [Archlinux (AUR)](https://aur.archlinux.org/packages/?K=git-bug)
46* [NixOS](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/version-management/git-and-tools/git-bug/default.nix#L31)
47
48</details>
49
50<details><summary>macOS packages</summary>
51
52* [Homebrew](https://formulae.brew.sh/formula/git-bug)
53 ```
54 brew install git-bug
55 ```
56
57</details>
58
59<details><summary>FreeBSD package/port</summary>
60
61Install via the package manager
62 ```
63 pkg install git-bugs
64 ```
65
66Or from the ports collection
67 ```
68 cd /usr/ports/devel/git-bug && make install clean
69 ```
70
71</details>
72
73<details><summary>Compile from git (unstable)</summary>
74
75```shell
76git clone git@github.com:MichaelMure/git-bug.git
77make install
78```
79
80If it's not done already, add the golang binary directory in your PATH:
81
82```bash
83export PATH=$PATH:$(go env GOROOT)/bin:$(go env GOPATH)/bin
84```
85
86</details>
87
88## Workflows
89
90There are multiple ways to use `git-bug`:
91
92<details><summary>Native workflow</summary>
93<p align="center">
94 <img src="misc/diagrams/native_workflow.png" alt="Native workflow">
95</p>
96
97This 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.
98
99</details>
100
101<details><summary>Bridge workflow</summary>
102<p align="center">
103 <img src="misc/diagrams/bridge_workflow.png" alt="Bridge workflow">
104</p>
105
106As `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 !
107
108</details>
109
110<details><summary>Web UI workflow (WIP)</summary>
111<p align="center">
112 <img src="misc/diagrams/webui-workflow.png" alt="Web UI workflow">
113</p>
114
115Often, 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!
116
117</details>
118
119## CLI usage
120
121Create a new identity:
122
123```
124git bug user create
125```
126
127Create a new bug:
128
129```
130git bug add
131```
132
133Your favorite editor will open to write a title and a message.
134
135You can push your new entry to a remote:
136```
137git bug push [<remote>]
138```
139
140And pull for updates:
141```
142git bug pull [<remote>]
143```
144
145List existing bugs:
146```
147git bug ls
148```
149
150Filter and sort bugs using a [query](doc/queries.md):
151```
152git bug ls "status:open sort:edit"
153```
154
155You 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).
156
157## Interactive terminal UI
158
159An interactive terminal UI is available using the command `git bug termui` to browse and edit bugs.
160
161
162
163## Web UI (status: WIP)
164
165You can launch a rich Web UI with `git bug webui`.
166
167<p align="center">
168 <img src="misc/webui1.png" alt="Web UI screenshot 1" width="880">
169</p>
170
171<p align="center">
172 <img src="misc/webui2.png" alt="Web UI screenshot 2" width="880">
173</p>
174
175This web UI is entirely packed inside the same go binary and serve static content through a localhost http server.
176
177The web UI interact with the backend through a GraphQL API. The schema is available [here](api/graphql/schema).
178
179## Bridges
180
181### Importer implementations
182
183| | Github | Gitlab | Jira | Launchpad |
184|-------------------------------------------------|--------------------|--------------------|--------------------|--------------------|
185| **incremental**<br/>(can import more than once) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
186| **with resume**<br/>(download only new data) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
187| **identities** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
188| identities update | :x: | :x: | :x: | :x: |
189| **bug** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
190| comments | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
191| comment editions | :heavy_check_mark: | :x: | :heavy_check_mark: | :x: |
192| labels | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
193| status | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
194| title edition | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
195| **media/files** | :x: | :x: | :x: | :x: |
196| **automated test suite** | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |
197
198### Exporter implementations
199
200| | Github | Gitlab | Jira | Launchpad |
201|--------------------------|--------------------|--------------------|--------------------|-----------|
202| **bug** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
203| comments | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
204| comment editions | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
205| labels | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
206| status | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
207| title edition | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
208| **automated test suite** | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |
209
210#### Bridge usage
211
212Interactively configure a new github bridge:
213
214```bash
215git bug bridge configure
216```
217
218Or manually:
219
220```bash
221git bug bridge configure \
222 --name=<bridge> \
223 --target=github \
224 --url=https://github.com/MichaelMure/git-bug \
225 --login=<login>
226 --token=<token>
227```
228
229Import bugs:
230
231```bash
232git bug bridge pull [<name>]
233```
234
235Export modifications:
236
237```bash
238git bug bridge push [<name>]
239```
240
241Deleting a bridge:
242
243```bash
244git bug bridge rm [<name>]
245```
246
247## Internals
248
249Interested by how it works ? Have a look at the [data model](doc/model.md) and the [internal bird-view](doc/architecture.md).
250
251## Misc
252
253- [Bash completion](misc/bash_completion)
254- [Zsh completion](misc/zsh_completion)
255- [PowerShell completion](misc/powershell_completion)
256- [ManPages](doc/man)
257
258## Planned features
259
260- media embedding
261- more bridges
262- extendable data model to support arbitrary bug tracker
263- inflatable raptor
264
265## Contribute
266
267PRs accepted. Drop by the [Gitter lobby](https://gitter.im/the-git-bug/Lobby) for a chat or browse the issues to see what is worked on or discussed.
268
269```shell
270git clone git@github.com:MichaelMure/git-bug.git
271```
272
273You can now run `make` to build the project, or `make install` to install the binary in `$GOPATH/bin/`.
274
275To work on the web UI, have a look at [the dedicated Readme.](webui/Readme.md)
276
277
278## Contributors :heart:
279
280This project exists thanks to all the people who contribute.
281<a href="https://github.com/MichaelMure/git-bug/graphs/contributors"><img src="https://opencollective.com/git-bug/contributors.svg?width=890&button=false" /></a>
282
283
284## Backers
285
286Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/git-bug#backer)]
287
288<a href="https://opencollective.com/git-bug#backers" target="_blank"><img src="https://opencollective.com/git-bug/tiers/backer.svg?width=890"></a>
289
290
291## Sponsors
292
293Support 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)]
294
295<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>
296<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>
297<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>
298<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>
299<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>
300<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>
301<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>
302<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>
303<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>
304<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>
305
306
307## License
308
309Unless otherwise stated, this project is released under the [GPLv3](LICENSE) or later license © Michael Muré.
310
311The 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.