Skip to end of metadata
Go to start of metadata

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.

Icon

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 repo, typically you have read access to the code but not write access. This means that you can use a clone command to copy the repo but you cannot push changes to it. Instead, you use the Bitbucket interface to fork a repo.  Bitbucket hosts private or public repos. Anyone can fork a public repo. You can fork a private repo where you have permissions.

Forking a repository creates a new repository under your account. This new repository is a copy of the original repo and is called a fork. Even though you have a fork, you can still get a change into the original repository, to do this you:

  • clone the forked repo from Bitbucket to your local system
  • make changes to the local repo
  • push the changes to your fork on Bitbucket
  • issue a pull request against the hosted repo you forked from
  • wait for the repo owner to accept or reject your pull request

If a repo owner accepts a pull request, Bitbucket pulls your code changes into the original repo and merges them. Bitbucket recommends you work with forks and pull requests even if the repo owner gives you write access to a public repository.  While a pull is a DVCS concept, "pull requests" and forks are concepts used only by repository hosting services — like Bitbucket and GitHub. You won't find fork and pull requests in any Git or Mercurial workflow that doesn't involve a repository hosting service.

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. Choose the Fork button.

    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. Don'

  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

Step 4. Compare your fork to the original

During the time you were working on your fork, the original repository you forked from may have changed. At this point, you can check that and decide if you need to adjust your fork accordingly. 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. The Compare and Pull Request buttons toggle between two specialized views available only in forked repositories. 

Press Compare to reveal the Compare view which contains a lot of information.   This view allows you to look at your forked repository in comparison to the original repository. You can look at it from two "directions." You can compare your repository against Incoming changes from the original. Or, you can compare Outgoing changes from your fork to the original.  

Keep in mind that the outgoing changes can be from multiple people. How? Well if you have shared your fork repository with others (You'll learn more about how to do this later). Right now, though, you should be the only person on the repository so only your changes appear.  Scroll down the view and you will find it includes helpful Mercurial commands:

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.

The commits section displays the commits pushed from a local repository to the fork in Bitbucket. If there are multiple commits, you see their cumulative changes by file in the Files Changed section. You can toggle between the side-by-side diff button to see the changes displayed in that format. Or press the view file button and see the file.

To see the contents of a specific commit in isolation, select a Commit link and the system takes you to the Commits page. 

 

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

Accepting the pull request is not something you do,  it is something done by the repository owner. It is the next step though. When the original repository owner logs into their account, their Newsfeed shows your pull request. It also shows your fork from a few days earlier. For example:

The repo owner can click on the request and see your full request.  An owner can Merge, Edit, or Decline a request. Owners, and others with access to the repository can Approve a request.  Clicking Approve simply means the approver reviewed the changes in the pull request.

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.

  • No labels

52 Comments

  1. 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, 

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

  2. Anonymous

    Excellent Tutorial

  3. Anonymous

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

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

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

  4. 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!

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

       

  5. Anonymous

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

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

  6. 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!

     

     

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

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

     

  8. 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=
    1. 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.

  9. did not know how to edit index.html

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

       

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

  10. 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 !

    1. 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?

  11. 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)

     

     

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

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

    1. 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:

  13. 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)

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

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

  15. 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?

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

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

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

  17. 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!

     

     

    1. 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. 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
    1. This went away.  I am afraid I could have simply got the password wrong.  Stranger things have happened.  Feel free to laugh.

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

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

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

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

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

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

  20. 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)

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

  21. 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)

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

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

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

       

       

  23. Anonymous

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

  24. 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"?

     

  25. 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?

     

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

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