Fork a repository

We’re removing Mercurial support on June 30, 2020

Mercurial features and repositories will be removed from Bitbucket and its API on June 30, 2020. Creating new Mercurial repositories on Bitbucket was disabled on February 1, 2020. Learn more

In Git and Mercurial, you create branches by starting with either the head/trunk or an existing branch. When you do this, your changes become part of the main project repository. If you want to work on a completely separate copy of the project, you may want to consider creating a 'fork'. 

Forking is a way for you to clone a repository at a specific point, and to modify it from there. To fork is just another way of saying clone. Bitbucket Cloud manages the relationship between the original repository and the fork for you. Forking is particularly useful 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 on Bitbucket.

  • Clone the forked repository your local system.

  • Modify the local repository.

  • Commit your changes.

  • Push changes back to the remote fork on Bitbucket.

  • Create a pull request from the forked repository (source) back to the original (destination).

The final step in the workflow is for the owner of the original repository to merge your changes.

Fork a repository

  1. Go to a repository, click + on the leftmost global sidebar and select Fork this repository at the bottom of the lists.

  2. In the Fork dialog, define the options for your fork.

Workspace: This defaults to the logged-in account. If you have the rights to create repositories in more than one workspace, this is a drop-down.

Project: Name of your project.

Name: This is the name the forked repo will have.

Access level: By default, the system creates your fork with the same access level as the original. So, if the original is public your fork is too. You can change this, making your fork private. An administrator of the original repository can prevent public forks; In this case, then you cannot change the access.

Permissions: By default, your fork inherits the user/group permissions. For example, if 4 accounts have access to the original your fork will give them the same access. Forking a public repo under your account can cause you to go over the limit on your Bitbucket plan. You can avoid the impact to your plan by making your fork private or by not inheriting the users from the original repo.

Forking: Choose whether you want to allow only private forks.

3. Click Fork repository.
The system creates the fork and opens the repository's Source page.

Sync your fork

After you fork a repository, the original repository is likely to evolve as other users commit changes to it. These changes do not appear in your fork automatically; you need to sync the fork in order to pull in any outstanding commits. 

  1. Access the fork.

  2. If your fork is behind on commits, the Sync button displaying the number of outstanding commits will be displayed at the bottom of the Repository details pane on the rightmost sidebar.

  3. To sync your fork with the original repository, click the Sync button at the bottom of the Repository details pane.

  • Only the main branch of the repository is synced with your fork. No other branch changes will be detected or available to sync.

  • To sync branches that are not the main branch of the repository, you need to select the branch you want to sync as the main branch on both the parent and forked repository. Once you do this the Sync button will be displayed in the Repository details pane on the rightmost sidebar of the repository's Source page.



Last modified on Aug 11, 2020
Cached at 6:06 AM on Oct 30, 2020 |

Additional Help

Ask the Community