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

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.

Change the Name for example, to myquotefork.

Enter a Description that you think is appropriate.

Uncheck Inherit repository user/group permissions.There are several options for forking. For now, just leave all the remaining options at their defaults.

Press Fork repository.

Step 2. Clone your fork

Open a terminal window on your local system.

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.

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

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:

Use Google or some other search engine to locate your favorite quote.

Using your favorite editor, edit the editme.html file.

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 exampleExpand 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:

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:

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.

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.

Press the Compare button to compare your forked repository to the original repository.

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.

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:

Press Create Pull Request.The system displays the request form.

Complete the form.When you are done it will look something like this:

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.

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.

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:

Anonymous

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.

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.

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?

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.

Anonymous

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.

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?

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:

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?

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.

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.

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