Bitbucket: Branch or fork your repository

Share At:

How to create and merge a repository on Bitbucket - FoxuTech

There are a number of ways to get your Bitbucket Cloud 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 colleagues 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.

We recommend branching for development organizations 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 organization 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.

Branch a Repository

Branching offers a way to work on a new feature without affecting the main codebase. You can create a branch from Bitbucket, Jira Software, or from your terminal. After you make changes, you push your branch to Bitbucket so that you can get it reviewed with a pull request.

Creating a branch

There are three ways to create a Git branch: In Bitbucket, at your local command line, or in Jira Software.

If possible, create branch names that don't contain special characters, as these would need to be escaped. A safe default set of characters to use for branch names is the following:

- The English alphabet (a to z and A to Z)
- Numbers (0 to 9)
- A limited set of punctuation characters:
     -period (.)
     -hyphen (-)
     -underscore (_)
     -forward slash (/)

To avoid confusion, you should start branch names with a letter.

To create a branch from Bitbucket

  1. From the repository, click + in the global sidebar and select Create a branch under Get to work.
  2. From the popup that appears, select a Type (if using the Branching model), enter a Branch name and click Create.

Note: Whenever you create a branch from Bitbucket or from an issue in Jira Software, Bitbucket removes characters that are invalid in references, file systems or shell, and replace them with a valid substitute.

  1. After you create a branch, you need to check it out from your local system. Use the fetch and checkout commands that Bitbucket provides, similar to the following:
$ git fetch && git checkout <feature>
  1. Make your changes locally and then add, commit, and push your changes to the <feature> branch:
$ git add .
$ git commit -m "adding a change from the feature branch"
$ git push origin <feature>
  1. Click the Source page of your repository. You should see both the main branch and the <feature> branch in the branches dropdown. When you make commits to the feature branch, you’ll see the files specific to that branch.

To create a branch locally

You can create a branch locally as long as you have a cloned version of the repo.

  1. From your terminal window, list the branches on your repository.
$ git branch
1 * main
  1. This output indicates there is a single branch, the main and the asterisk indicates it is currently active.
  2. Create a new feature branch in the repository
$ git branch <feature_branch>
  1. Switch to the feature branch to work on it.
$ git checkout <feature_branch> 
  1. You can list the branches again with the git branch command.
  2. Commit the change to the feature branch:
$ git add .
$ git commit -m "adding a change from the feature branch"
  1. Switch back to the main branch.
$ git checkout main
  1. Push the feature branch to Bitbucket:
$ git push origin <feature_branch>
  1. View the Source page of your repository in Bitbucket. You should see both the main and the feature branch. When you select the feature branch, you see the Source page from that perspective. Select the feature branch to view its Recent commits.

The branching model

You can use the branching model to define a branch based workflow for your repositories. When you map your workflow to branch types, you can ensure that branches are named consistently by configuring which branch types to make available. We’ve suggested some branch prefixes you might want to use but you can also specify your own naming convention. A consistent naming convention makes it easier to identify branches by type. You can also define which branches are your development and production branches, which allows us to better suggest source and target branches for creation and pull requests.

Branch types

There are several types of branches that are frequently used in software development. This section explains what each branch type is for, and the typical prefix convention for each branch type. In Bitbucket, the prefix can be changed for all branches other than development or production.

Development branch
Usually the integration branch for feature work and is often the default branch or a named branch. For pull request workflows, the branch where new feature branches are targeted.
Production branch
Used for deploying a release. Branches from, and merges back into, the development branch. In a Gitflow-based workflow it is used to prepare for a new production release. 
Feature branch
Used for specific feature work or improvements. Generally branches from, and merges back into, the development branch, using pull requests.
Release branch
Used for release tasks and long-term maintenance versions. They are branched from the development branch and then merged into the production branch.
Bugfix branch
Typically used to fix Release branches.
Hotfix branch
Used to quickly fix a Production branch without interrupting changes in the development branch. In a Gitflow-based workflow, changes are usually merged into the production and development branches.

Configure a repository’s branching model

To configure the branching model for a repository (requires repository admin permission):

  1. Go to Repository settings
  2. Under Workflow select Branching model
  3. Choose the details of your repository branching model, then click Save

Listing commits on a branch

Bitbucket maintains a list of commits by branch. The list shows only the open branches with pending commits ahead of your main branch.  To view the commits associated with a particular branch, view your repository and do the following:

  1. Go to the Commits page.
  2. Choose Show all if All branches isn’t already selected.
  3. Click the commit tag link to drill down to its contents.

Closing a branch

It’s important to prune branches from your repository on a regular basis. Closing a branch deletes the branch from the Bitbucket interface. It does nothing to the branch in your local repository. You must delete that using the command associated with Git or Hg as applicable.

You can close a branch in two ways:

  • From the Branches page of the repository, hover over the options link on the right side and pick Delete branch.
  • When you create a pull request on a branch, pick the Close branch checkbox, which closes the branch when the pull request merges.

Bitbucket maintains a list of commits by branch. The list shows only the open branches with pending commits ahead of your main branch.  To view the commits associated with a particular branch, view your repository and do the following:

  1. Go to the Commits page.
  2. Choose Show all if All branches isn’t already selected.
  3. Click the commit tag link to drill down to its contents.

Bulk-delete branches

You can delete branches in bulk by following these steps:

  1. In your repository go to Branches.
  2. Click () > Delete multiple.
  3. Check the branches you want to delete and click Delete selected branches.
  4. Confirm your selection.

Fork a repository

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.

Happy Learning !!!

Share At:
0 0 votes
Article Rating
Notify of
Inline Feedbacks
View all comments
Back To Top

Contact Us