Creating pull requests in GitHub

Pull requests allow you to propose changes to a repository that can be reviewed, discussed, and, upon approval, merged by other team members. This guide will cover the process of creating pull requests in GitHub through various methods, including the GitHub web interface, command line, and the GitHub API.

What is a pull request?

A pull request is a mechanism employed by GitHub (and other version control systems) to request that changes you've made in a branch be merged into another branch in the repository, typically the main branch. PRs serve as a platform for code review, discussion, and integration of new changes.

Creating a pull request via the GitHub web interface

1. Commit to a branch:

   • Ensure your changes are committed to a feature branch in your GitHub repository. It's best practice to isolate changes to specific features or fixes per branch.

2. Navigate to the repository:

   • Go to the GitHub page for the repository where your branch resides.

3. Initiate the pull request:

   • Click on the 'Pull requests' tab and then click 'New pull request'.
   • Select the base branch (the one you want your changes to be merged into) and the compare branch (the branch that contains your changes).

4. Create the pull request:

   • Once you've reviewed the changes and are ready to propose them, click 'Create pull request'.
   • Provide a descriptive title and a detailed description that includes what changes have been made and why.
   • If the repository has templates for pull requests, fill out the required fields. (For further details on pull request templates see this guide on pull request templates in GitHub)

5. Review and merge:

   • After creating the pull request, other developers have the opportunity to review the changes, and leave feedback. Upon approval the pull request can then be merged into the base branch.

Creating a pull request via command line

Creating a pull request directly from the command line isn't supported by Git commands out of the box. However, you can use the GitHub CLI tool (gh) to manage pull requests.

1. Install GitHub CLI:

   • First, install the GitHub CLI from GitHub's official site.

2. Authenticate GitHub CLI:

   • Run gh auth login and follow the prompts to authenticate.

3. Create the pull request:

   • Navigate to your local repository and use the command:
     Terminal

     gh pr create --base main --head your-feature-branch
     
     

   • You will be prompted to enter the title and the body for the pull request. You can also specify reviewers, labels, and other options as needed.

Creating a pull request via GitHub API

For automated systems or custom integration, you might want to create pull requests programmatically using the GitHub API.

1. Obtain authentication token:

   • You need a personal access token with the appropriate scopes (like repo). Create one from your GitHub settings under 'Developer settings'. For further instructions see this guide on creating a GitHub personal access token.

2. Use the GitHub API to create pull request:

   • Send a POST request to the GitHub API to create a pull request. You can send requests to the API using curl:
     Terminal

     curl -X POST \
       -H "Authorization: token YOUR_ACCESS_TOKEN" \
       -H "Accept: application/vnd.github.v3+json" \
       -d '{"title":"Amazing new feature","body":"Please pull this in!","head":"your-feature-branch","base":"main"}' \
       https://api.github.com/repos/your-username/your-repository/pulls
     
     

For further reading see the official GitHub documentation.

Creating a pull request using Graphite CLI

You can also create a pull request on GitHub with Graphite. The Graphite CLI enhances the traditional Git workflow by introducing commands that simplify creating pull requests. With Graphite, you can create single pull requests or stacked pull requests, but this section focuses on single pull requests to build foundational knowledge.

Step 1: Install and authenticate the Graphite CLI

1. Install Graphite CLI:

   • Download and install the CLI by following the official installation guide.

2. Authenticate:

   • Run the following command to authenticate:
     Terminal

     gt login
     
     

     • You may be prompted to log in via the browser and link your account to your GitHub repository.

Step 2: Initialize the repository for Graphite

1. Navigate to the Git repository you want to use:
   Terminal

   cd ~/path/to/your/repo
   
   

2. Run the gt init command to configure the repository for Graphite:
   Terminal

   gt init
   
   

   • Select your trunk branch (e.g., main).
   • This prepares your repository to use Graphite's advanced features.

Step 3: Commit and create a branch with Graphite

Graphite simplifies the process of committing changes and creating a branch with a single command.

1. Make your changes to the code. For example:

   Terminal

   echo "console.log('New feature!');" > new_feature.js
   
   

2. Stage, commit, and create a branch using the gt create command:

   Terminal

   gt create --message "feat: Add new feature"
   
   

   • This command stages your changes, commits them, creates a new branch based on the commit message, and checks out the new branch.

3. Verify your branch creation:

   Terminal

   gt log short
   
   

   • You should see the new branch listed with the most recent commit message.

Step 4: Submit the branch as a pull request

1. Once your branch is ready for review, submit it as a pull request:
   Terminal

   gt submit
   
   

Step 5: Manage and respond to feedback

Graphite makes responding to feedback straightforward with commands designed to streamline updates.

1. Check out your branch to make changes:

   Terminal

   gt checkout
   
   

   • This command uses autocomplete, making it easy to select the correct branch without copying and pasting.

2. Make the necessary changes and stage them:

   Terminal

   echo "Fix: Updated feature implementation" >> new_feature.js
   gt modify --commit --message "fix: Address review feedback"
   
   

3. Submit the updated changes to the pull request:

   Terminal

   gt submit
   
   

Why use Graphite for pull requests?

• Streamlined commands: gt create combines staging, committing, and branch creation.
• PR synchronization: Changes in Graphite automatically sync with GitHub, allowing teams to choose their preferred interface.
• Draft or published PRs: Decide how to submit your work depending on its readiness.

For more information on Graphite’s features, visit Graphite’s pull request guide.