Technology · PRACTICAL GUIDE
Git LFS left pointer files after clone? Audit attributes and objects before recloning
Pointer text in a cloned working tree is a symptom, not a root cause. Preserve local changes, identify the exact LFS object, then separate attribute and filter setup from download, authentication, local-object and checkout failures before you reclone or reset anything.
A Git LFS repository stores a small pointer in Git and the large object elsewhere. Seeing that pointer in the working tree can mean Git LFS was not installed when files were checked out, smudging was deliberately skipped, attributes do not match the path, the object was not fetched, or checkout protected a modified file. It does not by itself prove that the repository is corrupt.
The safest diagnosis follows the object from pointer to attribute, filter, local cache, remote fetch and working-tree checkout. Each stage produces different evidence and needs a different fix. A blind reclone can repeat the same configuration, consume bandwidth, and discard useful local context.
This guide is read-first. It does not rewrite history, run hard reset or clean, bypass credentials, or delete the existing clone. The result is a small evidence ledger and the narrowest safe next action.
1. Preserve the working tree and confirm the symptom
Start with `git status --short` and save the output. Copy any locally edited pointer-looking file and any untracked work outside the repository before testing. Do not run `git reset --hard`, `git clean`, history migration, or delete the clone during diagnosis.
Open the unexpected small text file without editing it. A normal Git LFS v1 pointer has a specification line, an `oid sha256:` line and a declared `size`. Record the relative path, OID and size. Treat a file that merely resembles a pointer but does not parse as a separate malformed-content branch.
Use `git lfs pointer --check --file="PATH"` when available, or compare the text with the documented pointer structure. Do not publish repository credentials, signed download URLs, or private remote details with the evidence.
2. Verify that this path is actually governed by LFS attributes
Run `git check-attr -a -- "PATH"` from the affected commit. For a tracked LFS path, inspect the filter, diff, merge and text attributes that Git sees. The working-tree filename alone does not prove that the current attributes match it.
Inspect the relevant `.gitattributes` file in Git, not just an uncommitted local copy. Attribute patterns are path-sensitive, and the upstream FAQ notes that cross-platform behavior can expose incorrect patterns or historical files that were committed before tracking rules changed.
If the path is not marked for the LFS filter at this commit, stop. Installing Git LFS or fetching objects cannot repair an attribute mismatch by itself. Do not run renormalization or migration until a separate change plan establishes which files and commits should change.
3. Record the local Git LFS filter and selection state
Capture `git lfs version` and a sanitized `git lfs env`. Confirm that Git LFS is installed for the user and repository, and record whether checkout was created with `GIT_LFS_SKIP_SMUDGE=1`, `git lfs install --skip-smudge`, or an equivalent filter setting.
Review include and exclude filters before assuming that every LFS object should be downloaded. The pull manual documents path filters, and partial or sparse checkout can intentionally limit which paths enter the working tree.
Also record sparse-checkout state and any partial-clone filter. A reported Git LFS issue shows a real pointer-only result involving partial checkout and include filtering, but that specific regression should be considered only after the ordinary attribute, filter, fetch and checkout boundaries have been tested.
4. Separate fetching the object from checking it out
Git LFS pull combines a fetch step with checkout. Git LFS checkout alone does not download missing content; it replaces eligible pointers only from objects already present in local LFS storage. This distinction explains why repeating checkout can make no visible change.
Use a scoped fetch for the affected reference and path before attempting a broad download, for example `git lfs fetch REMOTE REF --include="PATH"` after verifying the command against your repository layout. Capture the exact remote, reference and first sanitized error.
If fetch fails with authentication, authorization, missing-object or quota evidence, stop at that boundary. A successful ordinary Git clone does not prove that the separate LFS object endpoint accepted the request or still has the OID.
5. Verify the exact OID in local storage before checkout
After a successful fetch, verify that the local LFS store contains the object for the recorded SHA-256 OID and that its byte length matches the pointer size. Use Git LFS commands and repository diagnostics rather than guessing from a similarly named file.
Run `git lfs fsck --objects` when appropriate for the repository and preserve its output. A local object with the wrong size or digest is an integrity problem; a completely missing local object is still a fetch or remote-availability problem.
Do not copy an arbitrary binary over the pointer just because its filename matches. The pointer OID is the content identity. A correct checkout must resolve that exact object and leave unrelated files unchanged.
6. Let checkout protect modifications, then interpret the result
With the exact object local, run a path-scoped `git lfs checkout -- "PATH"`. The checkout manual states that it does not overwrite a modified file. If the pointer-looking file differs from the index, a no-change result can be deliberate protection rather than a failed LFS installation.
Compare `git status --short`, `git diff -- "PATH"`, and the pointer recorded in the index. Preserve any local modification before restoring a clean placeholder. Do not force replacement until you know whether the difference is user work, line-ending damage, or an unexpected checkout result.
When checkout succeeds, confirm that the working-tree file no longer parses as a pointer, its size matches the declared size, and its digest corresponds to the OID when the normal Git LFS layout permits verification.
Evidence | Failed boundary | Smallest safe action Path has no LFS filter attribute | Attributes | Correct and review tracking rules separately; do not fetch blindly LFS absent or smudge intentionally skipped | Filter installation | Install/configure LFS, then scoped pull Fetch returns auth or missing-object error | Remote access/object availability | Fix access or restore the exact OID; do not reclone Object is local but checkout leaves a modified pointer | Working-tree protection | Back up the modification, compare index, then path-scoped checkout Only partial/sparse paths fail after other checks pass | Checkout selection or regression | Reproduce with versions and minimal filters before escalating
7. Validate recovery and prepare a support-ready ledger
The acceptance test is specific: the pointer parses, its OID and declared size were recorded, the same OID exists locally after fetch, the working-tree path contains the resolved content, and unrelated changes remain intact. Opening the file successfully in its intended application is an additional practical check.
For support, include the sanitized Git and Git LFS versions, operating system, pointer OID prefix and size, `check-attr` result, filter and include/exclude state, remote name, fetch result, local-object result, sparse or partial checkout state, and path-scoped checkout result. State observations separately from conclusions.
Escalate a possible version-specific regression only when a minimal reproduction still fails after attributes, configuration, remote access, object presence and modification protection are accounted for. Do not relabel every pointer-only checkout as the same reported issue.
Frequently asked questions
Why did cloning succeed if the Git LFS files did not download? The Git repository and the LFS object service are separate boundaries. Git can clone pointer files even when LFS is not installed, smudging is skipped, a path is excluded, credentials fail, or the remote object is unavailable.
Will `git lfs checkout` download missing objects? No. Checkout uses objects already in local LFS storage. Fetch or pull must obtain a missing object first.
Should I run `git reset --hard` to replace the pointers? Not during diagnosis. A hard reset can discard unrelated work and does not prove that the required LFS object is available. Record status, attributes, OID and fetch evidence first.
Does pointer text mean the file is corrupt? Not necessarily. The pointer is normal repository data. The problem is that the working tree was not populated with the matching large object, and several different boundaries can cause that state.
