Learn the Basics - GitHub's CLI

September 22, 2022193 min

GitHub CLI, or gh, is a free and open source tool that enables you to use GitHub's pull requests, issues, repositories and more directly from your command line. gh is available via Homebrew by running the command brew install gh.

You are working in one of your projects, where you will create (a) an issue, (b) a branch and (c) a pull request to (d) merge changes into your main production branch. We will explore these gh commands straight from its Manual.

Creating an issue

GitHub Issues helps you to track ideas, feedback, tasks, bugs and plan for your work right where development takes place.

## Other available flags
## -a --assignee <login> // Use "@me" to self-assign
## -l --label <name> // Check your pre-defined labels

$ gh issue create --t "My new issue"  --b "Here are more details." 

## Add the web flag at the end to open the draft before submitting
## -w --web

Creating a branch to work on an issue

If you used the --web flag, you can create a branch to work on an issue directly from the issue page by clicking under Development > Create a branch. Once the branch is created, to start working, you can checkout the branch in your local repository:

$ git fetch origin
$ git checkout <branch_name>

## Can verify by running
$ git branch

This is incredibly useful and convenient because this links any pull request created for that branch, where successfully merging that PR will replace the relationship (from branch to PR) and automatically close the issue.

Creating a pull request to review your work

You finished and committed your work. now you're ready to create a PR. Pull requests (PR) lets you discuss and review potential changes before (if 'LGTM') merging them into production. I would recommend creating your PR interactively. For more information on the available flags, visit CLI Manual: PR Create

## I would recommend creating your PR Interactively
## This will give you access to nano to write better notes
$ gh pr create
? Title <title>
? Body [(e) to launch nano, enter to skip]
## After editing the body it will display as <Received>

## Once created, you can view and access the PR by running:
$ gh pr list
$ gh pr <number> --web

Merging your changes to production

Once the changes you've made on your head branch are ready to be merged into the main (base) branch, you are ready to push your code to production.

## --delete-branch: will delete the local and remote branch after merge
## --merge: will merge the commits with the base branch
$ gh pr merge <number> --body <text> --delete-branch --merge

# If no argument, the PR that belongs to the current branch is selected.

Immediately after this, (a) your issue will be marked as closed, (b) the local and remote development branch will be deleted and your (c) commit change merged into the main branch. For more information on visit GitHub's documentation: Collaborating with pull requests.