Fork a Repo, Compare Code, and Create a Pull Request (Mac OSX/Linux)

So far, you've worked in a repository you own and you've been the only person working in it. You can only fully experience the power of a DVCS hosted repository by working with others. In this page, you work with a repository you don't own. You'll make a change to a code file, not just a README. You'll use Bitbucket's comparison features to compare your repository with the original.

The tutorial examples so far worked exclusively with Git repositories using git commands.  In this section, you'll work with a Mercurial repository.  If you start working extensively in the host DVCS community, you'll most likely find yourself working with multiple DVC systems. You may even find yourself working with other hosted products, such as GitHub or Kiln. It is good experience to see the workflow you'd use in these types of situations.

The examples on this page work for Mecurial in a Mac OSX or Linux environment. If you want to work in TortoiseHg on Microsoft Windows 7, see the instructions on this page.

Backgrounder

When you work with another user's public Bitbucket repository, typically you have read access to the code but not write access. This is where the concept of forking comes in. Here's how it works:

  • Fork the repository to copy it to your own account.
  • Clone the forked repository from Bitbucket to your local system.
  • Make changes to the local repository.
  • Push the changes to your forked repository on Bitbucket.
  • Create a pull request from the original repository you forked to add the changes you made.
  • Wait for the repository owner to accept or reject your changes.

If a repository owner accepts the pull request, Bitbucket merges your code changes into the original repository. It is recommended that you work with forks and pull requests, even if the repository owner gives you write access to a public repository. While a pull is part of the Git and Mercurial workflow, pull requests and forks are concepts used only by repository hosting services — like Bitbucket.

Step 1. Fork another user's repo

 In this example you'll fork a public repository belonging to a user called tutorials.

  1. Log into Bitbucket.
  2. Locate the Search field in the menu bar.
  3. Search for the tutorials/tutorials.bitbucket.org repository.
  4. Click on the search result to go to the repository.
  5. Click Fork.

    The system displays the fork page. 
  6. If your account is a member of a Bitbucket team, the page contains a field Owner.  If you don't belong to a team, there is no Owner field; Continue to the next step.
  7. Change the Name for example, to myquotefork.
  8. Enter a Description that you think is appropriate.
  9. Uncheck Inherit repository user/group permissions.
    There are several options for forking. For now, just leave all the remaining options at their defaults.
  10. Press Fork repository.

Step 2. Clone your fork

  1. Open a terminal window on your local system.
  2. Change directory to your repos directory.
    If you have followed along in this tutorial, your repos folder contains only a single Git repository.  There is no reason repos cannot also contain a Mercurial repository.
  3. Clone the fork to your local system.
    The command is similar to the following:

    hg clone https://bitbucket.org/atlassian_tutorial/myquotefork

    You would need to replace atlassian_tutorial with: your_accountname

  4. Change to the ~/repos/myquotefork directory.

Step 3. Make a change to the repository source

This repository contains a website which, as of this writing, has a single index.html file.  Bitbucket allows you to host a website in a Mercurial repository. To see the hosted website, go to https://tutorials.bitbucket.org – you may encounter an Untrusted Connection message. Go ahead through to the site. You'll see that the site contains a single page that lists favorite quotes from "bitbuckians" which is just a writer-invented word for users of Bitbucket.  Now, it is your turn to record your favorite comedic quote...or just a favorite quote. Do the following to contribute to this repository:

  1. Use Google or some other search engine to locate your favorite quote.
  2. Using your favorite editor, edit the editme.html file.
  3. Add your favorite quote by copying and pasting another entry and replacing the details with your own quote. See the following example for the full tag to copy.

    xml example  Expand source

    Be sure you paste the full tag structure and that you don't paste inside another tag or before the first <div> tag on the page.
    You can also add a linked image file if you wish. We ask you do not add images to the tutorial repository but rather create a linked image as shown in the following example:

    xml with image tag  Expand source
  4. Save and close the file.
  5. Display the status of the repo:

    myhost:myquotefork manthony$ hg status
    M editme.html

    If you added an image file, you'll see that as well.

  6. Commit your changes locally, for example:

    $ hg commit -m "adding a quote by Bill Hicks"
  7. Push your changes to your Bitbucket fork.

    myhost:myquotefork manthony$ hg push
    pushing to https://bitbucket.org/atlassian_tutorial/myquotefork
    searching for changes
    http authorization required
    realm: Bitbucket.org HTTP
    user: atlassian_tutorial
    password: 
    remote: adding changesets
    remote: adding manifests
    remote: adding file changes
    remote: added 1 changesets with 1 changes to 1 files
    remote: bb/acl: atlassian_tutorial is allowed. accepted
  8. Enter your password to finish pushing changes.

