Git LFS Guide for Large Files and GitHub Copilot Teams

GitHub blocks any file larger than 100 MiB from a normal Git push, and starts warning at 50 MiB. That hard limit is why "git lfs" still draws about 6,600 monthly US searches, with keyword difficulty around 36 and CPC near 7.42 USD. Most teams only hit the wall after a design export, game asset, model checkpoint, or agent dump lands in a commit and the push fails.

Git LFS (Large File Storage) replaces large binary blobs in Git history with lightweight pointers while storing the real files outside the normal Git object store. A pointer looks like this:

version https://git-lfs.github.com/spec/v1
oid sha256:4cac19622fc3ada9c0fdeadb33f88f367b541f38b89102a3f1261ac81fd5bcb5
size 84977953

Git keeps the small pointer in history. The remote LFS store holds the bytes. On clone or checkout, Git LFS swaps the pointer for the real file when you have bandwidth quota and LFS installed.

That design is elegant for a narrow job: keep a few large, versioned binaries next to the code that depends on them. It is a poor fit for client portals, frame-by-frame video review, or the noisy output of coding agents. GitHub Copilot can help you write and refactor the code that sits next to those assets, but it does not change Git's storage model. If you treat LFS as "unlimited Dropbox inside the repo," you will pay in clone time, bandwidth bills, and painful history rewrites.

When Git alone is enough

Keep ordinary source, configs, and small docs in plain Git. GitHub still recommends repositories stay small, ideally under 1 GB, and strongly under 5 GB. Package managers (npm, Maven, Bundler) should own dependencies. Releases should own shipped binaries that consumers download but never edit in a working tree.

What LFS is good for Use Git LFS when:

• A binary is part of the build or test fixture and must stay in lockstep with a commit
• Diffs of the binary itself are useless, but knowing which version of the asset belongs to a commit is useful
• Every clone that needs the asset should fetch it through the same Git remote
• File sizes fit your GitHub plan's per-file LFS maximum (2 GB on Free/Pro, 4 GB on Team, 5 GB on Enterprise Cloud)

What LFS is not

LFS is not a media review tool. It is not a branded client delivery path. It is not a durable store for agent-generated PDFs, screenshots, or dataset dumps that nobody wants in every clone. GitHub also notes that Git LFS cannot be used with GitHub Pages sites or template repositories.

For distribution of large binaries without tracking them in history, GitHub points teams at Releases. For sharing databases and other bulk data with collaborators, GitHub recommends a file sharing service rather than stuffing SQL dumps into Git. That split, code in Git, bulk data outside, is the core decision this guide keeps returning to.

You need the Git LFS client in addition to Git. Install once per machine, then enable LFS hooks for your user account.

Install on macOS, Windows, and Linux

macOS (Homebrew):

brew install git-lfs
git lfs install

Windows: download the installer from git-lfs.com, run the setup wizard, open a new Git Bash window so PATH updates, then run:

git lfs install

Linux: download the package from git-lfs.com or use your distro packages, run the install script if required, then:

git lfs install

A successful run prints Git LFS initialized. You only need git lfs install once per user account on that machine. It installs the clean/smudge filters Git uses on checkout and commit.

Track the right extensions

Inside the repository that needs large files:

cd /path/to/repo
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "models/**/*.bin"
git add .gitattributes
git commit -m "Track design and model binaries with Git LFS"

Every pattern you care about needs its own git lfs track call (or a hand-edited .gitattributes line). Tracking does not rewrite history. Files already committed as normal Git blobs stay as normal Git blobs until you migrate them.

Commit .gitattributes into the repo. GitHub strongly recommends this so forks and fresh clones share the same LFS rules, and so ZIP/tarball archives can optionally include LFS objects.

Add, commit, push checklist

Use this sequence when introducing a new large asset type:

1. Confirm Git LFS is installed: git lfs version
2. Confirm hooks: git lfs install
3. Add track patterns and commit .gitattributes
4. Add the large file: git add path/to/asset.psd
5. Confirm it is an LFS object: git lfs status or git lfs ls-files
6. Commit: git commit -m "Add hero PSD for landing page"
7. Push: git push origin main

