Hot Posts

6/recent/ticker-posts

How to level up your Git game with GitHub CLI

Types Digital Programming August 15, 2024
[Collection]

Developers love working with the tools that make sense for them. At GitHub, we understand developers want to use GitHub in various ways. This includes using GitHub from the web, or even having a lightweight web editor with GitHub.dev. Developers can experience a full editing environment on the internet with Codespaces, use GitHub integrations with various editors, such as VS Code or JetBrains, and even use GitHub Desktop or GitHub from your mobile device with GitHub Mobile. Did you know, you can also use GitHub directly from the terminal?

GitHub and the terminal

We recently showed you many Git commands you can use directly from your terminal. These commands are key, and every developer will use them when it comes to version control for your project. Not everyone, however, uses Git in the CLI. Doing so can improve your development speed and power. This is where you can become a power user of GitHub, using GitHub commands in the terminal alongside Git commands.

The GitHub CLI brings GitHub to your terminal. It allows you to have your entire GitHub workflow available from the command line. No more context switching, and more time staying in the flow: instead of working with Git on the command line and having to switch to a browser to perform GitHub related tasks, such as opening issues, reviewing pull requests, or editing repositories, you can do everything directly from your terminal. That means more time coding, and doing the thing you love ❤️.

If you’re already familiar with GitHub, and you have either a Windows, Mac, or Linux operating system (OS), then this guide is for you. Here’s how to get started with the GitHub CLI, and some of the top commands you can use for managing your projects in the way that suits you best.

How to get the GitHub CLI

To get started, download the GitHub CLI. Follow the instructions to download for Windows, Mac, and Linux on the GitHub CLI repository, or the open source documentation. Once you’ve followed the instructions to install the GitHub CLI, open a terminal, and check to see if you have GitHub CLI by running gh to check. If you are on Windows, then you might receive something like this if you have the GitHub CLI:

Want to know if you have the latest version of GitHub CLI? You can type gh --version to see what version you have installed:

Terminal showing: $ gh --version gh version 2.53.0 (2024-07-17) https://github.com/cli/cli/releases/tag/v2.53.0

Once the CLI is installed, you’ll need to authenticate with GitHub in order to continue. You can authenticate with GitHub by running the gh auth login command. You can follow the steps in GitHub CLI Docs to ensure you authenticate with the correct credentials.

Top 8 most useful GitHub CLI commands

These commands will be your bread and butter as a developer. You will use these almost every time you are working on a project.

Note that I’m working on a Windows machine, so the examples shown here will be from Windows PowerShell.

1. Create and clone repositories in your local environment

When working with any new project, you will need to create a space for your project to live. We can achieve this in just a few steps using GitHub CLI. In order to create a repository, firstly navigate to the directory where you want to create your new project, and use the command gh repo create:

Terminal showing: $ gh repo create my-awesome-project --private Created repository mishmanners/my-awesome-project on GitHub

We can then clone this new empty repository:

Terminal showing: $ cd <directory for local environment> $ gh repo clone my-awesome-project --private Cloning into my-awesome-project You have cloned an empty repository $ cd <directory for cloned project on local environment>

You can also clone any repository using gh repo clone <OWNER/REPO>. For example, use gh repo clone cli/cli to clone the GitHub repository for the CLI. Yes that’s correct, the GitHub CLI is open source 🙌.

Terminal showing: $ gh repo clone cli/cli Cloning into 'cli'... There are four lines of

Using this gh repo clone command instead of git clone helps by simplifying authentication and Git configuration, making your workflow faster.

Other useful commands for working with repositories include:

There are lots of other useful commands for working with repositories, and you can view the full list, including relevant flags, in GitHub CLI Docs.

2. Quickly view, create, and edit issues

Now that you have a new repository in your development environment, you can use the terminal to work on the project. Let’s start with issues. Issues are like tracking tasks for your project. They might be for creating a new feature, or fixing a bug in the code.

By looking at the list of issues you have, you can pick one to work on, or see an overview view of the current work assigned to the project. Use the gh issue list command to see a list of your currently open issues:

Terminal showing: $ gh issue list Showing 30 of 624 open issues in cli/cli We are showing the first 9 in the list

