Frequent Issues: Long File Names

Git has trouble handling very long file paths (over ~206 characters total, including folder path and file name). While it’s best to keep file names short and descriptive, sometimes you can’t avoid a long path—especially when working several folders deep.

If you hit an error when committing due to a long file name:

  1. Best fix: Shorten the file name or move it to a higher-level folder.

  2. If not possible:

    • In GitHub Desktop, go to Repository → Open in Command Prompt.

    • In the Command Prompt window, type (or right-click and paste):

      git config --global core.longpaths true

    • Press Enter. This enables Git to handle longer file paths. You should only need to do this once per computer.

Frequent Issues: Large Files

Working with Large Files using Box LFS

Some projects in WWS use Box Large File Storage (Box LFS) to handle files too big for GitHub. This setup keeps large files in Box while storing lightweight “pointer” files in GitHub.

Why this matters:

  • GitHub file limit: 100 MB

  • Git LFS raises the limit to 2 GB, but:

    • Free accounts have a storage cap

    • Deleted files still remain in Git history

    • Removing them often means recreating the repo and losing history

  • With WWS, we have unlimited Box storage.

  • Box LFS combines GitHub for code + Box for big data.

How it works

  • Large files stay in Box (inside a box-lfs folder).

  • GitHub stores only .boxtracker pointer files.

  • The real files are stored in Box, renamed with unique hashes to avoid overwriting.

  • A path-hash.csv file maps each hash back to its original file name and location.

Best practices

  • Pull first, push often — this prevents merge conflicts with .boxtracker files.

  • Remember: Box LFS doesn’t store file diffs, only full file versions when updated.

  • If two people change the same large file without pulling, you’ll get a merge conflict.

For more details directions on using Box LFS see the package page.

Setting up a new repo with Box LFS

# install.packages("remotes")
remotes::install_github("wildfire-water-security/WWS-box-lfs", subdir="blfs")
library(bfls)

new_repo_blfs(dir = "my_project", size = 10)

  • dir — the folder to set up

  • size — minimum MB for a “large” file (default 10 MB)

After running:

  • GitHub stops tracking your large files

  • box-lfs folder is created with:

    • .boxtracker files

    • upload folder with real large files (hashed names)

    • path-hash.csv

  • A message tells you to upload your files from box-lfs/upload into the right Box project folder.

  • Paste the Box share link when prompted.

Cloning a Box LFS repo

When you git clone a repo that uses Box LFS:

clone_repo_blfs(dir = "cloned_folder", download = "Downloads")

  1. Clone the GitHub repo as usual.

  2. Run clone_repo_blfs() to fetch large files from Box.

  3. Box will give you a .zip — confirm or provide its file path when prompted.

  4. The large files will be placed in the correct locations.

Pushing changes with Box LFS

Before pushing:

push_repo_blfs(dir = "my_project", size = 10)

  • If new/updated large files are found:

    • You’ll be told to upload them from box-lfs/upload to Box.

    • No changes? The function exits quietly.

Pulling changes with Box LFS

After git pull:

pull_repo_blfs(dir = "my_project", download = "Downloads")

  • If you have local updates, you may be told to upload to Box first.

  • If Box has newer files, download the .zip and confirm its location.

  • The files are placed automatically in the right spot.

Merge conflicts with .boxtracker files

If you see conflict markers:

<<<<<<< HEAD

*your version*

======= *their version*

>>>>>>> branch-name

  1. Decide which version’s large file is the latest:

    • If yours → keep your pointer file.

    • If theirs → keep their pointer file.

    • If both matter → rename one before uploading and update path-hash.csv.

  2. Remove the <<<<<<<, =======, >>>>>>> lines.

  3. Keep only the chosen version.

This keeps your GitHub repo lightweight and your large files safe in Box — no size caps, no lost history.