How to Track glTF 3D Assets with Git LFS

Combining Git Large File Storage (Git LFS) with the Graphics Language Transmission Format (glTF) enables development teams to version-control rich 3D pipelines without bloating repository sizes or degrading Git performance. This article explains how to configure Git LFS for both modular .gltf workflows and monolithic .glb binaries, enforce file locking to eliminate merge conflicts, and optimize production CI/CD pipelines for fast, reliable asset deployment.

Choosing Between .gltf and .glb in Version Control

glTF files exist in two primary delivery formats, each interacting differently with Git:

  • Modular .gltf (JSON + External Binaries): The main .gltf file contains human-readable JSON defining scene hierarchy, materials, node trees, and animation metadata. It references external binary geometry files (.bin) and texture maps (.png, .jpg, .ktx2). This approach allows teams to track structural and property changes using native Git text diffs while offloading the heavy binaries to LFS.
  • Monolithic .glb (Binary Container): The .glb format encapsulates JSON, binary buffers, and textures into a single binary file. While .glb simplifies asset distribution, Git cannot diff it natively. The entire file must be tracked via Git LFS to prevent repository bloat on every revision.

Configuring .gitattributes for glTF Workflows

To track glTF assets with Git LFS, install the LFS extension and configure the .gitattributes file in the root of the repository.

  1. Initialize Git LFS in your environment:
git lfs install
  1. Configure tracking rules in .gitattributes based on your pipeline format:
# Monolithic glTF binaries
*.glb filter=lfs diff=lfs merge=lfs -text

# External buffers for modular glTF
*.bin filter=lfs diff=lfs merge=lfs -text

# Associated texture formats
*.ktx2 filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.hdr filter=lfs diff=lfs merge=lfs -text

# Keep .gltf JSON tracked by standard Git for text diffs
*.gltf text eol=lf
  1. Add and commit the .gitattributes file to ensure all contributors inherit the configuration:
git add .gitattributes
git commit -m "Configure Git LFS tracking for glTF and associated binary assets"

Preventing Binary Merge Conflicts with Git LFS Locks

Binary files such as .glb or .bin cannot be merged automatically. When multiple 3D artists modify the same file concurrently, resolving conflicts often requires discarding one person's work.

Git LFS provides a file-locking mechanism to prevent concurrent edits:

  1. Update .gitattributes to declare lockable assets:
*.glb filter=lfs diff=lfs merge=lfs -text lockable
*.bin filter=lfs diff=lfs merge=lfs -text lockable
  1. Before modifying an asset, acquire the lock:
git lfs lock models/character.glb
  1. After committing and pushing changes, release the lock:
git lfs unlock models/character.glb

Files marked as lockable are set to read-only in the local file system until locked, creating an explicit safeguard against uncoordinated edits in production teams.

Optimizing Production Repositories and CI/CD

Tracking 3D assets creates substantial network and storage overhead if not managed efficiently. Implement the following practices in production repositories:

  • Bandwidth Management with Sparse Checkout: Developers working exclusively on code can exclude heavy 3D assets during clone operations:

    GIT_LFS_SKIP_SMUDGE=1 git clone <repository-url>

    Specific assets can be pulled on demand using:

    git lfs pull --include="models/environment/*"

  • CI/CD Optimization: Automated build environments should cache the .git/lfs directory between runs. This prevents pipelines from re-downloading unchanged .glb and .bin assets on every build, reducing bandwidth usage and reducing deployment durations.

  • Pruning Stale LFS Data: Over time, local caches accumulate unused revisions of updated 3D models. Run periodic maintenance commands to reclaim disk space:

    git lfs prune