Skip to end of metadata
Go to start of metadata

A pull request has source code that comes from one repository (fork or branch) into another. When a pull request originates in a branch of your repository, it is commonly called "a pull across branches." You can incorporate a pull request into your repository using Bitbucket. You can also incorporate a request by pulling the code manually into your local repository and pushing the resulting repository back to Bitbucket.

If a pull request conflicts with your repository, you must manually pull the code to your local repository and resolve the request there. You resolve the conflicts locally by merging or whatever other means works best. Then, push the changes back to Bitbucket. After the push, Bitbucket shows the request as accepted. Pulling a request locally is also a means for evaluating a code change before accepting the change.

On this page:

Make sure you understand the pull request settings

A pull request has a source and a destination repository. The source is the repository where the changes reside. The destination repository is the repository into which you want to pull (merge) your changes. Both the source and destination also have a branch () designation:

While you cannot change the source repository, you can specify a branch on the source. On the destination end, you can specify both the destination repository and the branch.

If you are pulling a request across branches, you can have the option to close the branch when your request is merged. Whether you have this option depends on whether the repository is Git or Mercurial. Mercurial repositories always have this option. Git repositories have this option if the repo administrator allows it; Otherwise, the option is greyed out.

If you elect to close a branch after the pull request, the system closes the branch when the request is accepted. When a branch is closed, it no longer appears in the list of branches. 

Compare before issuing a request

Before creating a pull request, you should compare your outgoing requests to the destination repository. This tells you how much the destination repository changed while you worked on your fork or branch. You do this by comparing incoming changes.It is good practice to make sure that there are no incoming changes before you make your pull request.

If there are changes what do you do? It depends on your project workflow. For example, if you are working on a team your project workflow might require you to merge and test incoming changes before sending your outgoing changes back to the destination. To compare your source to the destination, do the following:

  1. Navigate to the repository with the changes.
  2. Press the Compare button.
    The system displays the Compare page. 
  3. Adjust the Source and Destination values so they match the pull request you anticipate making.
  4. Press Incoming to see how the destination has changed since you've been working.
    If there were no changes on the destination repository, the dialog reports:
    There are no changes.
    If there are changes, the system provides you with some helpful tips for merging them into your local repository. 

Request the destination repo owner pull your changes

To create a pull request, do the following:

  1. Navigate to the repository with the changes.
  2. Press the Pull Request button.
    The system displays the request form.
     
  3. Complete the form as appropriate for your request.
  4. Press Create pull request.
    The system opens your latest request on the Pull Request page of the original repository
  5. To see the list of all the pull requests against this repository, click Pull Requests in the navigation bar. 
    The system also sent a notification email to your account Inbox.
  6. Go ahead and open your account inbox avatar > Inbox.
  7. Locate and review the pull request email (it should be near the top).
  8. Adjust the Source branch if necessary.
  9. Adjust the Destination repository or branch if necessary.
  10. Enter a Title and Description for your pull request.
  11. Press Create pull request.

Accepting a pull request without Conflicts

Only a user with write permissions on the destination repository can accept or reject a pull request. Any user with read permission in a repository can review the open, accepted and rejected pull requests. The following procedure illustrates the steps in accepting a pull request:

  1. Go to your repository.
  2. Click Pull Requests in the navigation bar. 
    A list of incoming pull requests under the Open context. 
  3. Click a pull request on the list.
    The pull request details appear and the view defaults to the Diff context. You can also view the Commits or the comment Activity on the request.
  4. Examine the request using the various contexts..
  5. If you decide that you want to merge the fork into your own repository, click Merge.
  6. Confirm the action if prompted. 
    Bitbucket merges the changes into your repository, all on the Bitbucket server.
Icon

If an Update pull request button appears by a request this means that the fork changed after the pull request was sent. You can click Update pull request to apply those changes to the pull request. Or, you can accept and pull what is in the request alone.

