Diagnosing Git LFS Pointer Files in Sourcetree: A Step-by-Step Guide

Recognizable Condition

You open a repository in Sourcetree and see files that should be binary—PSDs, videos, large datasets—displayed as tiny text pointers instead of their actual content. The diff viewer shows lines like version https://git-lfs.github.com/spec/v1 oid sha256:abc123... size 12345678. This means Git LFS is tracking the files, but the real objects haven't been fetched to your working copy.

Quick Cause Reference

Ordered Diagnostic Checks

Run these in sequence from a terminal opened at the repository root. Administrator rights are not required unless you need to install Git LFS system-wide.

1. Confirm Git LFS Installation

git lfs version

Expected: a version line such as git-lfs/3.5.0 (GitHub; linux amd64; go 1.21). If the command is not found, Git LFS is missing from your PATH.

2. Verify Sourcetree LFS Endpoint

In Sourcetree: Repository → Repository Settings → Git LFS. The endpoint should match your remote's LFS URL, typically https://<host>/<owner>/<repo>.git/info/lfs. A mismatch here prevents git lfs pull from reaching the object store.

3. Inspect .gitattributes

cat .gitattributes

Look for lines like *.psd filter=lfs diff=lfs merge=lfs -text. Without these, Git treats the files as regular text and never invokes the LFS filter.

4. List Tracked LFS Objects

git lfs ls-files

Output should show each tracked file with its OID and size. An empty list means nothing is configured for LFS tracking.

5. Test Endpoint Connectivity

curl -I "https://your-host/owner/repo.git/info/lfs"

A 200 OK or 401 Unauthorized means the endpoint is reachable. Timeouts or connection refused indicate a firewall/proxy block.

Fixes Mapped to Findings

Git LFS Not Installed

1. Download the installer for your OS from git-lfs.github.com.
2. Run the installer (Windows/macOS) or use your package manager (brew install git-lfs, apt install git-lfs, dnf install git-lfs).
3. Run git lfs install once per user account to register the global filters.

Missing .gitattributes Patterns

1. Add patterns for your binary types:

   echo "*.psd filter=lfs diff=lfs merge=lfs -text" >> .gitattributes

2. Commit the change:

   git add .gitattributes && git commit -m "Add LFS tracking for PSD files"

3. Run git lfs pull to fetch the actual objects.

Incorrect LFS Endpoint in Sourcetree

1. Open Preferences → Git → LFS (or Repository Settings → Git LFS for per-repo override).
2. Set the endpoint to the correct /info/lfs URL of your remote.
3. Run git lfs pull again.

Network Block (Proxy/Firewall)

1. If your organization uses a proxy, configure Git to use it:

   git config --global http.proxy http://proxy.example.com:8080

   git config --global https.proxy http://proxy.example.com:8080
2. Or whitelist the LFS domain in your firewall.
3. Re-test with curl -I and then git lfs pull.

Verification After Fixes

1. Run git lfs pull and watch for Downloading ... lines.
2. Open one of the previously pointer-only files in its native application (Photoshop for PSD, VLC for video). It should open normally.
3. In Sourcetree, the file size column should now show the real byte count, not the pointer's ~130 bytes.

Limitations & Escalation

If git lfs pull still returns authentication errors (401/403) after correcting the endpoint and proxy, the issue is likely credential-related—expired tokens, missing SSH keys, or server-side permissions. Capture the full console output (GIT_TRACE=1 GIT_CURL_VERBOSE=1 git lfs pull) and provide it to Atlassian Support or the Git LFS maintainers along with your repository URL and Sourcetree version (Help → About Sourcetree).

Always clone the repository to a backup location before modifying .gitattributes or running destructive LFS commands (git lfs prune, git lfs migrate) to avoid accidental data loss.