Configuring Git LFS To Use Dropbox

Backstory

I need to store binary and large files in git, more specifically in GitHub, which supports LFS. However, I only get 1 GB of LFS space for free, after that I have to pay $60/year for 50 GB (price as of 9 Aug 2019). Well, I already have a Dropbox subscription, so why pay more money when I can point LFS to a local Dropbox folder instead. I did some research and found a git custom transfer adapter that allows me to do exactly that.

Prerequisites

I assume you already have the following programs installed.

1. You have git installed, v2.19.1 or later
2. You have LFS installed, v2.3.0 or later

Tutorial Time

Install LFS Folderstore

LFS folderstore is a custom transfer agent, created by Steve Streeting, for LFS which allows you to use a plain folder as the remote storage location for all your large media files. Check out the readme for more details.

Step 1, download and install LFS folderstore from the release page. Note, for Windows, it’s a single executable that can be put anywhere. Make note of the path to use in the next step. I put mine at C:\Dropbox\Programs\LfsFolderstore.

Step 2, Add the path to LFS folderstore to your Windows path environment variable.
Step 2.1, In the file explorer, right-click on your computer.
Step 2.2, Click the Properties on the context menu
Step 2.3, In the Windows System Info window click Advanced system settings on the left side
Step 2.4, In the System Properties window click Environment Variables...
Step 2.5, You can change your path (upper box) or the system path (lower box) depending on whether you want to apply the change to just you or everybody.
Step 2.6, Select Path then click Edit...
Step 2.7, Click New
Step 2.8, Type in your path from Step 1.
Step 2.9, Click Ok all the way out.
Step 2.10, You will need to log out of your profile and back in for this to take affect. If that doesn’t work then reboot and log back in.

Configure A Fresh Repo For Unity Project

Step 1, create your Unity project.

Step 2, create a _Game\Sprites folder under the Assets folder.
Note: See my folder structure entry on my Tips & Tricks page for why I create a _Game folder first.

Step 3, add some picture files to the Sprites folder. These enable you to test your setup.

Step 4, add a ‘.gitattributes‘ file to the root project folder. This configures which file types are handled by LFS.

Step 5, add a ‘.gitignore‘ to the root project folder.

Step 6, open git bash in the root project folder.

Step 7, run git init to initialize the local repo.

Step 8, run git add -A to stage all the files.

Step 9, run git commit -m "initial commit" to commit everything locally.

Step 10, create a repo on GitHub, no license, no readme, no git ignore.
Note: minecraftchest1 confirmed this works GitLab as well.
Note: I assume this can be done with Bitbucket but I haven’t tested it. If you have please leave me a comment.

Step 11, run git remote add origin https://github.com/{GitHubName}/{ProjectName}.git to set your remote. Replace the items in the {} with your info.

Step 12, run git branch -M master

❗ Make sure you have the ‘lfs-folderstore.exe’ added to the path. ❗

Step 13, run git config --add lfs.customtransfer.lfs-folder.path lfs-folderstore to add the custom transfer agent.

Step 14, run git config --add lfs.customtransfer.lfs-folder.args "C:/{path/to}/Dropbox/{path/to/LFS}/{ProjectName}" to point the agent to your local folder. Replace the items in {} with your info.
Note: even on Windows use forward slashes as path separators.
Note: I created a LFS folder in my Dropbox and then created a folder for each project.

Step 15, enter git config --add lfs.standalonetransferagent lfs-folder as the last config item.

Step 16, enter git push -u origin master to push the code to your remote and LFS folder.

Now you can check your local LFS folder and you will find your files there, and if you check GitHub your Git LFS Data (in the Billings section of Settings) shouldn’t have increased.

Clone An Existing Repo

The downside to this method is that you have to do a bit more work to clone an existing repo. I recently got a new laptop and have first hand experience with the following process. Let me know if you have a different experience.

Step 1, open a Git Bash window.

Step 2, run git clone {repo URL} {folder name}.
Note: This will pull the non-LFS data, however, it will report “Error downloading object” when trying to get the LFS data.

Step 3, run cd {folder name} to enter your freshly cloned repo.

Step 4, run git lfs install to reinstall LFS

Step 5, run git config --list to inspect the LFS config.

Step 6, run git config --unset lfs.https://github.com/{name}/{repo}.git/info/lfs.access=basic to remove the default LFS setup.

Step 7, run the following three commands:
Step 7.1, git config --add lfs.customtransfer.lfs-folder.path lfs-folderstore
Step 7.2, git config --add lfs.customtransfer.lfs-folder.args "C:/path/to/your/folder"
Step 7.3, git config --add lfs.standalonetransferagent lfs-folder

Step 8, run git reset --hard master to sort out the LFS files in your checkout and copy the content from the now-configured shared LFS folder.

Epilogue

Note, that you have to set this up again on every machine you use to develop your game. You can’t store a custom transfer agent config in GitHub due to security concerns. I mean I wouldn’t trust a repo that downloaded a “random EXE” and configured my system to use it, would you?

I’d leave to hear your feedback, please leave a comment telling me about your experience with this tutorial.