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...
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?
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
pr. Let's interact with those.
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.
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
nanoto add the text, which I did).
- Then either Preview in the browser, or Submit.
And you can see this issue was created:
I went ahead a created a few more issues in order to test the list command.
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?
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?
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:
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.
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
$ 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.
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?
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?
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:
Is that all there is? Is there any more?
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.
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!