Configuring and troubleshooting Netlify Large Media
Sam and I were working together to debug some issues encountered while configuring Netlify Large Media for a particular repository. It’s a *very* cool option when it comes to media for static site generators, particularly since it allows you to transform images. This is a run-down of the process, including a few specific snags we hit along the way.
Overview of the steps we took
First, we read through the Netlify Large Media documentation to check that our setup met the requirements. Next, we installed Netlify’s Large Media plugin by running the Netlify CLI commands below:
netlify plugins:install netlify-lm-plugin netlify lm:install
netlify lm:install command checked the system for the requirements and installed
netlify-credential-helper. As part of this process, the installation script added the following lines to the Git configuration file
# This next lines include Netlify's Git Credential Helper configuration in your Git configuration. [include] path = /Users/username/.netlify/helper/git-config
The contents of this file read as follows:
# The first line resets the list of helpers so we can check Netlify's first. [credential] helper = "" [credential] helper = netlify helper = osxkeychain
Note both the
credential reset and the order of the helpers in the subsequent lines. This is relevant for troubleshooting problems with the helper simply not working, covered below.
The current Netlify Large Media documentation says that after running
netlify lm:install, “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.” This is was the output we got from
Run this command to use Netlify Large Media in your current shell source /Users/username/.netlify/helper/path.bash.inc
source ... command added the Netlify credential helper executables to the
$PATH and didn’t return any output. Note that it is added for the current shell only. This is relevant for troubleshooting the “not a git command” error covered below.
The next step was to enable Netlify Large Media for the relevant repository. We linked the repository to Netlify by running
netlify link and then ran
netlify lm:setup. This command enabled Large Media for our linked Netlify site and configured Git LFS to use Netlify Large Media by adding a
.lfsconfig file to the repository.
We then told Git LFS which files to track using the
git lfs track command (see the docs) which added these details to the
.gitattributes in the repository.
At this point, we committed everything to the
master and pushed it by running
git push origin master.
This is where we started hitting snags with two particular problems, a
'credential-netlify' is not a git command error and screwed up credential helpers.
Troubleshooting: resolving “not a git command” error
We ran in to the following error when trying to run
git: 'credential-netlify' is not a git command.
Remember the “current shell” note accompanied the
source command? We missed that note and had opened a new shell at some point during the process, meaning that the
$PATH was missing the Netlify credential helper directory containing the necessary executables. We ran
netlify lm:install again to get the necessary
source command, ran the
source command, and the error was resolved within that shell.
I’m still a bit confused about this part of the Netlify Large Media setup process. None of the documentation for Netlify Large Media or
netlify-credential-helper indicates anything about adding the
source ... line to your
~/.bash_profile, but surely we have to do that in order to set the necessary
$PATH permanently moving forward? It seems kind of annoying to have to run
netlify lm:install and then the returned
source ... command every time you want to push code. Maybe there is a good reason for it that I don’t understand, not sure!
While we were debugging this error, we tried installing the Netlify credential helper manually via Homebrew since a bunch of different discussion threads online indicated that this could help. This led to a new problem.
Troubleshooting: No credential helpers are working
When we ran
git push, we were asked for a username and password. This wasn’t just happening in the repository we were working in, every repository on the computer was behaving the same. This totally locked us out since the related account had two factor authentication enabled, meaning that we could not log in via the command line.
This means that the
osxkeychain credential helper was no longer working, something related to our Git configuration
credential value wasn’t quite right. Running
git config --list --show-origin revealed the problem. This was the output:
file:/Applications/Xcode.app/Contents/Developer/usr/share/git-core/gitconfig credential.helper=osxkeychain file:/Users/username/.gitconfig user.name=Firstname Lastname file:/Users/username/.gitconfig email@example.com file:/Users/username/.gitconfig alias.co=checkout file:/Users/username/.gitconfig alias.cp=cherry-pick file:/Users/username/.gitconfig alias.ci=commit file:/Users/username/.gitconfig alias.st=status file:/Users/username/.gitconfig alias.br=branch file:/Users/username/.gitconfig color.ui=auto file:/Users/username/.gitconfig color.branch.current=yellow reverse file:/Users/username/.gitconfig color.branch.local=yellow file:/Users/username/.gitconfig color.branch.remote=green file:/Users/username/.gitconfig color.diff.meta=yellow file:/Users/username/.gitconfig color.diff.frag=magenta file:/Users/username/.gitconfig color.diff.old=red file:/Users/username/.gitconfig color.diff.new=green file:/Users/username/.gitconfig color.diff.whitespace=red reverse file:/Users/username/.gitconfig color.status.added=yellow file:/Users/username/.gitconfig color.status.changed=green file:/Users/username/.gitconfig color.status.untracked=cyan file:/Users/username/.gitconfig filter.lfs.smudge=git-lfs smudge -- %f file:/Users/username/.gitconfig filter.lfs.process=git-lfs filter-process file:/Users/username/.gitconfig filter.lfs.required=true file:/Users/username/.gitconfig filter.lfs.clean=git-lfs clean -- %f file:/Users/username/.gitconfig credential.helper=netlify file:/Users/username/.gitconfig include.path=/Users/username/.netlify/helper/git-config file:/Users/username/.netlify/helper/git-config credential.helper= file:/Users/username/.netlify/helper/git-config credential.helper=netlify file:.git/config core.repositoryformatversion=0 file:.git/config core.filemode=true file:.git/config core.bare=false file:.git/config core.logallrefupdates=true file:.git/config core.ignorecase=true file:.git/config core.precomposeunicode=false file:.git/config remote.origin.url=https://firstname.lastname@example.org/github-username/git-repo-name.git file:.git/config remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* file:.git/config branch.master.remote=origin file:.git/config branch.master.merge=refs/heads/master
Of course there’s a lot in there that’s not important for the problem at hand. To break down just the relevant parts:
First, Xcode sets the
osxkeychain credential helper. This makes sense since Git had originally been installed via the Xcode Command Line Tools.
Next, the Netlify credential helper is added by the
~/.gitconfig file. This is due to the manual
netlify-credential-helper Homebrew installation we completed when trying to resolve the “not a command” error. As part of the manual installation process, we edited the
~/.gitconfig file as required by the instructions in the current Netlify credential helper README.
file:/Users/username/.gitconfig include.path=/Users/username/.netlify/helper/git-config file:/Users/username/.netlify/helper/git-config credential.helper= file:/Users/username/.netlify/helper/git-config credential.helper=netlify
These lines are the result of running
netlify lm:install. It seems like the installation script uses some aspect of the preexisting Git configuration to determine what should go in that file. In our case, the Homebrew-related
~/.gitconfig edit was causing the missing
helper = osxkeychain line in
/Users/username/.netlify/helper/git-config. Note that the reason we ran
netlify lm:install after installing the Netlify credential helper via Homebrew was that we needed the resulting the
source ... command to fix the
'credential-netlify' is not a git command error.
In summary: If you’re on a Mac – particularly if you have Git installed via Xcode – and you’re starting to work with Netlify Large Media from scratch, I think it is probably best to install the Netlify credential helper exclusively via
netlify lm:install and avoid manual installation via Homebrew due to everything described above. If you’re not starting from scratch and are trying to resolve this problem in the midst of getting everything set up, make sure you remove all rogue
credential values from your
~/.gitconfig file before running
netlify lm:install and this *should* sort out the credential values in your Git configuration.
A final note about the Netlify Git credential helper simply not working: someone else had a similar problem, see this issue. Setting
true was part of the solution for her (read more about
useHttpPath). This wasn’t ultimately part of our problem, but it’s worth being aware of the possibility.