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.
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
- Log into Bitbucket.
- Locate the Search field in the menu bar.
- Search for the
- Click on the search result to go to the repository.
- Click More then click Fork.
The system displays the fork page.
- 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
- 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
- Start the TortoiseHG Workbench.
- Choose View > Show Repository Registry.
- Choose File > Clone Repository.
- Enter location of your forked repository in the Source field
- Enter a destination on your system for your local repository, for example:
When you are done the dialog will look similar to the following:
- Press Clone.
The system clones the repository and displays it in the registry list.
Step 3. Make a change to the repository source
This repository contains a website which, as of this writing, has a an
editme.html file. Bitbucket allows you to host a website in a Mercurial repository. To see the hosted website, go to http://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.
- In the TortoiseHG Workbench, select the
- Right-click to display the context menu.
- Choose Edit Local.
The file is an HTML file.
Go ahead and add a quote of your choosing. You can add an image link to your quote if you like, just place it above the <blockquote> tag.Here is a sample of what an addition will look like:
If you are not sure what to do, you can copy the example tags at the top of the file, paste them just below the last quote on the page, and modify them with your quote, as shown in the preceding example.
- Close and save the file.
- Refresh the Working Directory.
- Enter a commit message in the space provided.
- Press the Commit icon (check symbol) to commit your changes.
- Press the Push outgoing changes to selected URL icon.
The system prompts you to confirm your action.
- Press Yes.
The system pushes your changes to the forked repository.
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. You can see your change by clicking the diff tab (1).
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.
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:
- 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
After you create a pull request, you can't delete it. Neither can the person that receives your request. The receiver either merges or declines your request. If you delete your fork after you make a request, the receiver can only decline your request because the repository to pull from is gone.
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 (1) a request. Owners, and others with access to the repository can Approve (2) a request. The owner can also see any additional commits or activity (3) and how many files are in this pull request (4). Clicking Approve simply means the approver reviewed the changes in the pull request.
You'll get an email when your pull request is accepted or rejected. For now, continue to the next step.
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.