Branch or fork your repository

There are a number of ways to get your Bitbucket repository code so that you can work on the project. Each method is slightly different and is done for different reasons.  

What is a branch? What is a fork?

Branching and forking provide two ways of diverging from the main code line. Both Mercurial and Git have the concept of branches at the local level. A repository code branch, like a branch of a tree, remains part of the original repository. The code that is branched (main trunk) and the branch know and rely on each other. Like a tree trunk's branch, a code branch knows about the trunk (original code base) it originated from.

Fork is another way of saying clone or copy. The term fork (in programming) derives from an Unix system call that creates a copy of an existing process. So, unlike a branch, a fork is independent from the original repository. If the original repository is deleted, the fork remains. If you fork a repository, you get that repository and all of its branches.

As DVCS hosting evolved, the term fork evolved. The Bitbucket software adds management to forks; forking a repository in Bitbucket has functionality you normally wouldn't associate with a simple DVCS clone. For example, on Bitbucket, you can always see which repository the fork came from. This isn't the case with a DVCS clone on your local system.

A comparison of branching and forking

Whether you use either branching or forking, and to what extent, depends on your working environment. There are lots of ways a team can work with and combine fork and branch functionalities. You can google for discussions about this. Generally, for hosted systems, forks work well in situations where, as a repository admin:

  • You don't want to manage user access on your repository. 
  • You want fine-grain control over merging.
  • You expressly want to support independent branches.
  • You want to discard experiments and changes easily.

The Bitbucket team recommends branching for development teams on Bitbucket; We use a modified form of Vincent Driessen's GitFlow technique. Bitbucket branches are useful when:

  • You have a small group of programers who trust each other and are in close communication.
  • You are willing to give the development team write access to a repository.
  • You have a rapid iteration cycle.

Ultimately, though it is your choice – branch or fork – Bitbucket supports both.

Cloning a repository fork or branch

When you want to work on a project by updating its files or adding new files, you need to make a local clone of the remote Bitbucket repository onto your machine or local network. You do this using the Clone button from the Bitbucket repository. If you forked a repository, you simply clone the fork. If you branched a repository, you clone the repository and checkout the branch.

Read about how to clone a Bitbucket repository.

Was this helpful?

Thanks for your feedback!

2 Archived comments

  1. User avatar

    lu yuan

    Could you please explain more clearly on these two sentences?
    • You expressly want to support independent branches.
    • You want to discard experiments and changes easily.
    27 Aug 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Hello,

      I didn't write this section but I believe they mean: 

      • You expressly want to support independent branches: means you want to be able to have completely separate development environments. When you fork a repository you create a new repository and though the two are linked (you can create pull requests from one to the other, for example) so you can create branches and develop code in the fork with no impact to the origin repository. (on a personal note, the more I use Git I prefer branches, you can do most of the same things and don't have to manage two repositories, but that's just me)
      • You want to discard experiments and changes easily: means you can create a fork as a "sandbox" to basically do anything you want, for example you might use a fork to try out a crazy idea or a new integration. 

      Thanks for taking the time to comment!

      Happy coding!

      27 Aug 2014
Powered by Confluence and Scroll Viewport