GitLab Documentation

Git LFS

Managing large files such as audio, video and graphics files has always been one of the shortcomings of Git. The general recommendation is to not have Git repositories larger than 1GB to preserve performance.

GitLab already supports managing large files with git annex (EE only), however in certain environments it is not always convenient to use different commands to differentiate between the large files and regular ones.

Git LFS makes this simpler for the end user by removing the requirement to learn new commands.

How it works

Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication to authorize client requests. Once the request is authorized, Git LFS client receives instructions from where to fetch or where to push the large file.

GitLab server configuration

Documentation for GitLab instance administrators is under LFS administration doc.

Requirements

Known limitations

Note: With 8.12 GitLab added LFS support to SSH. The Git LFS communication still goes over HTTP, but now the SSH client passes the correct credentials to the Git LFS client, so no action is required by the user.

Using Git LFS

Lets take a look at the workflow when you need to check large files into your Git repository with Git LFS. For example, if you want to upload a very large file and check it into your Git repository:

git clone git@gitlab.example.com:group/project.git
git lfs install                       # initialize the Git LFS project
git lfs track "*.iso"                 # select the file extensions that you want to treat as large files

Once a certain file extension is marked for tracking as a LFS object you can use Git as usual without having to redo the command to track a file with the same extension:

cp ~/tmp/debian.iso ./                # copy a large file into the current directory
git add .                             # add the large file to the project
git commit -am "Added Debian iso"     # commit the file meta data
git push origin master                # sync the git repo and large file to the GitLab server

Cloning the repository works the same as before. Git automatically detects the LFS-tracked files and clones them via HTTP. If you performed the git clone command with a SSH URL, you have to enter your GitLab credentials for HTTP authentication.

git clone git@gitlab.example.com:group/project.git

If you already cloned the repository and you want to get the latest LFS object that are on the remote repository, eg. from branch master:

git lfs fetch master

Troubleshooting

error: Repository or object not found

There are a couple of reasons why this error can occur:

Check if you have permissions to push to the project or fetch from the project.

LFS object you are trying to push to the project or fetch from the project is not available to the project anymore. Probably the object was removed from the server.

Invalid status for <url> : 501

Git LFS will log the failures into a log file. To view this log file, while in project directory:

git lfs logs last

If the status error 501 is shown, it is because:

getsockopt: connection refused

If you push a LFS object to a project and you receive an error similar to: Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused, the LFS client is trying to reach GitLab through HTTPS. However, your GitLab instance is being served on HTTP.

This behaviour is caused by Git LFS using HTTPS connections by default when a lfsurl is not set in the Git config.

To prevent this from happening, set the lfs url in project Git config:

git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs"

Credentials are always required when pushing an object

Note: With 8.12 GitLab added LFS support to SSH. The Git LFS communication still goes over HTTP, but now the SSH client passes the correct credentials to the Git LFS client, so no action is required by the user.

Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing the LFS object on every push for every object, user HTTPS credentials are required.

By default, Git has support for remembering the credentials for each repository you use. This is described in Git credentials man pages.

For example, you can tell Git to remember the password for a period of time in which you expect to push the objects:

git config --global credential.helper 'cache --timeout=3600'

This will remember the credentials for an hour after which Git operations will require re-authentication.

If you are using OS X you can use osxkeychain to store and encrypt your credentials. For Windows, you can use wincred or Microsoft's Git Credential Manager for Windows.

More details about various methods of storing the user credentials can be found on Git Credential Storage documentation.