Bitbucket Backup



Bitbucket Backup is a backup tool which clones/pulls all your Bitbucket repositories to your local machine.


How does it work?

Bitbucket Backup uses the Bitbucket API to get a list of all your repositories.
Then, it uses Mercurial and/or Git (which need to be installed on your machine if you have at least one repository of the given type) to clone every repository into your local backup folder (or just pull the newest changes if it already is in your local backup folder).
It also checks for each repository, whether it has a wiki (which is a repository itself). If yes, that will be automatically cloned/pulled as well.


System requirements:

  • Windows (at least XP)
  • .NET Framework 4 Client Profile (of course it works with the full framework as well, but Client Profile is enough)
  • Mercurial (any version) if you have Mercurial repositories
  • Git (at least version 1.7.x) if you have Git repositories

Please note that Bitbucket Backup assumes that you have the Mercurial and Git executables in your %PATH% variable.
(depending on the version, Git may come with a git.exe AND a git.cmd - it doesn't matter which one is in the %PATH%, Bitbucket Backup will find both)

To install Bitbucket Backup on your machine, just run the setup.
If you want a "portable" version without installer, there's a .zip download with the binaries as well (starting with version 1.3.2).

When you run Bitbucket Backup the first time, it will ask you for:

  1. Your Bitbucket username and password
    This user's repositories will be backed up.

  2. Your Bitbucket team name (optional)
    If entered, the repositories of that team will be backed up instead of the user's repositories.
    The user is still needed for authentication.

  3. A backup folder on your local machine
    The folder must already exist, Bitbucket Backup won't create it!

  4. Timeout for pulling (optional, Mercurial only)
    By default, Mercurial times out after 60 seconds. You may want to increase that value if you have large repositories or a slow connection.

After that, Bitbucket Backup will run without user interaction, but you can re-enter your data any time by pressing SPACE on startup.

What is actually backed up and how do I restore from that backup?

Bitbucket Backup creates local repositories and pulls from the remote Bitbucket repositories into the local ones.
Those local repositories are bare repositories, i.e. they don't contain a working directory.

When you look inside the repository directories, you'll see this:

  • Mercurial: A single folder named .hg
  • Git: Some folders (objects, refs, ...) and some files

Your complete history and your source code are in there - you just don't see the actual files.
The repository is backed up without a working directory, because it's not necessary. All the data already exists inside the repository, a second copy of everything in the working directory would just be a waste of space.

The easiest way to restore your working directory is to clone the bare repository that Bitbucket Backup created (called bare-repo in the examples), which will create a clone with a working directory (called working-repo in the examples):


hg clone bare-repo working-repo 

It's also possible to create the working directory directly inside the bare repository:

cd bare-repo
hg update tip


git clone bare-repo.git working-repo

(Note: It seems the Git tools do not like cloning from a bare repository that does not end in the .git extension, so Bitbucket Backup automatically appends it to all Git repositories)

For more background information (and the discussion that led to the creation of this section) see this issue.


How to build

To create a release build, just run build.bat or build-setup.bat in the main folder.

  • build.bat will create a new folder named release\bin with the compiled exe and all necessary files.
  • build-setup.bat will do the same, and additionally create:
    • a release\msi folder with a MSI setup
    • a release\zip folder with a ZIP file (containing the content of the release\bin folder)


Bitbucket Backup makes use of the following open source projects:



Bitbucket Backup is licensed under the MIT License. See License.rtf for details.

Project Info