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.

Viewing 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.

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. 

Label

Description

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.

Collaborate on code and provide feedback

Adding and viewing comments

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 read access or higher 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.

Add comments to pull requests

To add multiple comments and tasks on a pull request

Whether you are adding comments or tasks on the pull request or directly on the diff, you can batch your comments and task together and only receive one email notification.

  1. Add your comment and/or create a task.

  2. Select the Start review button.

  3. Continue to review the PR and add any other comments and tasks you would like to be part of your review by selecting Add comment.

  4. When you are done adding all your comments and tasks, select Finish Review to submit the review.

    1. You can review your comments prior to submitting your review by selecting View all pending comments and tasks. This will open a preview of your comments and tasks.

    2. Approval status: As part of your review, you will need to select one of the approval statuses provided prior to submitting your review.

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 select Add comment now.

  • Inline - Click the '+' associated with the line in the diff you want to comment on and/or add a task to > select Add comment now. Add your comment to the text field and click Save.

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.

  • Resolve - Resolves the comment thread. You and your team may use this to ensure all comments are addressed prior to approving or merging a pull request. Resolved comment threads will be collapsed in the diff by default.

  • 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.

  • Reopen - You can always reopen a comment thread in case more action needs to be taken to get to a solution. If you need to open an outdated comment, you will need to go to the outdated comments associated with the diff and reopen the comment.

View and access 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 and access comments from the Comments dropdown list or inline with the other actions taken on the pull request in Activity on the right sidebar.

Comments dropdown

Navigate resolved, unresolved, or outdated comments associated with the diff using the Comments dropdown available above the diff header.

  1. Select the Comments dropdown. The number of unresolved comments on the diff is displayed on the dropdown.

  2. To go to a particular comment in the diff, select the comment from the dropdown list.

The list is divided into unresolved and resolved comments with the unresolved comments listed first. Outdated comments will always be labeled as such within the comments list.

Activity feed

  • 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.

Create tasks

Add one or more tasks to a comment to track required changes. Anyone with ‘Read’ permissions or higher 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.

Mark files as viewed

As a reviewer of a pull request, you can mark files you have reviewed as ‘viewed’ by selecting the Viewed checkbox on the diff (file) header. Once you have marked a file as ‘viewed’, that file will be collapsed and will remain in a collapsed state when or if you return to the pull request.

When new commits to the source branch alter any files that you've marked as viewed, Bitbucket resets the Viewed status for these files, so that it's clear you need to review these files again.

Approve a pull request

Anyone with ‘Read’ permissions or higher can approve a pull request.

To approve a pull request:

Within the pull request you would like to approve, select the Approve button in the upper-right corner of the pull request.

Additional Help