Skip to end of metadata
Go to start of metadata

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

  1. Locate the repository you want to fork.
    You can use the search area in the Bitbucket menu bar. 
  2. Navigate to the repository.
  3. Click the Fork button.
    The system displays the Fork dialog:
  4. Define options for your fork.

    OptionDescription
    OwnerThis 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.
    NameName of your fork. This defaults to the same name as the original repository.
    DescriptionExplains the purpose of the fork.
    Access levelBy 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.
    PermissionsBy 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 ManagementChoose whether you want an issue tracker or wiki for your fork. By default, Bitbucket defaults to the same values as the original repo.
    Fork atChoose 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.
  5. 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:

  1. Go to your fork.
  2. 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. 
  3. 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.
  4. Merge the changes on your local clone of the fork.
  5. 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.

 

 


20 Comments

  1. Anonymous

    Lets say I created fork from my original branch O into F. While I am working in F, there are new commits made to O. How do I pull delta changes from O into F?

    1. In this case, F is your fork and O the original.  So, you would do the following:
      1. Go to your forked repository F.
      2. Click the Compare button.
      3. Click Incoming to see what changes were made on the source O.
        If the system finds there were changes on O not in F, it provides instructions for merging them. 
  2. Anonymous

    I have a private repo If I give read permissions to a user, can he fork it? And if he can, will it force a private repo?

  3. A new feature of bitbucket is the keep in sync with the forked repository. See what's new for a screenshot under 'syncing and merging'.

  4. Anonymous

    What would happen if I just push the changes? Would that affect the changes other people had made?... and how can I just update the file in here?

    1. Your fork is in a separate silo from the original repository. If you make changes on a fork, your changes only impact your fork. When you push the changes, they push to your fork.  When you make a pull request Bitbucket bundles up your changes from your fork and sends them as a pending request on the original repository.  When the owner of the original repository accepts the request, then your changes are seen on the original repository.

      This will not affect other people's work; unless you want it to. For example, you may choose to work with another person on your fork.

  5. Anonymous

    Leaving a fork name the same as the original seems to have the potential to cause confusion. Wouldn't best practice be to give it a meaning name related to the original?  I would not have the system have a default for this.

    1. You have a point.  I think most people do switch out the default name.  

  6. merging changes from the forked git repo also can be done locally instead of clicking on a button in the web site:

    $ git remote add <remote_name> git@bitbucket.org:<upstream>/<repo>.git
    $ git fetch <remote_name>
    $ git checkout master
    $ git merge <remote_name>/master

     

     

    1. Once you've added the upstream repo to your remotes, could you just run:

      $ git remote update <remote_name>

      or optionally:

      $ git remote update <remote_name> --prune

      Are the lines following the fetch command necessary?

  7. Anonymous

    Hey, just wanted to know.... that currently I have a read only access to a repository... So I go to that repository and fork it. After cloning it to my local machine, I make my changes and commit those changes... Now my question here is that, since I have a read only access to the main repository, will I be able to push my changes to the forked repo? How does the pushing works in terms of forked repository and especially when you have a read-only access on the main repo? 

    1. You can push from your local code back to your fork on the Bitbucket remote server.  You can create a pull-request from your fork on Bitbucket back to the original repo.  It is up to the original repo owner if they want to accept your request.

      1. Anonymous

        So basically it means that even when I have read only access on the original repo, I can push may changes to the forked repo. That's nice... Thanks a lot. (smile)

        1. You forked it (which is really a clone operation) to create a new repo on the server. So now you own the new repo. You then cloned that new repo to your local machine. So pushing to your own remote repo is fine. And as Mary pointed out, it's up to the original repo owner whether they want to use any pull-request you create.

  8. Anonymous

    How can one remove his own forks(unfork)?

    1. A fork, like any other repository, can be deleted by the owner. So, yes, you can remove a fork.

  9. Anonymous

    Thanks Mary

  10. I have a site I am working on, until I'm workin on putting together a team so I already created a team on my account whilst hunting manpower.....

    I created a fork of the website to the team so that when the team comes, we all can continue and I can delegate duties now here is my question:

    is there a way to autoupdate a fork when the original gets a new commit?


    I need this so that my fork is automatically in sync with the original so that when the team come, i can totally transfer ownership to the team.

     

    Thanks in advance

  11. I have a site I am working on, until I'm workin on putting together a team so I already created a team on my account whilst hunting manpower.....

    I created a fork of the website to the team so that when the team comes, we all can continue and I can delegate duties now here is my question:

    is there a way to autoupdate a fork when the original gets a new commit?


    I need this so that my fork is automatically in sync with the original so that when the team come, i can totally transfer ownership to the team.

     

    Thanks in advance

  12. I have a site I am working on, until I'm workin on putting together a team so I already created a team on my account whilst hunting manpower.....

    I created a fork of the website to the team so that when the team comes, we all can continue and I can delegate duties now here is my question:

    is there a way to autoupdate a fork when the original gets a new commit?


    I need this so that my fork is automatically in sync with the original so that when the team come, i can totally transfer ownership to the team.

     

    Thanks in advance