Windows Git Ref Guard

Fix git fetch / SourceTree pull failures on Windows when a remote branch name contains characters that Windows cannot store as a local ref file.

The Problem

Git branch names can legally contain characters such as < and >.

Windows file names cannot contain:

< > : " \ | ? *

When Git for Windows fetches a remote branch, it stores the remote-tracking ref under .git/refs/remotes/.... If a remote branch contains one of those characters, Windows cannot create the ref file and fetch fails.

Example error:

error: cannot lock ref 'refs/remotes/origin/feature/windows-invalid-ref-test-<div>':
Unable to create '.git/refs/remotes/origin/feature/windows-invalid-ref-test-<div>.lock':
Invalid argument

What This Tool Does

windows-git-ref-guard scans the remote branch list and adds local-only negative fetch refspecs for Windows-incompatible branch names.

It changes only the current repository's local .git/config.

It does not:

• rename remote branches
• delete remote branches
• modify source files
• change repository history

Quick Start

Download windows-git-ref-guard.exe from Releases, put it anywhere, then run it from the affected repository:

cd path\to\your\repo
windows-git-ref-guard.exe --apply --fetch

If you are running from source:

python -m pip install .
cd path\to\your\repo
windows-git-ref-guard --apply --fetch

Dry Run

Preview what would be added to .git/config:

windows-git-ref-guard.exe

Example output:

Windows-incompatible remote branches:
  - feature/windows-invalid-ref-test-<div>

Fetch refspec updates (dry-run):
  git config --add remote.origin.fetch ^refs/heads/feature/windows-invalid-ref-test-<div>

Run again with --apply to write these local-only guard rules.

SourceTree

Run the tool once in the repository directory:

windows-git-ref-guard.exe --apply --fetch

SourceTree uses the same local .git/config, so later SourceTree pull/fetch operations will skip the incompatible remote branch.

See docs/sourcetree.md for Custom Action setup.

Demo Repository

A separate repository is used to reproduce the Windows failure:

DanielDcool/windows-git-ref-guard-test

This tool repository intentionally does not contain Windows-incompatible branch names, so Windows users can clone it normally.

How It Works

For a bad remote branch:

refs/heads/feature/windows-invalid-ref-test-<div>

the tool adds a negative refspec:

^refs/heads/feature/windows-invalid-ref-test-<div>

Git then ignores that branch during fetch, while continuing to fetch normal branches.

Requirements

• Windows 10/11
• Git for Windows available in PATH
• For source usage: Python 3.10+

Troubleshooting

If you see:

git executable was not found. Install Git for Windows or add git.exe to PATH.

install Git for Windows, then reopen your terminal.

If your remote is not named origin:

windows-git-ref-guard.exe --remote upstream --apply --fetch

If Clone Itself Fails

If the repository cannot be cloned because the bad branch already exists, download the exe first, then create the local repository manually:

mkdir affected-repo
cd affected-repo
git init
git remote add origin git@github.com:owner/affected-repo.git
windows-git-ref-guard.exe --apply --fetch
git checkout main

If the default branch is not main, replace main with your repository's default branch.

Chinese Documentation

中文说明见 README.zh-CN.md.