To see this list, you’ll need to make sure your terminal is pointed towards the repository you want to work in. For example .\cli in the above demonstration or .\my-awesome-project for the new project repository we created in the first demo.

You can create issues directly from the command line using gh issue create, and following the prompts to open an issue, and then use gh issue list to see the list of your issues for that repository, as well as gh issue view to view a particular issue:

Terminal showing: $ cd <location in local environment> $ gh issue create Creating issue in mishmanners/my-awesome-project ? Title EPIC TRACKING ISSUE for this awesome project ? Body <received> ? What's next? Submit https://github.com/mishmanners/my-awesome-project $ gh issue list Showing 1 of 1 open issues $ gh issue view 1 open # 1 EPIC TRACKING ISSUE for this awesome project opened 1 minute ago

You can then edit issues further by using gh issue edit or even try launching the notepad whilst you are creating the issue to add the body text for that issue.

Another useful command is gh issue status which shows the current status of all the open issues in a repository, and how they relate to you:

Terminal showing: $ cd <location in local environment> $ gh issue status Relevant issues in mishmanners/mish-friendly-food The terminal screen shows issues assigned to me, issues I'm mentioned in, and issues opened by me.

There are lots more useful commands for working with issues and you can find the full list in GitHub CLI Docs.

3. Checkout, review, and merge pull requests

Instead of opening GitHub.com and working with pull requests on the web, we do all this development work from the terminal. There are several useful commands when it comes to working with pull requests. Once you’ve navigated to your repository, you can view a list of open pull requests by typing gh pr list into your terminal. You’ll receive a list of all the open pull requests in your repository. This will also include any draft pull requests:

Terminal showing: $ gh pr list Showing 15 of 15 open pull requests We are showing you the top nine PRs, where some are in green and others are in gray.

Note that the pull requests shown in gray are draft pull requests. Draft pull requests are pull requests that we can create when we’re actively working on changes, but aren’t quite ready to merge those changes. Draft pull requests mean we can start collaborating without our code being completely polished. This is a new feature and you can read more about draft pull requests in our blog post.

You might also like to create a pull request directly from the terminal. We can use a combination of Git and GitHub commands to achieve this. For example, git checkout will switch you to the branch of your repository. Then, you can use gh pr create to create a pull request. You can then follow the prompts on the terminal to open the pull request.

Here’s an example of checking the list of pull requests. Use git checkout to ensure we’re on the correct branch that has the changes to merge. I can then use gh pr create to create the pull request. By following the prompts, I’m able to open a notepad to add a body for the pull request. Since I haven’t tested these changes, I want to create this particular pull request as a draft pull request. Finally, I can use gh pr list to see a list of the repository’s pull requests with the new draft pull request I just created:

Terminal showing: $ gh pr list Showing 1 of 1 open pull request in mishmanners/mish-friendly-food (the open pull request is show on a few lines here) $ git checkout translations Already on 'translations' $ gh pr create Creating pull request for translations into main in mishmanners/mish-friendly-food ? Title (Translations using GitHub Copilot) ? Body (press e to launch notepad - here we launch a note pad and make changes to the comments in the notepad. Save the notepad and it goes back to the terminal) ? What's next? Submit https://github.com/mishmanners/mish-friendly-food/pull/112 $ gh pr list We can see the new pull request made here in this list.

Here are some other useful commands to use in relation to pull requests:

  • gh pr status to see the status of PRs and how they relate to you.
  • gh pr checkout to switch to a particular branch and see information for that branch. This is super powerful. As a reviewer, you can now quickly pull down the branch and test the changes locally before approving or merging a pull request.
  • gh pr merge to merge the pull request.

View the full list of pull request related issues, including relevant flags, in GitHub CLI Docs.

4. Create and view releases for your project

When working on a project, you might like to work with the releases for that project. A release is a software package and includes release notes and binary files for other people to use. You can create a new release by using gh release create and follow the prompts to create a release for your project:

"Terminal

Use gh release list to view releases for a particular project, and use gh release view to view a project’s particular release.

5. Monitor your GitHub Actions workflows at a glance

