PhpStorm 2024.2 Help

Work with GitHub pull requests

Pull requests are used in open-source projects or in some corporate workflows to manage changes from contributors and to initiate code review before such changes are merged.

By creating a pull request, you tell others about the changes you want to push to the original repository so that the maintainers of that repository can review your changes, discuss them, and integrate them into the base branch.

Create a pull request

  1. In the main menu, go to Git | GitHub | Create Pull Request. The Pull Requests tool window opens with a pull request draft.

    Pull Requests tool window with a new pull request

    Alternatively, open the Pull Requests tool window and click Plus Create Pull Request in the top-right corner.

  2. The repository on the left is the base repository that will receive the updates.

    Click its name and select the branch to which you want to apply your changes.

    Base repository popup
  3. The repository on the right is the head repository with the changes that will be added to the base repository.

    Click its name and select the branch that contains the changes you want to apply.

    Head repo popup

    If you have a project that uses multiple remote repositories, you can change the head repository in this popup as well.

  4. In Changes from, select the commits you want to include in the pull request.

  5. Double-click the name of any file to open the Diff view and review the changes you are about to submit.

  6. Specify the name for your pull request in the Title field, and, optionally, provide a description of the changes to be applied through your request.

  7. Optionally, add reviewers, assign your pull request to someone, or add a label to your pull request.

  8. Click Create Pull Request.

    If you are not yet ready to push your pull request, you can save it as a draft.

    • Click Chevron Down next to the Create Pull Request button.

    • In the menu that opens, select Create Draft Pull Request.

    Your pull request will appear in the GitHub repository as a draft. You can come back to it later by choosing Git | GitHub | View Pull Requests in the main menu.

If you have a pull_request_template.md file, PhpStorm should add the template description to your pull requests. For more information about templates, refer to GitHub documentation.

Manage incoming pull requests

If you are a project maintainer, and you have a GitHub remote configured for your project, you can view and manage incoming pull requests directly from PhpStorm.

To view incoming pull requests, select Git | GitHub | View Pull Requests in the main menu.

GitHub Pull Requests tool window

Use the Pull Requests tool window to:

  • Filter requests by state, author, label, assignee, and review status.

  • Jump to a pull request on GitHub: select a pull request and choose Open Pull Request in Browser from the context menu.

  • View diff between the suggested changes and the base revision: click the name of a pull request, select a file, and double-click it or press Ctrl+D.

  • Create a local branch based on incoming changes: open a pull request, click the branch with incoming changes, and choose Checkout 'branch name' in the context menu.

    Checkout branch with incoming changes
  • Investigate branch-related changes in the Log tab of the Git tool window: open a pull request, click the branch with incoming changes, and choose Show 'branch name' in Git Log in the context menu.

    This will help you navigate the code related to this pull request, make sure the project builds and the tests pass.

  • Resolve merge conflicts: if the branch in an incoming pull request has merge conflicts, you can resolve them right from the Pull Requests tool window either by creating a merge commit from the target branch or by rebasing onto the target branch.

    Option to resolve merge conflicts

To make sure you always have the latest information about the pull requests, press Ctrl+F5. Alternatively, right-click the list of pull requests and select Refresh List.

Review a pull request

When there are changes that require your attention, a white dot marks the Pull Requests tool window and the unseen pull requests are marked with blue dots.

A blue dot on the pull requests tool window icon
  1. In the main menu, go to Git | GitHub | View Pull Requests.

  2. In the list of pull requests, select the one you want to work with and double-click it.

    PhpStorm opens an overview of the selected pull request.

    Tab with an overview of the selected pull request
    • Next to the title, there is the pull request number. Click it if you want to open the pull request on GitHub.

    • Click the View Timeline button to open the pull request timeline.

    • To filter the list of changed files, select the commit you want to investigate in Changes from.

    • Right-click any file to open the context menu for this file.

    • In case a reviewer has left any comments or suggestions, there is a counter with the number of comments in the list of files.

  3. Click the branch with incoming changes and choose Checkout 'branch name' in the context menu to start the review mode.

    Checkout branch with incoming changes
  4. Select the file you want to investigate, right-click it and select Jump to Source F4 from the context menu.

    In the file that opens, pink markers in the gutter indicate the changes and the comments that are available for review.

    Clicking the comment icons in the gutter will hide and open the comments.

    Changes and comments in the review mode

    Clicking the pink markers reveals a popup displaying the original code.

    Review mode - view differences
  5. Hover over the gutter and click or press Ctrl+Shift+X to leave a comment.

    For suggestions, add your version of the code wrapped in a Markdown code block with the suggestion specified as a language.

    ```suggestion Your suggestion for this code line ```
    Comment field with a suggestion
    • Select Add Single Comment to post a comment immediately and get other reviewers notified.

    • Select Start Review to add multiple comments.

      Before you submit your review, your comments are marked Pending, and you can edit or delete them.

  6. To place a high-level comment on a pull request as a whole, open the timeline view of this pull request.

  7. When you are ready to finish the review, click Submit in the pull request overview.

    After clicking submit, three options appear

    Alternatively, open the branches popup and click Submit Review.

    Select one of the possible outcomes:

    • Approve: to approve merging changes.

    • Request changes: to submit feedback, a pull request author must apply the suggested changes before merging.

    • Comment: to submit a comment without an approval.

View and apply the suggested changes

If the maintainers of the original repository left comments or made suggestions with regard to your changes, you can view and apply them directly from PhpStorm.

  1. In the main menu, go to Git | GitHub | View Pull Requests.

  2. In the list of pull requests, select the one you want to work with and double-click it.

    PhpStorm opens an overview of the selected pull request.

  3. Double-click a file to view the suggested changes and comments.

  4. You can resolve a comment, reply to it, or leave your reaction.

    GitHub review comment
  5. If the reviewer has left a suggestion, you will see the diff between your code and suggested one and can either Apply locally (applies a patch to the working copy) or Commit (opens a commit message pop-up).

    GitHub suggested change apply locally
  6. After you finished working on the pull request, you can re-request review, merge pull request or close it.

Merge or close a pull request

After submitting your review and solving all the issues, you can merge or close the pull request.

  1. In the main menu, go to Git | GitHub | View Pull Requests.

  2. In the list of pull requests, select the one you want to work with and double-click it.

  3. At the bottom of the overview, there is a button with merge options that differ depending on the stage of the review process.

    Pull request overview with merge options
    • If you have approved the updates after your review, you can merge the pull request by clicking Merge.

      For more merge options, click the Down arrow and select Squash and Merge to squash the commits with your changes into one before merging them or Rebase to rebase the commits from the pull request branch and add them to the base branch.

    • Click More and select Request Review if you need another opinion on this pull request or Close Pull Request if you do not want to merge it.

    • If you are ready to merge the pull request without submitting your review, in the pull request overview, click More | Merge Review and select Merge, Squash and Merge, or Rebase.

      Merge options available before submitting review
Last modified: 23 September 2024