Git LFS and large/binary assets (future-proofing)

[flyingmongoose]

This repo already has a .gitattributes file, but it is limited in scope.

Today it mainly enforces line endings (e.g. * text=auto eol=lf), which is normal for Godot projects and matches the idea of keeping text assets consistent across platforms, as well as matched the Godot Style Guide.

But to truly embrace Git LFS we would need to more fully define the .gitattributes file. Adopting Git LFS would mean extending .gitattributes with filter=lfs. Contributors would have to run git lfs install and have LFS available, which adds a small onboarding step.

As of now, the repo does not appear to track files with Git LFS.

Why raise this now

The port is still early, and the repository is small, so there is no hurry to make this the de facto standard at this time.

It can still be useful to agree on a direction before binary assets grow.

Most of us likely know game repos often see exponential growth in storage needs (textures, audio, models, large exports).

If many large blobs live in ordinary Git history, clones and CI can get slow, and rewriting history later is painful.

The motivation is “pull weeds early”: optional future-proofing, not a mandate to change workflow today.

Proposal (discussion only)

Open a maintainer-led conversation about whether to:

1. Adopt Git LFS for agreed file patterns (possibly new files only at first), or
2. Keep status quo until clone/push/size is a measured problem, or
3. Prefer a split asset pipeline (separate repo, release artifacts, documented download step, etc.).

This should not be implicitly actionable until maintainers choose a policy; contributors can then document the outcome in CONTRIBUTING.md or the wiki.

Tradeoffs

Pros

• Keeps the main Git object database smaller for the file types you put on LFS.
• Makes “big binary” vs “text/source” expectations explicit in .gitattributes.

Cons

• Onboarding: every contributor needs Git LFS installed and initialized; docs and CI must match.
• GitHub limits: LFS has storage and bandwidth quotas; busy repos or large teams can hit them on free tiers.
  • Though, admittedly, GitHub is actually fairly generous with this, it's still a risk to consider. GitHub Docs - About Git Large File Storage
• Migration: moving existing large blobs in history to LFS is a history rewrite; tracking new blobs on LFS only is much simpler but does not shrink past history.
• Policy choices: e.g. whether all .png go to LFS or only assets above a size threshold (small UI icons in LFS is sometimes debated).

Alternatives

• Split asset pipeline: code in one place, heavy art elsewhere. Can mean two places to maintain, but keeps the code clone lightweight.
• Status quo: stay on plain Git until metrics (clone time, repo size, contributor pain) justify a change.

Example .gitattributes (reference only)

Below is an example from a personal Godot + GDExtension project. It mixes LFS rules with text line endings. Several entries are not appropriate to copy verbatim into UH (e.g. rules that may conflict with how this repo treats .tscn/.tres as text).

Important for this port: Unknown Horizons Godot port work typically keeps .tscn and .tres as text (LF, versionable, diff-friendly). The example’s *.scn / *.res LFS rules are for binary Godot formats; do not blindly apply those to .tscn/.tres here without maintainer agreement.

# --- Git LFS (example patterns — policy TBD by maintainers) ---

# 3D models
*.fbx filter=lfs diff=lfs merge=lfs -text
*.obj filter=lfs diff=lfs merge=lfs -text
*.glb filter=lfs diff=lfs merge=lfs -text
*.gltf filter=lfs diff=lfs merge=lfs -text
*.blend filter=lfs diff=lfs merge=lfs -text

# Audio
*.wav filter=lfs diff=lfs merge=lfs -text
*.mp3 filter=lfs diff=lfs merge=lfs -text
*.ogg filter=lfs diff=lfs merge=lfs -text
*.flac filter=lfs diff=lfs merge=lfs -text

# Images & textures (team may want exceptions for tiny UI assets)
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.jpeg filter=lfs diff=lfs merge=lfs -text
*.tga filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text
*.bmp filter=lfs diff=lfs merge=lfs -text
*.exr filter=lfs diff=lfs merge=lfs -text
*.hdr filter=lfs diff=lfs merge=lfs -text

# Binary Godot formats only (do not apply to .tscn/.tres without discussion)
*.scn filter=lfs diff=lfs merge=lfs -text
*.res filter=lfs diff=lfs merge=lfs -text

# Fonts
*.ttf filter=lfs diff=lfs merge=lfs -text
*.otf filter=lfs diff=lfs merge=lfs -text

# --- Text / line endings (align with project conventions) ---

* text=auto eol=lf

# Explicit text types (adjust to match official UH Godot port guidelines)
*.gd text eol=lf
*.tscn text eol=lf
*.tres text eol=lf
*.md text eol=lf
*.yml text eol=lf
*.yaml text eol=lf

Remove or add patterns only after maintainers decide scope (e.g. “LFS for *.blend and *.wav first” is a smaller first step than “all images”).

Suggested outcomes

• Decision recorded in wiki or CONTRIBUTING.md: LFS yes/no, which extensions, CI notes.
• If no LFS: document when to revisit (e.g. repo size / clone time threshold).
• If split assets: document where contributors get full asset packs and how releases work.

---

This is offered as discussion material.

I'd be happy to help turn any consensus into a concrete contributor checklist once maintainers pick a direction. If one is picked, and again, it can wait too, no rush right now.