No project is complete without GitHub Actions, and now you can manage and run your GitHub Actions from the command line. GitHub Actions is our automation platform, allowing you to automate your project from idea to production. You can build, test, and deploy your project directly from GitHub using GitHub Actions. If you get confused around what is an action vs. what is a workflow, check out our guide on the difference between a GitHub Actions, actions, and workflows.

Use gh workflow list to view a list of all your available workflows.

Terminal showing: $ gh workflow list Showing the first eight workflows here.

This list shows the workflows that the repository owner has set up. Each project will have its own type and number of workflows. Once you can see the full list of workflows available within a particular project’s repository, use gh workflow run to select and run a particular workflow.

For example, if you wanted to run the “code scanning” action above, you can use gh workflow run 1208059 to run that workflow. You’ll need to have admin rights to a repository in order to run a workflow.

Here’s an example of a repository I have access to, and how I can run a particular workflow, and see the runs of that workflow:

Terminal showing:<br /> $ gh workflow list<br /> There are three workflows show<br /> $ gh workflow run 387697565<br /> The workflow runs<br /> $ gh run list --workflow=test.yml<br /> A list of the workflows runs for the test workflow are shown.

6. Write and edit labels

Labels are an important part of effectively managing projects. They help color-code and group particular issues so we can triage and manage them correctly. You can see a list of all the labels for your repository by typing gh label list. Then use gh label create to add a new label, or gh label edit to edit a particular label:

Terminal showing: $ cd <directory for local environment> $ gh label list Showing 9 of 9 labels gh label create "needs design" Label "needs design" created in mishmanners/my-awesome-project $ gh label list Showing 10 of 10 labels (shows the new label created) $ gh label edit "needs design" --description "This issue needs design work before it can be completed" $ gh label list Showing 10 of 10 labels (shows the edited label description)

7. See your GitHub status

One of the most useful commands is understanding your GitHub status. Use gh status and you’ll be provided with a list of GitHub status as it pertains to you. This includes your assigned issues and pull requests, any open pull requests that require your review, and any other repository activity:

Terminal showing: $ gh status A list of my GitHub status is shown including assigned issues, assigned pull requests, review requests, repository activity, and mentions.

8. Add more to your GitHub CLI with extensions

We’ve shown you lots of useful commands for working with GitHub. But what if there’s something you want to do that isn’t mentioned here? Since the GitHub CLI is open source, many developers–both at GitHub and in the community–create extensions for the GitHub CLI. These extensions add additional features to your command line. You can browse all the available GitHub CLI extensions via the terminal using gh ext browse and read a brief overview of each extension does:

Terminal showing: $ gh ext browse Browsing 475 gh extensions. A bunch of GitHub CLI Extensions are shown on the left hand side, with their README descriptions on the right.

If there’s an extension that you’d like to add that functionality for your use, you can install it by using gh ext install <OWNER/REPO>.

Bonus. Help?!

What happens if you can’t remember a particular command? Use gh help to see a list of helpful commands:

Terminal showing: $ gh repo --help A list of useful commands pertaining to GitHub repositories are shown here. This list here shows usage, general commands, GitHub Actions Commands, extension commands, flags, and examples on how to the use the command.

What’s next?

Now that we’ve walked through how to use GitHub CLI from your terminal, start practicing some of these commands. If you love working in the terminal, then this will help reduce context switching and you can spend more time in the place you love—the command line.

So, what happens when you get stuck in the terminal? Yes, you can use gh help to get some useful suggestions on where to go next, but it’s often not enough, or not exactly what we’re looking for. If this is you, then GitHub is here to help. In our next blog post, we’ll teach you how to use GitHub Copilot in the CLI to get unstuck when you run into errors or can’t remember a particular command. Stay tuned.

The post How to level up your Git game with GitHub CLI appeared first on The GitHub Blog.

Using Git in the CLI can improve your development speed and power. Here are our top eight commands for using GitHub via your command line.

The post How to level up your Git game with GitHub CLI appeared first on The GitHub Blog.

Types Digital Programming

Posted by Types Digital Programming

Our TD Program is designed to provide you with the knowledge and resources you need to excel in the world of cloud computing.