1<!--
  2    NOTE TO CONTRIBUTORS:
  3
  4    We use HTML elements within <details> in order to avoid parsing errors with
  5    GFM caused by triple-backtick blocks or alert elements being nested next to
  6    the summary or beginning of the <details> block.
  7
  8    Please keep this in mind as you make changes.
  9-->
 10
 11# Installation Guide<a name="installation-guide"></a>
 12
 13`git-bug` is distributed as a single binary, and is available for multiple
 14platforms. Follow this document for instructions on how to install `git-bug`,
 15and verify your installation.
 16
 17<!-- mdformat-toc start --slug=github --maxlevel=4 --minlevel=2 -->
 18
 19- [Download a pre-compiled release binary](#download-a-pre-compiled-release-binary)
 20- [Linux](#linux)
 21  - [Arch Linux](#arch-linux)
 22  - [Nixpkgs](#nixpkgs)
 23- [FreeBSD](#freebsd)
 24- [MacOS](#macos)
 25- [Windows](#windows)
 26- [Build from source](#build-from-source)
 27- [Verify your installation](#verify-your-installation)
 28
 29<!-- mdformat-toc end -->
 30
 31## Download a pre-compiled release binary<a name="download-a-pre-compiled-release-binary"></a>
 32
 33You can download the latest release binary from [the release page][rel/latest],
 34making sure to grab the appropriate binary for your system.
 35
 36Next, rename the binary to `git-bug`, or `git-bug.exe` if you're using Windows.
 37
 38Finally, place the binary in a directory that's in your `PATH`. That's it! You
 39should now have `git-bug` available as a command line tool.
 40
 41## Linux<a name="linux"></a>
 42
 43`git-bug` is available on a variety of Linux distributions, but how you install
 44it depends on your distribution and package manager(s), as there is no standard
 45package manager common to all distributions.
 46
 47### Arch Linux<a name="arch-linux"></a>
 48
 49`git-bug` is available in the [Arch Linux User Repository (AUR)][p/aur].
 50
 51Below, you'll find a **non-exhaustive** list of commands that use common third
 52party tools for installing packages from the AUR.
 53
 54<details><summary>Using <strong>aurutils</strong></summary>
 55<pre>aur sync git-bug-bin && pacman -Syu git-bug-bin</pre>
 56</details>
 57
 58<details><summary>Using <strong>yay</strong></summary>
 59<pre>yay -S git-bug-bin</pre>
 60</details>
 61
 62### Nixpkgs<a name="nixpkgs"></a>
 63
 64`git-bug` is available via [nixpkgs][p/nix].
 65
 66<details><summary>Using <strong>home-manager</strong></summary>
 67<pre>
 68home.package = with pkgs; [
 69  git-bug
 70];
 71</pre>
 72</details>
 73
 74<details><summary>Using <strong>system configuration</strong></summary>
 75<pre>
 76environment.systemPackages = with pkgs; [
 77  git-bug
 78];
 79</pre>
 80</details>
 81
 82<details><summary>Using <strong>nix profile</strong></summary>
 83<pre>nix profile install nixpkgs\#git-bug</pre>
 84</details>
 85
 86<details><summary>Temporary installation with <strong>nix shell</strong></summary>
 87<pre>
 88nix shell nixpkgs\#git-bug
 89</pre>
 90</details>
 91
 92## FreeBSD<a name="freebsd"></a>
 93
 94`git-bug` is available on FreeBSD through a few different methods.
 95
 96<details><summary>Using <strong>pkg</strong></summary>
 97<pre>pkg install git-bug</pre>
 98</details>
 99
100<details><summary>Using the <strong>ports</strong> collection</summary>
101<pre>make -C /usr/ports/devel/git-bug install clean</pre>
102</details>
103
104## MacOS<a name="macos"></a>
105
106`git-bug` is shipped via [**Homebrew**][brew.sh]:
107
108```
109brew install git-bug
110```
111
112## Windows<a name="windows"></a>
113
114`git-bug` is shipped via `scoop`:
115
116```
117scoop install git-bug
118```
119
120## Build from source<a name="build-from-source"></a>
121
122You can also build `git-bug` from source, if you wish. You'll need the following
123dependencies:
124
125- `git`
126- `go`
127- `make`
128
129Ensure that the `go` binary directory (`$GOPATH/bin`) is in your `PATH`. It is
130recommended to set this within your shell configuration file(s), such as
131`~/.zprofile` or `~/.bashrc`.
132
133```
134export PATH=$PATH:$(go env GOROOT)/bin:$(go env GOPATH)/bin
135```
136
137> [!NOTE]
138> The commands below assume you do not want to keep the repository on disk, and
139> thus clones the repository to a new temporary directory and performs a
140> lightweight clone in order to reduce network latency and data transfer.
141>
142> As a result, the repository cloned during these steps will not contain the
143> full history. If that is important to you, clone the repository using the
144> method you prefer, check out your preferred revision, and run `make install`.
145
146**First, create a new repository on disk:**
147
148```
149cd $(mktemp -d) && git init .
150```
151
152**Next, set the remote to the upstream source:**
153
154```
155git remote add origin git@github.com:git-bug/git-bug.git
156```
157
158Next, choose whether you want to build from a release tag, branch, or
159development head and expand the instructions below.
160
161<details><summary>Build from <strong>a release tag</strong></summary>
162
163First, list all of the tags from the repository (we use `sed` in the command
164below to filter out some unnecessary visual noise):
165
166<pre>
167git ls-remote origin refs/tags/\* | sed -e 's/refs\/tags\///'
168</pre>
169
170You'll see output similar to:
171
172<pre>
173c1a08111b603403d4ee0a78c1214f322fecaa3ca        0.1.0
174d959acc29dcbc467790ae87389f9569bb830c8c6        0.2.0
175ad59f77fd425b00ae4b8d7360a64dc3dc1c73bd0        0.3.0
176...
177</pre>
178
179<blockquote><strong>Tip</strong><p>
180The <em>tags</em> are in the right-most column. Old revisions up to and
181including <code>0.7.1</code> do not contain a <em>v</em> prefix, however, all
182revisions after, do.
183</p></blockquote>
184
185Select the tag you wish to build, and fetch it using the command below. Be sure
186to replace <code>REPLACE-ME</code> with the tag you selected:
187
188<pre>
189git fetch --no-tags --depth 1 origin +refs/tags/REPLACE-ME:refs/tags/REPLACE-ME
190</pre>
191
192<blockquote><strong>NOTE</strong><p>
193The <code>--no-tags</code> flag might seem out of place, since we <em>are</em>
194fetching a tag, but it isn't -- the reason we use this is avoid fetching other
195tags, in case you have <code>fetch.pruneTags</code> enabled in your global
196configuration, which causes <code>git</code> to fetch <em>all</em> tags.
197</p></blockquote>
198
199Next, check out the tag, replacing <code>REPLACE-ME</code> with the tag you
200selected:
201
202<pre>
203git checkout REPLACE-ME
204</pre>
205
206Finally, run the <code>install</code> target from <code>//:Makefile</code>:
207
208<pre>
209make install
210</pre>
211
212This will build <code>git-bug</code> and place it in your Go binary directory.
213
214</details>
215
216<details>
217<summary>
218Build the <strong>unstable development <code>HEAD</code></strong>
219</summary>
220
221First, fetch the most recent commit for the default branch:
222
223<pre>
224git fetch --no-tags --depth 1 origin HEAD:refs/remotes/origin/HEAD
225</pre>
226
227Next, check out the tree you pulled:
228
229<pre>
230git checkout origin/HEAD
231</pre>
232
233Finally, run the <code>install</code> target from <code>//:Makefile</code>:
234
235<pre>
236make install
237</pre>
238
239This will build <code>git-bug</code> and place it in your Go binary directory.
240
241</details>
242
243## Verify your installation<a name="verify-your-installation"></a>
244
245To verify that `git-bug` was installed correctly, you can run the following
246command. If you see output similar to what's shown below (and without any
247errors), you're all set!
248
249```
250git bug version
251```
252
253______________________________________________________________________
254
255##### See more
256
257- [Documentation home][docs/home]
258
259[brew.sh]: https://brew.sh
260[docs/home]: ./doc
261[p/aur]: https://aur.archlinux.org/packages/git-bug-bin
262[p/nix]: https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/applications/version-management/git-bug/default.nix
263[rel/latest]: https://github.com/git-bug/git-bug/releases/latest