1# How-to: Read/write offline Github issues with git-bug
 2
 3[git-bug](https://github.com/MichaelMure/git-bug) is a standalone distributed bug-tracker that is embedded in git. In short, if you have a git repository you can use it to store bugs alongside your code (without mixing them though!), push and pull them to/from a normal git remote to collaborate.
 4
 5<p align="center">
 6    <img src="../misc/diagrams/native_workflow.png" alt="Native workflow">
 7</p>
 8
 9Bridges with other bug-trackers are first-class citizen in `git-bug`. Notably, they are bidirectional, incremental and relatively fast. This means that a perfectly valid way to use `git-bug` is as a sort of remote for Github where you synchronize all the issues of a repository to later read and edit them and then propagate your changes back to Github.
10
11<p align="center">
12    <img src="../misc/diagrams/bridge_workflow.png" alt="Bridge workflow">
13</p>
14
15This has several upsides:
16- works offline, including edition
17- browsing is pretty much instant
18- you get to choose the UI you prefer between CLI, interactive terminal UI or web UI
19- you get a near complete backup in case Github is down or no longer fit your needs
20
21Note: at the moment, Gitlab and Jira are also fully supported.
22
23## Installation
24
25Follow the [installation instruction](https://github.com/MichaelMure/git-bug#installation). The simplest way is to download a pre-compiled binary from [the latest release](https://github.com/MichaelMure/git-bug/releases/latest) and to put it anywhere in your `$PATH`.
26
27Check that `git-bug` is properly installed by running `git bug version`. If everything is alright, the version of the binary will be displayed.
28
29## Configuration
30
311. From within the git repository you care about, run `git bug bridge configure` and follow the wizard's steps:
32    1. Choose `github`.
33    1. Type a name for the bridge configuration. As you can configure multiple bridges, this name will allow you to choose when there is an ambiguity.
34    1. Setup the remote Github project. The wizard is smart enough to inspect the git remote and detect the potential project. Otherwise, enter the project URL like this: `https://github.com/MichaelMure/git-bug`
35    1. Enter your login on Github
36    1. Setup an authentication token. You can either use the interactive token creation, enter your own token or select an existing token, if any.
371. Run `git bug bridge pull` and let it run to import the issues and identities.
38
39## Basic usage
40
41You can interact with `git-bug` through the command line (see the [Readme](../README.md#cli-usage) for more details):
42```bash
43# Create a new bug
44git bug add
45# List existing bugs
46git bug ls
47# Display a bug's detail
48git bug show <bugId>
49# Add a new comment
50git bug comment <bugId>
51# Push everything to a normal git remote
52git bug push [<remote>]
53# Pull updates from a git remote
54git bug pull [<remote>]
55```
56
57In particular, the key commands to interact with Github are:
58```bash
59# Replicate your changes to the remote bug-tracker
60git bug bridge push [<bridge>]
61# Retrieve updates from the remote bug-tracker
62git bug bridge pull [<bridge>]
63```
64
65The command line tools are really meant for programmatic usage or to integrate `git-bug` into your editor of choice. For day to day usage, the recommended way is the interactive terminal UI. You can start it with `git bug termui`:
66
67![termui recording](../misc/termui_recording.gif)
68
69For a richer and more user friendly UI, `git-bug` proposes a web UI (read-only at the moment). You can start it with `git bug webui`:
70
71![web UI screenshot](../misc/webui2.png)
72
73## Want more?
74
75If you interested to read more about `git-bug`, have a look at the followings:
76- [the project itself, with a more complete readme](https://github.com/MichaelMure/git-bug)
77- [a bird view of the internals](https://github.com/MichaelMure/git-bug/blob/master/doc/architecture.md)
78- [a description of the data model](https://github.com/MichaelMure/git-bug/blob/master/doc/model.md)
79
80Of course, if you want to contribute the door is way open :-)