Forking a bitbucket Repository

In CVS or SVN, you create branches by forking/copying either the head/trunk or an existing branch. In Mercurial, there are various ways to create branches, and there is the concept of forking as described on this page. We recommend forking as the main way for developers to work together.

On this page:

Overview of Forking
Step-by-Step Example – First the Fork
Step-by-Step Example – Now the Pull Request
Notes
Screenshots

Overview of Forking

Forking is a way for you to create an exact copy of a repository at a specific point, and take it from there. This is particularly useful if you have reader permissions for the repository but not writer permissions, and if you want to do some major development work that you may or may not later merge back into the repository.

Here is the basic workflow:

Create a fork of the repository. Go to the repository that you want to fork on bitbucket and click 'fork'. This gives you a copy of the code from the point where you fork it.
Clone your new fork. Now you may clone your new repository, to create a local copy.
Work on the files locally. Edit the files, add new files, and so on. It is your repository.
Commit changesets to your local repository as usual.
Push your changes up to your fork. Push your changes to bitbucket in the usual way. This will update your fork of the repository.
Send a pull request to the owner of the original repository. Once you are satisfied with your changes, you can ask the owners of the original repository to pull in your changes and merge them into the main repository. Click 'send pull request'. bitbucket will send a notification to the owner, making it easy for you to communicate with them about your changes from this point onwards.

Step-by-Step Example – First the Fork

Let's go through the steps to fork a repository, make some changes and push them to the new fork. (In a later step, we will ask the repository owners to pull the changes into their repository.)

Create a fork of the repository:
- Go to the repository on bitbucket. For this example, we use a simple test repository https://bitbucket.org/sarahmaddox/sarahmaddox.
- Click the fork option on the bitbucket repository screen.
- The Fork options screen appears. See screenshot 1 below. Enter the following information:
- Name: The name of your new repository.
- Private: Select this checkbox if you want your new repository to be private, not public. See Repository privacy, permissions, and more.
- Description: A sentence or two about your new repository. For example, describe why you are forking the repository.
- Wiki: Select this option if you want a bitbucket wiki with your repository. Select Wiki is private if you do not want your wiki visible to the general public. See Using your bitbucket Wiki and Making your bitbucket Wiki Private or Public.
- Issue tracking: Select this option if you want a bitbucket issue tracker with your repository. Select Issues are private if you do not want your issue tracker visible to the general public. See Using your bitbucket Issue Tracker and Making your bitbucket Issues Private or Public.
- Inherit repository user/group permissions: Select this option if you want the users of the original repository to be able to contribute to your new forked repository by default.
- Fork at: Choose the revision that you want to fork. The default is tip.
- Click Fork repository.
- bitbucket creates a new repository and opens the overview page of the new repository.
- You are the owner of this repository. It is a copy of the original, containing the files and metadata of the original. Notice the words fork of original repository name next to the name of the new repository. See screenshot 2 below.
- bitbucket sends a message to the owner of the original repository, letting them know that you have forked their repository. See screenshot 3 below. A similar message goes to the owner's email address.
- Your fork also appears on the Forks/queues tab of the original repository. See screenshot 4 below.

Clone your new repository (the fork), so that you can start working on it locally. Mercurial and Git examples of this are shown below.

Mercurial example:

C:\Atlassian\bitbucketTesting\sarahcm-fork>hg clone https://bitbucket.org/sarahcm/sarahmaddox-iii
destination directory: sarahmaddox-iii
requesting all changes
adding changesets
adding manifests
adding file changes
added 17 changesets with 29 changes to 18 files
updating to branch default
16 files updated, 0 files merged, 0 files removed, 0 files unresolved

Git example:

$ git clone https://alui@staging.bitbucket.org/alui/alui-git-fork.git
Cloning into alui-git-fork...
Password:
remote: Counting objects: 3, done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.

Work on your files locally, as usual. For our example, I edited a text file. I also copied an image file to the local directory, then used the addcommand to add the new image file to the repository.

Mercurial example:

C:\Atlassian\bitbucketTesting\sarahcm-fork>cd sarahmaddox-iii
C:\Atlassian\bitbucketTesting\sarahcm-fork\sarahmaddox-iii>hg add
adding BalloonTower.png
C:\Atlassian\bitbucketTesting\sarahcm-fork\sarahmaddox-iii>

Git example:

$ cd alui-git-fork
$ ls
BalloonTower.png  file.txt
$ git add *.*
$ git status
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       new file:   BalloonTower.png
#       modified:   file.txt
#

Commit your changes to the local repository.

Mercurial example:

C:\Atlassian\bitbucketTesting\sarahcm-fork\sarahmaddox-iii>hg commit -m "Changed 'odd' to 'occasional' and added pic of balloons"

Git example:

git commit -m "Changed 'foo' to 'I like chocolate.' and added pic of balloons"

Push your changes to your repository (the fork) on bitbucket.

Mercurial example:

C:\Atlassian\bitbucketTesting\sarahcm-fork\sarahmaddox-iii>hg push
pushing to https://bitbucket.org/sarahcm/sarahmaddox-iii
searching for changes
http authorization required
realm: bitbucket.org HTTP
user: sarahcm
password:
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 2 changes to 2 files
remote: bb/acl: sarahcm is allowed. accepted payload.

Git example:

$ git push
Password:
Counting objects: 6, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 23.98 KiB, done.
Total 4 (delta 0), reused 0 (delta 0)
remote: bb/acl: alui is allowed. accepted payload.
To https://alui@staging.bitbucket.org/alui/alui-git-fork.git
   0ad86b3..395d3c2  master -> master

Step-by-Step Example – Now the Pull Request

The steps above showed you how to fork a repository, make some changes and push them to your fork. Now we will ask the owner of the original repository to pull our changes into their repository. We will do this by sending the original owner a pull request.

Click the send pull request option on your forked repository on bitbucket.
The Send pull request screen appears. The bottom part of the screen shows the changes made in your fork. The top part of the screen asks for information about your pull request.
Scroll down to the Commits part of the screen and check the comparison between your fork and the original repository. See screenshot 5 below.
Enter the information about your fork and your pull request. See screenshot 6 below.
- Pull from: The branch of your fork that you would like to push into the original repository.
- Pull into: The branch in the original repository where you would like to push your changes to.
- Title: A short description of the changes you have made. This should provide enough information for you and the owners of the other repository to identify your changes.
- Description: More details about your changes.
Click Create pull request.
- The pull request appears on the Pull requests tab in your fork (see screenshot 7 below) and also in the original repository.
- bitbucket also sends a message to the owner of the original repository, containing your pull request. See screenshot 8 below.
The owner can now reply to your message, examine your changes and decide whether to merge them into the original repository.

Notes

What happens if you make changes to your fork after sending the pull request? A new option will appear, called update pull request. This option is visible to anyone who has writer permission on your fork, and to anyone who has writer permission on the original repository.

Can you see a diff between your fork and the original repository without sending a pull request? Yes. Click the compare fork option.

Can you see what has changed in the original repository since you made the fork? Yes. Click the compare fork option, then click incoming.

What happens if there is a conflict between the two repositories? If someone else has made a change in the original repository that conflicts with your own code:
- bitbucket will show you the conflicting lines of code. It will also display the code you need to pull the changes and merge them into your repository.
- You will then resolve the conflicts by comparing the lines of code and fixing them as necessary. Then you will push the changes back to your fork.