On a healthy push you should see upload progress for the LFS object, not a 100 MiB rejection from GitHub.

Browser vs Git push size rules

Remember the different surfaces on GitHub:

• Browser upload to a repo: max 25 MiB per file
• Git push without LFS: warning above 50 MiB, hard block above 100 MiB
• Git LFS: plan-based max file size (2 GB Free/Pro, 4 GB Team, 5 GB Enterprise Cloud)

If someone drops a 200 MB video through the web UI, it fails long before LFS enters the picture. Use the Git client with LFS, a Release asset, or an external store.

Migrating files already in history

If a large file is already in Git history, tracking alone is not enough. Remove it from normal Git objects and re-add through LFS, or use git lfs migrate for broader history rewrites. History rewrites need coordinated force-pushes and break existing clones, so treat migration as a planned ops task, not a casual Friday cleanup.

For a single recent, unpushed mistake:

git rm --cached GIANT_FILE
git commit --amend -CHEAD

Then track the path with LFS, re-add the file, commit, and push.

For older commits, GitHub recommends git filter-repo to strip blobs from history before reintroducing them under LFS. Always keep a full backup clone before rewriting.

Common push and clone failures

Push rejected for file size: the file is still a normal Git blob. Check git lfs ls-files and .gitattributes.

Pointer checked out instead of real file: the clone has the pointer text, not the binary. Install Git LFS, run git lfs install, then git lfs pull. Confirm the account still has bandwidth quota.

Upload failures mid-push: retry after checking network stability and LFS storage quota. GitHub documents separate troubleshooting for partial LFS uploads.

CI only sees pointers: install Git LFS in the job image and run git lfs pull (or enable LFS checkout in the CI action). Every LFS download in GitHub Actions counts against the repository owner's bandwidth.

Teams using GitHub Copilot in the IDE still need this client setup. Copilot does not install Git LFS for you, and it cannot turn a blocked 120 MiB commit into a legal push without the LFS path (or moving the file out of Git entirely).

Git LFS on GitHub has two separate ceilings: maximum size per file, and included storage plus bandwidth per account plan. Confusing them is how teams get a green local commit and a red remote.

Per-file maximums by plan According to GitHub's current docs:

• GitHub Free: 2 GB per LFS file
• GitHub Pro: 2 GB per LFS file
• GitHub Team: 4 GB per LFS file
• GitHub Enterprise Cloud: 5 GB per LFS file

Anything above the 5 GB ceiling is rejected by Git LFS with an error. If you need to distribute larger installers or datasets, use Releases for binaries under the plan LFS max, object storage such as Amazon S3 or Google Cloud Storage for bulk data, or a workspace product built for large delivery.

Included storage and bandwidth

GitHub moved LFS from prepaid data packs to metered billing with an included free quota:

• GitHub Free, Pro, and Free for organizations: 10 GiB bandwidth and 10 GiB storage
• GitHub Team and Enterprise Cloud: 250 GiB bandwidth and 250 GiB storage

Bandwidth free quota resets each billing cycle. Storage accrues hourly and resets at the start of the next cycle for billing math. Storage usage reflects all LFS objects associated with the repository, not only the latest tip.

How usage is measured

GitHub's billing examples are concrete:

• Push a 500 MB LFS file: 500 MB storage for the repo owner, no bandwidth on upload
• Change one byte and push again: another 500 MB of storage, because each version is stored
• Download that 500 MB file: 500 MB bandwidth against the repo owner
• GitHub Actions downloading LFS objects: same bandwidth rules as a human clone

That full-file-on-every-edit behavior is the silent cost driver for media work. A 400 MB After Effects project edited daily can burn through Free-tier storage in a few pushes even when the "diff" is tiny.

If you exceed storage without a payment method on file, clones may still work but you only get pointers, and new LFS pushes fail. If you exhaust bandwidth without payment, LFS support is disabled until the next month. Budgets can either block overages at $0 or allow spend above the included quota.

Releases as a distribution path

GitHub does not limit total binary size or bandwidth for Releases the same way it treats Git history, but each individual Release asset must still stay under the Git LFS maximum file size for your plan. Releases fit "download this build" better than LFS when consumers are not developers cloning the repo.

Practical budgeting rules

