Large Files and Binary Assets

Most source code works well as-is: Git’s delta compression is efficient for text, and the ingest path streams directly to object storage. This page covers how large files, Git LFS, and binary assets work today, and where the limits sit.

Source code and normal binaries — handled well today

For the overwhelming majority of repositories — source code, config files, scripts, documentation, build artifacts under a few hundred megabytes, images for a web app, compiled binaries for a CLI tool — neosource uses standard git pack format stored on distributed object storage. This is the same format git uses locally, which means:

• git clone, git push, and git fetch all work without any client-side changes
• delta compression between versions is efficient
• shallow and blobless clones work normally (--depth, --filter=blob:none)

The ingest path streams the wire pack directly to durable object storage without buffering the whole pack in memory, so even a multi-gigabyte initial push of a large project lands cleanly.

Git LFS

neosource implements the Git LFS Batch API over HTTPS (https://neosource.dev/<owner>/<repo>.git/info/lfs/objects/batch), supporting standard basic transfers (download and upload) authenticated with the same personal, workspace, or CI job tokens you use for Git over HTTPS.

LFS objects are stored content-addressed by SHA-256 and verified on upload. Git LFS file locking (/locks) is not implemented yet.

Files larger than approximately 512 MiB in plain Git

Git stops applying delta compression to objects larger than its core.bigFileThreshold (approximately 512 MiB by default). Past this threshold, git stores blobs verbatim, so the pack-delta win disappears. For truly large individual files — video masters, large ML model weights, high-resolution CAD exports, AAA-scale uncompressed assets — the storage profile shifts: each version is stored essentially in full, with no cross-version savings. Use Git LFS for large binary blobs that change across commits so clones do not have to pull every historical version in the packfile.

Actively-edited large structured assets — gamedev and media workflows

For game development, visual effects, and similar workflows involving large binary assets that are edited repeatedly by multiple people — .blend files, .fbx meshes, .psd layered images, Godot .scn scenes, large audio files — the challenges are different from raw file size:

1. Binary files cannot be merged. Merge and conflict tooling is powerful for source code, but a .png or a .blend cannot be 3-way-merged. Two simultaneous edits to the same binary file have exactly one safe resolution: someone’s work wins and the other’s is discarded.
2. Large frequently-changed binaries accumulate quickly even with delta compression, because binary formats often change wholesale between saves.

The complete answer for this workflow involves two things that are not yet available:

• File locking: exclusive locks on binary assets so collaborators see who has a file checked out before they start editing it.
• A native large-asset backend: a substrate built around whole-object and chunked deduplication for files that change in predictable ways.

Large blobs that re-encode wholesale — retention and file locking

Some binary assets change completely with each edit rather than accumulating incrementally. A rendered video frame, a baked lighting map, or a compiled shader cache has essentially no relationship to its predecessor at the byte level. For these:

• Whether delta compression or chunking finds anything to save depends on framing, not file size or extension. Formats whose compressor restarts at fixed raw-data boundaries with an offset table (TIFF- and EXR-style block framing) delta and chunk well — measured incremental cost of ~4.6-4.8%, ~95% chunk duplication. Formats that emit one continuous bit-packed stream recover essentially nothing, because a single change downstream shifts everything after it by a non-integral number of bits — measured at 100% incremental cost for PNG and 0.0% chunk duplication for JPEG. The same compressor produces both outcomes: TIFF with Deflate measures 4.8%, PNG with the identical Deflate codec measures 100.0%. It’s this framing property of the asset pipeline, not the corpus it happens to be measured on, that decides whether delta/chunk storage helps.
• Retention policy matters more than encoding. If each version of a large baked asset is kept forever, storage grows with every commit. The practical answer is retention: decide how many historical versions to keep, and prune older ones. This integrates with file locking — the lock lifecycle includes releasing old versions.
• Where re-encoding is on the table, re-framing beats converting format class. Moving the same codec into a block-framed container — PNG → TIFF-Deflate — is lossless, same codec, same size class, and turns a 100% incremental cost into 4.8%. That’s a smaller, safer change than converting to a different format class (e.g. DDS) entirely.

Both file locking and the retention mechanics are still at the proposal stage.

Storage and quota

Repositories are self-contained: each repository’s storage usage is measured as the packed bytes of its own live packs (after pack delta compression), plus the uploaded bytes of any LFS objects, issue/PR attachments, and container registry blobs in your workspace. Because each repository is self-contained, a fork is a physical copy and counts its own live pack bytes against its owner’s workspace quota.

File size caps are enforced at ingest: a single push above 5 GiB is rejected, and individual objects above 2 GiB are rejected before they land. These limits exist to keep the read path well-behaved; contact support if your workflow genuinely requires larger individual objects.