Resolving a pull request with conflicts

When it detects conflicts in a pull request's incoming code, Bitbucket cannot automatically accept and merge. When this happens, Bitbucket notifies you and instructs you how to proceed:

To resolve these kinds of conflicts you pull the changes to your local repository and resolve them there. 

Manually pulling requests to your local system

Sometimes it is a good idea to use a workflow where you test a changeset on your local system before accepting a pull request. You can do this with any pull request. The typical workflow is this:

  • Receive a pull request in Bitbucket.
  • Update your local repository with the incoming changeset.
  • Investigate and/or test the change set.

If you the change set is good, you merge it into your local repository. You may have to resolve some conflicts. Then, you push the local repository back to Bitbucket. Back on Bitbucket, the pull request is marked as accepted in the Pull requests tab. If you don't like the change request, you discard the changes locally and reject the pull request on Bitbucket.

 

Git command line example

This is a simple Git example of the procedure for pulling changes made by another user from a fork of a Bitbucket repository, back into the original repository also on Bitbucket.

  1. Check for incoming changes (one change detected).

    $ git fetch && git log ..origin/master
    Password:
    commit 2f41d64e75f2b4f0405cbfb1d2f882882809c209
    Author: ANDREW <alui@atlassian.com>
    Date: Thu Sep 8 11:50:08 2011 +1000
    
     adding images
    
  2. Check for outgoing changes (no changes detected).

    $ git fetch && git log origin/master..
    Password:
    remote: Counting objects: 6, done.
    remote: Compressing objects: 100% (3/3), done.
    remote: Total 4 (delta 1), reused 0 (delta 0)
    Unpacking objects: 100% (4/4), done.
    From https://staging.bitbucket.org/alui/alui-git
     2f41d64..7e28ddb master -> origin/master
    
  3. Pull the changes into the local repository.

    $ git pull
    Password:
    Updating 2f41d64..7e28ddb
    Fast-forward
     Thumbs.db | Bin 0 -> 11776 bytes
     file.txt | 4 +++-
     2 files changed, 3 insertions(+), 1 deletions(-)
     create mode 100644 Thumbs.db
    

Mercurial command line example

This is a simple Mercurial example of the procedure for pulling changes made by another user from the main Bitbucket repository, down into the local working copy.

  1. Check for incoming changes (one change detected).

    $ hg incoming https://bitbucket.org/sarahcm/sarahmaddox
    comparing with https://bitbucket.org/sarahcm/sarahmaddox
    searching for changes
    changeset:   6:9f0a3d22d0be
    tag:         tip
    user:        Sarah Maddox <smaddox@atlassian.com>
    date:        Fri Aug 27 12:07:21 2010 +1000
    summary:     Changed 'bounding' to 'pounding' and added pic of cockatoo'
    
  2. Check for outgoing changes (no changes detected).

    $ hg outgoing https://bitbucket.org/sarahcm/sarahmaddox
    comparing with https://bitbucket.org/sarahcm/sarahmaddox
    searching for changes
    no changes found
    
  3. Pull the changes into the local repository.

    $ hg pull https://bitbucket.org/sarahcm/sarahmaddox
    pulling from https://bitbucket.org/sarahcm/sarahmaddox
    searching for changes
    adding changesets
    adding manifests
    adding file changes
    added 1 changesets with 2 changes to 2 files
    (run 'hg update' to get a working copy)
    
  4. Update the working copy.

    $ hg update
    2 files updated, 0 files merged, 0 files removed, 0 files unresolved
    
  5. Push the changes up to Bitbucket.

    $ hg push
    pushing to http://bitbucket.org/sarahmaddox/sarahmaddox
    searching for changes
    http authorization required
    realm: bitbucket.org HTTP
    user: sarahmaddox
    password:
    remote: adding changesets
    remote: adding manifests
    remote: adding file changes
    remote: added 1 changesets with 2 changes to 2 files
    

 

 

