Convert to LFS

For repositories that have reached the 1GB limit it is necessary to move large files already in the repository to LFS. Simply deleting files is not enough as these are still present in previous revisions.

Please read these instructions carefully. The conversion may damage the repository if not done right.


A script that uses BFG to move files to LFS is available from isginf:

git clone 
cd convert-to-git-lfs

The usage of the tool is as follows:

Usage =>  convert-to-git-lfs [optional arguments] repository_url

    -u	    bfg-jar download url	=>  -u ''

    -b	    bfg-jar download target	=>  -j './bfg-1.12.13.jar'

    -t	    lfs track file extensions	=>  -t 'bin,exe,jar,dmg,pkg,apk,deb,rpm,msi,msu,zip,rar,7z,tar,tar.gz,tgz,gz,bz2,xz,cab,mp4,m4v,mkv,flv,wmv,ogv,avi,mov,mp3,m4a,m4r,au,ogg,wav,wma,raw,iso,img'

    -j	    java runtime binary		=>  -j 'java'

    -d	    working directory		=>  -d '/local/convert-to-git-lfs'

    -h	    show this help

The default work directory is /local/convert-to-git-lfs. On systems not managed by isginf you will probably need to change this.

Before You Begin

Make sure nobody is interacting with the repository and that all changes are committed. There is not way to enforce this on GitLab so you need to communicate this to everybody who can make changes.

Also, make an additional backup of the repository as it was before the conversion using this command:

git clone --mirror<group>/<project>.git /some/path/<project>.git.backup-before-lfs'


Run convert-to-git-lfs with the URL of the repository:



When done you will need to push the changes back:

git --git-dir='/local/convert-to-git-lfs/project-name.git' push


Execute the Housekeeping in the GitLab project settings.

This will free the actual space in repository.

After You Finish

If the project did not have LFS already enabled then every project member must remove the old local repository and clone a fresh copy with LFS support.

Are these instructions wrong, incomplete or outdated? Are they not helpful?
Please let us know.

Page URL:
© 2020 Eidgenössische Technische Hochschule Zürich