Step 4. Compare your fork to the original

While you were working on your fork, another Bitbucket user might have made updates to the original repository. At this point, you can check that and decide if you need to adjust your fork accordingly. Do the following to compare your changes with the repository:

  1. Log into Bitbucket and navigate to your myquotefork repository. Forked repositories have a special widget that lets you compare your fork work to the original or to create a pull request.
  2. Click the Compare link on the left side of the page. The Compare section has a specialized view that is available only in forked repositories.
  3. Press the Compare button to compare your forked repository to the original repository.
  4. Click the Diff tab to compare changes from your fork to the original. If there are multiple commits, you see their cumulative changes by file in this section. Click the Side-by-side diff button to see changes displayed side-by-side. Or press the View file button to view the full file in Bitbucket.
  5. Switch back to the Compare tab to see the list of commits pushed from your local repository to the fork in Bitbucket. To see the contents of a specific commit in isolation, select a Commit link and the system takes you to the Commits page. 

You can merge your fork into another repository — for example a local copy you may have of the original repository. If you merge locally, you can test your changes before making a pull request through Bitbucket.

Step 5. Create a pull request

If you haven't already done so, log into Bitbucket and navigate to your myquotefork repository. Then, do the following:

  1. Press Create Pull Request.
    The system displays the request form.
  2. Complete the form.
    When you are done it will look something like this:
  3. Press Create pull request.
    The system opens your latest request on the Pull Request page of the original repository. To see the list of all the pull requests against this repo, click the Pull Request tab. 

Step 6. Learn what happens to your pull request

You have to wait for the repository owner to accept your pull request. When the original repository owner logs into Bitbucket, that user's newsfeed shows your pull request and your fork from a few days earlier, as shown in the following image.

When the repo owner clicks on your pull request, that user can Merge, Edit, or Decline (1) it. In addition to owners, anyone with access to the repository can Approve (2) the request, which means that the approver reviewed the changes in the pull request. The owner can also see any additional commits or activity (3) and how many files are in this pull request (4).

You'll get an email when your pull request is accepted. For now, continue onto the next section.

Next

That was intense. Maybe. Depends on your daily life. In the next section, you learn ways to be social on Bitbucket which includes adding users to your repository.

Was this helpful?

Thanks for your feedback!