1. Track only extensions that must be commit-aligned
2. Prefer one stable large fixture over daily full-file rewrites
3. Put high-churn media in object storage or a shared workspace
4. Watch LFS usage at the 90% alert so a single CI matrix does not surprise-bill the org
5. Document for the team: "if it is bigger than 50 MiB and not a build dependency, ask before you track it"

Command tutorials stop at git lfs track. Production pain starts when LFS is used for jobs Git never owned: client delivery, media review, and agent-generated artifacts. Use the table below before you add another pattern to .gitattributes.

Client delivery

Clients do not want a clone, LFS install, and SSH key. They want a link, a portal, or a time-boxed download. WeTransfer-style links, Google Drive folders, Box shared links, and branded Send shares all fit better than LFS. Keep the repo private; publish the deliverable from a release or a share.

Media review

Frame comments, timestamp anchors, and in-browser playback matter more than commit hashes for review cycles. LFS will store the file, but it will not give producers a review surface. Object storage plus a review app, or a media-capable workspace with HLS streaming and comments, is the right layer.

Agent-generated artifacts

Coding agents and GitHub Copilot-assisted sessions can produce large logs, build outputs, screenshots, exported PDFs, and intermediate datasets. Putting those into LFS couples every collaborator's clone cost to temporary automation noise. Prefer a run-scoped folder in cloud storage, S3 with lifecycle rules, or a shared workspace with per-file version history so humans can inspect output without bloating Git.

Alternatives, then Fast.io

Common external options:

• Amazon S3 / GCS / Azure Blob: durable bulk storage, lifecycle policies, fine cost control; you build the share UX
• Google Drive / Dropbox / Box: familiar for humans; weak for commit alignment and agent APIs
• GitHub Releases: good for versioned downloads tied to a tag
• Fast.io workspaces: org-owned shared storage with branded Send/Receive/Exchange shares, chunked uploads, HLS video streaming, append-only audit log, Intelligence Mode for semantic search, and a consolidated MCP toolset for agents

A practical split for many teams:

1. Source code and small configs stay in Git (with GitHub Copilot helping in the IDE)
2. True commit-coupled binaries stay in Git LFS with strict track patterns
3. Client packages go to Releases or a branded share
4. Review media and agent outputs land in a workspace humans and agents both can open

On Fast.io, agents connect through Streamable HTTP at /mcp (legacy SSE at /sse). Enable Intelligence on a workspace to index files for hybrid search and citation-backed chat. Every file keeps version history, so concurrent agent writes remain recoverable. Ownership transfer lets an agent assemble the workspace, then hand the org to a human while keeping admin access. Plans start at Starter $29/mo, Business $99/mo, and Growth $299/mo, each with a 14-day free trial that requires a credit card. There is no permanent free storage tier.

Product detail for agent storage and MCP setup is at /storage-for-agents/.

Move heavy deliverables off git lfs

Keep git lfs for commit-coupled build fixtures. Put client packages, media review files, and agent artifacts in a Fast.io workspace with MCP access, version history, and branded shares. Starts with a 14-day free trial.

Start 14-Day Trial

GitHub Copilot is an AI coding assistant that suggests code in the IDE, answers chat questions about a codebase, helps on the command line, and can research, plan, and open pull requests for review. None of that replaces Git LFS, and none of it removes GitHub's 100 MiB hard block. The useful pattern is separation of concerns: Copilot works on the text that belongs in Git; large and high-churn binaries live where review and delivery tools work.

Recommended layout

repo/
  src/                   (plain Git, Copilot-friendly)
  tests/fixtures/tiny/   (plain Git)
  tests/fixtures/large/  (Git LFS patterns only)
  docs/                  (plain Git)

Outside the repo:
  client_delivery/       -> Release or Fast.io Send share
  review_media/          -> workspace with video preview
  agent_runs/            -> workspace or object storage

Document the layout in CONTRIBUTING.md so Copilot-assisted commits do not invent a new git lfs track "*.*" line under deadline pressure.

Example: keep models out of daily noise

Suppose a team ships a small inference service. The ONNX model is 180 MB and must match the API code. Track it:

git lfs track "models/*.onnx"
git add .gitattributes models/model.onnx
git commit -m "Pin inference model v3"
git push

