Windows: Long Path and Filename Too Long Errors When Cloning SPECLAN

If you're on Windows and Git is refusing to clone, check out, pull, or switch branches in a SPECLAN repository, the most likely cause is the platform's default 260-character path limit. This page walks you through what you're seeing, why it happens, and the one-line fix.

Symptoms

You're running one of these Git operations:

git clone <speclan-repo-url>
git checkout <branch> or git switch <branch>
git pull
git checkout -- <file> (restoring a file)

…and Git stops with an error that mentions any of the following:

Filename too long
unable to create file …: Filename too long
error: invalid path '…'
Clone succeeded, but checkout failed
Files appear missing from your working tree after a clone or pull, even though the clone command itself seemed to finish
Files that were present a moment ago disappear after you switch branches

These errors point at specific file paths inside speclan/features/… whose total length looks unusually long.

Why this happens

SPECLAN uses deliberately long, descriptive filenames so that you — and the AI coding agents working alongside you — can identify what's in a spec without opening the file. For example:

speclan/features/F-7897-assistants/F-6752-new-spec-assistant/requirements/R-5088-unsaved-draft-warning-on-tab-close/R-5088-unsaved-draft-warning-on-tab-close.md

That single path is already 173 characters relative to the repo root. Combined with the absolute path on your machine (e.g. C:\Users\YourName\Projects\…\), it can easily exceed Windows' default 260-character maximum.

When a Windows process — including the Git binary — tries to create, read, or delete a file whose path is longer than that limit, the operating system rejects it with ERROR_FILENAME_EXCED_RANGE (a.k.a. "Filename too long"). Git surfaces that as the clone/checkout failure you see in the terminal.

This is a Windows-only issue. macOS and Linux do not enforce a comparable global path-length limit, which is why your colleagues on those platforms aren't seeing the same errors.

The fix

Run this command once in any terminal:

git config --global core.longpaths true

Then retry the failing operation (clone, checkout, pull, switch). It should now complete successfully.

That's the whole fix. No reboot, no environment-variable changes, no admin privileges required.

What the command does (and doesn't)

It does:

Tells Git to use the Windows long-path API when it talks to the filesystem, lifting the 260-character ceiling.
Applies globally to every Git repository on your user account from this point forward — not just SPECLAN.
Persists across terminal sessions, reboots, and Git upgrades. You only ever need to run it once per machine and user account.

It does not:

Change anything about other repositories you already have. They continue to work exactly as before; the setting just removes a limit that wasn't being hit.
Affect Git running on macOS, Linux, WSL, or any other platform — those don't have the limit in the first place.
Require enabling Windows long-paths at the operating-system level. The Git setting alone is sufficient for Git operations. (Some other tools may still have their own limits — see "Other tools" below.)
Modify your shell, your editor, or your operating system in any way. It writes a single key into your global .gitconfig file.

Verifying the setting

To confirm the value is set, run:

git config --global --get core.longpaths

You should see:

true

If nothing prints, the command from the fix step didn't take effect — re-run it and make sure you're using the exact form --global (not --local, which would only apply inside the current repo).

If the error persists

If you still see "Filename too long" after applying the fix, work through these checks in order:

Confirm the setting is true with git config --global --get core.longpaths (see above). If it shows blank or false, re-run the fix command.
Make sure you ran the command for the same user account. --global writes to %USERPROFILE%\.gitconfig. If you ran it inside an admin command prompt while normally working as a non-admin (or vice versa), the setting may not be picked up by the Git invocation that's failing.
Restart your terminal or IDE. Some integrated terminals (and some Git GUI clients) cache the config they read at startup. Closing and reopening the terminal — or the IDE itself — picks up the new value.
Clean up a half-cloned repository. If a previous clone failed partway through, Git may have left a directory in a state where retrying picks up corrupt internal files instead of starting fresh. Delete the partial directory entirely and re-run git clone ….
Check your antivirus / file-protection software. Some real-time protection tools quarantine files whose paths look unusual and surface the rejection as a Git error. Try temporarily disabling on-access scanning for your repository directory and re-run the failing command.
Confirm your Git version supports long paths. core.longpaths was added in Git for Windows 2.x; any release from the last several years has it. Check with git --version and update from git-scm.com/download/win if you're on an older release.

If none of these resolve it, the error is likely something other than path length — copy the full error message and ask in your team's usual channel.

Other tools

Git is the most common entry point for this issue, but Windows' path limit can affect any tool that talks to the filesystem without using the long-path API:

File Explorer sometimes refuses to copy, move, or delete files whose paths are too long. Use the command line (del, rmdir /s) or a tool like 7-Zip as a workaround.
Archive utilities (built-in ZIP, some older third-party tools) may fail to extract archives containing long paths. Modern utilities like 7-Zip handle them correctly.
Editors and IDEs vary. Most modern editors (VS Code, JetBrains IDEs) handle long paths transparently; some older Windows-specific tools do not.

SPECLAN itself is not affected by this limit when it's running — the limit is enforced by the filesystem at the path-creation moment, which is exactly when Git fails. Once the files exist on disk (after a successful clone or checkout) reading and editing them through SPECLAN works normally.

Why SPECLAN doesn't simply shorten its filenames

The long, descriptive filenames are load-bearing for the way both human users and AI coding agents navigate the spec set:

You can identify a spec from the filesystem without opening it.
Search tools (ripgrep, fd, your editor's quick-open) work against the filename itself, not just the file contents.
AI agents working with the codebase use filenames as natural-language anchors — R-5088-unsaved-draft-warning-on-tab-close is far more useful than R-5088.md.

Shortening the names — for example to just the ID — would remove the discoverability benefit for every user on every platform to work around a default setting that takes one command to change. The remediation here is the smaller cost.

TL;DR

Run this once:

git config --global core.longpaths true

Then retry whatever Git operation failed.