This repo is intended as a demonstration for common Github Command Line Interface (CLI) uses, and covers how to install the CLI, checking out someone else's PR, creating issues and PRs, making a new repo, and cloning an existing repo. This demo assumes some familiarity with git and github; If you are unfamiliar with these tools, I suggest following the git novice lesson from Software Carpentry.
Do not fork or clone this repo before starting (that will be covered in the demonstration).
I am by no means an expert with this tool, but I hope you can integrate it in to your workflow with my rudimentary example. This is based on (by based on I mean I copied a lot of the text I wrote and added snarky comments like this) a repo I made several years ago, you can find it here.
1. Installing the command line interface
Follow the existing guide to install the CLI.
You may also have to setup
SSH keys or some other form of authentication
before this process works, but it's likely that if you
already use git and github on your machine you'll be
good to go.
2. Clone the repo
Using your command line, navigate to the place where you store your .git repositories, and run
gh repo clone gh_cli_test
This will clone the example repository to where you
are at in the command line. This isn't how I
typically clone repositories, but it is something
you can do so I wanted to highlight it. I haven't done any sort of investigation into how this method of cloning is different other than the fact that you only need the repo name, which is pretty nice now that I think about it... maybe I'll start using this feature more.
3. Enter the repo
cd gh_cli_test
Yeah, that's seriously a whole subsection in the readme I made years ago. I guess points for thoroughness?
4. Find out what issues and PRs there are
Ok, we're back to useful steps. These two commands are so helpful!
gh pr list
and
gh issue list
These commands generate a list of the issues or PRs that are active in the repo, and gives you their name, number, who made them, and what branch they are coming from in that person's fork. The issue command should result in something like:
Showing 1 of 1 open issue in nsryan2/gh_cli_example
#2 I found a bug about 1 year ago
5. Check out Greg's PR
gh pr checkout 1
I use this command all the time. Working with others on code stored in GitHub means reviewing code from your collaborators, and this command will make a branch with the contents of the PR on your machine so that you can review/use it on your machine. You do need to know the number of the PR, but that's what the previous command is for!
6. Creating an issue
My next most used command for the interface has to be this one. You can create an issue directly from the command line.
gh issue create -a"@me" --title "Bug 4” --body "Nothing works"
There are other tags you can add to the base command of issue create, and my favorite is `--web`.
gh issue create --web
Where, instead of typing out the issue in your command line, it opens a new issue on GitHub for you to input your problem. This is particularly useful for the repositories I use that have issue templates.
7. Create a new PR
To do this, you'll need to be on a branch other than main.
git checkout -b bug_fix
Now try:
gh pr create --assignee “nsryan2” --title "The new new new bug is fixed" --body "Everything works again"
This will create a PR to the GitHub repository and and assign me to it.
8. Creating a new repo
The final one we'll go over in this demo is creating a new repository. NEVER CREATE A GIT REPO INSIDE AN EXISTING GIT REPO cd ..
Ok, with that out of the way, run something like (you'll have to change the name of the repo to something that doesn't exist).
gh repo create new_repo
9. Other commands
This is by no means an exhaustive list of the commands you can do with the cli, you can find more in the gh manual!
