How to Use the Command 'gh' (with Examples)

The gh command is a powerful command-line interface tool developed by GitHub that allows users to work seamlessly with their GitHub repositories directly from the terminal. It offers a wide array of functionalities to manage repositories, issues, pull requests, and more, streamlining the workflow through the convenience of the command line.

Clone a GitHub Repository Locally

Code:

gh repo clone owner/repository

Motivation: Cloning a repository is often the first step in interacting with a project. It allows you to create a local copy of a GitHub repository on your machine, enabling you to work on it without requiring an internet connection. This action is essential for developers who want to explore the code, contribute to the project, or manage files locally.

Explanation:

• gh: Calls the GitHub CLI tool.
• repo: Indicates that you’re working with a repository.
• clone: The subcommand that fetches the entire repository from GitHub and makes a local copy.
• owner/repository: Specifies the owner and the repository name that you wish to clone. Replace owner with the GitHub username or organization name and repository with the repository name.

Example Output:

Cloning into 'repository'...
remote: Enumerating objects: 100, done.
remote: Counting objects: 100% (100/100), done.
Receiving objects: 100% (100/100), 1.23 MiB | 2.00 MiB/s, done.

Create a New Issue

Code:

gh issue create

Motivation: Creating issues is crucial for tracking tasks, bugs, and enhancement proposals within a project. Issues serve as a communication tool among developers and stakeholders to discuss, prioritize, and implement work items effectively.

Explanation:

• gh: Uses the GitHub command-line interface.
• issue: Specifies that the command will manage issues.
• create: The subcommand to initiate the creation of a new issue, prompting the user for details like the title and body.

Example Output:

Creating issue in owner/repository...
Title: Fix login bug
Body: The login page throws an error when the password is incorrect. 
Issue created at https://github.com/owner/repository/issues/34

View and Filter the Open Issues of the Current Repository

Code:

gh issue list

Motivation: Viewing and filtering open issues helps developers and project managers track progress, workload, and pending tasks. It allows users to quickly recognize which issues need attention and prioritize them accordingly.

Explanation:

• gh: The GitHub CLI command.
• issue: Specifies the operation involves issues.
• list: Lists all the currently open issues in the repository, displaying essential details like issue titles and numbers.

Example Output:

#34  Fix login bug       Labels: bug             2 comments
#33  Update README.md    Labels: documentation   0 comments

View an Issue in the Default Web Browser

Code:

gh issue view --web issue_number

Motivation: Opening an issue directly in the web browser is beneficial when a more detailed view or interaction with the issue is required beyond what the terminal interface offers, such as viewing comments, attachments, or editing.

Explanation:

• gh: Initiates the GitHub CLI tool.
• issue: Specifies that the command pertains to issues.
• view: Views the specified issue.
• --web: Opens the issue in the default web browser instead of displaying it in the terminal.
• issue_number: The specific issue number you want to view.

Example Output:

Opening https://github.com/owner/repository/issues/34 in your browser...

Create a Pull Request

Code:

gh pr create

Motivation: Creating a pull request is a fundamental part of the GitHub workflow, where changes are proposed, reviewed, and ultimately merged into the main codebase. This command is crucial when contributing to a project or managing team collaboration.

Explanation:

• gh: Invokes the GitHub command-line tool.
• pr: Denotes that the operation involves pull requests.
• create: Initiates the creation of a new pull request by taking changes in a branch and submitting them to be merged.

Example Output:

Creating pull request for branch-name into main in owner/repository...
? Title Fix login issue
? Body Extended explanation of what has been fixed and how
Pull request created: https://github.com/owner/repository/pull/45

View a Pull Request in the Default Web Browser

Code:

gh pr view --web pr_number

Motivation: Viewing a pull request in the web browser provides a comprehensive view of all related discussions, files changed, and merge status, which might be necessary for in-depth analysis or reviews.

Explanation:

• gh: Executes the GitHub command-line interface.
• pr: Indicates the command deals with pull requests.
• view: Views a designated pull request.
• --web: Opens the pull request in the default web browser.
• pr_number: The specific pull request number you wish to view.

Example Output:

Opening https://github.com/owner/repository/pull/45 in your browser...

Check Out a Specific Pull Request Locally

Code:

gh pr checkout pr_number

Motivation: Checking out a pull request locally is significant for testing, reviewing, or further development needs. It allows developers to test changes in their local environment and ensure everything works as expected before merging.

Explanation:

• gh: Calls the GitHub CLI utility.
• pr: Relates to pull request operations.
• checkout: Switches the current working branch to the branch of the specified pull request.
• pr_number: The identifier for the specific pull request you want to check out.

Example Output:

Switched to branch 'pr/45'
# You are now on a branch where the pull request changes are applied

Check the Status of a Repository’s Pull Requests

Code:

gh pr status

Motivation: Regularly checking the status of pull requests is workflow efficient. This command provides a summary of all pull requests, indicating which are open, merged, or closed, and helps prioritize them effectively.

Explanation:

• gh: Initiates the GitHub CLI tool.
• pr: Stands for pull requests.
• status: Displays the status of all pull requests, including which ones are pending review or already merged.

Example Output:

Current branch
  #45  Fix login issue  draft
Created by you
  #42  Implement new feature  open
  #40  Refactor codebase      merged

Conclusion:

The gh command-line tool is an invaluable resource for developers seeking to streamline their workflow with GitHub. From cloning repositories to creating issues and managing pull requests, this tool reduces dependency on the web interface, empowering users with efficient and rapid command-line interactions. Through understanding and utilizing these commands as exemplified above, you are better equipped to enhance productivity and improve collaborative processes on GitHub projects.