Large Files on UnityFreak

1. Why Git LFS

Game projects live and die by binary assets — textures, meshes, audio, video, and packaged engine data — that are often many gigabytes in size and don't diff or merge like source code. Storing them directly in Git bloats every clone and makes history unusable. Git Large File Storage (LFS) replaces those large files in your repository with small text pointers, while the actual bytes are stored separately and streamed on demand.

UnityFreak hosts LFS objects on object storage with a zero-egress model, so LFS bandwidth is unmetered — you only think about storage, not download costs. This matters most for Unity and Unreal projects, where a single asset (a video capture, a baked lighting cache, a set of source-art files) can easily exceed what a normal Git blob should hold.

2. Quickstart

If you created your repository from the Unity or Unreal Engine template, its .gitattributes already tracks the common binary extensions for that engine (textures, meshes, audio, video, and engine-specific formats like .uasset/.umap or .unitypackage). You don't need to configure tracking rules yourself — just install LFS locally and work as normal:

# one-time, per machine
git lfs install

# clone or work as usual
git clone <clone-url>
git add .
git commit -m "Add source art"
git push

On push, any file matching a tracked pattern is uploaded to LFS storage automatically and only its pointer is stored in the Git history. If your project uses a binary type that isn't already tracked, add a line to .gitattributes, for example:

*.myext filter=lfs diff=lfs merge=lfs -text

3. File Locking

Binary assets can't be merged the way text can — if two people edit the same texture or scene at once, one person's work is lost. UnityFreak supports Git LFS file locking so teams can claim exclusive edit rights on a binary asset before working on it:

# claim a lock before editing
git lfs lock Assets/Art/Character.psd

# release it when you're done
git lfs unlock Assets/Art/Character.psd

Only extensions marked lockable in .gitattributes can be locked — the Unity and Unreal templates mark the usual binary-workflow types (art, audio, video, and engine packages) as lockable out of the box.

A repository admin can release someone else's lock with git lfs unlock --force — useful when a teammate forgets to unlock a file before going offline. Locked files show a lock badge next to their name in the repository's file browser, along with who holds the lock, so you can see at a glance what's currently claimed without running any commands. Repository admins can also review and force-unlock every active lock from the repository's Settings page.

4. Storage & Limits

LFS storage is billed by plan, pooled across all repositories owned by the same account or organization. Bandwidth for LFS uploads and downloads is unmetered on every plan.

Individual objects are limited to 5 GB each. If a push would put a repository over its plan's quota, the push is rejected with a quota-exceeded error before any objects are stored — upgrade your plan or remove unneeded LFS objects to free up space. Paid plans can also enable auto-purchase in their billing settings to automatically buy more storage the moment a push needs it, up to a cap you set, instead of being rejected. You can track a repository's current LFS usage against its quota from the repository's Settings page at any time.

5. Imported Repositories

When a repository is imported by URL from another host, the import brings over your commit history and LFS pointer files, but not the LFS bytes themselves — those live on the original host's LFS storage, not UnityFreak's.

To pull the actual large-file contents onto UnityFreak, open the repository's Settings page and use "Fetch LFS objects" under the LFS section. This fetches every LFS object referenced by the imported history from the original source and stores it on UnityFreak, so clones and checkouts work without reaching back to the original host. You can check progress and any error from the same section.