skip to content

With Git LFS, what does `git lfs migrate import --everything --include="*.psd,*.fbx"` rewrite, and what does that cost everyone who already cloned the repository?

level: seniorimportance: should knowfreq 22%

answer

  1. default scope is surprisingly narrow
  2. local refs only, never the remote
  3. new commit IDs from first match
  4. force-push, then everyone re-syncs
  5. object map records old to new

basics

~20 s

It rewrites every commit, reachable from any local or remote ref, from the first matching file onwards, giving new IDs, and moves only local refs; you force-push, and every existing clone must move onto the new history.

solid answer

~50 s

By default `git lfs migrate` touches only the current branch and only commits no remote has, so on a fully pushed repository a plain `import` converts nothing old; `--everything` widens it to commits reachable from all local and remote refs. Every commit from the first matching file onwards is rewritten with pointers and `.gitattributes` entries, so it gets a **new ID**, and so does every descendant. Git LFS updates only local refs and never pushes: you validate with `migrate info`, then force-push the rewritten branches (`git push --force --all`, plus tags). The cost lands on everyone else: existing clones, open pull or merge requests and unpushed work are built on the old commits, and merging an old branch into the new history brings the old commits and their blobs straight back. Collaborators re-clone, or reset each branch and rebase their own commits onto the new history.

code

bash · 7 lines
bash
$ git status --short   # commit or stash first
$ git lfs migrate info --everything --top=10
$ git lfs migrate import --everything \
    --include="*.psd,*.fbx" --object-map=migrate-map.csv
$ git lfs migrate info --everything --pointers=ignore
$ git push --force --all origin
$ git push --force --tags origin

go deeper

for a junior

Recall that migrate import rewrites history, so commit IDs change and the result has to be force-pushed.

for a middle

Explain the default scope (current branch, unpushed commits), what --everything adds, and why only local refs move.

for a senior

Plan the cut-over: freeze pushes, migrate a fresh clone, validate with migrate info, force-push branches and tags, and walk every collaborator and open review onto the new history.

for a principal

Weigh a one-time disruptive rewrite against living with an oversized history, and decide who owns the freeze, the communication and the rollback path.

## What the command is for `git lfs migrate import` converts files that were committed as ordinary Git blobs into **Git LFS pointers**, inside existing history. It is how a team that committed binary art straight into Git for a year actually gets the weight out of its clones. Because a commit's ID is a hash of its tree, its parents and its metadata, changing any file inside a commit changes that commit's ID — and every descendant's. That is the whole cost of the operation, and every step around it exists to manage it. ## Which commits it considers The scope rules surprise people: - **By default**, every `git lfs migrate` mode operates only on the **currently checked-out branch** and only on commits **that do not exist on any remote**. It refreshes remote refs first (unless `--skip-fetch`) to know what is unpushed. On a clone where everything is pushed, a plain `import` therefore finds nothing old to convert. - **Branch arguments** and `--include-ref=<ref>` add refs; `^branch` and `--exclude-ref=<ref>` subtract the commits reachable from them. - **`--everything`** considers every commit reachable from **all local and remote refs**. File types are still limited by `--include` / `--exclude`; with `import` you normally give patterns, or `--fixup` to convert only what existing `.gitattributes` already says should be in LFS. - **`--above=<size>`** selects individual files above a size instead of by pattern, and cannot be combined with `--include`, `--exclude` or `--fixup`. The Git LFS FAQ recommends patterns, because attributes cannot match by size and later large files would not be tracked. ## What it changes - Matching blobs in each commit become pointers, and `.gitattributes` entries are added at the points in history where each file type first appears — as if `git lfs track` had been run back then. - Every rewritten commit and all of its descendants receive **new IDs**. `--object-map=<path>` writes a CSV of `OLD-SHA,NEW-SHA` pairs, useful for re-pointing references kept outside Git such as tickets or build records. - Only **local refs** move. Remote-tracking refs such as `refs/remotes/origin/main` are deliberately left as they were, so they keep describing what the remote really has until you push. - Git LFS **never pushes** and never changes a remote. It also asks before overwriting uncommitted working-copy changes; `--yes` answers that prompt for you, and can lose work. Files in the working copy may afterwards be pointers; the migrate documentation notes this is normal and that `git lfs checkout` repopulates them from the local cache. ## The cut-over, step by step 1. **Freeze pushes** to the repository and tell everyone, so no new commits land on the old history mid-migration. 2. Work in a **fresh clone** with all tags fetched and a **local branch for every remote branch** you want converted — only local refs are rewritten, so a branch that exists only as `refs/remotes/...` is not carried over. Commit or stash anything uncommitted. 3. Size the problem: `git lfs migrate info --everything --top=10`. 4. Rewrite: `git lfs migrate import --everything --include="*.psd,*.fbx" --object-map=migrate-map.csv`. 5. Validate: `git lfs migrate info --everything --pointers=ignore` should no longer list PSD or FBX bytes; inspect a few rewritten commits. 6. **Force-push** branches and tags: `git push --force --all origin` and `git push --force --tags origin`. The host must allow force pushes to the protected branches for this window. 7. Lift the freeze and walk everyone onto the new history. ## What it costs everyone else | Who | What breaks | What they do | |---|---|---| | Collaborators with clones | Their branches point at old commits | Re-clone, or reset each branch to the rewritten remote branch | | Unpushed local work | Built on old parents | Rebase it onto the rewritten branch | | Open pull or merge requests | Their base and head are old commits | Re-push the rebased branches, often recreating the review | | Anything recording commit IDs | Old IDs no longer exist on the remote | Map them through the object map | The dangerous case is the collaborator who merges their old branch into the rewritten one, for example through a pull configured to merge: the old commits — with every full PSD blob — come straight back, undoing the migration on the next push. Removing the old objects from the server's storage is the host's business and depends on its own garbage collection. ## Alternatives and the way back - **`--no-rewrite`** converts listed, already-tracked files in a single new commit on the current branch. No ID changes and no force push, but history keeps its blobs, so clones do not shrink. - **`git lfs migrate export --everything --include=...`** reverses an import, converting pointers back into blobs (downloading missing objects from `origin` or `--remote`). It is also a history rewrite with the same costs.

  • Why does a plain `git lfs migrate import --include="*.psd"` on an up-to-date clone appear to do nothing?
    Without ref options, `migrate` operates only on the currently checked-out branch and only on commits that do not exist on any remote. On a clone where everything is pushed that set is empty. `--everything`, explicit branch names or `--include-ref` widen the scope; `--exclude-ref` and `^branch` narrow it.
  • Why does the Git LFS FAQ recommend patterns over `--above=<size>` for the import?
    `--above` converts files that happen to be large at migration time, but Git attributes cannot match by size, so files that later grow past the threshold are not tracked automatically. Patterns such as `*.psd` keep applying to every future file. `--above` also cannot be combined with `--include` or `--exclude`.
  • How would the team undo the move to Git LFS later?
    `git lfs migrate export --everything --include="*.psd,*.fbx"` converts the pointers back into plain Git blobs, downloading objects missing locally from `origin` or the remote named by `--remote`. It inserts do-not-track entries in `.gitattributes` and rewrites history just like import, with the same force-push cost.

  • git lfs migrate import pushes the rewritten history to the remote for you.
  • Only the commits that added a PSD get new IDs; later commits keep theirs.
  • Collaborators can merge their old branches into the rewritten history safely.
  • --everything also rewrites the remote-tracking refs under refs/remotes.
  • --no-rewrite gives the same clone-size saving without changing commit IDs.