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

The 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 ~/.gitconfig:

# 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 netlify lm:install:

Run this command to use Netlify Large Media in your current shell

source /Users/username/.netlify/helper/path.bash.inc

Running the 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 push:

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     user.email=youremail@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://github-username@github.com/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:

file:/Applications/Xcode.app/Contents/Developer/usr/share/git-core/gitconfig    credential.helper=osxkeychain

First, Xcode sets the osxkeychain credential helper. This makes sense since Git had originally been installed via the Xcode Command Line Tools.

file:/Users/username/.gitconfig     credential.helper=netlify

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 credential.useHttpPath to 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.