With Git LFS, how do `git lfs ls-files`, `status` and `fsck --pointers` reveal a tracked FBX committed as a plain Git blob?
answer
- who is missing from the list
- asterisk against minus
- Git or LFS on each side
- should-have-been-pointer check
- renormalize, then commit
basics
~20 sgit lfs ls-files omits it, since it lists only pointers; git lfs status labels each change Git or LFS; git lfs fsck --pointers flags files that should be pointers. Renormalizing and committing fixes the tip.
solid answer
~50 s`git lfs ls-files` lists only paths stored as LFS pointers at a ref, so a tracked `.fbx` missing from it is a plain blob; for listed files `*` means the full object is in the working tree and `-` means the pointer text is still there. `git lfs status` groups objects to be pushed, to be committed and not staged, and labels each side `Git` or `LFS`, so a fix shows as `(Git: … -> LFS: …)`. `git lfs fsck --pointers` checks that pointers are canonical and that every file that should be in Git LFS is, and the Git LFS FAQ suggests running it over `BASE..HEAD` in CI to stop recurrences. The usual causes are a teammate without `git lfs install`, a pattern tracked without renormalizing, or a case mismatch; the fix is `git add --renormalize .` and a commit on each affected branch.
go deeper
Recall that git lfs ls-files lists files stored in Git LFS, and that a tracked file missing from it was committed as an ordinary blob.
Explain the ls-files markers, the three groups and Git or LFS labels in status, and what fsck --pointers checks.
Trace the cause — missing install, unrenormalized tracking or a case mismatch — fix each branch with renormalize, and gate merges with fsck --pointers over the pushed range.
Decide how a team keeps LFS hygiene enforced rather than remembered: install in onboarding, a pointer check on every change, and patterns that survive every operating system.
## The symptom On a repository that tracks `*.fbx` with **Git LFS**, an artist reports that `Characters/hero.fbx` is always shown as modified, even straight after `git reset --hard`, and checkouts print: ```bash Encountered 1 file that should have been a pointer, but wasn't: Characters/hero.fbx ``` The attributes say the path belongs in Git LFS, but the content committed for it is an ordinary Git blob. Three Git LFS commands tell you exactly where the mismatch is, and none of them needs the server. ## `git lfs ls-files` — what is stored as a pointer `git lfs ls-files [<ref>]` lists the paths that are **stored as Git LFS pointers** in the tree at a ref (the checked-out branch by default). It answers "what is in LFS?", so its silences matter as much as its output: - A tracked file that is **missing** from the list was committed as a plain blob. - An **asterisk** (`*`) after the object id means the full object is in the working tree. - A **minus** (`-`) means the working tree still holds the pointer text — the smudge filter did not run or the object was not available. A typical listing, with the first ten characters of each oid: ```bash $ git lfs ls-files 5eea10d5b5 * Art/hero.psd 2be7f6377a - Characters/villain.fbx ``` Here `hero.psd` is fully checked out, `villain.fbx` is still pointer text on disk, and `Characters/hero.fbx` — tracked by `*.fbx` but absent — is a plain blob. Useful flags: `--long` for the full 64-character oid, `--size` for object sizes, `--all` to scan the whole history, `--name-only`, `--json` for scripts, and `--include` / `--exclude` to filter paths. Given two refs, it lists the LFS files modified between them. ## `git lfs status` — what is about to change `git lfs status` shows Git LFS objects in three groups: 1. Objects **to be pushed** — LFS objects the next `git push` would upload. 2. Objects **to be committed** — differences between the index and `HEAD`. 3. Objects **not staged for commit** — differences between the working tree and the index. Each entry labels where its content lives, `Git` or `LFS`, with a short hash. After renormalizing the FBX you would see an entry such as `Characters/hero.fbx (Git: 1a2b3c4 -> LFS: 5d6e7f8)`: a plain blob becoming an LFS pointer. `--porcelain` and `--json` give script-friendly output, and the command needs a non-bare repository. ## `git lfs fsck` — the consistency check `git lfs fsck [<options>] [<revisions>]` checks HEAD by default, a single commit, or a range written `A..B`: | Option | What it checks | |---|---| | `--pointers` | Each pointer is **canonical**, and each file that should be stored in Git LFS **is** stored as a pointer | | `--objects` | Each LFS object exists in the local cache and matches its SHA-256 | | neither | Both checks | Corrupt objects are moved to `.git/lfs/bad` unless `--dry-run` is given. The Git LFS FAQ suggests running `git lfs fsck --pointers BASE..HEAD` in CI so that nobody reintroduces plain blobs for tracked paths. For a single file, `git lfs pointer --check --file=<path>` exits 0 for a valid pointer and 1 otherwise, and `--strict` adds an exit code of 2 for a non-canonical one. ## Why it happened - **Someone committed without Git LFS set up.** With no `lfs` filter in their Git config, the attribute names a filter that does not exist, so Git stores the raw content. - **The pattern was tracked after the file was committed** and the file was never re-added through the clean filter. - **Case.** Attribute patterns are case-sensitive. A file named `HERO.FBX` does not match `*.fbx` on a case-sensitive file system, so behaviour differs between machines; the Git LFS FAQ recommends bracket globs such as `*.[fF][bB][xX]`. ## The fix On an otherwise clean tree, on **every** branch that carries the file: ```bash $ git add --renormalize . $ git commit -m "Store hero.fbx as a Git LFS pointer" $ git lfs ls-files | grep hero.fbx ``` Then make sure everyone working with large files has run `git lfs install` at least once, and add the `fsck --pointers` check to the pipeline. Renormalizing corrects the tip only: the plain blob that was committed stays in history until the history is migrated.
- What does the checkout warning `Encountered 1 file that should have been a pointer, but wasn't` tell you?Git LFS's filter was asked to handle a path whose attributes say `filter=lfs`, but the committed content is an ordinary blob, not a pointer. Someone committed it without the Git LFS filters, or the pattern was tracked after the file was committed and never renormalized.
- How does `git lfs fsck --objects` differ from `--pointers`?`--objects` checks that each LFS object referenced at HEAD exists in the local cache and matches its SHA-256, moving corrupt objects to `.git/lfs/bad` unless `--dry-run` is given. `--pointers` checks the Git side: that pointers are canonical and that files meant for Git LFS are stored as pointers. With no option, both checks run.
- How can a script check whether one file is a valid pointer?`git lfs pointer --check --file=<path>` exits 0 if the file is a valid Git LFS pointer and 1 if it is not; adding `--strict` also requires the canonical encoding and exits 2 when it is not. `--stdin` reads the candidate from standard input instead.
- git lfs ls-files lists every file matching a tracked pattern.
- A minus sign in git lfs ls-files means the object is missing on the server.
- git reset --hard clears a file that is permanently shown as modified.
- git lfs pull converts a committed plain blob into a pointer.
- git lfs fsck only checks object hashes, never whether files should be pointers.