Nightly evaluation reports (multi-hundred MB HTML and CSV dumps) do not belong beside that model. An agent or CI job should upload reports to S3 or a Fast.io workspace folder named evals/2026-07-16/, then post the link on the PR. Reviewers open the report without pulling LFS bandwidth. If the report is a PDF or spreadsheet pack, Metadata Views on Fast.io can extract structured fields into a queryable grid via /product/document-data-extraction/, which is a different job from Intelligence Mode's search and summarization.

Example: design handoff without LFS sprawl

Designers export 300 MB PSDs and motion comps. Tracking every export burns storage on each full-file rewrite. Better path:

1. Source code and design tokens stay in Git
2. Current approved assets for the build pipeline use a single LFS path if the build truly needs them
3. Working exports and client review files go to a shared workspace with branded shares and comments
4. Final installers for customers go to GitHub Releases when they need a version tag

Helping Copilot stay inside the rails

Copilot will happily suggest git add assets/huge.mov if that path is open in the editor. Guardrails that work in practice:

• Pre-commit hook that fails when a staged non-LFS file exceeds 40 MiB
• CODEOWNERS on .gitattributes so track-pattern changes need review
• CI check using git lfs ls-files and git cat-file size probes on new blobs
• A short team rule: "Copilot may edit source; humans decide LFS tracking"

Agent handoff pattern

When an automation account prepares a demo workspace for a customer:

1. Agent creates the org and project workspace (human later starts the paid trial on the org)
2. Agent uploads build artifacts and docs via MCP or API
3. Agent configures a Send share for the client package and a Receive share for feedback uploads
4. Agent transfers ownership to a human lead; agent can remain admin
5. Repo stays lean; only the code and commit-coupled fixtures use Git or Git LFS

Webhooks on the workspace can notify your bot when the client uploads a new file, so you react without polling. Cloud import can pull existing Drive, Dropbox, OneDrive, or Box material without a laptop hop when the source of truth already lives in those systems.

What success looks like

• Clones stay fast for developers using Copilot day to day
• LFS bandwidth graphs stay boring
• Clients never install Git LFS
• Agent run folders are searchable and versioned without polluting git log
• On-call can answer "which model binary shipped with tag v1.4.2?" from the repo, and "where is last week's client review cut?" from the workspace

Quick diagnosis

Symptom: GitHub reports large files detected, or the push is blocked over 100 MiB.

Fix: File is not in LFS. Track the extension, unstage the blob, re-add after git lfs track, or move the file out of the repo.

Symptom: Repo clones quickly but files contain pointer text starting with version https://git-lfs.github.com/spec/v1.

Fix: Install Git LFS, run git lfs install and git lfs pull. Check bandwidth quota and payment method if the owner account is over limit.

Symptom: CI is green locally, red in Actions on missing binaries.

Fix: Install LFS in the workflow and fetch objects explicitly. Budget for Actions bandwidth.

Symptom: Storage doubles after tiny binary edits.

Fix: Expected for LFS. Reduce churn, use external storage for editable media, or accept metered cost.

Symptom: Need to share a 6 GB dataset.

Fix: Above Enterprise Cloud's 5 GB per-file LFS max. Use object storage, split archives, or a workspace that accepts large chunked uploads (Fastio plan docs list plan-dependent max file sizes up to 40 GB for general uploads).

Team operating checklist

1. Install Git LFS on every developer machine and CI image
2. Commit .gitattributes with the smallest track set that is still correct
3. Cap accidental large adds with a pre-commit size guard
4. Prefer Releases for consumer downloads
5. Prefer S3/Drive/Box/Fast.io for client delivery and review
6. Keep GitHub Copilot focused on source; treat LFS tracking as a human-owned policy
7. Review LFS storage and bandwidth monthly against the included 10 GiB or 250 GiB quotas
8. Document the split so new hires and agents do not invent a second policy

Git LFS is a precision tool for commit-coupled binaries under GitHub's plan limits. Used that way, it keeps history honest and clones sane. Used as a general dump for media and agent output, it becomes the expensive middle of a problem that Releases, object storage, and shared workspaces already solve more cleanly.