Fork a Repo, Compare Code, and Create a Pull Request (Mac OS X/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 OS X or Linux environment. If you want to work in TortoiseHg on Microsoft Windows 7, see the instructions on this page.


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/ 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

    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 – 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
      <div class="quote">
       <blockquote>"Only in our dreams are we free. The rest of the time we need wages.”</blockquote>
           <cite>Terry Pratchett</cite>

    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
    	<div class="quote">
    	<img src="" />
    		<blockquote>'Tis but a scratch!</blockquote>
    		<cite>The Black Knight</cite>
  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
    searching for changes
    http authorization required
    realm: HTTP
    user: atlassian_tutorial
    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.


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!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport