Skip to content

Commit a247a04

Browse files
andyfellerandyfeller
authored
Merge pull request cli#11473 from cli/andyfeller/github-cli-934-reorganize-install-docs
Reorganize installation docs
2 parents dd26fba + 5b9324b commit a247a04

6 files changed

Lines changed: 544 additions & 220 deletions

File tree

‎.github/CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,14 @@ We accept pull requests for bug fixes and features where we've discussed the app
1010
* Open an issue if things aren't working as expected
1111
* Open an issue to propose a significant change
1212
* Open an issue to propose a design for an issue labelled [`needs-design` and `help wanted`][needs design and help wanted], following the [proposing a design guidelines](#proposing-a-design) instructions below
13+
* Open an issue to propose a new community supported `gh` package with details about support and redistribution
1314
* Mention `@cli/code-reviewers` when an issue you want to work on does not have clear Acceptance Criteria
1415
* Open a pull request for any issue labelled [`help wanted`][hw] and [`good first issue`][gfi]
1516

1617
### Please _do not_:
1718

1819
* Open a pull request for issues without the `help wanted` label or explicit Acceptance Criteria
1920
* Expand pull request scope to include changes that are not described in the issue's Acceptance Criteria
20-
* Add installation instructions specifically for your OS/package manager
2121
* Open pull requests for any issue marked `core`. These issues require additional context from
2222
the core CLI team at GitHub and any external pull requests will not be accepted
2323

‎README.md‎

Lines changed: 26 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -8,106 +8,44 @@ GitHub CLI is supported for users on GitHub.com, GitHub Enterprise Cloud, and Gi
88

99
## Documentation
1010

11-
For [installation options see below](#installation), for usage instructions [see the manual][manual].
11+
For [installation options see below](#installation), for usage instructions [see the manual]( https://cli.github.com/manual/).
1212

1313
## Contributing
1414

15-
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.
15+
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.
1616

17-
If you are a hubber and are interested in shipping new commands for the CLI, check out our [doc on internal contributions][intake-doc].
17+
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)
1818

1919
<!-- this anchor is linked to from elsewhere, so avoid renaming it -->
2020
## Installation
2121

22-
### macOS
22+
### [macOS](docs/install_macos.md)
2323

24-
`gh` is available via [Homebrew][], [MacPorts][], [Conda][], [Spack][], [Webi][], and as a downloadable binary including Mac OS installer `.pkg` from the [releases page][].
24+
- [Homebrew](docs/install_macos.md#homebrew)
25+
- [Precompiled binaries](docs/install_macos.md#precompiled-binaries) on [releases page][]
2526

26-
> [!NOTE]
27-
> 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.
27+
For additional macOS packages and installers, see [community-supported docs](docs/install_macos.md#community-unofficial)
2828

29-
#### Homebrew
29+
### [Linux & Unix](docs/install_linux.md)
3030

31-
| Install: | Upgrade: |
32-
| ----------------- | ----------------- |
33-
| `brew install gh` | `brew upgrade gh` |
31+
- [Debian, Raspberry Pi, Ubuntu](docs/install_linux.md#debian)
32+
- [Amazon Linux, CentOS, Fedora, openSUSE, RHEL, SUSE](docs/install_linux.md#rpm)
33+
- [Precompiled binaries](docs/install_linux.md#precompiled-binaries) on [releases page][]
3434

35-
#### MacPorts
35+
For additional Linux & Unix packages and installers, see [community-supported docs](docs/install_linux.md#community-unofficial)
3636

37-
| Install: | Upgrade: |
38-
| ---------------------- | ---------------------------------------------- |
39-
| `sudo port install gh` | `sudo port selfupdate && sudo port upgrade gh` |
37+
### [Windows](docs/install_windows.md)
4038

41-
#### Conda
39+
- [WinGet](docs/install_windows.md#winget)
40+
- [Precompiled binaries](docs/install_windows.md#precompiled-binaries) on [releases page][]
4241

43-
| Install: | Upgrade: |
44-
|------------------------------------------|-----------------------------------------|
45-
| `conda install gh --channel conda-forge` | `conda update gh --channel conda-forge` |
42+
For additional Windows packages and installers, see [community-supported docs](docs/install_windows.md#community-unofficial)
4643

47-
Additional Conda installation options available on the [gh-feedstock page](https://github.com/conda-forge/gh-feedstock#installing-gh).
48-
49-
#### Spack
50-
51-
| Install: | Upgrade: |
52-
| ------------------ | ---------------------------------------- |
53-
| `spack install gh` | `spack uninstall gh && spack install gh` |
54-
55-
#### Webi
56-
57-
| Install: | Upgrade: |
58-
| ----------------------------------- | ---------------- |
59-
| `curl -sS https://webi.sh/gh \| sh` | `webi gh@stable` |
60-
61-
For more information about the Webi installer, see [its homepage](https://webinstall.dev/).
62-
63-
#### Flox
64-
65-
| Install: | Upgrade: |
66-
| ----------------- | ----------------------- |
67-
| `flox install gh` | `flox upgrade toplevel` |
68-
69-
For more information about Flox, see [its homepage](https://flox.dev)
70-
71-
### Linux & BSD
72-
73-
`gh` is available via:
74-
- [our Debian and RPM repositories](./docs/install_linux.md);
75-
- community-maintained repositories in various Linux distros;
76-
- OS-agnostic package managers such as [Homebrew](#homebrew), [Conda](#conda), [Spack](#spack), [Webi](#webi); and
77-
- our [releases page][] as precompiled binaries.
78-
79-
For more information, see [Linux & BSD installation](./docs/install_linux.md).
80-
81-
### Windows
82-
83-
`gh` is available via [WinGet][], [scoop][], [Chocolatey][], [Conda](#conda), [Webi](#webi), and as downloadable MSI.
84-
85-
#### WinGet
86-
87-
| Install: | Upgrade: |
88-
| ------------------- | --------------------|
89-
| `winget install --id GitHub.cli` | `winget upgrade --id GitHub.cli` |
90-
91-
> [!NOTE]
92-
> 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.)
93-
94-
#### scoop
95-
96-
| Install: | Upgrade: |
97-
| ------------------ | ------------------ |
98-
| `scoop install gh` | `scoop update gh` |
99-
100-
#### Chocolatey
101-
102-
| Install: | Upgrade: |
103-
| ------------------ | ------------------ |
104-
| `choco install gh` | `choco upgrade gh` |
105-
106-
#### Signed MSI
44+
### Build from source
10745

108-
MSI installers are available for download on the [releases page][].
46+
See here on how to [build GitHub CLI from source](docs/install_source.md).
10947

110-
### Codespaces
48+
### GitHub Codespaces
11149

11250
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):
11351

@@ -119,13 +57,13 @@ To add GitHub CLI to your codespace, add the following to your [devcontainer fil
11957

12058
### GitHub Actions
12159

122-
GitHub CLI comes pre-installed in all [GitHub-Hosted Runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners).
60+
[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.
12361

124-
### Other platforms
62+
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.
12563

126-
Download packaged binaries from the [releases page][].
64+
For information on all pre-installed tools, see [`actions/runner-images`](https://github.com/actions/runner-images)
12765

128-
#### Verification of binaries
66+
### Verification of binaries
12967

13068
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.
13169

@@ -157,29 +95,11 @@ There are two common ways to verify a downloaded release, depending on whether `
15795
Verified OK
15896
```
15997

160-
### Build from source
161-
162-
See here on how to [build GitHub CLI from source][build from source].
163-
16498
## Comparison with hub
16599

166-
For many years, [hub][] was the unofficial GitHub CLI tool. `gh` is a new project that helps us explore
100+
For many years, [hub](https://github.com/github/hub) was the unofficial GitHub CLI tool. `gh` is a new project that helps us explore
167101
what an official GitHub CLI tool can look like with a fundamentally different design. While both
168102
tools bring GitHub to the terminal, `hub` behaves as a proxy to `git`, and `gh` is a standalone
169-
tool. Check out our [more detailed explanation][gh-vs-hub] to learn more.
170-
171-
[manual]: https://cli.github.com/manual/
172-
[Homebrew]: https://brew.sh
173-
[MacPorts]: https://www.macports.org
174-
[winget]: https://github.com/microsoft/winget-cli
175-
[scoop]: https://scoop.sh
176-
[Chocolatey]: https://chocolatey.org
177-
[Conda]: https://docs.conda.io/en/latest/
178-
[Spack]: https://spack.io
179-
[Webi]: https://webinstall.dev
103+
tool. Check out our [more detailed explanation](docs/gh-vs-hub.md) to learn more.
104+
180105
[releases page]: https://github.com/cli/cli/releases/latest
181-
[hub]: https://github.com/github/hub
182-
[contributing]: ./.github/CONTRIBUTING.md
183-
[gh-vs-hub]: ./docs/gh-vs-hub.md
184-
[build from source]: ./docs/source.md
185-
[intake-doc]: ./docs/working-with-us.md

0 commit comments

Comments
 (0)