Review code in a pull request

Code review is an integral part of the pull request process, as well as the development process as a whole, and brings the following benefits to your organization and team:

  • Knowledge sharing — Because all code is reviewed by someone knowledgeable, it gives more developers a chance to work on something new and get feedback from others.

  • Quality assurance — Even experienced developers are always learning and could use a few extra eyes on their code to ensure high quality, error-free work.

  • Mentorship opportunity — New users who have just started delving into the codebase can learn lots from the feedback more seasoned users can provide.

Reviewing code in a pull request has two parts: 1) looking at the changes made and comparing it to the original code and 2) adding comments and feedback to start a discussion about code. For more details about what it means to be a pull request reviewer, see Reviewers in Pull requests and code review.

Looking at file diffs

Each pull request shows a diff of each file to compare the updates made to the repository and the repository or branch where the author wants to merge. 

Bitbucket uses git diff ...

A three-dot diff is a comparison between the commit where the feature branch was last synched with the destination branch and the most recent version of the feature branch.

A two-dot diff is the direct comparison of two committish references such as SHAs.

Setting your default pull request settings

  1. Access the pull request.

  2. Select the Settings button located in the upper-right corner of the pull request.

  3. Update your pull request settings.

  4. Click Save.

Pull request settings

  • Diff view - Set your default diff view preference to either unified or side-by-side.

  • Show - Select the various options below to display them within your pull request

    • Whitespace changes - Enable to show any changes in the file that involve spaces and tabs from the diff view, by default.

    • Word diff - Enable to display a darker shade of color on lines that have been updated or changed.

    • Color accessibility - Enable to change the background color of the diff to more visually accessible colors for people with color blindness. 

    • Annotations - Enable to display annotations by default in any pull requests.

  • Load files

    • All at once - Enable to display all the files in the pull request by default.

    • Individually - Enable to individually display files in a pull request, by default, regardless of size.

  • Tab size - Select a default size for tabs from the dropdown.

  • File view - Select how your files will be displayed, by default, on the right sidebar in a pull request.

    • Tree - Displays the files in a hierarchical view.

    • List - Displays the files as a list.

In the new pull request experience, we’ve added the Load files individually setting to your Pull request settings. When enabled, any pull request you view will display files individually regardless of the size of the pull request. When disabled, only pull requests with 8,000 or more lines will display files individually - this is to help optimize the loading process and ensure the files are loaded and displayed successfully.

Setting viewing preferences for each file

From each file, you can set the following viewing preferences from the More options... dropdown menu which can be accessed by clicking the More options... (meatball) button in the upper-right corner of the file. 



View side-by-side

Compares the code changes in two columns. The left column (prior version) visually indicates the original set of code and the right column (new version) visually indicates the updates.

View entire file

Opens the entire file in a separate modal which allows you to view the entire file and make comments throughout.

Open in source

Opens the file in the Source view. You'll see the full file and can make edits from Bitbucket.

Add comment

Adds a comment to the file in the pull request. For other ways to comment on a pull request, see Adding comments.

Collapse all files

Collapses all the files in the diff view.

Expand all files

Expands all the files in the diff view.

If you have not opted in to the new pull request experience, these settings will be located under Files changed on the Overview tab, you have a unified diff that shows the changes in one column by default.

Discussing code and giving feedback

Comments and discussion are a large part of the code review process. As authors and reviewers comment and reply to the discussion, the author might push additional commits until the pull request is ultimately approved.

Anyone with write access to the repository can comment on a pull request. Pull requests have 3 different levels of comments:

  • At the pull request as a whole

  • On individual files

  • On individual lines of code

No longer see an inline comment that was there previously?

Unless a user deleted the comment, it may still be there! When the content of a line gets removed, the comment becomes outdated. When this is the case, look for a button at the top of the file diff with a number. Clicking this button should reveal all comments on previous versions.

Adding comments

Anyone with write access to the repository can comment on a pull request. 

To add a comment at each level:

  • Pull request – Under Comments on the pull request, click in the Add a comment text field. Add your comment and click Save.

  • File - Click the More optionsbutton in the upper-right corner of the file > click Add comment. Add your comment to the text field and click Save.

  • Inline - Scroll the mouse pointer over (or tab to) the line of code where you would like to leave a comment > click on the icon that is displayed between the line number and the line of code. Add your comment to the text field and click Save.

If you have not opted in to the new pull request experience, below are the ways in which you can leave comments on a pull request.

  • Pull request — Under Comments on the Overview tab, click the text field with What do you want to say?

  • File — Click the Comment button above the file diff.

  • Inline — Click the Add a comment to this line button next to the line.

To format your comments:

Use the WYSIWYG editor toolbar.

To mention another user:

You can mention another user by entering the @ symbol and typing / selecting that user's name.

To take action on comments:

You've got links below the comment that gives you some options:

  • Reply - Keeps the conversation going by opening another comment field.

  • Edit - Reopens the comment field so you can make your updates and click Comment again. You can only edit your own comments.

  • Delete - Permanently removes the comment from the pull request. Deleting a comment also removes it from the Activity.

  • Like - Click to like the comment.

  • Create task - Click to create a task for yourself or someone else who is a reviewer on the pull request.

Viewing and accessing comments on pull requests

You can always view comments on a pull request or inline with the file or a specific line of code, but you can also view comments inline with the other actions taken on the pull request in Activity on the right sidebar.

  • Click on the link associated with the comment to be taken to the comment in the diff file. 

  • You can filter by My comments and All comments on the Activity feed.

  • Outdated comments open in a new modal.

Creating tasks

Add one or more tasks to a comment to track required changes. Anyone can create a task from a comment, not just the comment creator. Tasks give pull request authors a list of action items that they need to complete as part of their code updates.

Repository admins can set a merge checklist item that requires all tasks to be resolved before the pull request is merged.

Reviewers can...

Authors and repository admins can...

  • Create a task

  • Resolve existing tasks

  • Edit their own tasks

  • Delete their own tasks

  • Edit any task

  • Delete any task

To create a task:

At the comment level: If the exact text you want to use for a task is in the comment, highlight the text and click Create task. Otherwise, click Create task under the comment, enter the task description, and click Save. These comments are contextual, so when you click on the link icon associated with the task in the right sidebar Tasks list, the comment will be highlighted on the pull request.

At the pull request level: Click on Create a task at the bottom of the Task card on the right sidebar. Type or add the task to the text field. Press Enter (Return) to save the task.

To see a list of tasks in the pull request:

Tasks are listed in the Task panel on the right sidebar. You can also find tasks listed in context in the Activity on the right sidebar.

If you have not opted in to the new pull request experience, below are the ways in which you can create and view tasks on a pull request.

  • Pull request — Under Comments on the Overview tab, click the text field with What do you want to say?

  • File — Click the Comment button above the file diff.

  • Inline — Click the Add a comment to this line button next to the line.

Viewing tasks on pull requests

Look for the tasks link in the meta-data section on the right side, for example: 2 open tasks or All tasks resolved. Click that link to review all the open and resolved tasks. You'll only see this option if the pull request has tasks.

Additional Help