52 Archived comments

  1. User avatar

    Anonymous

    Excellent, clear tutorial. In step 2, cloning the fork, the shell command

    $ hg clone https://bitbucket.org/atlassian_tutorial/myquotefork

    must, of course, be replaced by 

    $ hg clone https://bitbucket.org/my_username/myquotefork

    where 

    my_username

    is your BitBucket username, 

    14 Jun 2012
    1. User avatar

      manthony

      Glad you are finding the tutorial useful. I've clarified that section per your suggestion. Thanks for the catch!

      14 Jun 2012
  2. User avatar

    Anonymous

    Excellent Tutorial

    10 Jul 2012
  3. User avatar

    Anonymous

    tutorial is great..but can u provide this same procedure with git instead of Mecurial

    19 Jul 2012
    1. User avatar

      manthony

      The steps are identical both git and hg.  The exception are the command lines. We have general instructions for both DVCS flavors here: Forking a bitbucket Repository

      19 Jul 2012
      1. User avatar

        YannisDran

        I suggest you move this link up in the tutorial. I was following up all steps until I ended here feeling there was an dead end. It would definitely save some time to beginners. (wink)

        Uh ah, now I realized that you were referring to a general method and not to an identical method for git users. Also, this link is incorrectly pointing to the very same page we are viewing now..

        14 Feb 2013
  4. User avatar

    Kevin McCarthy

    This tutorial is fantastic, and a great deal of thanks for the time and effort made to put it together, but I need to point out that in my case the 'Send Pull Request' and 'Create Pull Request' sequence did not match what is described here. When I navigated to the 'myquotefork' repo here I did not see 'Send Pull Request' as the image and text suggest, but only a button to 'Create Pull Request'. I selected the 'Create' button and then got a subsequent 'Send a pull request' page that looked a little different than the image shows here.

    I think it went the way I expected but since there is a lot to pick up in this tutorial, even the slightest discrepancy can cause confusion for the user. If I inadvertently followed a sequence that diverts from the directions, let me know. Otherwise I'll chalk it up to a slight change in the BitBucket UI since the tutorial was first written.

    And thanks again!

    20 Jul 2012
    1. User avatar

      manthony

      Hi Kevin,

      You are right, there are changes in the UI since last I worked on this. I have plans to update the entire tutorial in August and retake all the captures then.

      Cheers,

      Mary

       

      23 Jul 2012
  5. User avatar

    Anonymous

    Okay. I came here to know what's the suggested workflow for when a pull request is declined.

    26 Oct 2012
    1. User avatar

      manthony

      Ah, ok.  Well, typically the destination repo owner will provide a reason for declining your pull request.  So:

      1. Locate your pull request (for example, it should be listed on your account's Newsfeed).
      2. Click on the request link.
        The system takes you to the Pull Request detail view.
      3. Choose the Activity tab.
        You can see who declined your request and if they gave a reason. 
      4. Send an email to the user if you need more detail.

      If there was something wrong with you request, you will see comments from reviewers.  You can always correct the problem and resubmit.

      26 Oct 2012
  6. User avatar

    Anonymous

    Hello,

    After i've forked to my bb account and then tried to clone using git i get the following error:

    "fatal: https://bitbucket.org/*******/myquotefork/info/refs not found: did you run git update-server-info on the server?"

    (i've changed ******* above to my own account)

    i used the the command "git clone " instead of 'hg clone' followed by the path of the fork on my bitbucket account.

    suggestions?

    Thanks!

     

     

    15 Dec 2012
    1. User avatar

      manthony

      The tutorial repo is a Mercurial repo.  You would need to clone it with a Mercurial command.  Git doesn't know about that repo.  

      17 Dec 2012
  7. User avatar

    Anonymous

    When I tried to clone the Hg fork with the command from the tutorial, and also the command given on the BitBucket repo page (only difference was user name had @bitbucket.org  appended to user name, in either case I get the error:

    abort: error: _ssl.c:504: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

    Any simple way to identify and resolve this?

     

    17 Jan 2013
  8. User avatar

    Anonymous

    Found a solution that worked:

    Quick fix, go to .hgrc and put this on your [web] section (.hgrc file is the mercurial config file located at ~/)r

    1
    2
    [web]
    cacerts=
    17 Jan 2013
    1. User avatar

      manthony

      Thank you for the comment and your solution. My apologies that you encountered the problem.  I'm working on a big project this week, but I'll pick this up next week and see what I can discover to prevent other people from running into the same problem.

      17 Jan 2013
  9. User avatar

    Richard Waldinger

    did not know how to edit index.html

    01 Feb 2013
    1. User avatar

      klunk

      Hello.

      With ubuntu:

      cd ~/repos/myquotefork/

      ls -al              (optional : you should see some index.html file with that, in the obtained list, or you are in wrong place)

      gedit index.html

      Then do modification, register, you done.

      "gedit" is the name of the editor used in my case. If last line doesn't work, try with a name of an editor provided with your distribution.

       

      01 Feb 2013
    1. User avatar

      manthony

      Hi Richard,

      It isn't clear if you do not know which editor to use or you are concerned about editing HTML.  You can usually find the nano editor on Mac OSX. If you are concerned about not knowing HTML, just wing it a bit – and don't be afraid to make a mistake.  I'll catch it when I pull the request.

      Mary

      01 Feb 2013
  10. User avatar

    klunk

    Hello Mary Anthony.

    On ubuntu, about step 3:

    - hg status return two files, at least when using gedit:

    M index.html

    ? index.html~   (a backup of index.html was created).

    - And commit localy:

    hg commit -m "blabla"

    result in : abandon : no username supplied, until you edit ~/repos/myquotefork/.hg/hgrc, putting in the following:

    [ui]
    username = First Last <email@address.com>

    - Thanks for sharing you work !

    01 Feb 2013
    1. User avatar

      manthony

      Hi you should have edited the global .hgrc file when you initially installed Mercurial. If you were following this tutorial, that would be this page: Set up Git and Mercurial (Ubuntu Linux).  It would have avoided the error; did you have the global configuration file set up?

      05 Mar 2013
  11. User avatar

    dzejn

    Hi Mary Anthony, 

    I had also same problem as @klunk with $hg commit -m "blabla" but on mac. Solved globally with editing  ~/.hg/hgrc.

    Reading this tutorial (including precedent pages) I did know which hash code should be in $hg merge (shown didn't work) and also I posed one question to myself : why $hg update precedes $hg pull before merging. 

    -- Thanks for your tutorials (smile)

     

     

    05 Mar 2013
    1. User avatar

      manthony

      hg update will updates the working directory to the tip of the branch; it is a precaution.

      05 Mar 2013
  12. User avatar

    Anonymous

    Great tutorial indeed!

     I didn't understand one thing.I'm apologizing in advance if the question is dumb, but don't know how to commit a picture.

    when i typed hg status it says: 

    M index.tml

    ? name_of_picture.jpg

    Why I get question mark?

    I was unable to commit that picture. The rest was ok.

    28 Mar 2013
    1. User avatar

      manthony

      Ah, good catch, I should mention this.  If you add an image you need to put it under source control with a command like this:

      28 Mar 2013
  13. User avatar

    Anonymous

    It seems that I have given up too soon (smile)

    I have to add each modification with: hg add

    (in my case hg add * in order to add all files at once)

    28 Mar 2013
  14. User avatar

    Anonymous

    Hi,

    Everything seems to be clear enough, but when I tried submitting the pull request, I get this message:

    "Bitbucket cannot automatically merge this request due t oconflicts" and when I go down to the Overview section it only says conflicts between parenthesis, but I can't find from the light-yellow highlight what is the conflict with my pull request.

    Thanks

    24 May 2013
    1. User avatar

      manthony

      That's ok.  The side-by-side Diff is the best way to look at that.  There were some changes by another between when you forked and your pull request.  I'll fix them when I merge your request.  

      It isn't necessarily a problem you need to fix.  As a the owner of the tutorial repo, I decide if I want to fix the conflict and merge or decline.  

      24 May 2013
  15. User avatar

    David Stahl

    When I open a Pull Request I get to add Reviewers to it. This is great. However, the auto-complete on the reviewers looks like it's showing everyone in BitBucket. I'd love it to show everyone in my group/team. Is that possible to configure?

    26 Jul 2013
    1. User avatar

      manthony

      It isn't possible to configure that. If you belong to a team, we do group the team members at the top.  And, if you have had a set or past reviewers, we list those for you to add quickly.

      26 Jul 2013
  16. User avatar

    Dennis Yu

    It would be helpful for a lot of beginners if there was a brief mention of the differences between a fork and a branch.

    13 Sep 2013
    1. User avatar

      manthony

      I'm about to restructure the tutorial in favor of branching over forking.  You'll see this information then. Until then, I have that here.

      13 Sep 2013
  17. User avatar

    Anonymous

    Hello everyone, I'm making the tutorial and find this message when trying to clone the forked repo.

    remote: Warning: Permanently added the RSA host key for IP address 'xxx.xxx.xx.xxx' to the list of known hosts.

    remote: Permission denied (publickey).

    abort: no suitable response from remote hg!

     

    Ummm.. any ideas? what does this mean? 
    Thanks for any input!

     

     

    18 Sep 2013
    1. User avatar

      manthony

      The message you are getting shows you are trying to clone with the SSH protocol not the HTTPS protocol. At this point, you should be using https. Make sure you are using the clone command that has HTTPS in it:

      hg clone https://bitbucket.org/YOURACCOUNT/myquotefork

       

      18 Sep 2013
  18. User avatar

    David Vincent

    Hi again MAnthony, My computer's hg tool says the version is 2.7.7 2.7.2, which seems to agree with the Mercurial list of releases at http://mercurial.selenic.com/wiki/Mercurial.  

    The CACertificates link you gave me was interesting.  I took some action based on that page, and that fixed the warnings.  I am still getting the abort, though:  

    shell session transcript  Expand source
    17 Oct 2013
    1. User avatar

      David Vincent

      This went away.  I am afraid I could have simply got the password wrong.  Stranger things have happened.  Feel free to laugh.

      21 Oct 2013
      1. User avatar

        manthony

        David, I'm glad you got it sorted, however mysteriously.

        21 Oct 2013
  19. User avatar

    Joseph Landau

    Hi manthony,

    When attempting the fork in this lesson, I get these responses:

    joe@Ubiquity-VBox:~/repos$ hg clone https://bitbucket.org/jrlandau/myquotefork

    destination directory: myquotefork
    requesting all changes
    adding changesets
    adding manifests
    adding file changes

    --after which there is no visible progress, so I use Ctrl-C to kill it after about 10 minutes.

    Can you advise?

    I'm using Ubuntu 12.

    Thanks,   Joe Landau

    24 Oct 2013
    1. User avatar

      manthony

      Hi Joe I tried the same operation with your clone.  It was slow but it did resolve.  Try running with the verbose flag (-v) on and see if you get more information.

      24 Oct 2013
      1. User avatar

        Joseph Landau

        That did work, thanks.  Incidentally, it seemed that I had to insert the -v in just the right place.

        Unfortunately I am now stuck on step 4–the screen I get isn't the same as the illustration.  Probably I forgot something in some forgotten configuration file. At least for now, after 4 hours, I give up. Maybe tomorrow I can try again.

        I like the style of your tutorials, they seem simple and clear.  But I think that I now have 2 programs to learn instead of one (i.e., bitbucket and git) in 2 environments (web and command).  Is this inescapable?

        Joe

        25 Oct 2013
        1. User avatar

          manthony

          I like the style of your tutorials, they seem simple and clear.  But I think that I now have 2 programs to learn instead of one (i.e., bitbucket and git) in 2 environments (web and command).  Is this inescapable?

          The short answer is yes. Bitbucket is a hosted service for coders that use Git or Mercurial to revision control their software.  Using Bitbucket only makes sense if you know Git or Mercurial source control software.  

          As a user, you can use a GUI client or a command-line client to run Git or Mercurial commands on your code. The makers of Git and Mercurial are not always the makers of these clients.

          Atlassian does not make Git or Mercurial. This documentation walks you through basic in Git and Mercurial basic commands as a means to teaching readers about Bitbucket. However, it is the makers of Git and Mercurial that write detailed documentation about using their software.

          25 Oct 2013
          1. User avatar

            Joseph Landau

            Sounds as though I should go back and learn some more Git/Mercurial, then I'll be in a better position to learn about Bitbucket.  Thanks.

            25 Oct 2013
  20. User avatar

    Anonymous

    In Step#4 I do not seem to see those useful hints about what commands to run next.

    Also, when I issue the pull request, it seemed to allow m to authorize the pull myself, which I do not understand since I am not the maintainer of the original repo from which I cloned.

    Rob Stevens aka dunciad (sorry about anon: I forgot I had no account on this website and did not want to go back and create one)

    20 Nov 2013
    1. User avatar

      manthony

      Hi Rob.  After you create a pull request, Bitbucket puts you in the list of open pull requests at the destination repository.  You are right, this does make it seem like you can pull the request yourself even if you don't have permissions on the repository.

      20 Nov 2013
  21. User avatar

    Anonymous

    Worked fine up until step 4.  When I do the compare, I only see one side, and, like Rob, I don't see the merge command hints.

    Bill Bohling (I'm logged in, just not for these tutorial pages)

    20 Dec 2013
    1. User avatar

      Anonymous

      Still stuck on step 4.  I've deleted my previous attempts and reforked, but still only see one side when I do a Compare after pushing changes, and I still don't see the merge hint.

      27 Dec 2013
  22. User avatar

    Henry Scullion

    Step 3 says to edit index.html, which is incorrect.

    It should say to edit editme.html.

    I have seen a couple of pull requests which have been rejected because people have edited the wrong file.

    26 Jan 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Thank you Henry, I have fixed this in the instructions. I apologize for any trouble this caused you and others. Thank you for taking the time to go through our tutorial.

       

       

      26 Jan 2014
  23. User avatar

    Anonymous

    A sentence is not complete: «If you added an image file, you'll see that as well. Don'».

    29 Jan 2014
  24. User avatar

    Defining Mac

    Sorry to be a little bit too much stupid : ( but i do not understand what i have to do ine Step3 nbr 5 or 7 : "

    myhost:myquotefork manthony$ hg status" what do I have to put instead of "myhost"? et instead of "manthony"?

     

    29 Jan 2014
  25. User avatar

    Alex Mattingley

    I am struggling with Step 2. I enter:

    hg clone https://bitbucket.org/user_name/myquotefork

    I keep getting the response:

    -bash: hg: command not found

    What is the command I need to use?

     

    03 Feb 2014
  26. User avatar

    Erwin Fallaux

    The tutorial assumes that you have a mercurial client installed on your system.

    You don't seem to have it installed, or your PATH is messed up (unlikely).

    You can download and install Mercurial from here: http://mercurial.selenic.com

    07 Feb 2014
    1. User avatar

      Anonymous

      Yep, you are spot on about the mercurial thing. When I started the tutorial I was under the impression that I did not have to download mercurial. I figured out how to do it in git so were all good, but thank you for your help

      07 Feb 2014
Powered by Confluence and Scroll Viewport