Large Media

Storing your site content in a Git repository is great until you start adding large files that aren’t made up of text — files like images, zip files, and PDFs. Git’s system of tracking diffs doesn’t work with these files, so it saves full copies of every version in your Git repository.

Netlify Large Media uses Git LFS to combine the benefits of Git version tracking without bloating your repository. Your designated Large Media files are uploaded directly to our media servers while Git tracks their versions with text pointer files in the repository.

This saves local development time and speeds up builds in the following ways:

  • Smaller repositories – Whether you’re cloning for local development, or our buildbot is cloning to run your build, smaller repositories mean faster clones.
  • Separate uploads – Uploads to our Large Media service run in parallel with the build, so both processes can run as efficiently as possible.
  • Transformations when you need them – With our image transformation service, you can serve the exact image size you need for each context, from thumbnail to retina, without having to save multiple versions or run repetitive resizing operations in your build.

You can use Netlify Large Media when working with a local clone of your site repository, or directly within Netlify CMS.

Requirements

To enable Large Media on a site repository, or to connect to an existing Large-Media-enabled site for local development, you need the following:

  • A Netlify site connected with a Git repository for continuous deployment.
  • A Netlify user login with access to the site settings, connected to your Git provider account. (This is true for every collaborator committing large media files to the site, unless they are using Netlify CMS.)
  • Git LFS version 2.5.1 or above, installed on your local machine. You can run git lfs version in your terminal to see if you have a valid version installed. If not, follow the installation instructions on the Git LFS website.
  • Netlify CLI version 2.6.4 or above. Refer to the CLI docs for information on installation, authentication, and linking your local repository clone to your Netlify site.
  • Netlify Large Media plugin for Netlify CLI. Run the following commands in your terminal to install the plugin:

    netlify plugins:install netlify-lm-plugin
    netlify lm:install
    

    After running these commands, you will be presented with a custom command to run in order to use Netlify Large Media in your shell. Copy and run this command.

Limitations

Netlify Large Media can be a powerful tool for your sites and apps, but because it’s built on Git LFS, it fundamentally changes how your Git repository works, and how your files are handled on Netlify.

Make sure to review the following before enabling Large Media on a site and repository:

  • Files tracked with Netlify Large Media are tied to a specific site. This means that Deploy to Netlify buttons and repositories with multiple connected sites are not supported. Similarly, you cannot create a new site from a fork of a repository, though you can fork a Large-Media-enabled repository for the purpose of making contributions to be merged into the original repository.
  • Files tracked with Large Media are uploaded directly to the Netlify Large Media storage service on push, completely bypassing the site build. This saves build time, but also means that the files are not available to tools that process asset files during the build, such as Hugo’s image processing or the gatsby-image plugin. Depending on your needs, you may be able to replace this functionality with Netlify’s image transformation service.
  • Uploading tracked files to the Netlify Large Media storage service requires Git to have access to the /.netlify/large-media path on the connected site. This will not work with site-wide password protection, but will work with other forms of visitor access control, as long as you leave access open to the /.netlify/large-media path.
  • Netlify Large Media is not compatible with Netlify’s built-in asset optimization. If you enable Netlify Large Media, you need to select Disable asset optimization in your site dashboard under Settings > Build & deploy > Post processing > Asset optimization.
  • Netlify Large Media is not suitable for streaming audio or video files. Downloads of these types of assets should work well.

Because Netlify Large Media and Git LFS change the way your files are saved, disabling Large Media requires assistance from Netlify Support.

Enabling Netlify Large Media

To get started using Netlify Large Media on your site, you need to enable the Large Media add-on and configure Git LFS on a connected local repository. You can do this by completing the following steps:

  1. Make sure you have reviewed the limitations and fulfilled all of the requirements stated above, and open your terminal into the local repository connected with your Netlify site.

    Note: If your respository is stored on GitLab, you will need to disable GitLab’s Large File Service (LFS) in the project permissions settings.

  2. If you haven’t already, log in to Netlify CLI and link your local repository to your site on Netlify:

    netlify link
    
  3. Run the following command for Large Media:

    netlify lm:setup
    

    This command will do the following:

    • Enable the Large Media add-on for your Netlify site.
    • Configure Git LFS to use the Netlify Large Media service.
  4. Check your git status, and commit the .lfsconfig file. This file stores your Large Media settings.

Your repository and site are now ready to start tracking files. Continue to the next section to configure file tracking.

Large Media file tracking configuration

After you enable Netlify Large Media on your site and local repository, you need to specify which files to track with Git LFS. When you push a tracked file to your remote repository, Git will store a text pointer file in its place, and upload the file itself to the Netlify Large Media storage service.

