In CVS or Subversion, you create branches by starting with either the head/trunk or an existing branch. 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 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.
How to Fork a Repository
- Locate the repository you want to fork.
You can use the search area in the Bitbucket menu bar.
- Navigate to the repository.
- Click the Fork button.
The system displays the Fork dialog:
Define options for your fork.
Option Description Owner This defaults to the logged-in account. If you have the rights to create repos under more accounts (for example a team), this is a drop-down. Name Name of your fork. This defaults to the same name as the original repository. Description Explains the purpose of the fork. 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 acces 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 limits 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. Project Management Choose whether you want an issue tracker or wiki for your fork. By default, Bitbucket defaults to the same values as the original repo. Fork at Choose at what point in the code to fork the repository. This option is only available for Mercurial repositories that have one or more branches, tags, or revisions. This option is never available for Git repositories.
- Press Fork repository.
The system creates the fork and opens the page to its Overview page.
Using the Bitbucket GUI to sync your fork to the original repo
After you fork a repository, the original repository is likely to continue to evolve as other users commit changes to it. These changes do not appear in your fork. You can, however, pull these changes into your fork later by going to Bitbucket and doing the following:
- Go to your fork.
- Click the Compare button.
By default, the system shows you outgoing changes. That is, changes made on your fork that do not exist in the original repository.
- Click Incoming to see what changes were made in the original that do not exist on your fork.
Bitbucket lists any changes it finds and provides instructions for merging the changes in the local repository.
- Merge the changes on your local clone of the fork.
- Push the changes back to your remote repository.
Sync changes from the command line
You can also synch changes locally from the command line without using the Bitbucket GUI.