Out of the beta, GitHub has just released GitHub CLI 1.0.
GitHub CLI (Command Line Interface) is a free and open-source program that brings GitHub to your terminal and will help you to easily and seamlessly work with GitHub from the command line. With the help of numerous ‘gh’ commands, GitHub CLI will help you to manage GitHub Repositories, Pull Requests, Issues, Releases and Reviews from the terminal itself (where you already work with the “git” commands). So, no need to open browser in between. This will help you to focus on your scripting/ GitHub workflows by reducing context switching from terminal to browser and vice-versa.
GitHub CLI Installation
Installing GitHub CLI in your system is a very easy process. Since I am using Windows, I downloaded the Windows Installer package (.msi) from the official site https://cli.github.com/ and installed it in my system following the standard installation process. You can also download it using Chocolatey and Scoop package managers.
For MAC, run the Home brew command: brew install gh and for installing in various Linux distributions, you can refer to the page: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
To check successful installation in Windows, run the command: gh –version
(Note: There is an unofficial GitHub tool ( hub – https://github.com/github/hub ) which also brings GitHub to the terminal but the difference is that with a fundamentally different design, “gh” is GitHub- official standalone tool, whereas “hub” acts as a proxy to git).
A Step-by-Step working with the “gh” commands
Let’s now start working with the GitHub CLI commands and you will see how easy it is to perform the actions from the terminal. For demo purpose, I will be using my GitHub account ( https://github.com/sumon-dey ).
Authentication and Configuration Setting
First, we need to authenticate ourselves with the GitHub host using the command “gh auth login”. It will prompt us to choose from the Enterprise Server or the non-enterprise version. After selecting GitHub.com, it will ask to authenticate using our default browser or using authentication token. Once we select browser, it will ask us to open the browser, paste the generated one-time code there, authorize and enter GitHub credentials to authenticate.
Once it is done, we will be asked to select default git protocol (between “HTTPS” and “SSH”).
We can check the information regarding the authentication state using the command: “gh auth status” and also refresh the stored authentication credentials using the command: “gh auth refresh”.
To logout from the GitHub host, we have to run the command: “gh auth logout”.
To set our preferred “gh” configuration, there are a set of commands:
gh config set editor [editor] (To set our preferred editor. On Windows, it is by default “Notepad”)
gh config set git_protocol [ssh/https] (To set our preferred git protocol. Default is “https”)
gh config set prompt [enabled/disabled] (To disable interactive prompts. Default is “enabled”)
We can view the config values using the command: “gh config get <key>”. For example:
“gh config get git_protocol” will display “https” for me.
With authentication done and configs set, let us now explore how to create and manage Repositories.
Creating and Managing GitHub Repositories
We can create a GitHub repository from the terminal using the command: “gh repo create”.
Examples:
gh repo create (This will create a new GitHub repository under our account using the current local directory name)
gh repo create new-project (This will create a new repository with a specific name “new-project”)
gh repo create owner/new-project (This will create a new repository “new-project” under the account “owner” ).
We can use several flags with the command to perform specific operations e.g. use “-d/ –description <Enter the repository description here>” to provide description of the repository.
I am creating a new remote and local repository with the name “GitHubCLITest” using the command: “gh repo create GitHubCLITest” from the terminal (after moving to the location where I want to create the local repository). We can select whether the repository should be “Public”, “Private” or “Internal”.
Next, I will add and push a README file and a text file to the remote repository using the usual “git” commands:
echo This is README > README.md
echo Inside the sample text file > SampleTextFile.txt
git add –all
git commit –m “Initial Commit”
git push –u origin master
To view the description and the README of the remote repository, run the command: “gh repo view GitHubCLITest”.
Also, we can clone this repository in our local by running the commands:
gh repo clone sumon-dey/GitHubCLITest (using owner/repo)
gh repo clone https://github.com/sumon-dey/GitHubCLITest (using the remote repository url)
To create a fork, run the commands:
gh repo fork (This creates a fork of the current repository)
gh repo fork sumon-dey/GitHubCLITest (This creates a fork of the specified “GitHubCLITest” repository)
Creating and Managing Issues
Probably the most interesting feature of GitHub CLI is creating and managing issues for a project. To create a Github issue for the project, we have to follow the below syntax:
gh issue create [flags] where flags can be:
-a, –assignee <userid> (To assign people by their userid)
-b, –body <string> (To supply a body to the issue. It will prompt for one otherwise)
-l, –label <labelName> (To add labels to the issue)
-m, –milestone <name> (To add the issue to a milestone by name)
-p, –project <name> (To add the issue to projects by name)
-t, –title <string> (To supply a title to the issue. It will prompt for one otherwise)
-w, –web (This will open the browser to create the issue)
Let us create two new issues for the project “GitHubCLITest” by running the following commands:
gh issue create –title “There is a bug” –body “Need to fix the bug asap”
gh issue create –label “bug,help wanted”
We can list the created issues using the command: “gh issue list”. We can also filter the result by label, assignee, author, limit, mention, milestone and state (open/closed).
The “gh issue status” command can be used to display the status of the relevant issues and “gh issue view {<number> | <url>}” to display the Title, Body and other information about the mentioned GitHub issue.
Closing and reopening the issues are considerably straight-forward with the usage of the commands “gh issue close {<issueNumber> | <url>}” and “gh issue reopen {<issueNumber> | <url>}” respectively.
Dealing with Pull Requests (PRs)
Handling of Pull Requests have also been made simple using the CLI.
Let us create a new branch (e.g. dev), switch to it by using the command “git checkout -b dev”, make some changes in the “SampleTextFile.txt” file, and perform “git add”, “git commit” and “git push” operations to push the change to the remote repository “dev” branch. Now to create a PR to the “master” branch, we run use the command:
gh pr create –title “The bug has been fixed” –body “Everything should start working again.” –reviewer sumon-dey
You can see that the PR got created successfully in remote.
Now, if you are in “master” or any other branch in your local and you want to checkout to the branch from where the PR has been raised, you can run the command (using the PR number, URL or branch name):
gh pr checkout {<number> | <url> | <branch>}
To view the changes in the PR, run the command (using the PR number, URL or branch name):
gh pr diff [<number> | <url> | <branch>]
To view all the raised PRs, use “gh pr list”. You can filter it by using flags like the following:
gh pr list –limit 2
gh pr list –state [open/closed]
To check the status of the relevant PRs, use “gh pr status”
Run “gh pr view [<number> | <url> | <branch>]” to display the title, body, and other information about the PR. To add comment to the PR, use the command “gh pr review 3 –comment -b “<Your comment here>””. To approve any PR, use “gh pr review 3 –approve”
Run the command “gh pr close {<number> | <url> | <branch>}” to close the PR using PR number, URL or branch name and use the command “gh pr reopen {<number> | <url> | <branch>}” to reopen the PR using PR number, URL or branch name.
Setting Releases and Aliases
Setting releases to your project using GitHub CLI is super-easy. You just need to use the following command syntax:
gh release create <tag> [<files>…]
Example: I am using the command “gh release create v1.0.0 -F changelog.md” after adding the “changelog.md” file in my local directory. This file is supposed to contain the release notes for the release v1.0.0.
Run the commands “gh release list” to view all the releases and “gh release delete <tag>” to delete a particular release.
One of the finest feature of the GitHub CLI is “alias”.
We can use “gh alias” to create gh command shortcuts or to compose multiple gh commands.
For example, run the command “gh alias set pv ‘pr view’”.
After this, if we want to view any PR, we can simply use the alias “pv” like below:
gh pv 3
The will display the title, body, and other information related to the Pull Request #3.
If you want to view all the created gh aliases, run the command “gh alias list” and to delete a particular alias, use “gh alias delete <aliasName>”.
So that’s it for today!!
Hope you enjoyed this new feature from GitHub and are looking forward to use it in your projects. Don’t forget to let me know whether you like this capability or not. You can reach out to me in LinkedIn/ Twitter. Cheers!!