You can change which files are tracked at any time. You can follow the steps below to set up a new configuration, or to make changes to an existing configuration.

  1. Specify which files you would like to track with Large Media by using the git lfs track command. You can name individual files, one at a time, or in the same command, containing the files in quotation marks and separating them with a space:

    git lfs track "dog.jpg" "cat.gif"
    

    You can also track groups of files using gitignore pattern rules. For example, you could run the following to track all files in the static/pdfs directory:

    git lfs track "static/pdfs/**"
    

    You can also track all files with certain extensions, like so:

    git lfs track "*.jpg" "*.png"
    

    You can combine different types of patterns in a single command, or run the command multiple times.

  2. Commit your changes. When you run the git lfs track command, Git saves your tracking configuration in a .gitattributes file. For example, running all three of the sample commands in step 1 would add the following lines to the .gitattributes file:

    dog.jpg filter=lfs diff=lfs merge=lfs -text
    cat.gif filter=lfs diff=lfs merge=lfs -text
    static/pdfs/** filter=lfs diff=lfs merge=lfs -text
    *.jpg filter=lfs diff=lfs merge=lfs -text
    *.png filter=lfs diff=lfs merge=lfs -text
    

    The git lfs track command also applies Git LFS tracking to any files which match the rules specified. You can see newly tracked files listed as modified when you run git status. Commit all of these changes to Git.

  3. Push the changes to your remote. For example, if you are working on your master branch and pushing to origin, run:

    git push origin master
    

    Newly tracked files you committed in the previous step will upload to the Netlify Large Media storage service. If you started tracking a large number of files, this initial push may take a long time as all of the files are uploaded.

    When the tracked files are uploaded to Large Media, Git replaces them with pointer files in your remote repository. If you navigate to one of the files on your Git provider, you will find plain text information about the original file.

    This pointer file is usually much smaller than the file it tracks, saving space in your repository and reducing cloning time. In your local repository and in your built site on Netlify, all tracked files can still be accessed as normal.

  4. Continue working in your repository as normal. Any files you add or change which match your tracking rules will automatically be handled by Git LFS and Netlify Large Media on every pushed commit.

Checking which files are tracked

Git LFS stores your tracking rules in a .gitattributes file in your repository. You can read the rules in this file directly, or list them with the following command:

git lfs track

To list all of the files being tracked based on these rules, run:

git lfs ls-files

Troubleshooting

If Large Media isn’t working as expected, you can visit our Community forum for guidance on troubleshooting your Netlify Large Media configuration.

Migrating files from Git history

When you start tracking files for Netlify Large Media, all subsequent pushed commits of tracked files will be handled by Git LFS. However, this does not change the previous versions of the files, stored full-size in your repository as part of your Git history.

You can see how much space these files are taking in your history with the following command:

git lfs migrate info

The command also accepts options flags to filter your search by file type, location, or size.

Note: If you have many large files in your Git history, it may take a very, very long time for all of them to migrate and upload to the Netlify Large Media storage service.

To migrate asset files from your Git history to Large Media, complete the following steps.

  1. In your local repository, use the git lfs migrate import command to convert files in your Git history. The command accepts several options flags, including:

    --everything – migrates all matching files in all commits in all branches in your Git history. If you don’t want the migration to apply to your entire history, you can use a different flag as described in the command documentation.

    --include – accepts rules for which files to migrate. These rules follow the same format as the git lfs track command used to set up your initial file tracking configuration. In this case, rules are separated by commas, and the entire list is wrapped in quotation marks.

    Here is an example to convert all files in the images directory along with any other gif files, throughout the entire repository history:

    git lfs migrate import --everything --include="images/**,*.gif"
    

    You can find more examples in the Git LFS migrate command documentation.

  2. Push the newly migrated files to your remote repository. Unless you specify otherwise, the git lfs migrate import command will rewrite your commit history, converting all previous file version to Git LFS pointers. Pushing this rewritten history to the remote on your Git provider may require a force-push, as follows:

    git push --force-with-lease
    

    This will upload the previous file versions to Netlify Large Media, and replace the files in the remote repository with pointer files.

Contributing to a repository with Large Media enabled

When a repository is configured to use Large Media and Git LFS, contributors cloning and working with the repository locally must also have these services installed, and must have access to the site on Netlify.

To start working locally with a repository configured for Large Media, complete all of the stated requirements, then clone and push as normal.

Note: No local setup is required for contributing to a repository via Netlify CMS.

Contributing by forking

You can fork a repository connected to a site enabled for Large Media, with the following limitations:

  • In order to access the Large Media files, you must fulfill all of the Large Media requirements, including access to the Netlify site connected to the main (upstream) repository.
  • You cannot create a new Netlify site from the fork, because the Large Media files are viewable on the original site only.

Contributing without downloading Large Media files

For contributions that don’t require access to a repository’s Large Media files, you can use GIT_LFS_SKIP_SMUDGE=1 with your clone command to ignore LFS settings and download the text pointer files only:

GIT_LFS_SKIP_SMUDGE=1 git clone REPOSITORY_URL

Note: PowerShell does not support the above syntax. For Windows users, we recommend running the command above using Git Bash.

Using with Netlify CMS

If you use Netlify CMS with Netlify Identity and Git Gateway, your Identity users can work seamlessly with Large Media files in the Netlify CMS UI.

Visit the Netlify CMS docs for more information on setup and configuration options.

Repositories with multiple connected sites

Large Media asset files are configured to work on a single site. For this reason, Large Media is not supported for monorepos or other configurations connecting multiple sites to a single repository.

Deleting a site with Large Media enabled

When you configure a repository to use Git LFS and Large Media, your designated LFS-tracked files will no longer be stored in your repository on your Git provider. Instead, they will be stored in the Large Media store for your connected Netlify site. This means that if you delete that site, you will not be able to recover the files at your Git provider.

If you delete a site with Large Media enabled, you will lose all Large Media files that you don’t have stored locally. To clone your entire respository with all branches and history, run the following command:

git clone --mirror REPOSITORY_URL

Make sure your files have downloaded properly before deleting the connected site on Netlify.

Usage and billing

You can check your Large Media service usage under Settings > Large Media > Asset storage > Usage. This shows your current usage level and tracks your usage of the following services:

  • Image transformations: This counts the total number of image transformations performed on any images on your site during the current billing period.

Metered features like image transformations are charged based on usage. When usage reaches a level limit, the site will automatically upgrade to the next level or package.

Changing levels

Any team member with the ability to change settings on your site can also change levels for services on that site.

To do this, go to Settings > Large Media > Asset storage > Usage, and select Change level. Level fees will be prorated and charged at the end of the billing cycle, to the team’s payment method.


Notice something is incorrect or outdated?

First off, great catch! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.



Want to have a conversation?

Visit the Netlify Community to discuss ideas and questions with your fellow Netlify users.

Want to get started quick?