There are a number of ways to take a copy of a bitbucket repository so that you can work on the project. Each method is slightly different and is done for different reasons.
Cloning a Repository
This is useful if you have writer permission for the repository.
When you want to work on a project by updating its files or adding new files, you need to make a local copy of the project onto your machine or local network. To make a local copy of a bitbucket repository, you must 'clone' the repository. Read more about cloning a bitbucket repository.
Forking a Repository
Forking is a way for you to create an exact copy of a repository at a specific point, and take it from there. This is particularly useful if you have reader permissions for the repository but not writer permissions, and 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 of the repository. Go to the repository that you want to fork on bitbucket and click 'fork'. This gives you a copy of the code from the point where you fork it.
- Clone your new fork. Now you may clone your new repository, to create a local copy.
- Work on the files locally. Edit the files, add new files, and so on. It is your repository.
- Commit changesets to your local repository as usual.
- Push your changes up to your fork. Push your changes to bitbucket in the usual way. This will update your fork of the repository.
- Send a pull request to the owner of the original repository. Once you are satisfied with your changes, you can ask the owners of the original repository to pull in your changes and merge them into the main repository. Click 'send pull request'. bitbucket will send a notification to the owner, making it easy for you to communicate with them about your changes from this point onwards.
Read more about forking a bitbucket repository.
Branching a Repository
Branching offers a way to work on a new feature without affecting the main code line. You can branch on a local repo and make changes without ever making that branch visible in bitbucket. Or you can push a branch up to bitbucket so other repo users can access and work with your changes. There are a number of ways to branch a repository this page 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:
| Git | Mercurial |
|---|---|
| Clone a repository to your local system. | Clone a repository to your local system. |
Create a branch on your local system.git branch BRANCH_NAME | Create a named branch. |
Push the branch to bitbucket.git push origin BRANCH_NAME | Push the repo 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).
Read more about branching a bitbucket repository.
A Comparison of Branching and Forking
Forking and branching provide two ways of diverging from the main code line. Both Mercurial and Git have the concept of branches at the local level. The code that is branched and the branch know and rely on each other. Like a tree branch, a code branch knows about the tree (original code base) it originated from. The origin of the term fork (in programming) comes from an Unix system call that created a copy of an existing process. A fork is another way of saying clone. As DVCS hosting has evolved, the term fork has grown. The bitbucket software adds management to forks; forking a repo in bitbucket has functionality you normally wouldn't associate with DVCS clone. 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 functionality. You can google for discussions about this. Generally, for hosted systems, forks work well in situations where, as a repo admin, you don't want to manage user access on your repo. Branching works well in situations where you have a small group of programers who trust each other and who all have write access to a repository. The bitbucket team recommends forking rather than branching for these reasons:
- Forking creates an independent repository. These can be simpler to work with.
- If you fork, you are the admin of the repo you create and have full control over it. For example, you can add other users.
- If you need to abandon your changes, it is easier to delete a fork than a branch.
Finally, forks don't require the coordination with the repo owner that branching does. Ultimately, though it is your choice – branch or fork – bitbucket supports both.
Add Comment