_index.md

stage: Create
group: Source Code
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
description: Use Git LFS to manage binary assets, like images and video, without bloating your Git repository's size.
title: Git Large File Storage (LFS)

Git Large File Storage (LFS) is an open source Git extension that helps Git repositories manage large binary files efficiently. Git can't track changes to binary files (like audio, video, or image files) the same way it tracks changes to text files. While text-based files can generate plaintext diffs, any change to a binary file requires Git to completely replace the file in the repository. Repeated changes to large files increase your repository's size. Over time, this increase in size can slow down regular Git operations like clone, fetch, or pull.

Use Git LFS to store large binary files outside of your Git repository, leaving only a small, text-based pointer for Git to manage. When you add a file to your repository using Git LFS, GitLab:

1. Adds the file to your project's configured object storage, instead of the Git repository.

2. Adds a pointer to your Git repository, instead of the large file. The pointer contains information about your file, like this:

   version https://git-lfs.github.com/spec/v1
   oid sha256:lpca0iva5kpz9wva5rgsqsicxrxrkbjr0bh4sy6rz08g2c4tyc441rto5j5bctit
   size 804

   • Version - the version of the Git LFS specification in use
   • OID - The hashing method used, and a unique object ID, in the form {hash-method}:{hash}.
   • Size - The file size, in bytes.

3. Queues a job to recalculate your project's statistics, including storage size and LFS object storage. Your LFS object storage is the sum of the size of all LFS objects associated with your repository.

Files managed with Git LFS show a LFS badge next to the filename:

Git LFS clients use HTTP Basic authentication, and communicate with your server over HTTPS. After you authenticate the request, the Git LFS client receives instructions on where to fetch (or push) the large file.

Your Git repository remains smaller, which helps you adhere to repository size limits. For more information, see repository size limits for GitLab Self-Managed and for GitLab SaaS.

Understand how Git LFS works with forks

When you fork a repository, your fork includes the upstream repository's existing LFS objects that existed at the time of your fork. If you add new LFS objects to your fork, they belong to only your fork, and not the upstream repository. The total object storage increases only for your fork.

When you create a merge request from your fork back to the upstream project, and your merge request contains a new Git LFS object, GitLab associates the new LFS object with the upstream project after merge.

Configure Git LFS for a project

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

GitLab enables Git LFS by default for both GitLab Self-Managed and GitLab SaaS. It offers both server settings and project-specific settings.

• To configure Git LFS on your instance, such as setting up remote object storage, see GitLab Git Large File Storage (LFS) Administration.

• To configure Git LFS for a specific project:

  1. In the root directory of your local copy of the repository, run git lfs install. This command adds:
     • A pre-push Git hook to your repository.
     • A .gitattributes file to track handling for individual files and file types.
  2. Add the files and file types you want to track with Git LFS.

Enable or disable Git LFS for a project

Git LFS is enabled by default for both GitLab Self-Managed and GitLab SaaS.

Prerequisites: