What if I told you it’s possible to manage your GitHub repository within the CLI? No more pointing and clicking on a user interface, just commands. That would mean faster work with less context-switching, right? Brace yourself. GitHub’s official command line is right here for you.
Triaging issues, creating or checking out pull requests, releasing packages, forking repos, even creating gists can now be done from your terminal. And we all know its power and how fast it can be. Using GitHub CLI has been a real win for my workflow. Want to learn more? It all happens down here. 👇
First things first, installing GitHub CLI. If you’re a macOS user, run
brew install gh. If you’re a Windows user, you can install it via scoop or Chocolatey. As for Linux, you have great installation instructions here: Installing gh on Linux.
It’s installed? Good. As said previously, GitHub CLI aims at managing your workflow directly from the terminal. But it needs to have access to your account,
gh auth login
You’ll be prompted to configure your preferred Git protocol, pick whatever suits you here. If you choose SSH, make sure you added a SSH key to your account.
Finally, set your preferred editor. In my case, I mostly work with VS Code. Thus, I ran:
gh config set editor "code --wait"
--wait option is essential here. Indeed, when you are prompted to enter a longer message (such as a pull request’s body), the CLI needs to have a signal you’re done, such as closing a VS Code window.
You’re now good to go.
What can GitHub CLI do for you? Good question. As with most CLIs, you have a dedicated help command for that:
➜ gh helpWork seamlessly with GitHub from the command line.USAGEgh <command> <subcommand> [flags]CORE COMMANDSgist: Create gistsissue: Manage issuespr: Manage pull requestsrelease: Manage GitHub releasesrepo: Create, clone, fork, and view repositoriesADDITIONAL COMMANDSalias: Create command shortcutsapi: Make an authenticated GitHub API requestauth: Login, logout, and refresh your authenticationcompletion: Generate shell completion scriptsconfig: Manage configuration for ghhelp: Help about any commandFLAGS--help Show help for command--version Show gh versionEXAMPLES$ gh issue create$ gh repo clone cli/cli$ gh pr checkout 321...
That’s quite helpful. Most of the time, you’ll use core commands. Use the
--help option to know what you can do with each of them. Here’s an example with the
➜ gh issue --helpWork with GitHub issuesUSAGEgh issue <command> [flags]CORE COMMANDSclose: Close issuecreate: Create a new issuelist: List and filter issues in this repositoryreopen: Reopen issuestatus: Show status of relevant issuesview: View an issueFLAGS-R, --repo OWNER/REPO Select another repository using the OWNER/REPO formatINHERITED FLAGS--help Show help for commandARGUMENTSAn issue can be supplied as argument in any of the following formats:- by number, e.g. "123"; or- by URL, e.g. "https://github.com/OWNER/REPO/issues/123".EXAMPLES$ gh issue list$ gh issue create --label bug$ gh issue view --web...
Now, I don’t want to explain to you each command. On the official GitHub CLI website, you can find a well-explained manual of all these commands. Instead, I’m going to show you examples of how this CLI can improve your workflow in your everyday developer’s life.
Create a PR
Let’s say you work on a brand new feature for your company or open-source project. You finished the work and want to create a PR on GitHub. Usually, you would have gone to github.com to open the PR, right? Well, now, you can do exactly the same with
gh pr create:
➜ gh pr create? Where should we push the 'feat/signup' branch? company/repoCreating pull request for feat/signup into master in company/repo? Title feat(signup): Add signup screen? Body <Received>? What's next? [Use arrows to move, type to filter]> SubmitContinue in browserAdd metadataCancel
As you can see, this command is interactive. I provided the title, the body in VS Code, and then submitted the PR in a snap.
Suppose you were to provide some metadata such as the reviewers, assignees, or labels. In that case, you could also do it by selecting
? What's next? Add metadata? What would you like to add? [Use arrows to move, space to select, <right> to all, <left> to none, type to filter][ ] Reviewers> [x] Assignees[ ] Labels[ ] Projects[ ] Milestone
See relevant pull requests
It’s common for a developer to have many tasks at once: your review is requested on a piece of code, you fix a bug while waiting for a review on one of your feature PRs. In that case, you may want to know the statuses to know your next actions:
> gh pr statusRelevant pull requests in company/repoCurrent branch#234 fix(homepage): Avatar is not shown if account created with Google [fix/avatar]- Checks pending - Review requiredCreated by you#234 fix(homepage): Avatar is not shown if account created with Google [fix/avatar]- Checks pending - Review required#224 feat(signup): Add signup screen [feat/signup]✓ Checks passing - Review requiredRequesting a code review from you#231 docs(onboarding): Add docs on how to deploy on production [docs/onboarding]✓ Checks passing
How convenient this command is. I know at a glance what’s going on with your PRs:
- Current branch: I’m working on a fix
- Created by you: My fix has some checks pending, and I didn’t get any reviews yet. I also have another opened PR that passes the checks, but I haven’t received any reviews.
- Requesting a code review from you: A PR on documentation has passed the checks and I need to give my review.
If I were to review the docs PR, I could simply type
gh pr view 231, and view the PR on the terminal or on the web using the
Waiting for Travis
Let’s say your PR is already opened and you got some review comments. You worked through your comments, pushed your code, and wanted to know if you can merge the PR. Maybe you’ve set up Travis CI, and you’re waiting for the build to pass:
> gh pr checks➜ gh pr checksAll checks were successful0 failing, 1 successful, and 0 pending checks✓ Travis CI - Pull Request 5m26s https://travis-ci.com/github/comp...
(Let’s be honest, one of our favorite tasks, as developers, is to wait for Travis, isn’t it? 😄)
If everything’s OK, you can also merge the PR right from your terminal:
gh pr merge
Testing a colleague’s changes
Developers, when reviewing code, tend to focus on the code only. It’s indeed faster, but perhaps it’s worth it to check out the changes live. It allows you to have a better vision of what the code really implies and its value.
Now, you can check out your colleague’s branch with GitHub CLI. Use the
pr checkout along with the pull request’s number, and you’re good to go:
gh pr checkout 6838
As a front-end developer, I often use it to make sure the UI changes properly work.
Note that you can find an example of this command on GitHub directly:
Your next issue
You’re maintaining an open-source project, and you want to know what’s the next thing you can work on. Then, you can browse your issues with the
> gh issue listShowing 15 of 15 open issues in testing-library/eslint-plugin-testing-library#227 [await-async-utils] false p... (bug) about 23 days ago#222 [await-async-query] Support... (help wanted) about 1 month ago#219 feature request: no-await-f... about 1 month ago#202 Support eslint fix command ... (enhancement) about 2 months ago#198 Move custom render function... (BREAKING CHANGE) about 18 days ago#187 Autogenerate configs from r... about 3 months ago:
Maybe you don’t have much time and you want to fix a bug. Then, filter them with the
> gh issue list --label bugShowing 2 of 2 issues in testing-library/eslint-plugin-testing-library that match your search#227 [await-async-utils] false positive pr... (bug) about 23 days ago#141 Lint RenderResult when returned from ... (bug) about 2 months ago
There are lot of other filtering options. Don’t hesitate to run
gh issue list --help to know more.
Someone at your company spotted a bug in production and needs to quickly ship a small fix. Let’s say its PR is the number #211. You can approve it in just two commands:
- Visualize the changes:
gh pr diff 211
- Approve the PR
gh pr review 211 --approve
Your colleague gets a fast approval and you don’t fully interrupt your workflow. I call that a win-win.
Contributing to an open-source project
At the time of writing, it’s the 2020 edition of Hacktoberfest. Maybe you want to make a contribution to open-source. Usually, that includes forking a repo:
➜ gh repo fork organization/repo- Forking organization/repo...✓ Created fork user/organization/repo? Would you like to clone the fork? YesCloning into 'repo'......✓ Cloned fork
Some maintainers label issues as
good first issue for the newcomers. Then, you can search through them from the CLI:
gh issue list --label "good first issue"
Note: if you’re considering contributing to a project? Please don’t spam them with meaningless contributions such as adding “Amazing project” next to a title or similar. Open source maintainers are working hard on their beloved repos. ❤️
Using both GitHub and GitHub CLI
As you can see, GitHub CLI is powerful and can improve your workflow. It has already become a tool I’m using every day. Approving a pull request, finding an issue on which I can work, quickly see if a build pass, it’s a real time-saver, and it has become a tool I’m using every day.
It doesn’t mean you should use only GitHub CLI as of now. Don’t forget the UI. For example, I still find it useful to do a complete review or browsing issues. Use what suits your needs best.