Branching offers a way to work on a new feature without affecting the main code line. You can branch on a local repository and make changes without ever making that branch visible in Bitbucket. Or you can push a branch up to Bitbucket so other repository users can access and work with your changes.
There are a number of ways to branch a repository this documentation only shows you the very basic ways to branch. Review your Git or Mercurial resources to get fancy with branching. From a Bitbucket perspective, you have to do some extra work to get a branch to appear:
|Clone a repository to your local system.||Clone a repository to your local system.|
|Create a branch on your local system.|
Create a named branch.
|Push the branch to Bitbucket.|
Push the repository to Bitbucket.
Git branches always have a name. Mercurial has the concept of branch and named branch. (Steve Losh's guide is a good resource explaining branching in the two systems).
On this page:
Branch a Git repo
If you still have your
bb101practice repository from the 101, you can try these operations directly on that.
- Open a terminal window on your local system.
List the branches on your repository.
This output indicates there is a single branch, the
masterand the asterisk indicates it is currently active.
Create a new
featurebranch in the repository
Switch to the
featurebranch to work on it.
List the branches again with the
- Edit the
READMEfile and add a new line.
Commit the change to the
Switch back to the
featurebranch to Bitbucket.
View the bb101repo Source page in Bitbucket.
You should see both the master and the feature branch. When you select the
featurebranch, you see the Source page from that perspective.
featurebranch to view its Recent commits.
Branch a Mercurial repo
Create a new feature branch in the repository.
Nothing changes in the working directory. The
branchcommand tells Mercurial the branch name to use with your next commit. If you use the
hg branchescommand, you'll see you still only have the
Edit files, add files, etc, in the working copy.
- Commit your changes.
hg branchescommand again.
Push the feature branch back to Bitbucket.
Viewing Commits by Branch
Bitbucket maintains a list of commits by branch. The list shows only the open branches with pending commits ahead of master. To view the commits associated with a particular branch, view your repository and do the following:
- Go to the Commits page.
- Choose Show all.
You'll see a list of commits with branch tags to the right and a graph to the left:
- Click the commit tag link to drill down to its contents.
Closing a Branch
It is important to prune branches from your repository on a regular basis. You should close branches when you merge any final commits into the trunk with a pull request. Simply choose to close the branch with the final pull request:
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.