Skip to end of metadata
Go to start of metadata

When creating a new repository, you can import code from an existing project into Bitbucket. You can do this using the Bitbucket importer or you can do this by pushing code from your local system to an empty Bitbucket repository.

If you are interested in migrating away from Subversion to Mercurial and bringing your history along, see Goodbye Subversion, Hello Mercurial: A Migration Guide in Atlassian Blogs.

Import an existing, unversioned code project to an empty repository

If you have code on your local machine that is not under source control, you can put it under source control and import it into Bitbucket. To do this:

  1. Locally, change to the root directory of your existing source.
  2. Initialize the directory under source control.

    git init

    hg init .

  3. Add the existing files to the repository.

    git add .

    hg add .

  4. Commit the files.

    git commit -m "message"

    hg commit -m "message"

  5. Log into Bitbucket.
  6. Create a new repository.
  7. Locate the Getting Started panel.
  8. Choose I have code I want to Import.
  9. Follow the directions in the pane for your repository.


Import from a hosting site or project using the importer

You can import from popular code hosting sites like GitHub or SourceForge, or from Git, Google Code, Mercurial or Subversion repositories, via the Bitbucket importer. The importer cannot convert Git repositories to Mercurial repositories or vice versa. When you import code from an external Git or Mercurial repository, the importer simply creates a clone of the repository which is then hosted in Bitbucket.

Bitbucket does not host Subversion repositories. When you import from a Subversion repository, the importer:

  • exports a working copy of your trunk code base
  • builds a new DVCS repository
  • commit the entire working copy as a single DVCS changeset into the new repository on Bitbucket.

Bitbucket does not retain the history when importing code from Subversion.  If you would like to retain your Subversion revision history in Bitbucket, you must perform an offline synchronization. This may take a long time to complete and be CPU intensive, depending on the size of your repository, the number of revisions, branches and tags in your repository.

To import code do this.

  1. Choose Repositories > import repository from the menu bar.
  2. Select the Source of the code you want to import. 
  3. Depending on the Source, the system asks you to provide the following information:

    SourceInformation you must supply
    CodePlexURL, Project name, Repository type
    Git/GitHubURL, a Username/Password combination for private repositories that Require authorization
    Google CodeURL, Project name, Repository type
    MercurialURL, a Username/Password combination for private repositories that Require authorization
    SourceForgeURL, Project name, Repository type
    SubversionURL, a Username/Password combination for private repositories that Require authorization
  4. Enter a Name for your new repository.
  5. Uncheck Private if you want the repository to be Public.
  6. Select a Language
  7. Click Issue tracking and/or Wiki if you want those features.
  8. Enter a Description and Website if you wish.
  9. Press Import.

Uploading or pushing a Git or Mercurial project to an empty repository

You can upload an existing repository to a empty project in Bitbucket. When you do this, Bitbucket maintains your commit history.

Pushing a Git project


This kind of push overwrites the contents of the Bitbucket repository. You should use it with great caution.

  1. Create an empty repository in Bitbucket.
  2. Open a shell on your local machine (GitBash terminal for Windows users).
  3. Verify your SSH key is working.

    $ ssh -T
    conq: logged in as tutorials.
    You can use git or hg to connect to Bitbucket. Shell access is disabled.

    The message should report you are logged in as your Bitbucket account. In this example, my ssh key was on my tutorials account. If you don't get this message, stop and troubleshoot your SSH connection to Bitbucket. (See Use the SSH protocol with Bitbucket for information about doing this.)

  4. Navigate to the root directory of the repository you want to push.

    $ cd ~/repos/originalrepo
  5. Push the local repo up to Bitbucket

    $ git push --mirror

    This command pushes your local repository to the Bitbucket server.

Push Several Branches at Once

If you want, you can push several branches at once to your Bitbucket repository. To do this, do the following:

  1. Checkout each branch to your local repository from your existing Git host.
  2. List all the branches to make sure you have what you want:

    git branch -a
  3. Make sure the remote origin in your local repository points to Bitbucket.
    For example, if you are using ssh with Bitbucket, you would use the following:

    git remote set-url origin ssh://
  4. Then push all the branches to Bitbucket:

    git push -u origin --all


Pushing a Mercurial project


This kind of push overwrites the contents of the Bitbucket repository. You should use it with great caution.

  1. Create a new, empty repository on Bitbucket.
  2. Go to your local machine and start the TortoiseHg Workbench.
  3. Select the repository you want to push from the Repository Registry.
  4. Choose File > Settings from the menu bar.
    The TortoiseHg Settings dialog appears. It includes a tab for your global settings and a tab for the repository you selected.
  5. Select the tab for the repository settings.
  6. Click Edit File.
  7. Change the default value.
    This value is the repository on Bitbucket you want to push to:
  8. Press Save to save your edits and close the file.
  9. Press OK to close the settings.
  10. Press Push outgoing changes to selected URL.
