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.

Before You Begin

Make sure nobody is interacting with the repository and that all local 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'

Install LFS

LFS needs to be installed into a repository using this command:

cd <repository>
git lfs install

Enable Tracking by File Extenstion

LFS identifies files to be put in LFS by the file name extension. Run the following command to add the most common extensions for large files that should be placed in LFS:

for ext in 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
   git lfs track "*.$ext"

Migrate to LFS

Migrate all files matching the tracked file extensions with this command:

git lfs migrate import --everything --object-map commit-map

Prepare for Push

Got to Settings » Repository of the project at and under Protected branches enable Allowed to force push for all entries.


Push the changes made by enabling LFS and importing files to LFS:

git add .gitattributes
git commit -m "move large files to LFS"
git push --force

If the push is successful then revert all Allowed to force push changed in the previous step again.

Free Space

Execute a repository cleanup by navigating to Settings » Repository and expanding Repository cleanup. This requires a commit-map but the file create with git lfs migrate is not compatible with GitLab. All commas must be replaces with space. Use a text editor or run the following command:

sed -i -e 's/,/ /' commit-map

Start the cleanup with the altered commit-map. If the space is not shortly freed after this then you may need to wait 30 minutes and try again. Once the space is freed the file commit-map can be deleted.

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:
© 2024 Eidgenössische Technische Hochschule Zürich