Exploring the preview release of GitHub CLI

February 5, 2020 - 6 minutes read - 1264 words

GitHub have recently released a preview version of their CLI (Command Line Interface) to enable you to interact with GitHub from your favourite terminal.

Although I use VS Code as my code editor, which has built in Git support, I still favour using GitHub desktop for handling all things Git related; repos, branches, commits and creating pull requests. However, it would be create to not have to run two GUI’s and handle everything from within VS Code via the built in terminal. So let’s dive in…

Installation

The CLI can be installed very easily. As I’m on a Mac, I did:

$ brew install github/gh/gh
$ brew update && brew upgrade gh

and once it’s finished you should see a message like:

Already up-to-date.
Warning: github/gh/gh 0.5.4 already installed

Sweet! Now, what can we do with this CLI?

The Interface

As with any CLI, there should be a help command to show you what the interface provides. Let’s check that out:

$ gh help
Work seamlessly with GitHub from the command line.

GitHub CLI is in early stages of development, and we'd love to hear your
feedback at <https://forms.gle/umxd3h31c7aMQFKG7>

Usage:
  gh [command]

Available Commands:
  help        Help about any command
  issue       Create and view issues
  pr          Create, view, and checkout pull requests

Flags:
      --help              Show help for command
  -R, --repo OWNER/REPO   Select another repository using the OWNER/REPO format
      --version           Show gh version

Use "gh [command] --help" for more information about a command.

So it looks like the only available commands are issue and pr. Let’s interact with those.

Issues

Let’s check out what the issue interface looks like:

$ gh issue help
Work with GitHub issues.

An 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".

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

Global Flags:
      --help              Show help for command
  -R, --repo OWNER/REPO   Select another repository using the OWNER/REPO format

Use "gh issue [command] --help" for more information about a command.

Let’s try to create, list, get the status and view some issues.

Create issues

Let’s create an issue in the repository marcusturewicz/github-cli-explore.

First, clone the repository and go into that directory.

Now that we’re in the repository directory, let’s run the issue create command and follow the prompts:

$ gh issue create

Creating issue in marcusturewicz/github-cli-explore

Notice: authentication required
Press Enter to open github.com in your browser... 
Authentication complete. Press Enter to continue... 

? Title My first issue with GitHub CLI
? Body <Received>
? What's next? Submit
https://github.com/marcusturewicz/github-cli-explore/issues/1

You can see that I had to:

Login to GitHub via the browser
Create an issue title
Add an optional issue body (it allows you to open nano to add the text, which I did).
Then either Preview in the browser, or Submit.

And you can see this issue was created:

Issue shown in browser, created with GitHub CLI

I went ahead a created a few more issues in order to test the list command.

List Issues

Let’s list the issues in the repository:

$ gh issue list

Issues for marcusturewicz/github-cli-explore

#3  My third issue with GitHub CLI   
#2  My second issue with GitHub CLI  
#1  My first issue with GitHub CLI

You can see that each issue is shown from oldest to newest.

That’s cool, but what are the status of those issues?

Status of Issues

Let’s check the status of the issues:

$ gh issue status

Relevant issues in marcusturewicz/github-cli-explore

Issues assigned to you
  There are no issues assigned to you

Issues mentioning you
  There are no issues mentioning you

Issues opened by you
  #3 My third issue with GitHub CLI about 3 minutes ago
  #2 My second issue with GitHub CLI about 3 minutes ago
  #1 My first issue with GitHub CLI about 9 minutes ago

Now that is a bit more information, but what if I want to see the full detail in the browser?

View Issues

Let’s view the second issue in the browser to get the full detail:

$ gh issue view 2
Opening https://github.com/marcusturewicz/github-cli-explore/issues/2 in your browser.

Which takes me to:

Alt Text

Pull Requests

Let’s check out what you can do with Pull Reqeusts:

$ gh pr help
Work with GitHub pull requests.

A pull request can be supplied as argument in any of the following formats:
- by number, e.g. "123";
- by URL, e.g. "https://github.com/OWNER/REPO/pull/123"; or
- by the name of its head branch, e.g. "patch-1" or "OWNER:patch-1".

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

Global Flags:
      --help              Show help for command
  -R, --repo OWNER/REPO   Select another repository using the OWNER/REPO format

Use "gh pr [command] --help" for more information about a command.

Looks very similar to Issues. Let’s interact with it.

Create Pull Request

Firstly, I’ve create a branch called first-pr and edited the README.md. I’m also currently on the first-pr branch. Let’s use gh to create a PR from first-pr into master.

$ gh pr create

Creating pull request for first-pr into master in marcusturewicz/github-cli-explore

? Title My first PR with GitHub CLI
? Body <Received>
? What's next? Submit
https://github.com/marcusturewicz/github-cli-explore/pull/4

This was the same process as creating an issue.

I went ahead a created a few more PR’s in order to test the list command.

List Pull Requests

Let’s list the PR’s in the repo:

$ gh pr list

Pull requests for marcusturewicz/github-cli-explore

#6  My third PR with GitHub CLI   third-pr
#5  My second PR with GitHub CLI  second-pr
#4  My first PR with GitHub CLI   first-pr

How about their status?

Status of Pull Requests

Let’s check the PR statuses:

$ gh pr status

Relevant pull requests in marcusturewicz/github-cli-explore

Current branch
  #6  My third PR with GitHub CLI [third-pr]

Created by you
  #6  My third PR with GitHub CLI [third-pr]
  #5  My second PR with GitHub CLI [second-pr]
  #4  My first PR with GitHub CLI [first-pr]

Requesting a code review from you
  You have no pull requests to review

What about more details?

View Pull Requests

Let’s view the second PR:

$ gh pr view 5
Opening https://github.com/marcusturewicz/github-cli-explore/pull/5 in your browser.

Which takes me to:

Alt Text

Is that all there is? Is there any more?

Checkout Pull Requests

An additional feature of the PR interface is being able to checkout PR’s. I went ahead and created a PR in the browser on github.com.

Let’s checkout this PR:

$ gh pr checkout 7
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.
From https://github.com/marcusturewicz/github-cli-explore
 * [new branch]      pr-browser -> origin/pr-browser
Switched to a new branch 'pr-browser'

I am now on the branch that is attached to the PR.

Summary

GitHub have released a CLI that is in preview. It allows you to interact with issues and pull requests currently. It is therefore quite limited and I wouldn’t recommend moving all of your Git activity over to it right now, but do try it out. I’m going to keep an eye on it and see where it gets to. They are also very keen to get your feedback, so don’t hesitate if something doesn’t work or you think there is a feature it needs, log an issue on the CLI - it’s open source!