No TortoiseHg Workbench Available?

The TortoiseHg Workbench was introduced in version 2.0. If you don't have this version of TortoiseHg, you can upgrade.  Alternatively, you can:

  1. Change to the root of your Mercurial repository.
  2. Change to the .hg subdirectory.
  3. Edit the hgrc file.
  4. Edit the default value making sure to specify the address of the empty repository you created in Step 1.
  5. Save and close the file.
  6. Push the repository.


The following users contributed tutorials that provided information which improved this page. Thank you.

After I redid this page, I deleted the old comments that no longer applied. You can find them here as an attachment.


  1. Anonymous

    Does the this feature support the new SourceForge format? Because it the URL that it says for my project is incorrect. This is what it says: but it should be would be nice if we could just enter the URL manually.

  2. Anonymous

    Before importing the existing repository, don't forget to commit first!

  3. The instructions for pushing a Mercurial repository to a new empty repository on Bitbucket start with

    This kind of push overwrites the contents of the bitbucket repository. You should use it with great caution.

    That's not true: you can never overwrite anything when running "hg push", it's an append-only operation. Furthermore, Mercurial will refuse to push into an unrelated repository by default. Here, the empty repository is related to any other repository and so the push is allowed.

  4. OK - so can import from an existing Git repo (e.g., an OSS project). How though do we then later pull updates from that repo directly to Bitbucket (the equivalent of "git pull")? Or is that not possible and we have to pull to a local clone, then push the changes to Bitbucket (which requires double the amount of data transfer)?

    I.e., is there any concept of "remotes" and "pull" within Bitbucket, or is the initial clone just a one off import?  If not, it seems bizarre that you'd have  advanced diff tools, pull request workflow, etc, but not a means to do a simple pull from the original clone origin!  If a pull is possible, is there a way to manage the remote URL later (e.g., if it changes)?  And can we add multiple remotes, like when working with Git locally?

    1. If you have an existing Git repo, you should just be able to configure your remote origin to be your new BB repo. Remove the existing remote:

      Add in the new BB remote:

      Then, yes, you would just later do push/pull as you would normally.  Hope this helps.

      1. Hi Mary - not a local pull, a pull issued directly on the Bitbucket server, to update the repo from the origin. Otherwise we have to do a pull locally, then push those updates up to Bitbucket - twice as much data and potentially slow for large updates. If this isn't possible, it seems strange - cloning an existing third-party repo, then not being able to pull updates to BB (directly)!

        1. B,

          If you have imported your repo into Bitbucket. Then, you need to set your remote origin to the remote Bitbucket repo. Both of these are  one-time setup tasks.

          After that, you simply push and pull from the local clone as you normally would.  Both the push and pull commands act on the remote origin you have configured — which is the repository on the Bitbucket server.

          If that doesn't make sense, sadly, you may have exhausted my understanding and my ability to help.  Please go ahead and ask for further clarification from


    2. Anonymous

      concerning that this question cannot be answered by Atlassian documentation.  creating got mirrors is such a common thing in distributed  VCS.  The question is straightforward.  How can we create a mirrored repository in gitbucket that can pull from the origin it is tracking/mirroring without needing to use my local clone of the mirror as an intermediary?  indeed without this capability I don't see much benefit of bitbucket over a gerrit installation on my own servers.  please atlassian answer this basic  for us all.

      1. You should file a ticket with — I track the Support calls and will incorporate the answer into the documentation.

  5. Anonymous

    The Importer says: "If you would like to bring your Subversion revision history with you to Bitbucket, you will need to perform an offline synchronization." Is there a documentation for that? I have no idea on how to do that.Thx in advance. 

    1. Anonymous

      PS.: i want to convert to git!

    2. Ok, I did it. I wanted to move my subversion project entirely to git, so I can delete my subversion project later on and continue with git on bitbucket.  But I did'n want to loose all the commit history which happens when simply using the importer.

      I did the following in the terminal:

      $ cd /path/to/my/repo

       $ git svn clone --no-minimize-url --no-metadata -A authors.txt -b branches -T trunk -t tags https://svn.path/to/my/project/ repoName


      What is what:

      git svn

      # creates a svn repo inside of the git repo. You might have to install this feature into git first. 

      # Wird hier nur einmalig genutzt um den Export zu erstellen, danach egal.

      # Initializes the git repo with that data out of the svn repo including the commits (takes some time)

      # seperates your project from your svn if you have more than one 

      # Don't map the commit numbers from git to svn because i will delete svn in my case

      -A authors.txt
      #  use this file to map the users to the bitbucket users. Example file:

      user1 = Name LastName <>
      user2 = Tim Bold <>

      -b branches -T trunk -t tags
      # since svn doesn't have strict naming conveniences with trunk, branches and tags you need to map these to the branches,trunk and tag conveniences in git  

       https://svn.path/to/my/project/ repoName
      # SVN Url and the local repository name 

      Now start importing your lokal svn to bitbucket as explained:

      $ cd /path/to/my/repo
      $ git remote add origin ssh://<user>/<projekt>.git
      $ git push -u origin --all   # to push changes for the first time

      That's it.  Hope that helps someone..

  6. Anonymous

    If I'm importing from a pre-existing git repo, I am going to want to pull post-import changes from the origin (the one I cloned using bitbucket) to my bitbucket master (the one I cloned using the web tool).

    Is there a way to cause the bitbucket master to perform a git fetch from origin?  Or do I need to configure my local repo to fetch from both origin and master, and then push updates I locally fetch, merge, and commit up to bitbucket?

    My issue is that I'm trying to follow and run my own repo for an open-source project (OpenSim) which master is not on bitbucket or on github.  I have cloned its master (what I now refer to as 'origin') to bitbucket, and I'd like to have bitbucket do the fetch from origin instead of having to fetch from origin on my local machine and then push it to bitbucket.

    I believe that this is the issue which B Johnson also has.

  7. Anonymous

    How can I import a mercurial repo that uses hgnested?

  8. Anonymous

    I have a git account and a repo. I need to create another repo in another machine. how do i link that to bitbucket. I need to import to the new machine and i tried to checkout my repo, but the connection is always refused.

    1. It is hard to diagnose from what you have said. It would help to see the command you are entering and the output you are getting.  Can you paste that here?

      If you are connecting with SSH, you should review Troubleshoot SSH Issues.  


  9. Anonymous

    What if I want to import a repo from git , and i have setup ssh key authorization there. How to import that repo using importer?

  10. How can I import a repo exclusively via ssh? We're moving from our own privately-hosted Git server to use Bitbucket and are trying to import all our repos. We do not support git://, http://, or https:// for our Git server, so I can't enter our project URLS in the importer. We only have ssh access to push/pull to our repos, i.e. from home I can do git clone git@our-server-ip:some-project in a Bash prompt. 

    Currently I'm manually cloning a repo locally, adding a remote to a BitBucket repo I just created, pushing to BitBucket, then deleting the local repo. It'd be real nice to use the importer instead! 


    1. James,  

      Please email they may be able to suggest another way to do this.


  11. I followed the standard import instructions (git push -u origin --all) and the commit history was transferred as well from my local repository.

    Given that the commit history was kept, I believe the following is misleading:

    Uploading or pushing a Git or Mercurial project to an empty repository
    You can upload an existing repository to a empty project in Bitbucket. When you do this, Bitbucket maintains your commit history.

    I'm not sure why anyone would want to upload the repository instead of following the provided import instructions.  Can someone please update this document with clarifications?

  12. Hello Ladies and Gents,

    I would first like to say thank you for all the hard work and collaboration that everyone puts into this project. I hope that in time, I'll be able to help others with understanding BB and all of Atlassian's products; however, I am a beginner.

    I've successfully installed GitBash, and got my SSH keys, both public and private, working wonderfully on my machine and inside of Bit Bucket but this topic stumps me from the very first step.

    What does:

    1. "Locally, change to the root directory of your existing source." mean?

    I'm familiar with Git Bash, and various shell command prompts, but I can't seem to figure out how to bury into a directory on my local machine. Can someone perhaps help me answer the first question I have?

    Thanks so much, Zacchaeus.

    1. Sounds to me like you should be using the "cd" command to the root directory of your project, unless I'm not understanding your question.  This is very basic shell stuff, so I don't understand how you can say that you're familiar with various shell command prompts and still have trouble with this.  See here for example specific to your question.

      1. Thank you Alex. I figured it out shortly after I posted this; but if I'm not mistaken, I think the cd command cannot be used in Windows Shell, but only in Linux.

        1. Glad you figured it out.  Sorry if I was harsh.

          "cd" command is pretty universal.  Windows also supports this command, although the path formats will be a little different.  I think it's the 2nd command I learned 20 years ago, right after "dir".

    2. Alex is correct, if not a bit harsh, in the basics of his answer. You can switch to the local directory by using the following from the command line:

      Change directory

      Hope that helps.

      1. Dan~

        Thanks so much. Yeah, I figured it out shortly thereafter. Appreciate the feedback.


  13. I want to verify that when using the Bitbucket importer from SVN to Git, the code imported will have the contributor's name of the person that imports the code. The user of the last commit in SVN of that will NOT be brought over into the Bitbucket repo. 

    In order to have the SVN author in the new Bitbucket repo, you have to go through the steps to migrate using something like git-svn.

    Is this correct?