Import code from an existing project

Learn how to get your existing code into Bitbucket Cloud quickly from another hosting site or your local system.

Use the importer in Bitbucket to grab a repository from another hosting site.

Or learn how to create and push your first DVCS repository, or push an existing Git or Mercurial repository from your local system to Bitbucket.

This page

Related pages

Git Tutorial
Everything to get someone new to Git and Bitbucket going.

Getting Git Right
All about Git from beginner to advanced workflows. 

Converting from another version control system

If you have an SVN repository you'd like to convert to either Git or Mercurial see one of the following:

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:

    Source Information you must supply
    CodePlex URL, Project name, Repository type
    Git/GitHub URL, a Username/Password combination for private repositories that Require authorization
    Google Code URL, Project name, Repository type
    Mercurial URL, a Username/Password combination for private repositories that Require authorization
    SourceForge URL, Project name, Repository type
    Subversion URL, 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.

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 Hg
    git init

    hg init .

  3. Add the existing files to the repository.

    Git Hg
    git add .

    hg add .

  4. Commit the files.

    Git Hg
    git commit -m "message"

    hg commit -m "message"

  5. Log into Bitbucket.
  6. Create a new repository.
  7. Locate the Getting Started panel (4).
  8. Choose I have an existing project.
  9. Follow the directions in the pane for your repository.

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 Cloud 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.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

33 Archived comments

  1. User avatar


    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.

    17 Apr 2012
  2. User avatar


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

    01 Jul 2012
  3. User avatar

    Martin Geisler

    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.

    10 Jul 2012
  4. User avatar

    B Johnson

    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?

    08 Dec 2012
    1. User avatar


      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.

      10 Dec 2012
      1. User avatar

        B Johnson

        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)!

        10 Dec 2012
        1. User avatar



          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


          10 Dec 2012
    1. User avatar


      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.

      20 Nov 2013
      1. User avatar


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

        20 Nov 2013
  5. User avatar


    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. 

    18 Jan 2013
    1. User avatar


      PS.: i want to convert to git!

      18 Jan 2013
    1. User avatar

      Dennis Hahn

      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..

      23 Jan 2013
  6. User avatar


    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.

    01 Mar 2013
  7. User avatar


    How can I import a mercurial repo that uses hgnested?

    17 May 2013
  8. User avatar


    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.

    31 Oct 2013
    1. User avatar


      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.  


      31 Oct 2013
  9. User avatar


    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?

    08 Nov 2013
  10. User avatar

    James Mehorter

    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! 


    26 Nov 2013
    1. User avatar



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


      26 Nov 2013
  11. User avatar

    Alex Feldman

    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?

    31 Dec 2013
  12. User avatar

    Zacchaeus Nifong

    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.

    05 Jan 2014
    1. User avatar

      Alex Feldman

      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.

      10 Jan 2014
      1. User avatar

        Zacchaeus Nifong

        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.

        10 Jan 2014
        1. User avatar

          Alex Feldman

          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".

          10 Jan 2014
    1. User avatar

      Dan Stevens [Atlassian]

      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.

      10 Jan 2014
      1. User avatar

        Zacchaeus Nifong


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


        10 Jan 2014
        1. User avatar

          Dan Stevens [Atlassian]

          Great! Glad to hear it.


          10 Jan 2014
  13. User avatar

    Chris Miles

    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? 

    04 Feb 2014
  14. User avatar

    Benjamin Brink

    B Johnson,

    Your post is a bit old, but I had a similar question: How to import changes to Bitbucket hosted git repository from an essentially forked project hosted on github?

    github answers the question for merging between a forked project and it's original:

    and am editing to add a document on a related topic by Atlassian:!workflow-forking


    29 Aug 2014
  15. User avatar

    Eric Anderson

    Why was the separate documentation page on "Convert from other version control systems" (note the plural) deleted?

    By contrast, the small section above in this current page on "Converting from another version control system" (note the singular) covers only methods of  conversion from Subversion – just one source VCS covered.  The deleted page addressed other version control systems, including comments that covered how to use fast-export and fast-import to convert from a diverse set of VCSs to either Git or Mercurial.  An example was given using the Bazaar VCS as the source system and Git as the destination system.

    Shouldn't at least the fast-export and fast-import methods be made known so that people who start from something other than Subversion have a solid option?

    16 Oct 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Hey Eric,

      That didn't take long. I'm trying to pare down the space a bit and work on some new IA and page layouts. I moved the page "off the grid' in error. I'm restoring it now. I'm still thinking of removing it but after I have a better compilation of the content and comments. 

      Sorry about that. (sad)

      Happy coding,


      16 Oct 2014
      1. User avatar

        Eric Anderson

        From the start, my hope was that the information on how to effectively use fast-export piped to fast-import would not remain hidden away in the comments, but rather that the Atlassian "documentation for converting from other version control systems should be updated to include the standard method of using fast-export with fast-import."  So I fully support the idea that the old page could be removed once you "have a better compilation of the content."  I agree that there is a certain clunkiness to having multiple pages on converting from other VCSs, where these pages refer back and forth to each other (e.g. redundantly addressing coming from SVN on multiple pages).

        My main caution would be about taking care to not lose certain valuable details, which were not easy to come by in one place.  For example, not all of the web pages discussing this method will mention the valuable --rewrite-tag-names option, while others that might include that will omit mention of renaming the ignore file, or might not explain how to first populate the work space files (which can be quite obscure for those new to git).  For some people, the link to the script for converting special field information to git format might be vital (else they would lose too much information).

        17 Oct 2014
        1. User avatar

          Dan Stevens [Atlassian]

          Thank you for making such a clear and complete case for better doc on this. I'll do my best to create something which matches this criteria. It's often a challenge in an organization to determine where information will live so as not to duplicate and duplicate efforts and to put our energies where they will do the most good for our customers and the community at large.

          Happy coding,


          17 Oct 2014
Powered by Confluence and Scroll Viewport