Create pull request from the GitHub command line

While many developers create their pull requests using the GitHub web dashboard, you can also use the GitHub command line interface (CLI) to create PRs without having to leave your terminal. This guide will cover how to create a pull request with the GitHub CLI.

Prerequisites

Before creating a pull request via the GitHub CLI, ensure you meet the following prerequisites:

• GitHub CLI installed: You need the GitHub CLI tool (gh) installed on your machine. You can download it from GitHub's official page.
• Authenticated session: Ensure that you're authenticated to GitHub via the CLI. You can login by running gh auth login and following the prompts.
• Existing repository: This guide assumes you are working with an existing repository that you can clone locally.

Step 1: Clone the repository

First, you need to have a local copy of the repository you intend to contribute to. Use the git clone command to clone the repository:

git clone https://github.com/username/repository.git
cd repository

For more detailed instructions, see this guide on cloning in GitHub.

Step 2: Create a new branch

Creating a branch in Git allows you to work on new features or fixes without affecting the main codebase. Use the git checkout command to create and switch to a new branch:

git checkout -b feature-branch

Here, feature-branch is the name of your new branch. Choose a descriptive name that reflects the nature of your changes.

Step 3: Make changes and commit them

After creating your branch, make your code changes. Once you're done, use the git add command to stage your changes and git commit to commit them:

git add .
git commit -m "Add a detailed commit message describing your changes"

Step 4: Push your branch to GitHub

To make your branch available on GitHub, use the git push command. Since this branch doesn’t exist on GitHub yet, you need to set the upstream branch:

git push --set-upstream origin feature-branch

Step 5: Create the pull request

Now that your branch is on GitHub, you can use the GitHub CLI to create a pull request. Run the following command:

gh pr create --base main --head feature-branch --title "Your PR title" --body "Detailed description of the changes"

• --base main: Specifies that you want to merge into the main branch.
• --head feature-branch: Specifies your feature branch.
• --title and --body: Allow you to add a title and detailed description to your pull request.

This command will interactively prompt you to configure additional options, such as assigning reviewers or adding labels. You can also specify these options in the command line to skip the interactive prompts.

Step 6: Monitor and modify the pull request

Once your pull request is created, you may need to monitor its status or make additional modifications based on feedback from reviewers. Use the following commands to manage your pull request:

• List pull requests: gh pr list — shows a list of pull requests in the repository.
• Check out pull requests locally: gh pr checkout PR_NUMBER — allows you to checkout a particular pull request locally.
• View pull request in the browser: gh pr view --web — opens the pull request in your web browser.

As an example here’s what you might see in your terminal when pushing a branch and creating a pull request:

$ git push --set-upstream origin feature-branch
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 12 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 362 bytes | 362.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
remote: Resolving deltas: 100% (0/0), completed with 0 local objects.
To https://github.com/username/repository.git
 * [new branch]      feature-branch -> feature-branch
Branch 'feature-branch' set up to track remote branch 'feature-branch' from 'origin'.

$ gh pr create --base main --head feature-branch --title "New feature" --body "Adding a new feature"
Creating pull request for feature-branch into main in username/repository
https://github.com/username/repository/pull/1

For further reading on creating pull requests using the GitHub command line, see the official GitHub documentation.