diff --git a/README.md b/README.md index 8257cf566..84ab978fd 100644 --- a/README.md +++ b/README.md @@ -8,106 +8,57 @@ GitHub CLI is supported for users on GitHub.com, GitHub Enterprise Cloud, and Gi ## Documentation -For [installation options see below](#installation), for usage instructions [see the manual][manual]. +For [installation options see below](#installation), for usage instructions [see the manual]( https://cli.github.com/manual/). ## Contributing -If anything feels off or if you feel that some functionality is missing, please check out the [contributing page][contributing]. There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project. +If anything feels off or if you feel that some functionality is missing, please check out the [contributing page](.github/CONTRIBUTING.md). There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project. -If you are a hubber and are interested in shipping new commands for the CLI, check out our [doc on internal contributions][intake-doc]. +If you are a hubber and are interested in shipping new commands for the CLI, check out our [doc on internal contributions](docs/working-with-us.md) ## Installation -### macOS +### [macOS](docs/install_macos.md) -`gh` is available via [Homebrew][], [MacPorts][], [Conda][], [Spack][], [Webi][], and as a downloadable binary including Mac OS installer `.pkg` from the [releases page][]. +#### [Recommended _(Official)_](docs/install_macos.md#recommended-official) -> [!NOTE] -> As of May 29th, Mac OS installer `.pkg` are unsigned with efforts prioritized in [`cli/cli#9139`](https://github.com/cli/cli/issues/9139) to support signing them. +- [Homebrew](docs/install_macos.md#homebrew) +- [Precompiled binaries](docs/install_macos.md#precompiled-binaries) on [releases page][] -#### Homebrew +#### [Community _(Unofficial)_](docs/install_macos.md#community-unofficial) -| Install: | Upgrade: | -| ----------------- | ----------------- | -| `brew install gh` | `brew upgrade gh` | +- Package managers: [Conda](docs/install_macos.md#conda), [Flox](docs/install_macos.md#flox), [MacPorts](docs/install_macos.md#macports), [Spack](docs/install_macos.md#spack), [Webi](docs/install_macos.md#webi) -#### MacPorts +### [Linux & Unix](docs/install_linux.md) -| Install: | Upgrade: | -| ---------------------- | ---------------------------------------------- | -| `sudo port install gh` | `sudo port selfupdate && sudo port upgrade gh` | +#### [Recommended _(Official)_](docs/install_linux.md#recommended-official) -#### Conda +- [Debian, Raspberry Pi, Ubuntu](docs/install_linux.md#debian) +- [Amazon Linux, CentOS, Fedora, openSUSE, RHEL, SUSE](docs/install_linux.md#rpm) +- [Precompiled binaries](docs/install_linux.md#precompiled-binaries) on [releases page][] -| Install: | Upgrade: | -|------------------------------------------|-----------------------------------------| -| `conda install gh --channel conda-forge` | `conda update gh --channel conda-forge` | +#### [Community _(Unofficial)_](docs/install_linux.md#community-unofficial) -Additional Conda installation options available on the [gh-feedstock page](https://github.com/conda-forge/gh-feedstock#installing-gh). +- Package managers: [Conda](docs/install_linux.md#conda), [Flox](docs/install_linux.md#flox), [Spack](docs/install_linux.md#spack), [Webi](docs/install_linux.md#webi) +- Operating systems: [Alpine Linux](docs/install_linux.md#alpine-linux), [Android](docs/install_linux.md#android), [Arch Linux](docs/install_linux.md#arch-linux), [Fedora Community](docs/install_linux.md#fedora-community), [FreeBSD](docs/install_linux.md#freebsd), [Funtoo](docs/install_linux.md#funtoo), [Gentoo](docs/install_linux.md#gentoo), [Manjaro Linux](docs/install_linux.md#manjaro-linux), [MidnightBSD](docs/install_linux.md#midnightbsd), [NetBSD/pkgsrc](docs/install_linux.md#netbsdpkgsrc), [Nix/NixOS](docs/install_linux.md#nixnixos), [OpenBSD](docs/install_linux.md#openbsd), [openSUSE Tumbleweed](docs/install_linux.md#opensuse-tumbleweed), [Solus Linux](docs/install_linux.md#solus-linux), [Void Linux](docs/install_linux.md#void-linux). -#### Spack +### [Windows](docs/install_windows.md) -| Install: | Upgrade: | -| ------------------ | ---------------------------------------- | -| `spack install gh` | `spack uninstall gh && spack install gh` | +#### [Recommended _(Official)_](docs/install_windows.md#recommended-official) -#### Webi +- [WinGet](docs/install_windows.md#winget) +- [Precompiled binaries](docs/install_windows.md#precompiled-binaries) on [releases page][] -| Install: | Upgrade: | -| ----------------------------------- | ---------------- | -| `curl -sS https://webi.sh/gh \| sh` | `webi gh@stable` | +#### [Community _(Unofficial)_](docs/install_windows.md#community-unofficial) -For more information about the Webi installer, see [its homepage](https://webinstall.dev/). +- Package managers: [Chocolatey](docs/install_windows.md#chocolatey), [Conda](docs/install_windows.md#conda), [Scoop](docs/install_windows.md#scoop), [Webi](docs/install_windows.md#webi) -#### Flox +### Build from source -| Install: | Upgrade: | -| ----------------- | ----------------------- | -| `flox install gh` | `flox upgrade toplevel` | +See here on how to [build GitHub CLI from source](docs/install_source.md). -For more information about Flox, see [its homepage](https://flox.dev) - -### Linux & BSD - -`gh` is available via: -- [our Debian and RPM repositories](./docs/install_linux.md); -- community-maintained repositories in various Linux distros; -- OS-agnostic package managers such as [Homebrew](#homebrew), [Conda](#conda), [Spack](#spack), [Webi](#webi); and -- our [releases page][] as precompiled binaries. - -For more information, see [Linux & BSD installation](./docs/install_linux.md). - -### Windows - -`gh` is available via [WinGet][], [scoop][], [Chocolatey][], [Conda](#conda), [Webi](#webi), and as downloadable MSI. - -#### WinGet - -| Install: | Upgrade: | -| ------------------- | --------------------| -| `winget install --id GitHub.cli` | `winget upgrade --id GitHub.cli` | - -> [!NOTE] -> The Windows installer modifies your PATH. When using Windows Terminal, you will need to **open a new window** for the changes to take effect. (Simply opening a new tab will _not_ be sufficient.) - -#### scoop - -| Install: | Upgrade: | -| ------------------ | ------------------ | -| `scoop install gh` | `scoop update gh` | - -#### Chocolatey - -| Install: | Upgrade: | -| ------------------ | ------------------ | -| `choco install gh` | `choco upgrade gh` | - -#### Signed MSI - -MSI installers are available for download on the [releases page][]. - -### Codespaces +### GitHub Codespaces To add GitHub CLI to your codespace, add the following to your [devcontainer file](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-features-to-a-devcontainer-file): @@ -119,13 +70,13 @@ To add GitHub CLI to your codespace, add the following to your [devcontainer fil ### GitHub Actions -GitHub CLI comes pre-installed in all [GitHub-Hosted Runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners). +[GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners) have the GitHub CLI pre-installed, which is updated weekly. -### Other platforms +If a specific version is needed, your GitHub Actions workflow will need to install it based on the [macOS](#macos), [Linux & Unix](#linux--unix), or [Windows](#windows) instructions above. -Download packaged binaries from the [releases page][]. +For information on all pre-installed tools, see [`actions/runner-images`](https://github.com/actions/runner-images) -#### Verification of binaries +### Verification of binaries Since version 2.50.0, `gh` has been producing [Build Provenance Attestation](https://github.blog/changelog/2024-06-25-artifact-attestations-is-generally-available/), enabling a cryptographically verifiable paper-trail back to the origin GitHub repository, git revision, and build instructions used. The build provenance attestations are signed and rely on Public Good [Sigstore](https://www.sigstore.dev/) for PKI. @@ -157,29 +108,11 @@ There are two common ways to verify a downloaded release, depending on whether ` Verified OK ``` -### Build from source - -See here on how to [build GitHub CLI from source][build from source]. - ## Comparison with hub -For many years, [hub][] was the unofficial GitHub CLI tool. `gh` is a new project that helps us explore +For many years, [hub](https://github.com/github/hub) was the unofficial GitHub CLI tool. `gh` is a new project that helps us explore what an official GitHub CLI tool can look like with a fundamentally different design. While both tools bring GitHub to the terminal, `hub` behaves as a proxy to `git`, and `gh` is a standalone -tool. Check out our [more detailed explanation][gh-vs-hub] to learn more. +tool. Check out our [more detailed explanation](docs/gh-vs-hub.md) to learn more. -[manual]: https://cli.github.com/manual/ -[Homebrew]: https://brew.sh -[MacPorts]: https://www.macports.org -[winget]: https://github.com/microsoft/winget-cli -[scoop]: https://scoop.sh -[Chocolatey]: https://chocolatey.org -[Conda]: https://docs.conda.io/en/latest/ -[Spack]: https://spack.io -[Webi]: https://webinstall.dev [releases page]: https://github.com/cli/cli/releases/latest -[hub]: https://github.com/github/hub -[contributing]: ./.github/CONTRIBUTING.md -[gh-vs-hub]: ./docs/gh-vs-hub.md -[build from source]: ./docs/source.md -[intake-doc]: ./docs/working-with-us.md diff --git a/docs/install_linux.md b/docs/install_linux.md index 15e843f4e..42886fcff 100644 --- a/docs/install_linux.md +++ b/docs/install_linux.md @@ -1,17 +1,18 @@ # Installing gh on Linux and BSD -Packages downloaded from https://cli.github.com or from https://github.com/cli/cli/releases -are considered official binaries. We focus on popular Linux distros and -the following CPU architectures: `i386`, `amd64`, `arm64`, `armhf`. +## Recommended _(Official)_ -Other sources for installation are community-maintained and thus might lag behind -our release schedule. +### Debian -## Official sources +Debian packages are hosted on the [GitHub CLI marketing site](https://cli.github.com/) for various operating systems including: -### Debian, Ubuntu Linux, Raspberry Pi OS (apt) +- [Debian](https://www.debian.org/) +- [Raspberry Pi](https://www.raspberrypi.com/) +- [Ubuntu Linux](https://ubuntu.com/) -Install: +These packages are supported by the GitHub CLI maintainers with updates powered by [GitHub CLI deployment workflow](https://github.com/cli/cli/actions/workflows/deployment.yml). + +To install: ```bash (type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \ @@ -25,56 +26,59 @@ Install: && sudo apt install gh -y ``` -Upgrade: +To upgrade: ```bash sudo apt update sudo apt install gh ``` -> [!NOTE] -> If errors regarding GPG signatures occur, see [cli/cli#9569](https://github.com/cli/cli/issues/9569) for steps to fix this. +### RPM -### Fedora, CentOS, Red Hat Enterprise Linux (DNF4 & DNF5) +RPM packages are hosted on the [GitHub CLI marketing site](https://cli.github.com) for various operating systems including: -Install from our package repository for immediate access to latest releases. +- [Amazon Linux 2](https://aws.amazon.com/amazon-linux-2/) +- [CentOS](https://www.centos.org/) +- [Fedora](https://fedoraproject.org/) +- [Red Hat Enterprise Linux](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) +- [openSUSE](https://www.opensuse.org/) +- [SUSE](https://www.suse.com/) + +These packages are supported by the GitHub CLI maintainers with updates powered by [GitHub CLI deployment workflow](https://github.com/cli/cli/actions/workflows/deployment.yml). #### DNF5 > [!IMPORTANT] > **These commands apply to DNF5 only**. If you're using DNF4, please use [the DNF4 instructions](#dnf4). +To install: + ```bash -# DNF5 installation commands sudo dnf install dnf5-plugins sudo dnf config-manager addrepo --from-repofile=https://cli.github.com/packages/rpm/gh-cli.repo sudo dnf install gh --repo gh-cli ``` +To upgrade: + +```bash +sudo dnf update gh +``` + #### DNF4 > [!IMPORTANT] > **These commands apply to DNF4 only**. If you're using DNF5, please use [the DNF5 instructions](#dnf5). +To install: + ```bash -# DNF4 installation commands sudo dnf install 'dnf-command(config-manager)' sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo sudo dnf install gh --repo gh-cli ``` -> [!NOTE] -> If errors regarding GPG signatures occur, see [cli/cli#9569](https://github.com/cli/cli/issues/9569) for steps to fix this. - -### Fedora, CentOS, Red Hat Enterprise Linux - Community repository - -Alternatively, install from the [community repository](https://packages.fedoraproject.org/pkgs/gh/gh/): - -```bash -sudo dnf install gh -``` - -Upgrade: +To upgrade: ```bash sudo dnf update gh @@ -82,7 +86,7 @@ sudo dnf update gh ### Amazon Linux 2 (yum) -Install using our package repository for immediate access to latest releases: +To install: ```bash type -p yum-config-manager >/dev/null || sudo yum install yum-utils @@ -90,18 +94,15 @@ sudo yum-config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.re sudo yum install gh ``` -Upgrade: +To upgrade: ```bash sudo yum update gh ``` -> [!NOTE] -> If errors regarding GPG signatures occur, see [cli/cli#9569](https://github.com/cli/cli/issues/9569) for steps to fix this. - ### openSUSE/SUSE Linux (zypper) -Install: +To install: ```bash sudo zypper addrepo https://cli.github.com/packages/rpm/gh-cli.repo @@ -109,50 +110,140 @@ sudo zypper ref sudo zypper install gh ``` -Upgrade: +To upgrade: ```bash sudo zypper ref sudo zypper update gh ``` -> [!NOTE] -> If errors regarding GPG signatures occur, see [cli/cli#9569](https://github.com/cli/cli/issues/9569) for steps to fix this. +### Homebrew -## Manual installation +[Homebrew](https://brew.sh/) is a free and open-source software package management system that simplifies the installation of software on Apple's operating system, macOS, as well as Linux. -* [Download release binaries][releases page] that match your platform; or -* [Build from source](./source.md). +The [GitHub CLI formulae](https://formulae.brew.sh/formula/gh) is supported by the GitHub CLI maintainers with help from our friends at Homebrew with updated powered by [homebrew/hoomebrew-core](https://github.com/Homebrew/homebrew-core/blob/main/Formula/g/gh.rb). -## Unofficial, community-supported methods +To install: -The GitHub CLI team does not maintain the following packages or repositories and thus we are unable to provide support for those installation methods. - -### Snap (do not use) - -There are [so many issues with Snap](https://github.com/casperdcl/cli/issues/7) as a runtime mechanism for apps like GitHub CLI that our team suggests _never installing gh as a snap_. - -### Arch Linux - -Arch Linux users can install from the [extra repo][arch linux repo]: - -```bash -sudo pacman -S github-cli +```shell +brew install gh ``` -Alternatively, use the [unofficial AUR package][arch linux aur] to build GitHub CLI from source. +To upgrade: + +```shell +brew upgrade gh +``` + +### Precompiled binaries + +[GitHub CLI releases](https://github.com/cli/cli/releases/latest) contain precompiled binaries for `386`, `amd64`, `arm64`, and `armv6` architectures. + +## Community _(Unofficial)_ + +> [!IMPORTANT] +> The GitHub CLI team does not maintain the following packages or repositories and thus we are unable to provide support for those installation methods. + +### Alpine Linux + +The [GitHub CLI package](https://pkgs.alpinelinux.org/package/edge/community/x86_64/github-cli) is supported by the Alpine Linux community with updates powered by [alpine/aports](https://gitlab.alpinelinux.org/alpine/aports/-/tree/master/community/github-cli. + +To install stable release: + +```bash +apk add github-cli +``` + +To install edge release: + +```bash +echo "@community http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories +apk add github-cli@community +``` ### Android -Android 7+ users can install via [Termux](https://wiki.termux.com/wiki/Main_Page): +The [GitHub CLI package](https://packages.termux.dev/apt/termux-main/pool/main/g/gh/) is supported by the Termux community with updates powered by [termux/termux-packages](https://github.com/termux/termux-packages/tree/master/packages/gh) + +To install and upgrade: ```bash pkg install gh ``` +### Arch Linux + +The [GitHub CLI package](https://www.archlinux.org/packages/extra/x86_64/github-cli) is supported by the Arch Linux community with updates powered by [Arch Linux packaging](https://gitlab.archlinux.org/archlinux/packaging/packages/github-cli) + +To install: + +```bash +sudo pacman -S github-cli +``` + +To upgrade all packages: + +```bash +sudo pacman -Syu +``` + +Alternatively, use the [unofficial AUR package](https://aur.archlinux.org/packages/github-cli-git) to build GitHub CLI from source. + +### Conda + +[Conda](https://docs.conda.io/en/latest/) is an open source package management system and environment management system for installing multiple versions of software packages and their dependencies and switching easily between them. It works on Linux, OS X and Windows, and was created for Python programs but can package and distribute any software. + +The [GitHub CLI package](https://anaconda.org/conda-forge/gh) is supported by the Conda community with updates powered by [conda-forge/gh-feedstock](https://github.com/conda-forge/gh-feedstock#installing-gh). + +To install: + +```shell +conda install gh --channel conda-forge +``` + +To upgrade: + +```shell +conda update gh --channel conda-forge +``` + +### Fedora Community + +The [GitHub CLI package](https://packages.fedoraproject.org/pkgs/gh/gh/) is supported by the Fedora community with updates powered by [Fedora Project](https://src.fedoraproject.org/rpms/gh). + +To install: + +```bash +sudo dnf install gh +``` + +To upgrade: + +```bash +sudo dnf update gh +``` + +### Flox + +[Flox](https://flox.dev/) is a virtual environment and package manager all in one. With Flox you create environments that layer and replace dependencies just where it matters, making them portable across the full software lifecycle. + +Flox relies upon the [GitHub CLI package](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/gh/gh/package.nix) supported by the [NixOS community](https://nixos.org/) + +To install: + +```shell +flox install gh +``` + +To upgrade: + +```shell +flox upgrade toplevel +``` + ### FreeBSD -FreeBSD users can install from the [ports collection](https://www.freshports.org/devel/gh/): +The [GitHub CLI port](https://www.freshports.org/devel/gh/) is supported by the FreeBSD community with updates powered by [FreeBSD ports](https://cgit.freebsd.org/ports/tree/devel/gh) ```bash cd /usr/ports/devel/gh/ && make install clean @@ -164,9 +255,55 @@ Or via [pkg(8)](https://www.freebsd.org/cgi/man.cgi?pkg(8)): pkg install gh ``` +### Funtoo + +The GitHub CLI portage is supported by the Funtoo community with updates powered by [funtoo/dev-kit](https://github.com/funtoo/dev-kit/tree/1.4-release/dev-util/github-cli). + +To install: + +```bash +emerge -av github-cli +``` + +To upgrade: + +```bash +ego sync +emerge -u github-cli +``` + +### Gentoo + +The [GitHub CLI portage](https://packages.gentoo.org/packages/dev-util/github-cli) is supported by the Gentoo community with updates powered by [Gentoo portage](https://gitweb.gentoo.org/repo/gentoo.git/tree/dev-util/github-cli). + +To install: + +``` bash +emerge -av github-cli +``` + +To upgrade: + +``` bash +emerge --sync +emerge -u github-cli +``` + +### Manjaro Linux + +The [GitHub CLI package](https://manjaristas.org/branch_compare?q=github-cli) is the same package produced by the [Arch Linux community](#arch-linux) + +To install and upgrade: + +```bash +pamac install github-cli +``` + ### MidnightBSD -MidnightBSD users can install from [mports](https://www.midnightbsd.org/documentation/mports/index.html) +The [GitHub CLI port](https://www.midnightbsd.org/mports/devel/gh/README.html) is supported by the MidnightBSD community with updates powered by [MidnightBSD/mports](https://github.com/MidnightBSD/mports/tree/master/devel/gh) + +To install: ```bash cd /usr/mports/devel/gh/ && make install clean @@ -180,133 +317,110 @@ mport install gh ### NetBSD/pkgsrc -NetBSD users and those on [platforms supported by pkgsrc](https://pkgsrc.org/#index4h1) can install the [gh package](https://pkgsrc.se/net/gh): +The [GitHub CLI package](https://pkgsrc.se/net/gh) is supported by the NetBSD community with updates powered by [NetBSD/pkgsrc](https://github.com/NetBSD/pkgsrc/tree/trunk/net/gh). + +To install: ```bash pkgin install gh ``` -To install from source: - -```bash -cd /usr/pkgsrc/net/gh && make package-install -``` - -### OpenBSD - -In -current, or in releases starting from 7.0, OpenBSD users can install from packages: - -``` -pkg_add github-cli -``` - -### Funtoo - -Funtoo Linux has an autogenerated github-cli package, located in [dev-kit](https://github.com/funtoo/dev-kit/tree/1.4-release/dev-util/github-cli), which can be installed in the following way: - -``` bash -emerge -av github-cli -``` - -Upgrading can be done by syncing the repos and then requesting an upgrade: - -``` bash -ego sync -emerge -u github-cli -``` - -### Gentoo - -Gentoo Linux users can install from the [main portage tree](https://packages.gentoo.org/packages/dev-util/github-cli): - -``` bash -emerge -av github-cli -``` - -Upgrading can be done by updating the portage tree and then requesting an upgrade: - -``` bash -emerge --sync -emerge -u github-cli -``` - -### Kiss Linux - -Kiss Linux users can install from the [community repos](https://github.com/kisslinux/community): - -```bash -kiss b github-cli && kiss i github-cli -``` - ### Nix/NixOS -Nix/NixOS users can install from [nixpkgs](https://search.nixos.org/packages?query=gh&sort=relevance&show=gh): +The [GitHub CLI package](https://search.nixos.org/packages?query=gh&sort=relevance&show=gh) is supported by the NixOS community with updates powered by [NixOS/nixpkgs](https://github.com/NixOS/nixpkgs/tree/master/pkgs/by-name/gh/gh). + +To install: ```bash nix-env -iA nixos.gh ``` -### Flox +### OpenBSD -Flox users can install from the [official community nixpkgs](https://github.com/flox/nixpkgs). +The [GitHub CLI port](https://openports.pl/path/devel/github-cli) is supported by the OpenBSD community with updates powered by [OpenBSD ports](https://cvsweb.openbsd.org/ports/devel/github-cli/). -```bash -# To install -flox install gh +To install: -# To upgrade -flox upgrade toplevel ``` - -For more information about Flox, see [its homepage](https://flox.dev). +pkg_add github-cli +``` ### openSUSE Tumbleweed -openSUSE Tumbleweed users can install from the [official distribution repo](https://software.opensuse.org/package/gh): +The [GitHub CLI package](https://software.opensuse.org/package/gh) is supported by the openSUSE community. + +To install: + ```bash -sudo zypper in gh +sudo zypper install gh ``` - -### Alpine Linux - -Alpine Linux users can install from the [stable releases' community package repository](https://pkgs.alpinelinux.org/packages?name=github-cli&branch=v3.15). +To upgrade: ```bash -apk add github-cli -``` - -Users wanting the latest version of the CLI without waiting to be backported into the stable release they're using should use the edge release's -community repo through this method below, without mixing packages from stable and unstable repos.[^1] - -```bash -echo "@community http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories -apk add github-cli@community -``` - -### Void Linux -Void Linux users can install from the [official distribution repo](https://voidlinux.org/packages/?arch=x86_64&q=github-cli): - -```bash -sudo xbps-install github-cli -``` - -### Manjaro Linux -Manjaro Linux users can install from the [official extra repository](https://manjaristas.org/branch_compare?q=github-cli): - -```bash -pamac install github-cli +sudo zypper update gh ``` ### Solus Linux -Solus Linux users can install using [eopkg package manager](https://help.getsol.us/docs/user/package-management/basics/): + +The GitHub CLI package is supported by the Solus Linux community with updates powered by [getsolus/packages](https://github.com/getsolus/packages/blob/main/packages/g/github-cli/) + +To install: ```bash sudo eopkg install github-cli ``` -For more information about the `github-cli` package, see [the package definition](https://github.com/getsolus/packages/blob/main/packages/g/github-cli/package.yml) in the `getsolus/packages` repository. +### Spack -[releases page]: https://github.com/cli/cli/releases/latest -[arch linux repo]: https://www.archlinux.org/packages/extra/x86_64/github-cli -[arch linux aur]: https://aur.archlinux.org/packages/github-cli-git -[^1]: https://wiki.alpinelinux.org/wiki/Package_management#Repository_pinning +[Spack](https://spack.io/) is a flexible package manager supporting multiple versions, configurations, platforms, and compilers for supercomputers, Linux, and macOS. + +The [GitHub CLI package](https://packages.spack.io/package.html?name=gh) is supported by the Spack community with updates powered by [spack/spack-packages](https://github.com/spack/spack-packages/tree/develop/repos/spack_repo/builtin/packages/gh). + +To install: + +```shell +spack install gh +``` + +To upgrade: + +```shell +spack uninstall gh && spack install gh +``` + +### Void Linux + +The [GitHub CLI package](https://voidlinux.org/packages/?arch=x86_64&q=github-cli): is supported by the Void Linux community with updates powered by [void-linux/void-packages](https://github.com/void-linux/void-packages/tree/master/srcpkgs/github-cli) + +To install: + +```bash +sudo xbps-install github-cli +``` + +### Webi + +[Webi](https://webinstall.dev/) is a tool that aims to effortlessly install developer tools with easy-to-remember URLs from official builds quickly, without sudo or Admin, without a package manager, and without changing system file permissions. + +The [GitHub CLI package](https://webinstall.dev/gh/) is supported by the Webi community with updates powered by [webinstall/webi-installers](https://github.com/webinstall/webi-installers/tree/main/gh). + +To install: + +```shell +curl -sS https://webi.sh/gh \| sh +``` + +To upgrade: + +```shell +webi gh@stable +``` + +## Discouraged + +> [!WARNING] +> The GitHub CLI team actively discourages use of the following methods of installion. + +### Snap + +The [GitHub CLI package](https://snapcraft.io/gh) has [so many issues with Snap](https://github.com/casperdcl/cli/issues/7) as a runtime mechanism for apps like GitHub CLI that our team suggests _never installing gh as a snap_. diff --git a/docs/install_macos.md b/docs/install_macos.md new file mode 100644 index 000000000..5e5cedf72 --- /dev/null +++ b/docs/install_macos.md @@ -0,0 +1,129 @@ +# Installing gh on macOS + +## Recommended _(Official)_ + +### Homebrew + +[Homebrew](https://brew.sh/) is a free and open-source software package management system that simplifies the installation of software on Apple's operating system, macOS, as well as Linux. + +The [GitHub CLI formulae](https://formulae.brew.sh/formula/gh) is supported by the GitHub CLI maintainers with help from our friends at Homebrew with updated powered by [homebrew/homebrew-core](https://github.com/Homebrew/homebrew-core/blob/main/Formula/g/gh.rb). + +To install: + +```shell +brew install gh +``` + +To upgrade: + +```shell +brew upgrade gh +``` + +### Precompiled binaries + +[GitHub CLI releases](https://github.com/cli/cli/releases/latest) contain precompiled binaries for `amd64` and `arm64` architectures along with a universal installer. + +> [!NOTE] +> As of May 29th, Mac OS installer `.pkg` are unsigned with efforts prioritized in [`cli/cli#9139`](https://github.com/cli/cli/issues/9139) to support signing them. + +### Build from source + +Users who want the latest changes can build the GitHub CLI from source. + +For more information, see [installation from source](install_source.md). + +## Community _(Unofficial)_ + +> [!IMPORTANT] +> The GitHub CLI team does not maintain the following packages or repositories and thus we are unable to provide support for those installation methods. + +### Conda + +[Conda](https://docs.conda.io/en/latest/) is an open source package management system and environment management system for installing multiple versions of software packages and their dependencies and switching easily between them. It works on Linux, OS X and Windows, and was created for Python programs but can package and distribute any software. + +The [GitHub CLI package](https://anaconda.org/conda-forge/gh) is supported by the Conda community with updates powered by [conda-forge/gh-feedstock](https://github.com/conda-forge/gh-feedstock#installing-gh). + +To install: + +```shell +conda install gh --channel conda-forge +``` + +To upgrade: + +```shell +conda update gh --channel conda-forge +``` + +### Flox + +[Flox](https://flox.dev/) is a virtual environment and package manager all in one. With Flox you create environments that layer and replace dependencies just where it matters, making them portable across the full software lifecycle. + +Flox relies upon the [GitHub CLI package](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/gh/gh/) supported by the [NixOS community](https://nixos.org/) + +To install: + +```shell +flox install gh +``` + +To upgrade: + +```shell +flox upgrade toplevel +``` + +### MacPorts + +[MacPorts](https://www.macports.org/) is an open-source community initiative to design an easy-to-use system for compiling, installing, and upgrading either command-line, X11 or Aqua based open-source software on the Mac operating system. + +The [GitHub CLI port](https://ports.macports.org/port/gh/) is supported by the MacPorts community with updates powered by [macports/macports-ports](https://github.com/macports/macports-ports/blob/master/devel/gh/Portfile) + +To install: + +```shell +sudo port install gh +``` + +To upgrade: + +```shell +sudo port selfupdate && sudo port upgrade gh +``` + +### Spack + +[Spack](https://spack.io/) is a flexible package manager supporting multiple versions, configurations, platforms, and compilers for supercomputers, Linux, and macOS. + +The [GitHub CLI package](https://packages.spack.io/package.html?name=gh) is supported by the Spack community with updates powered by [spack/spack-packages](https://github.com/spack/spack-packages/tree/develop/repos/spack_repo/builtin/packages/gh). + +To install: + +```shell +spack install gh +``` + +To upgrade: + +```shell +spack uninstall gh && spack install gh +``` + +### Webi + +[Webi](https://webinstall.dev/) is a tool that aims to effortlessly install developer tools with easy-to-remember URLs from official builds quickly, without sudo or Admin, without a package manager, and without changing system file permissions. + +The [GitHub CLI package](https://webinstall.dev/gh/) is supported by the Webi community with updates powered by [webinstall/webi-installers](https://github.com/webinstall/webi-installers/tree/main/gh). + +To install: + +```shell +curl -sS https://webi.sh/gh \| sh +``` + +To upgrade: + +```shell +webi gh@stable +``` diff --git a/docs/install_source.md b/docs/install_source.md new file mode 100644 index 000000000..e37c7679c --- /dev/null +++ b/docs/install_source.md @@ -0,0 +1,59 @@ +# Installation from source + +1. Verify that you have Go 1.24+ installed + + ```sh + $ go version + ``` + + If `go` is not installed, follow instructions on [the Go website](https://golang.org/doc/install). + +2. Clone this repository + + ```sh + $ git clone https://github.com/cli/cli.git gh-cli + $ cd gh-cli + ``` + +3. Build and install + + #### Unix-like systems + ```sh + # installs to '/usr/local' by default; sudo may be required, or sudo -E for configured go environments + $ make install + + # or, install to a different location + $ make install prefix=/path/to/gh + ``` + + #### Windows + ```pwsh + # build the `bin\gh.exe` binary + > go run script\build.go + ``` + There is no install step available on Windows. + +4. Run `gh version` to check if it worked. + + #### Windows + Run `bin\gh version` to check if it worked. + +## Cross-compiling binaries for different platforms + +You can use any platform with Go installed to build a binary that is intended for another platform +or CPU architecture. This is achieved by setting environment variables such as GOOS and GOARCH. + +For example, to compile the `gh` binary for the 32-bit Raspberry Pi OS: +```sh +# on a Unix-like system: +$ GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 make clean bin/gh +``` +```pwsh +# on Windows, pass environment variables as arguments to the build script: +> go run script\build.go clean bin\gh GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 +``` + +Run `go tool dist list` to list all supported values of GOOS/GOARCH. + +Tip: to reduce the size of the resulting binary, you can use `GO_LDFLAGS="-s -w"`. This omits +symbol tables used for debugging. See the list of [supported linker flags](https://golang.org/cmd/link/). diff --git a/docs/install_windows.md b/docs/install_windows.md new file mode 100644 index 000000000..c5e678673 --- /dev/null +++ b/docs/install_windows.md @@ -0,0 +1,97 @@ +# Installing gh on Windows + +## Recommended _(Official)_ + +### WinGet + +The [GitHub CLI package](https://winget.run/pkg/GitHub/cli) is supported by Microsoft with updates powered by [microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs/tree/master/manifests/g/GitHub/cli/) + +To install: + +```pwsh +winget install --id GitHub.cli +``` + +To upgrade: + +```pwsh +winget upgrade --id GitHub.cli +``` + +> [!NOTE] +> The Windows installer modifies your PATH. When using Windows Terminal, you will need to **open a new window** for the changes to take effect. (Simply opening a new tab will _not_ be sufficient.) + +### Precompiled binaries + +[GitHub CLI releases](https://github.com/cli/cli/releases/latest) contain precompiled `exe` and `msi` binaries for `386`, `amd64` and `arm64` architectures. + +## Community _(Unofficial)_ + +> [!IMPORTANT] +> The GitHub CLI team does not maintain the following packages or repositories and thus we are unable to provide support for those installation methods. + +### Chocolatey + +The [GitHub CLI package](https://community.chocolatey.org/packages/gh) is supported by the Chocolatey communty with updates powered by [pauby/ChocoPackages](https://github.com/pauby/ChocoPackages/tree/master/automatic/gh) + +To install: + +```pwsh +choco install gh +``` + +To upgrade: + +```pwsh +choco upgrade gh +``` + +### Conda + +[Conda](https://docs.conda.io/en/latest/) is an open source package management system and environment management system for installing multiple versions of software packages and their dependencies and switching easily between them. It works on Linux, OS X and Windows, and was created for Python programs but can package and distribute any software. + +The [GitHub CLI package](https://anaconda.org/conda-forge/gh) is supported by the Conda community with updates powered by [conda-forge/gh-feedstock](https://github.com/conda-forge/gh-feedstock#installing-gh). + +To install: + +```shell +conda install gh --channel conda-forge +``` + +To upgrade: + +```shell +conda update gh --channel conda-forge +``` + +### Scoop + +To install: + +```pwsh +scoop install gh +``` + +To upgrade: + +```pwsh +scoop update gh +``` + +### Webi + +[Webi](https://webinstall.dev/) is a tool that aims to effortlessly install developer tools with easy-to-remember URLs from official builds quickly, without sudo or Admin, without a package manager, and without changing system file permissions. + +The [GitHub CLI package](https://webinstall.dev/gh/) is supported by the Webi community with updates powered by [webinstall/webi-installers](https://github.com/webinstall/webi-installers/tree/main/gh). + +To install: + +```shell +curl -sS https://webi.sh/gh \| sh +``` + +To upgrade: + +```shell +webi gh@stable +```