From 19f3c214288647b61bc730bb0b1d400fc59c74b0 Mon Sep 17 00:00:00 2001 From: Michael Muré Date: Fri, 27 Dec 2019 14:47:07 +0100 Subject: add a how-to to explain usage with Github --- doc/howto-github.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 doc/howto-github.md (limited to 'doc/howto-github.md') diff --git a/doc/howto-github.md b/doc/howto-github.md new file mode 100644 index 000000000..cd1855b01 --- /dev/null +++ b/doc/howto-github.md @@ -0,0 +1,61 @@ +# How-to: Read/write offline Github issues with git-bug + +[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. + +Bridges 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. + +This has several upsides: +- works offline, including edition +- browsing is pretty much instant +- you get to choose the UI you prefer between CLI, interactive terminal UI or web UI +- you get a near complete backup in case Github is down or no longer fit your needs + +## Installation + +Follow the [installation instruction](https://github.com/MichaelMure/git-bug#install). 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`. + +Check that `git-bug` is properly installed by running `git bug version`. If everything is alright, the version of the binary will be displayed. + +## Configuration + +1. From within the git repository you care about, run `git bug bridge configure` and follow the wizard's steps: + 1. Choose `github`. + 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. + 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` + 1. Setup an authentication token. You can either use the interactive token creation, enter your own token or select an existing token, if any. +1. Run `git bug bridge pull` and let it run to import the issues and identities. +1. Find your imported identity by running `git bug user ls` and select it as your own with `git bug user adopt ` + +## Basic usage + +You can interact with `git-bug` through the command line (see the [Readme](../README.md#cli-usage) for more details): +```bash +# Create a new bug +git bug add +# List existing bugs +git bug ls +# Display a bug's detail +git bug show +# Add a new comment +git bug comment +# Push everything to a normal git remote +git bug push [] +# Pull updates from a git remote +git bug pull [] +``` + +In particular, the key commands to interact with Github are: +```bash +# Replicate your changes to the remote bug-tracker +git bug bridge push [] +# Retrieve updates from the remote bug-tracker +git bug bridge pull [] +``` + +The 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`: + +![termui recording](../misc/termui_recording.gif) + +For a richer UI more user friendly UI, `git-bug` propose a web UI (read-only at the moment). You can start it with `git bug webui`: + +![web UI screenshot](../misc/webui2.png) -- cgit v1.2.3 From 710d85664e6cf933d2b1691871a4246b8e7eceb3 Mon Sep 17 00:00:00 2001 From: Michael Muré Date: Fri, 27 Dec 2019 20:12:11 +0100 Subject: doc: fix typos --- doc/howto-github.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/howto-github.md') diff --git a/doc/howto-github.md b/doc/howto-github.md index cd1855b01..44f24927f 100644 --- a/doc/howto-github.md +++ b/doc/howto-github.md @@ -18,7 +18,7 @@ Check that `git-bug` is properly installed by running `git bug version`. If ever ## Configuration -1. From within the git repository you care about, run `git bug bridge configure` and follow the wizard's steps: +1. From within the git repository you care about, run `git bug bridge configure` and follow the wizard's steps: 1. Choose `github`. 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. 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` @@ -56,6 +56,6 @@ The command line tools are really meant for programmatic usage or to integrate ` ![termui recording](../misc/termui_recording.gif) -For a richer UI more user friendly UI, `git-bug` propose a web UI (read-only at the moment). You can start it with `git bug webui`: +For 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`: ![web UI screenshot](../misc/webui2.png) -- cgit v1.2.3 From 8365c6334edea95a38b9b7d0184be7c537c2bee9 Mon Sep 17 00:00:00 2001 From: Michael Muré Date: Sun, 1 Mar 2020 12:50:22 +0100 Subject: doc: refresh the github howto --- README.md | 2 +- doc/howto-github.md | 12 ++++++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) (limited to 'doc/howto-github.md') diff --git a/README.md b/README.md index 873c62e17..be65b99e8 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ :construction: This is now more than a proof of concept, but still not fully stable. Expect dragons and unfinished business. :construction: -## Install +## Installation
Pre-compiled binaries diff --git a/doc/howto-github.md b/doc/howto-github.md index 44f24927f..672aa8b28 100644 --- a/doc/howto-github.md +++ b/doc/howto-github.md @@ -2,8 +2,16 @@ [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. +

+ Native workflow +

+ Bridges 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. +

+ Bridge workflow +

+ This has several upsides: - works offline, including edition - browsing is pretty much instant @@ -12,7 +20,7 @@ This has several upsides: ## Installation -Follow the [installation instruction](https://github.com/MichaelMure/git-bug#install). 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`. +Follow 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`. Check that `git-bug` is properly installed by running `git bug version`. If everything is alright, the version of the binary will be displayed. @@ -22,9 +30,9 @@ Check that `git-bug` is properly installed by running `git bug version`. If ever 1. Choose `github`. 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. 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` + 1. Enter your login on Github 1. Setup an authentication token. You can either use the interactive token creation, enter your own token or select an existing token, if any. 1. Run `git bug bridge pull` and let it run to import the issues and identities. -1. Find your imported identity by running `git bug user ls` and select it as your own with `git bug user adopt ` ## Basic usage -- cgit v1.2.3 From f82ad38671ab42690d83675166e5eefa03d74d85 Mon Sep 17 00:00:00 2001 From: Michael Muré Date: Sun, 1 Mar 2020 14:36:59 +0100 Subject: howto: link to other ressources --- doc/howto-github.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'doc/howto-github.md') diff --git a/doc/howto-github.md b/doc/howto-github.md index 672aa8b28..a441d15d6 100644 --- a/doc/howto-github.md +++ b/doc/howto-github.md @@ -18,6 +18,8 @@ This has several upsides: - you get to choose the UI you prefer between CLI, interactive terminal UI or web UI - you get a near complete backup in case Github is down or no longer fit your needs +Note: at the moment, Gitlab and Jira are also fully supported. + ## Installation Follow 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`. @@ -67,3 +69,12 @@ The command line tools are really meant for programmatic usage or to integrate ` For 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`: ![web UI screenshot](../misc/webui2.png) + +## Want more? + +If you interested to read more about `git-bug`, have a look at the followings: +- [the project itself, with a more complete readme](https://github.com/MichaelMure/git-bug) +- [a bird view of the internals](https://github.com/MichaelMure/git-bug/blob/master/doc/architecture.md) +- [a description of the data model](https://github.com/MichaelMure/git-bug/blob/master/doc/model.md) + +Of course, if you want to contribute the door is way open :-) \ No newline at end of file -- cgit v1.2.3