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>pacman</strong></summary>
 55<pre>pacman -S git-bug</pre>
 56</details>
 57
 58### Nixpkgs<a name="nixpkgs"></a>
 59
 60`git-bug` is available via [nixpkgs][p/nix].
 61
 62<details><summary>Using <strong>home-manager</strong></summary>
 63<pre>
 64home.package = with pkgs; [
 65  git-bug
 66];
 67</pre>
 68</details>
 69
 70<details><summary>Using <strong>system configuration</strong></summary>
 71<pre>
 72environment.systemPackages = with pkgs; [
 73  git-bug
 74];
 75</pre>
 76</details>
 77
 78<details><summary>Temporary installation with <strong>nix shell</strong> (flake)</summary>
 79<pre>
 80nix shell nixpkgs#git-bug
 81</pre>
 82</details>
 83
 84<details><summary>Temporary installation with <strong>nix-shell</strong> (stable)</summary>
 85<pre>
 86nix-shell -p git-bug
 87</pre>
 88</details>
 89
 90## FreeBSD<a name="freebsd"></a>
 91
 92`git-bug` is available on FreeBSD through a few different methods.
 93
 94<details><summary>Using <strong>pkg</strong></summary>
 95<pre>pkg install git-bug</pre>
 96</details>
 97
 98<details><summary>Using the <strong>ports</strong> collection</summary>
 99<pre>make -C /usr/ports/devel/git-bug install clean</pre>
100</details>
101
102## MacOS<a name="macos"></a>
103
104`git-bug` is shipped via [**Homebrew**][brew.sh]:
105
106```
107brew install git-bug
108```
109
110## Windows<a name="windows"></a>
111
112`git-bug` is shipped via `scoop`:
113
114```
115scoop install git-bug
116```
117
118## Build from source<a name="build-from-source"></a>
119
120You can also build `git-bug` from source, if you wish. You'll need the following
121dependencies:
122
123- `git`
124- `nix`
125
126> [!NOTE]
127> The commands below assume you do not want to keep the repository on disk, and
128> thus clones the repository to a new temporary directory and performs a
129> lightweight clone in order to reduce network latency and data transfer.
130>
131> As a result, the repository cloned during these steps will not contain the
132> full history. If that is important to you, clone the repository using the
133> method you prefer.
134
135**First, create a new repository on disk:**
136
137```
138cd $(mktemp -d) && git init .
139```
140
141**Next, set the remote to the upstream source:**
142
143```
144git remote add origin git@github.com:git-bug/git-bug.git
145```
146
147Next, choose whether you want to build from a release tag, branch, or
148development head and expand the instructions below.
149
150<details><summary>Build from <strong>a release tag</strong></summary>
151
152First, list all of the tags from the repository (we use `sed` in the command
153below to filter out some unnecessary visual noise):
154
155<pre>
156git ls-remote origin refs/tags/\* | sed -e 's/refs\/tags\///'
157</pre>
158
159You'll see output similar to:
160
161<pre>
162c1a08111b603403d4ee0a78c1214f322fecaa3ca        0.1.0
163d959acc29dcbc467790ae87389f9569bb830c8c6        0.2.0
164ad59f77fd425b00ae4b8d7360a64dc3dc1c73bd0        0.3.0
165...
166</pre>
167
168<blockquote><strong>Tip</strong><p>
169The <em>tags</em> are in the right-most column. Old revisions up to and
170including <code>0.7.1</code> do not contain a <em>v</em> prefix, however, all
171revisions after, do.
172</p></blockquote>
173
174Select the tag you wish to build, and fetch it using the command below. Be sure
175to replace <code>REPLACE-ME</code> with the tag you selected:
176
177<pre>
178git fetch --no-tags --depth 1 origin +refs/tags/REPLACE-ME:refs/tags/REPLACE-ME
179</pre>
180
181<blockquote><strong>NOTE</strong><p>
182The <code>--no-tags</code> flag might seem out of place, since we <em>are</em>
183fetching a tag, but it isn't -- the reason we use this is avoid fetching other
184tags, in case you have <code>fetch.pruneTags</code> enabled in your global
185configuration, which causes <code>git</code> to fetch <em>all</em> tags.
186</p></blockquote>
187
188Next, check out the tag, replacing <code>REPLACE-ME</code> with the tag you
189selected:
190
191<pre>
192git checkout REPLACE-ME
193</pre>
194
195Finally, run the <code>build</code> target from <code>//:Makefile</code>:
196
197<pre>
198make build
199</pre>
200
201This will build <code>git-bug</code> and place it at `./result/bin/git-bug`.
202Move this binary file to a location in your `PATH`.
203
204</details>
205
206<details>
207<summary>
208Build the <strong>unstable development <code>HEAD</code></strong>
209</summary>
210
211First, fetch the most recent commit for the default branch:
212
213<pre>
214git fetch --no-tags --depth 1 origin HEAD:refs/remotes/origin/HEAD
215</pre>
216
217Next, check out the tree you pulled:
218
219<pre>
220git checkout origin/HEAD
221</pre>
222
223Finally, run the <code>build</code> target from <code>//:Makefile</code>:
224
225<pre>
226make build
227</pre>
228
229This will build <code>git-bug</code> and place it at `./result/bin/git-bug`.
230Move this binary file to a location in your `PATH`.
231
232</details>
233
234## Verify your installation<a name="verify-your-installation"></a>
235
236To verify that `git-bug` was installed correctly, you can run the following
237command. If you see output similar to what's shown below (and without any
238errors), you're all set!
239
240```
241git bug version
242```
243
244______________________________________________________________________
245
246##### See more
247
248- [Documentation home][docs/home]
249
250[brew.sh]: https://brew.sh
251[docs/home]: ./doc
252[p/aur]: https://aur.archlinux.org/packages/git-bug-bin
253[p/nix]: https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/applications/version-management/git-bug/default.nix
254[rel/latest]: https://github.com/git-bug/git-bug/releases/latest