Skip to content

INSTALLATION.md

Latest commit

 

History

History
384 lines (289 loc) · 15.5 KB

INSTALLATION.md

File metadata and controls

384 lines (289 loc) · 15.5 KB
Raw

Installation Guide

git-bug is distributed as a single binary, and is available for multiple platforms. Follow this document for instructions on how to install git-bug, and verify your installation.

Download a pre-compiled release binary

Each release provides, for every supported system:

  • a binary: rename it to git-bug (git-bug.exe on Windows) and place it in a directory that's in your PATH.
  • an archive (tar.gz, or zip on Windows): the same binary, plus man pages and shell completions.
  • on Linux, packages that install all of the above where your system expects them.

The download links are in the section for your OS below. Binary links always point to the latest release. Archive and package filenames include the version, so their links point to v0.11.0; the release page may have a newer one.

Verify a download

Every release includes a checksums.txt file, which lists the SHA-256 of each download. It is signed with keyless cosign by the release workflow, and the signature is in checksums.txt.sigstore.json.

Download both files next to the file you want to check. The first command below confirms that checksums.txt was signed by git-bug's release workflow. The second checks your file against it:

cosign verify-blob checksums.txt \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/git-bug/git-bug/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

sha256sum --ignore-missing -c checksums.txt

Linux

git-bug is available on a variety of Linux distributions, but how you install it depends on your distribution and package manager(s), as there is no standard package manager common to all distributions.

You can download it from the release. The CPU is what uname -m prints:

CPU Binary tar.gz deb rpm apk Arch
x86_64 ⬇ ⬇ ⬇ ⬇ ⬇ ⬇
aarch64 ⬇ ⬇ ⬇ ⬇ ⬇ ⬇
armv7l ⬇ ⬇ ⬇ ⬇ ⬇ ⬇
armv6l ⬇ ⬇ ⬇ ⬇ ⬇

Install a package with your package manager:

sudo apt install ./git-bug_<version>_linux_amd64.deb                # Debian, Ubuntu
sudo dnf install ./git-bug_<version>_linux_amd64.rpm                # Fedora, RHEL
sudo apk add --allow-untrusted ./git-bug_<version>_linux_amd64.apk  # Alpine
sudo pacman -U ./git-bug_<version>_linux_amd64.pkg.tar.zst          # Arch

Arch Linux

git-bug is available in the Arch Linux User Repository (AUR).

Below, you'll find a non-exhaustive list of commands that use common third party tools for installing packages from the AUR.

Using aurutils 
aur sync git-bug-bin && pacman -Syu git-bug-bin
Using yay 
yay -S git-bug-bin

Nixpkgs

git-bug is available via nixpkgs.

Using home-manager 
home.package = with pkgs; [
  git-bug
];
Using system configuration 
environment.systemPackages = with pkgs; [
  git-bug
];
Using nix profile 
nix profile install nixpkgs\#git-bug
Temporary installation with nix shell 
nix shell nixpkgs\#git-bug

FreeBSD

git-bug is available on FreeBSD through a few different methods.

Using pkg 
pkg install git-bug
Using the ports collection 
make -C /usr/ports/devel/git-bug install clean

Or download it from the release:

CPU Binary tar.gz
x86-64 ⬇ ⬇
ARM64 ⬇ ⬇

OpenBSD and NetBSD

Download git-bug from the release:

System Binary tar.gz
OpenBSD x86-64 ⬇ ⬇
NetBSD x86-64 ⬇ ⬇

MacOS

git-bug is shipped via Homebrew:

brew install git-bug

Or download it from the release:

CPU Binary tar.gz
Apple Silicon ⬇ ⬇
Intel ⬇ ⬇

Windows

git-bug is shipped via scoop:

scoop install git-bug

Or download it from the release:

CPU Binary zip
x86-64 ⬇ ⬇
ARM64 ⬇ ⬇

Build from source

You can also build git-bug from source, if you wish. You'll need the following dependencies:

  • git
  • go
  • make

Ensure that the go binary directory ($GOPATH/bin) is in your PATH. It is recommended to set this within your shell configuration file(s), such as ~/.zprofile or ~/.bashrc.

export PATH=$PATH:$(go env GOROOT)/bin:$(go env GOPATH)/bin

Note

The commands below assume you do not want to keep the repository on disk, and thus clones the repository to a new temporary directory and performs a lightweight clone in order to reduce network latency and data transfer.

As a result, the repository cloned during these steps will not contain the full history. If that is important to you, clone the repository using the method you prefer, check out your preferred revision, and run make install.

First, create a new repository on disk:

cd $(mktemp -d) && git init .

Next, set the remote to the upstream source:

git remote add origin git@github.com:git-bug/git-bug.git

Next, choose whether you want to build from a release tag, branch, or development head and expand the instructions below.

Build from a release tag

First, list all of the tags from the repository (we use sed in the command below to filter out some unnecessary visual noise):

git ls-remote origin refs/tags/\* | sed -e 's/refs\/tags\///'

You'll see output similar to:

c1a08111b603403d4ee0a78c1214f322fecaa3ca        0.1.0
d959acc29dcbc467790ae87389f9569bb830c8c6        0.2.0
ad59f77fd425b00ae4b8d7360a64dc3dc1c73bd0        0.3.0
...
Tip

The tags are in the right-most column. Old revisions up to and including 0.7.1 do not contain a v prefix, however, all revisions after, do.

Select the tag you wish to build, and fetch it using the command below. Be sure to replace REPLACE-ME with the tag you selected:

git fetch --no-tags --depth 1 origin +refs/tags/REPLACE-ME:refs/tags/REPLACE-ME
NOTE

The --no-tags flag might seem out of place, since we are fetching a tag, but it isn't -- the reason we use this is avoid fetching other tags, in case you have fetch.pruneTags enabled in your global configuration, which causes git to fetch all tags.

Next, check out the tag, replacing REPLACE-ME with the tag you selected:

git checkout REPLACE-ME

Finally, run the install target from //:Makefile:

make install

This will build git-bug and place it in your Go binary directory.

Build the unstable development HEAD

First, fetch the most recent commit for the default branch:

git fetch --no-tags --depth 1 origin HEAD:refs/remotes/origin/HEAD

Next, check out the tree you pulled:

git checkout origin/HEAD

Finally, run the install target from //:Makefile:

make install

This will build git-bug and place it in your Go binary directory.

Verify your installation

To verify that git-bug was installed correctly, you can run the following command. If you see output similar to what's shown below (and without any errors), you're all set!

git bug version
See more