William Le
The GitHub CLI is a new tool released by GitHub that brings issue/PR management tasks to the terminal. This will be an important tool that brings more of our software development workflow into the textual realm instead of the visual realm (the browser). It’s called gh
!
The GitHub CLI allows you to manage issues/PRs/repos from within your terminal. To give you an idea, here’s a broad overview of the API:
$ gh issue [status, list, view, create]
$ gh pr [status, list, view, checkout, create]
$ gh repo [view, create, clone, fork]
$ gh help
You can also append --help
flags to get documentation about specific commands. Like this:
$ gh repo fork --help
It should be mentioned that gh
isn’t the same as git
. This is because gh
only brings GitHub features to the terminal. Version control still needs to be handled with git
. 💻
GitHub CLI has releases for major operating systems. For example, if you’re using a Mac you can install via Homebrew:
$ brew install github/gh/gh
Voilá! The gh
command should be available in your terminal. When you first run gh
you will need to authorize GitHub CLI (via OAuth) in your browser.
Ok, you’re ready to rock! 🤘😤
We’ll cover a few interesting commands just to whet our appetites. Let’s use the official React.js repo as a guinea pig to execute gh
commands.
Let’s clone, and navigate to the react repo:
$ git clone git@github.com:facebook/react.git
$ cd react
Let’s run $ gh issue --help
to see what commands are available:
# Usage:
# gh issue [command]
# Available Commands:
# create Create a new issue
# list List and filter issues in this repository
# status Show status of relevant issues
# view View an issue in the browser
Hmm, let’s view all of the issues:
$ gh issue list
You should see an output:
There’s also flags you can use with gh issue list
. Let’s use use the --help
flag to view more info:
$ gh issue list --help
You should see this documentation:
# Usage:
# gh issue list [flags]
# Flags:
# -a, --assignee string Filter by assignee
# -l, --label strings Filter by label
# -L, --limit int Maximum number of issues to fetch
# -s, --state string Filter by state: {open|closed|all}
I wonder what Dan Abramov (@gaearon) has on his plate right now. Let’s run:
$ gh issue list --assignee gaearon
He has 3 issues assigned to him. It must be nice being a senior dev…
The first issue seems interesting 🤨. Let’s view it:
$ gh issue view 18085
This will actually open your default browser, and navigate to the URL. Adding the --preview
flag will output directly to terminal:
$ gh issue view 18085 --preview
It’s amazing how far we got without opening a browser! So far, we’ve only looked at issues. Let’s see how gh
helps us with PRs.
Imagine if we were one of the lead maintainers of React. One of our daily routines might involve:
Can this be accomplished with only gh
? Let’s see what commands are available to us ($ gh pr --help
):
# Usage:
# gh pr [command]
# Available Commands:
# checkout Check out a pull request in Git
# create Create a pull request
# list List and filter pull requests in this repository
# status Show status of relevant pull requests
# view View a pull request in the browser
Ok, so let’s view all of PRs right now:
$ gh pr list
Outputs:
The first PR (#18212
) seems interesting. Let’s read about it, and switch to that branch:
$ gh pr view 18212 --preview
$ gh pr checkout 18212
Outputs:
chompy@mylaptop: ~/react$ gh pr view 18212 --preview
threepointone wants to merge 1 commit into master from electron-optional-dependencies
When we yarn/ci, we download electron only because it's listed in react-
devtools as a dependency. We don't seem to use it for any tests or bundles
though, so it's non-essential for the build. Further the electron download
point is flaky, leading to ci failures like this
https://circleci.com/gh/facebook/react/95743 This PR simply moves electron to
optionalDependencies, so the build doesn't fail even if the download fails.
View this pull request on GitHub: https://github.com/facebook/react/pull/18212
chompy@mylaptop: ~/react$ gh pr checkout 18212
From github.com:facebook/react
* branch refs/pull/18212/head -> FETCH_HEAD
Already up to date.
Just like that we grabbed the PR code, and switched to that branch. Pretty cool!
And briefly, let’s see what gh repo
can do:
# Usage:
# gh repo [command]
# Available Commands:
# clone Clone a repository locally
# create Create a new repository
# fork Create a fork of a repository.
# view View a repository in the browser.
If you’d like to start working on a new feature (or fix bugs) for the react repo, you can simply run:
$ gh repo fork
And immediately start working. After that you can create a new PR ($ gh pr create
)! It’s kinda amazing that all of this functionality is available in the terminal now!
The stated goal of gh
is to “minimize context switching” by enabling you to remain within your terminal/editor instead of popping open your browser to visit github.com. It certainly seems to deliver because the majority of GitHub-specific features are available via gh
! 💥
Check out the documentation website for GitHub CLI 🐙🐱
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!