Here at last – How to permanently delete/recycle projects in Gerrit
If you are using CollabNet’s TeamForge Git Integration, you may have felt the need to delete few or more repositories hosted on Gerrit for various reasons:
a) You want to delete repositories and all code reviews associated with it because you do not need the code any more and confuse users with its existance
b) You just want to create a Git repository with the same name all over again after deleting the original one, IOW recycle the project name
c) You want to save disk space
If you simply deleted the Git repository from TeamForge’s Web UI, you would only accomplish a) but not b) or c)
While all access rights to the corresponding Gerrit project will be removed, the Gerrit project itself remains and all the code reviews associated with the repository will be still shown on Gerrit WebUI (which is no reason to worry as nobody would be able to access the repository). This behavior is not by accident but by design. We have seen too many occasions where customers deleted a Git repository too early (without a backup), did a mistake during server migration or were in need of an audit trail for every single change. In those cases, Gerrit’s default behavior of just archiving the project but not making it possible to create a new one with the same name saved the day multiple times.
However, if you absolutely want to recycle a repository name and have done all necessary backups of the old repo, there should be a solution, shouldn’t it? Unfortunately, before Gerrit 2.7, if you decided to re-create a Git repository with the same name, it won’t be possible for the very reason that a repository with the same name still exists in Gerrit. Even if you go to the file system and delete the repository from the /gitroot directory, meta data associated with the repository will still continue to exist and might bring your code reviews into an inconsistent state.
So the question is how to permanently delete a Git repository/Gerrit project safely so that a new repository with the same name can be created?
Starting from Gerrit 2.7, there is finally an answer: Gerrit’s Delete-Project plug-in. Once installed, this plugin allows Gerrit administrators to delete Gerrit project’s (Git repositories) with all its references (reviews, access rights, cache references, …) in a safe way.
You can download a TeamForge Git Integration compatible version of this plug-in jar (delete-project-v2.8.7-6-g135eb93.jar) file from here. This plugin is only work if you are using version 8.2.x (based on Gerrit 2.8) of the TeamForge Git Integration. Note that, if you obtain the latest Open Source version of this plugin from Gerrit’s project page, it will not work with the TeamForge Git Integration (as it depends on a different schema version). After downloading the plugin and saving it as delete-project-v2.8.7-6-g135eb93.jar, it can be installed to Gerrit by a member of the Administrators group using the following command.
ssh -p 29418 ADMIN@GERRIT_HOST gerrit plugin install --name delete-project -<delete-project-v2.8.7-6-g135eb93.jar
Before executing command, note that ADMIN is to be replaced with username of the member who is part of the Administrators group in Gerrit. Also keep that user’s password handy, you will be asked for it. Similarly, replace GERRIT_HOST with host name of the server where Gerrit is installed.
Once the plugin is installed, Gerrit Administrators can perform project deletion operations over SSH. A documentation of all supported plugin parameters can be accessed from
So how would you properly delete a Git repository called test_repository from TeamForge so that you can reuse the same name?
First step: Delete the repository in question from its containing TeamForge project as shown in picture at beginning of this blog post. The corresponding Gerrit repository does not necessarily have the same name as the TeamForge repository but the file part of the clone URL and TeamForge directory name will match.
Second step: Delete the corresponding project from the Gerrit server
ssh -p 29418 ADMIN@GERRIT_HOST delete-project delete --yes-really-delete test_repository
WARNING:There is no sanity check whether the project you delete has already been deleted in TeamForge. If you specify a Gerrit project that still exists in TeamForge, this will cause an empty new repository being created and probably lots of trouble with your user base.
If your repository has any open reviews, the command above will suggest you to append the –force option which will also delete all open reviews along with the repository.
ssh -p 29418 ADMIN@GERRIT_HOST delete-project delete --yes-really-delete --force test_repository
Once the repository is deleted, you can go to TeamForge project and create a new Git repository with the same name again.
Finally, a (repeated) word of caution: If you use the delete-project plugin, this will permanently delete your old Git repository, IOW it prunes any repository content, any review and any other meta data related to this project. Before running this command, make sure you have a recent backup of the repository in question. For the reasons above, the project deletion plugin can only be run by Gerrit administrators. For most cases, the default Gerrit archiving behavior is just fine. Only use this plugin if you absolutely have to recycle a repository name or have to save disk space.