56 Comments

  1. Anonymous

    I created a branch and added a team member to work on it.

    He commits, I approve the commits, and the branch shows those changes when I browse on BitBucket.

    When I clone the repo, it is master by default. How do I fetch the Branch's lastest code instead of master?

    When I have tried is as follows:

    • I cloned the branch
    • Checkout dev-0.1 (that's the branch I wanted)
    • git fetch , git pull - tried these both, but no changes. It's already upto date according to git, while it's not.

    Can anyone help?

    1. Anonymous

      I believe you can set the default branch in your repo's admin page, under "Repository Details".

  2. Anonymous

    I don't seem to get a list of repositories in the right hand dialogue - is this correct? Is it possible issue cross repository pull requests?
    I'm using Mercurial. 

    1. No, you can't pull between two repositories who have nothing to do with each other.  You can only issue a pull request between an original repository and one of its forks.

  3. It would be cool if you have got some options when merging a pull request. In detail I miss the following:

    • an equivalent of 'git merge --squash' to merge the pull request as one commit without pulling in its development history
    • an option to modify the merge message ('git merge -m "..."')
    • an option to change the merge strategy and merge strategy options ('git merge -s ... -X ...')

    I set set up the issue #6107 for this. Please vote!

  4. Anonymous

    I`m probably missing something but how can I create a pull request but not send everything that was commited to my forked branch?

    Imagine I`m working on some debugging feature but that it doesn`t belong in the "main" repo. So I'd like to be able to send Pull requests for all the "valid" stuff from my branch, but ignore all the "unofficial" dev.

    Right now, the Pull Request picks up every commit done to my forked branch.

    Thx

    1. Hi,

      Unfortunately, there is no way to pick and choose which commits go into a request.  You could make a request for this.   There also might be a way to do this through a methodology.  For example, you might create a branch in your fork for the unofficial stuff or something...I'll ask the team about your use case and see if there is good way to accomplish this.

      Mary

    2. This is not how Mercurial and Git works: a merge commit always includes all the ancestors of the merged commits. You would need to rewrite the history locally and then push a clean branch that you can reference in a pull request.

  5. Anonymous

    I do things like that:

    git clone 
    git checkout -b new_feature
    < work and commit >
    git rebase master
    < work and commit >
    < finish working >
    git rebase master
    git push origin new_feature
    < I create pull request via bitbucket's web interface >

    Someone who reviewing the changes is doing:

    git pull 
    git checkout master
    git merge --squash new_feature
    git push origin master

    I was hoping this will close the pull request as accepted but it did not, what am I missing? I read lots of bitbucket's documentation "working with pull requests" but this is still not clear for me.

    I can see all my commits from new_feature branch have beed applied to the master branch (via merge --squash) and I can see which files have changed, but now when I press merge on a bitbucket's pull-request interface I have another commit in master which is merge and this does not change any files (all the changes were already applied by previous merge --squash) but just brings all those commits history into the master which is not what I wanted.

    Ideas?

  6. Anonymous

    Hi, Is there a way to enforce pull requests on a branch? So developers are not able to commit directly on the branch. Everything has to be a pull requests, and get approved? Can I simply give everyone only read access? What is the best approach? Thank you.

    1. Hi,

      So, a repository can have branches.  Within that repository, you can't set permissions on a branch that are different from the repository.  You can set permissions on the repository that would allow developers to fork the repository and issue pull requests against it. To configure this:

      1. Create a group on your account and call it  "developers".
      2. Give the group read permissions.
      3. Add all the developers to that group.
      4. Edit the groups on the repository and add developers.

      Hope this helps.

      Mary

  7. Anonymous

    Being able to pick out commits that go into a Pull Request as Anonymous pointed out would be very useful. Either on the side when creating a Pull Request (inside a fork) or on the side of accepting a Pull Request. This should be made easy not that it's necessary to pull locally and do all sorts of cmdline and local magic.

    Maybe put a column of checkboxes next to each commit in the Pull Request window?

    I'm actually very surprised this isn't already there, we don't always do one change, one commit, one pull request. This is very cumbersome.

    1. It is not there since Mercurial and Git don't work like that. Merge commits always include all the ancestors of the merged commits. You would need to rewrite the history locally (using the command line magic you talk about) and then push a clean branch that you can reference in a pull request.

  8. I would like to make a reference to an oustanding issue in my pull request.

    The pull request should show up in the issue as a comment or something.

    Is this possible?

    I tried using "issue #797" in the title or "ref #797", but that doesn't seem to work.

    1. You can refer to an issue in your commit message and it will show up in the pull request commit.

      issue #XXX

      Bitbucket doesn't cross reference the pull request from the issue though.  You'll need to comment on the issue and reference the pull request. 

      pull request #XXXX

      1. I think github does cross-reference automatically, so you need to keep up (smile) Would be good adition to bitbucket/stash.

  9. I just have one question about git, here it goes
    I am working on 5-6 member team and surely every one will have one copy of the repo in the local drive but what if one member changed a file, for example config.php file and pushed to the repo, then some time later I have edited the local config.php file and I think its good to push, I commit and I push but now here is the problem, file conflict.
    This is the main reason I am unable to get my head around, what should I do, Where I should pull all the changes again, what if I pull all the changes? Does it replaces my changes in the config.php file (Locallly)? how to solve this issue. Any Solution ?
    Please Help. Thanks in advance. 

    1. Kabir,

      Bitbucket recognizes there are conflicts. It doesn't pull the request automatically.  A human must manually review and fix the conflicts.  That means you, or someone on your team, pulls the destination repository. Pulls the request. Resolves the conflicts through a merge, and pushes the changes back.

      Alternatively, you can ask the requester to resolve the conflicts and update the pull request.  Or, even, you could just decline the request. There is a lot of flexibility and how your team chooses to handle the situation depends on several factors, the nature of the conflict, the way your team likes to work, and even things like project schedules.

      Hope this helps.

      Mary

    2. The solution is to stop versioning the config.php file. You should instead version a file called, say, config.php.template and ask your team members to copy this to config.php in their working copies. Add config.php to the ignore file so that it wont shot up in git status.

  10. Anonymous

    Has Atlassian considered adding tighter Continous Integration integration to Bitbucket?

    I would love to see something in the lines of GitLab CI integration where each pull request is decorated with CI build passed notices.

    1. Anonymous

      Apologies for the hilarious typo above, please s/bull/pull/ (smile).

      I see that something is already available for Stash and Bamboo - can these ideas be ported to BitBucket?

      1. We have plans to bring this feature to Bitbucket in the future. Right now it relies on an API in Stash that is not yet available in Bitbucket.

  11. Hello, I am a newbie to the Bitbucket World and still trying to understand the mecanics of it.

    The process of resolving the merge conflicts is not clear to me yet.

    Imagine this scenario:

    1- On Repository1 I have file text1.txt. This is my Main production Repository.

    2- Then I create a fork of this repository named 'Repository2' for developing some new features.

    3- at Repository2, due to my new features I also have to start making changes on file text1.txt

    4- Meanwhile at Repository1 I make a new change on file text1.txt and publish it.

    5- My changes at Repository2 are done and I now send a Pull Request to Repository1.

    6- At the repository1 I aprove the Pull Request and this new version of text1.txt should be the final one and choose merge.

    The problem is that BitBucket doesn't allow me to accept this changes made at file text1.txt.

    How can I solve this problem? bitBucket should have an option to allow me to accept this changes...

    Thanks in Advance ...

    Joao Santos

     

    1. Joao,

      If Repository1 and Repository2 have conflicts, Bitbucket cannot resolve those for you. We don't have the option of forcing a merge.  To accept the change, you do this:

      1. Go to the Repository1 repo on your local machine.
      2. Pull the changes from Repository2 into Repository1.
      3. Merge the changes.
      4. Push the updated Repository1 back to Bitbucket.
      5. Bitbucket marks the pull request as merged.

      Hope this helps.

      Mary

  12. Anonymous

    What happens when you approve a pull request w/o merging it?  Does it merge into the destination anyway?

    1. An Approval is equivalent to saying that you like the changes depicted in the request. It does not merge the changes at all. 

  13. Anonymous

    Hello, I forked a repo and cloned a copy of the new fork on my local machine. Later I went to the original repo and wanted to submit a pull from the original to my repo. When I clicked on the repos where I could merge to, my repo was not listed. What do I need to do to add my repo to the list of options for merging from the original to my fork?

    1. Anonymous

      I just sorted it out. I had to click on the branches icon in the destination repo and then click on the compare icon. When I did that it gave me the option to merge from the original repo and gave me a list of branches that I could use.

      1. Glad you solved it. (big grin)

  14. Hello. I have a few question about PR’s:

     

    1. If I marked PR as approved and then new changesets were added will it be marked back as unapproved (it did not in my test, but I run PR from one my repo to the other, and also was an approver)?

    2. Can I run a PR with changesets added automatically after push?

    3. And will I get notified about new changesets in PR…? …if I did approve it? …did not? …if it was already merged (if it is possible)?

    1. Here are some answers:

      1. No we don't reset the approval count if there is an update to the PR.
      2. Hmm, I'm not sure I understand the question.  You can change, commit, create PR, and then change, commit, update PR.
      3. You can get notifications if you have configured them. See Manage Inbox and email notifications for more information.
        1. What it is approval for then? I mean, I can approve specific state of the PR, but I do not want to approve both current state and any state the author of PR will happen to come to without actually seeing it. This can be resolved by either resetting count or blocking PR changeset updates, it would be fine with either. If neither is done “approved” only means “approver have checked some changeset(s), now guess which ones”.
        2. This part: “… update PR”. It would be fine if this should not be needed or happen automatically when I do `hg push` pushing to a branch I request to pull.
        1. Nikolay,

          1. Approve is a euphemism for like. Lack of approval does not prevent a request from being pulled. Others have raised the same point; you can add your comments to this issue.
          2. I believe it asks you if you want to update the request. If you want to suggest a change to the current behavior, you  can file an enhancement request for this behavior. 
            1. It should have been named “like” then. Behavior with lack of approval is up to authors, but “approve” is expected to mean “I think this is good to merge”, not “like”. Thanks for the link though.
            2. It was already requested: https://bitbucket.org/site/master/issue/5231/pull-requests-should-update-with-newest. Since this is how github works (= the behavior a big bunch of people already got used to and thus expect on bitbucket) I would be surprised if it was not. It would be fine for me to have a CLI tool that does update though: it could be used in hook then.
            1. Nikolay,

              1. Agreed. It used to be that. Think of the current name as a trailer for future functionality.
              2. Cool, glad you added your voice to the request.

              Mary

  15. Anonymous

    One more question which I didn't find an answer for (and don't see how to set up a test case).

    I have a repository which will have a number of contributors who will work based on forks and pull requests because we won't give everyone push access.

    We will work with peer review so any contribution has to be review prior to merging to 'master'.

    The question is: Is it possible to select another fork as the destination of a pull request instead of the original repository? In other words: Can I send a pull request to a specific other contributor who also works on a fork?

     

    1. Unfortunately, you can't.  The destination of a request can be your fork or the original repo.  You could have a single master repository and a working fork.  Everyone can have full access to the fork but a subset of people with access to the single master.  Then, users working on the fork can issue pull requests into branches on the fork.  IOW, the fork uses the branches and the master doesn't.  

  16. Anonymous

    What happens if you only want to pull request some commits but not all?

    say you have a repo, Foo, and forked that repo as Bar. you then make commits 1 and 2 to Bar. I only want to pull commit 2 back to Foo, how can I do that?

    Thx.

    1. Good question. If all your commits are pushed to Bitbucket, your pull request will include them all – you can't be selective.  

    2. Let me add to manthony's answer that this is not a limitation of Bitbucket — this is how Mercurial and Git works. In both systems, a merge commit always includes all the ancestors of the merged commits.

       

      In order to only pull commit 2 into Foo, you would need to make that commit first. That is of course difficult to know up-front, so what people normally do is that they commit locally and then rewrite the history to their liking before pushing it to Bitbucket. With Mercurial you would use hg histedit, with Git you might use git rebase -i. Both commands allow you to reorder commits and you can then push to Bitbucket and reference only commit 2 (which would then be commit nummer 1 on Bitbucket) in your pull request.

  17. FYI, you need to be logged in as a user account (not a team account) in order to see/click the Merge button.

  18. For those using Mercurial, please consider voting for this issue: Cannot create a pull request from a Mercurial bookmark. This makes it impractical to use bookmarks together with pull requests.

  19. I have project written in php, inside pull requests there is no code highlighting. How can I fix it?

    1. Artur,  can you explain what you mean by "inside pull requests?"   You could also just paste a screen capture in a comment.

      1. Yes, I can.

        "Inside pull requests" - this means that code, shown by pull requests mechanism, don't have any highlighted code. All code looks like a plain text.

        1. Ok, that is what I thought. So, for example the files or even the diffs:

          Sadly, that isn't supported yet. You can file an enhancement request for it.

  20. I have a very large pull request, is there any way to watch it per-file? For instance, like in Crucible.

    1. Currently, you can watch a pull request and a commit but you can't watch a particular file.  You can file an enhancement request for it.

  21. Hi, why doesn't Bitbucket have an option to mark a pull request as closed just like Github does? Some users might not want to use the default merge option mechanism but rather their own procedure of integration for pull requests/ commits. 

    1. You can decline any pull request. Declining a request doesn't merge it.  The automatic merge works only for the most simplest of merges.  Complex merging requires a manual merge.  Even so, you can ignore the automatic merge and merge manually  with your own procedure.  Merging manually also marks the pull request as merged. 

  22. Is there anyway to exclude/include specific commits in the pull request?

    Scenario I have is, made 4 commits to my branch and now I want to include last 2 commit but other two. I don't know if there's a way on webpage to do so? Please suggest possible alternatives.

    Thanks.

    1. No. Pull requests are an all or nothing object right now.  You can file an enhancement requests for that: https://bitbucket.org/site/master/issues/new

      1. In my not so humble opinion as a Mercurial developer, I don't think this is something Bitbucket can fix by itself. Merging is an all or nothing operation in both Mercurial and Git, please see my other reply here: Re: Work with pull requests.

  23. Anonymous

    If I want to test a pull request coming from a remote fork I have no read access to, the guide states that I should "Update your local repository with the incoming changeset.", but I'm not seeing how to do that. Is there another guide somewhere?

    1. Yes, please. When I saw the heading Manually pulling requests to your local system I thought it would do it, but I don't see how the git commands in that section would accomplish that when origin is the PR target (which would be the case in context). If these steps for git are not just plain wrong, they are frustrating.

      I understand that if I have read access on the source of the PR I can add it as a remote and fetch it, but that shouldn't be required. I should be able to get what I need just on the basis of receiving the PR.

      There's an interesting discussion on this here and here, but that doesn't exactly look like a mainstream solution at this time.

  24. Hi,

    I have created a repository in bitbucket and have given read access to other team members.The other team members have forked the master repository. I want to manually pull their changes into my local system to  test the  on my local system before accepting a pull request. What command should  I used to pull the changes from other forks? I f i use hg pull https://fork repo url it asks me for username and password but I do not have username and password for other users.