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 respository is stored on GitLab, you will need to disable GitLab's Large File Service (LFS) in the project permissions settings.
Run the following command for Large Media:
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.
git status, and commit the
.lfsconfigfile. 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 trackcommand. 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
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 trackcommand, Git saves your tracking configuration in a
.gitattributesfile. For example, running all three of the sample commands in step 1 would add the following lines to the
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
git lfs trackcommand 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.
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.
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 Community forum for guidance on migrating your files from other LFS providers.
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.
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 importcommand 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 trackcommand 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
imagesdirectory, 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
Push the newly migrated files to your remote repository. Unless you specify otherwise, the
git lfs migrate importcommand 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.
If Large Media isn’t working as expected, you can visit our Community forum for guidance on troubleshooting your Netlify Large Media configuration.
Did you find this doc useful?
Your feedback helps us improve our docs.