Git /Large Media /

Large Media setup

This feature is deprecated

Netlify’s Large Media service is deprecated. While Large Media continues to function for sites that currently have it enabled, new Large Media configuration is not recommended. Refer to the deprecation notice in our Support Forums for alternative services and more information.

To avoid the risk of file loss, read our Uninstalling Large Media Support Guide and contact support for assistance turning off Large Media for an existing site.

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:

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

Avoid conflicts with GitLab

If your repository is stored on GitLab, you will need to disable GitLab’s Large File Service (LFS) in the project permissions settings.
If you haven’t already, log in to Netlify CLI and link your local repository to your site on Netlify:
```
netlify link
```
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.
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.

# Configure file tracking

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.

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.
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 note newly tracked files listed as modified when you run git status. Commit all of these changes to Git.
Push the changes to your remote. For example, if you are working on your production branch and pushing to origin, run:
```
git push origin production
```
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.
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.

# Check file tracking

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

# Migrate 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.

Moving from another service?

If you are moving from another Git LFS provider, visit our Forums for a verified Support Guide on migrating your files from other LFS providers.

You can determine 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.

Be prepared to wait!

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.

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.
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.

# Troubleshooting

If Large Media isn’t working as expected, you can visit our Forums for a verified Support Guide on troubleshooting your Netlify Large Media configuration.

Last updated: January 9, 2024

Did you find this doc useful?

Your feedback helps us improve our docs.