2018-08-29 19:17:09 +03:00
< p align = "center" >
2018-09-05 01:04:10 +03:00
< img width = "150px" src = "https://cdn.rawgit.com/MichaelMure/git-bug/master/misc/logo/logo-alpha-flat-bg.svg" >
2018-08-29 19:17:09 +03:00
< / p >
2018-08-21 15:39:05 +03:00
< h1 align = "center" > git-bug< / h1 >
< div align = "center" >
2018-07-15 00:16:54 +03:00
2018-08-06 04:22:36 +03:00
[![Build Status ](https://travis-ci.org/MichaelMure/git-bug.svg?branch=master )](https://travis-ci.org/MichaelMure/git-bug)
2020-03-01 01:38:12 +03:00
[![Backers on Open Collective ](https://opencollective.com/git-bug/backers/badge.svg )](#backers)
[![Sponsors on Open Collective ](https://opencollective.com/git-bug/sponsors/badge.svg )](#sponsors)
[![License: GPL v3 ](https://img.shields.io/badge/License-GPLv3+-blue.svg )](http://www.gnu.org/licenses/gpl-3.0)
2018-08-06 04:22:36 +03:00
[![GoDoc ](https://godoc.org/github.com/MichaelMure/git-bug?status.svg )](https://godoc.org/github.com/MichaelMure/git-bug)
2018-08-07 17:01:13 +03:00
[![Go Report Card ](https://goreportcard.com/badge/github.com/MichaelMure/git-bug )](https://goreportcard.com/report/github.com/MichaelMure/git-bug)
2018-08-18 19:31:15 +03:00
[![Gitter chat ](https://badges.gitter.im/gitterHQ/gitter.png )](https://gitter.im/the-git-bug/Lobby)
2018-08-06 04:22:36 +03:00
2018-08-21 15:39:05 +03:00
< / div >
2019-05-07 14:24:30 +03:00
`git-bug` is a bug tracker that:
2019-08-07 22:03:13 +03:00
2019-11-29 17:37:10 +03:00
- **is fully embeded 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!
- **prevents vendor lock-in**: your usual service is down or went bad? You already have a full backup.
2019-05-07 14:24:30 +03:00
- **is fast**: listing bugs or opening them is a matter of milliseconds
- **doesn't pollute your project**: no files are added in your project
2019-11-29 17:37:10 +03:00
- **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
- **bridges to other bug trackers**: use [bridges ](#bridges ) to import and export to other trackers.
2018-07-15 00:16:54 +03:00
2019-05-07 14:24:30 +03:00
:construction: This is now more than a proof of concept, but still not fully stable. Expect dragons and unfinished business. :construction:
2018-07-15 01:16:49 +03:00
2020-03-01 14:50:22 +03:00
## Installation
2018-07-15 00:16:54 +03:00
2019-05-07 14:24:30 +03:00
< details > < summary > Pre-compiled binaries< / summary >
2018-07-15 00:16:54 +03:00
2018-08-12 22:53:36 +03:00
1. Go to the [release page ](https://github.com/MichaelMure/git-bug/releases/latest ) and download the appropriate binary for your system.
2019-11-29 17:37:10 +03:00
2. Copy the binary anywhere in your $PATH
2018-08-12 22:53:36 +03:00
3. Rename the binary to `git-bug` (or `git-bug.exe` on windows)
That's all !
2018-07-15 00:16:54 +03:00
2019-05-07 14:24:30 +03:00
< / details >
< details > < summary > Linux packages< / summary >
2018-08-20 00:12:50 +03:00
* [Archlinux (AUR) ](https://aur.archlinux.org/packages/?K=git-bug )
2020-03-01 01:38:12 +03:00
* [NixOS ](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/version-management/git-and-tools/git-bug/default.nix#L31 )
2018-08-20 00:12:50 +03:00
2019-05-07 14:24:30 +03:00
< / details >
2020-03-01 01:38:12 +03:00
< details > < summary > Compile from git (unstable)< / summary >
2019-05-23 20:06:46 +03:00
```shell
2020-03-01 01:38:12 +03:00
git clone git@github.com:MichaelMure/git-bug.git
make install
2019-05-23 20:06:46 +03:00
```
2020-02-12 23:41:22 +03:00
If it's not done already, add the golang binary directory in your PATH:
2019-05-23 20:06:46 +03:00
```bash
export PATH=$PATH:$(go env GOROOT)/bin:$(go env GOPATH)/bin
```
< / details >
2020-04-04 15:05:53 +03:00
## Workflows
There is multiple ways to use `git-bug` :
< details > < summary > Native workflow< / summary >
< p align = "center" >
2020-04-04 15:09:27 +03:00
< img src = "misc/diagrams/native_workflow.png" alt = "Native workflow" >
2020-04-04 15:05:53 +03:00
< / p >
2020-04-04 19:15:54 +03:00
This 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.
2020-04-04 15:05:53 +03:00
< / details >
< details > < summary > Bridge workflow< / summary >
< p align = "center" >
2020-04-04 15:09:27 +03:00
< img src = "misc/diagrams/bridge_workflow.png" alt = "Bridge workflow" >
2020-04-04 15:05:53 +03:00
< / p >
As `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 !
< / details >
< details > < summary > Web UI workflow (WIP)< / summary >
< p align = "center" >
2020-04-04 15:09:27 +03:00
< img src = "misc/diagrams/webui-workflow.png" alt = "Web UI workflow" >
2020-04-04 15:05:53 +03:00
< / p >
Often, 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!
< / details >
2018-08-13 03:19:34 +03:00
## CLI usage
2018-07-15 00:16:54 +03:00
2019-04-18 03:44:52 +03:00
Create a new identity:
```
git bug user create
```
2018-08-06 04:22:36 +03:00
Create a new bug:
2018-07-15 00:16:54 +03:00
```
2018-10-23 00:34:18 +03:00
git bug add
2018-07-15 00:16:54 +03:00
```
2018-08-06 04:22:36 +03:00
Your favorite editor will open to write a title and a message.
2018-07-15 00:16:54 +03:00
You can push your new entry to a remote:
```
git bug push [< remote > ]
```
And pull for updates:
```
git bug pull [< remote > ]
```
2018-08-06 04:22:36 +03:00
List existing bugs:
```
git bug ls
```
2018-07-16 16:22:09 +03:00
2018-09-09 23:24:43 +03:00
Filter and sort bugs using a [query ](doc/queries.md ):
```
git bug ls "status:open sort:edit"
```
2018-08-06 04:22:36 +03:00
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 ](doc/md/git-bug.md ).
2018-07-17 20:31:18 +03:00
2018-08-13 03:19:34 +03:00
## Interactive terminal UI
2018-07-16 16:22:09 +03:00
2018-08-08 19:51:11 +03:00
An interactive terminal UI is available using the command `git bug termui` to browse and edit bugs.
2018-07-16 16:22:09 +03:00
2019-04-17 21:27:33 +03:00
![Termui recording ](misc/termui_recording.gif )
2018-08-17 14:31:39 +03:00
2018-08-17 14:19:35 +03:00
## Web UI (status: WIP)
2018-07-16 16:22:09 +03:00
2018-08-08 19:51:11 +03:00
You can launch a rich Web UI with `git bug webui` .
2018-07-17 20:31:18 +03:00
2019-08-27 13:53:19 +03:00
< p align = "center" >
2020-02-23 18:32:08 +03:00
< img src = "misc/webui1.png" alt = "Web UI screenshot 1" width = "880" >
2019-08-27 13:53:19 +03:00
< / p >
< p align = "center" >
2020-02-23 18:32:08 +03:00
< img src = "misc/webui2.png" alt = "Web UI screenshot 2" width = "880" >
2019-08-27 13:53:19 +03:00
< / p >
2018-07-16 16:22:09 +03:00
2018-08-06 04:22:36 +03:00
This web UI is entirely packed inside the same go binary and serve static content through a localhost http server.
2018-07-16 23:38:52 +03:00
2018-12-23 19:55:41 +03:00
The web UI interact with the backend through a GraphQL API. The schema is available [here ](graphql/ ).
2018-07-17 21:51:09 +03:00
2019-04-21 16:31:54 +03:00
## Bridges
### Importer implementations
2020-03-01 01:38:12 +03:00
| | Github | Gitlab | Jira | Launchpad |
|-------------------------------------------------|--------------------|--------------------|--------------------|--------------------|
| **incremental** < br /> (can import more than once) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| **with resume** < br /> (download only new data) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| **identities** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| identities update | :x: | :x: | :x: | :x: |
| **bug** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| comments | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| comment editions | :heavy_check_mark: | :x: | :heavy_check_mark: | :x: |
| labels | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| status | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| title edition | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| **media/files** | :x: | :x: | :x: | :x: |
| **automated test suite** | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |
2019-04-21 16:31:54 +03:00
### Exporter implementations
2020-03-01 01:38:12 +03:00
| | Github | Gitlab | Jira | Launchpad |
|--------------------------|--------------------|--------------------|--------------------|-----------|
| **bug** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| comments | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| comment editions | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| labels | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| status | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| title edition | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| **automated test suite** | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |
2019-08-24 14:55:49 +03:00
#### Bridge usage
2019-08-24 15:18:22 +03:00
Interactively configure a new github bridge:
```bash
git bug bridge configure
```
Or manually:
2019-08-24 14:55:49 +03:00
```bash
git bug bridge configure \
2020-03-01 01:38:12 +03:00
--name=< bridge > \
2019-08-24 14:55:49 +03:00
--target=github \
2020-03-01 01:38:12 +03:00
--url=https://github.com/MichaelMure/git-bug \
--login=< login >
--token=< token >
2019-08-24 14:55:49 +03:00
```
2019-08-24 15:18:22 +03:00
Import bugs:
2019-08-24 14:55:49 +03:00
```bash
2019-08-24 15:18:22 +03:00
git bug bridge pull [< name > ]
2019-08-24 14:55:49 +03:00
```
2019-08-24 15:18:22 +03:00
Export modifications:
2019-08-24 14:55:49 +03:00
```bash
2019-08-24 15:18:22 +03:00
git bug bridge push [< name > ]
2019-08-24 14:55:49 +03:00
```
2019-08-24 15:18:22 +03:00
Deleting a bridge:
2019-08-24 14:55:49 +03:00
```bash
2019-08-24 15:18:22 +03:00
git bug bridge rm [< name > ]
2019-08-24 14:55:49 +03:00
```
2019-04-21 16:31:54 +03:00
2018-07-16 15:53:32 +03:00
## Internals
2019-04-18 03:48:27 +03:00
Interested by how it works ? Have a look at the [data model ](doc/model.md ) and the [internal bird-view ](doc/architecture.md ).
2018-07-16 15:53:32 +03:00
2018-08-06 04:22:36 +03:00
## Misc
- [Bash completion ](misc/bash_completion )
- [Zsh completion ](misc/zsh_completion )
2019-06-24 14:58:31 +03:00
- [PowerShell completion ](misc/powershell_completion )
2018-08-06 04:22:36 +03:00
- [ManPages ](doc/man )
2018-07-15 02:49:46 +03:00
## Planned features
2018-08-08 19:51:11 +03:00
- media embedding
2019-07-06 21:36:29 +03:00
- more bridges
2018-08-08 19:51:11 +03:00
- extendable data model to support arbitrary bug tracker
- inflatable raptor
2018-07-15 02:49:46 +03:00
2018-07-15 00:16:54 +03:00
## Contribute
2018-12-10 02:25:46 +03:00
PRs 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.
2018-12-09 00:42:16 +03:00
```shell
2020-03-01 01:38:12 +03:00
git clone git@github.com:MichaelMure/git-bug.git
2018-12-09 00:42:16 +03:00
```
2018-12-10 02:25:46 +03:00
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. ](webui/Readme.md )
2018-07-15 00:16:54 +03:00
2019-05-07 14:24:30 +03:00
## Contributors :heart:
2018-09-13 19:15:32 +03:00
2019-01-17 15:52:40 +03:00
This project exists thanks to all the people who contribute.
2018-09-29 12:45:55 +03:00
< a href = "https://github.com/MichaelMure/git-bug/graphs/contributors" > < img src = "https://opencollective.com/git-bug/contributors.svg?width=890&button=false" / > < / a >
2018-09-13 19:15:32 +03:00
## Backers
Thank you to all our backers! 🙏 [[Become a backer ](https://opencollective.com/git-bug#backer )]
2019-01-17 15:52:40 +03:00
< a href = "https://opencollective.com/git-bug#backers" target = "_blank" > < img src = "https://opencollective.com/git-bug/tiers/backer.svg?width=890" > < / a >
2018-09-13 19:15:32 +03:00
## Sponsors
Support 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 )]
2019-01-17 15:52:40 +03:00
< 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 >
< 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 >
< 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 >
< 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 >
< 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 >
< 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 >
< 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 >
< 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 >
< 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 >
< 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 >
2018-09-13 19:15:32 +03:00
2018-07-15 00:16:54 +03:00
## License
2018-09-03 22:28:39 +03:00
Unless otherwise stated, this project is released under the [GPLv3 ](LICENSE ) or later license © Michael Muré.
2018-09-02 23:00:51 +03:00
2018-09-05 02:04:56 +03:00
The 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.