Restore a deleted repository for Bitbucket Server

Still need help?

The Atlassian Community is here for you.

Ask the community


This page show the steps to restore the Git history for a deleted repository.

(warning) Repository details (including permissions, settings and hooks), pull requests (including their transition and comments) will not be restored. This procedure will only allow to restore the Git history.


Case #1 - recommended option

This option can be used if a backup of the repository, taken using one of the Data backup strategy, is available.

It is the recommended option because it is based on the repository backup available on the server. Compared to a cloned repository, this will contain all the branches and tags and not just the ones available on a local clone.

  • From the available backup, locate the bare repository that should be restored.
    Since Bitbucket Server 4.12.0, each repository contains a repository-config file that helps in identifying the repository slug and the project key. 
repository-config sample file
	hierarchy = <hierarchy id>
	project = <project key>
	repository = <repository slug>

For earlier versions, the missing repository can be identified by locating the missing folder in the $BITBUCKET_HOME/shared/data/repositories folder

  • Create a new repository in Bitbucket Server
  • Retrieve the repository clone URL from the Bitbucket Server
  • Browse into the directory containing the backup of the repository and run the following commands:

    # update the repository URL with the value of the newly created repository
    git remote add origin <new repository clone URL>
    # push the Git history (including branches and tags)
    git push --all origin
    git push --tags origin

    If you have LFS enabled on the repository, you'll need to get the LFS objects and add them to the storage directory. It will be in $BITBUCKET_HOME/shared/data/git-lfs/storage. The directory name will match the hierarchy id from above. If the hierarchy ID is 74243c1b6136cd5bc266:

    1. Navigate to $BITBUCKET_HOME/shared/data/git-lfs/storage of the backup
    2. Copy 74243c1b6136cd5bc266 and all it's subdirectories and objects
    3. Add the structure copied from step 2 to $BITBUCKET_HOME/shared/data/git-lfs/storage of the production instance.
    4. Rename the directory to match the hierarchy ID from the new repository (the new hierarchy ID can be found in $BITBUCKET_HOME/shared/data/repositories/<REPO ID>. The repo ID can be found on the settings page of the new repository).
    5. Check the "Allow LFS" box for the new repository

Case #2

This option can be used if you have another similar deleted repository folder at another test or backup server. 

  1. Clone the repository from the test server into a temporary directory in your machine (including checking out all the branches and tags)
  2. Create a new empty repository in the Bitbucket Server UI
  3. If the deleted repository is an LFS enabled repository. Ensure 'Allow LFS' is enabled in the newly created empty repository settings. If it is LFS enabled repository, perform below commands.

    # Install Git LFS client if it was not already installed
    git lfs install
    # Retrieve all LFS objects
    git lfs fetch --all
  4. Run in the cloned repository.

    # Add the new origin to your clone. $target_repo_url is an empty repository created in the Bitbucket application
    git remote add $target_instance_name $target_repo_url 
  5. If it is an LFS enabled repository. 

    # Push all LFS objects
    git lfs push --all 
  6. Push all cloned data to the empty repository created at Bitbucket Server UI.

    # Push the Git history (including branches and tags)
    git push --all origin
    git push --tags origin

Case #3

This option relies on a local clone available on a workstation of a Bitbucket Server, this may not contain the entire history as available on the server prior to the deletion.

Once a viable source repository has been identified, the steps to recreate the repository are the same as above.

Existing feature request

The feature request allowing a restore of a repository including all its details is available here: 

BSERV-4586 - Getting issue details... STATUS

Last modified on Jul 30, 2021

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.