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.gitcd 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-branchEnumerating objects: 5, done.Counting objects: 100% (5/5), done.Delta compression using up to 12 threadsCompressing 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-branchBranch '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/repositoryhttps://github.com/username/repository/pull/1
For further reading on creating pull requests using the GitHub command line, see the official GitHub documentation.