---
name: windows-git
description: Use Git correctly on Windows with coding agents. Use for line endings (CRLF/LF), core.autocrlf, file mode, case-only renames, long paths, credential helpers, path quoting, Git Bash vs PowerShell, and fixing Windows-specific git failures.
license: MIT
metadata:
  author: javeckbila
  version: "1.0.0"
  platform: windows
---

# Git on Windows for coding agents

## Default safe commands (PowerShell)

```powershell
git --no-pager status
git --no-pager diff
git --no-pager log -5 --oneline
```

Always prefer `--no-pager` in agent sessions so git does not open `less`.

## Line endings (most common footgun)

| Setting | Effect |
|---------|--------|
| `core.autocrlf=true` | Classic Windows default — converts LF→CRLF on checkout |
| `core.autocrlf=input` | Convert CRLF→LF on commit only |
| `core.autocrlf=false` | No conversion — rely on `.gitattributes` |

**Prefer `.gitattributes` in the repo** over fighting global config:

```gitattributes
* text=auto eol=lf
*.ps1 text eol=crlf
*.bat text eol=crlf
*.cmd text eol=crlf
*.png binary
*.jpg binary
```

When the user sees massive diffs with no real changes → almost always CRLF noise.

```powershell
git --no-pager diff --ignore-space-at-eol
# diagnose
git ls-files --eol | Select-Object -First 30
```

## Case-only renames

Windows is case-insensitive; git may not detect `util.ts` → `Util.ts`.

```powershell
git mv util.ts util.ts.tmp
git mv util.ts.tmp Util.ts
```

## Long paths

```powershell
git config --global core.longpaths true
```

Use when clone/checkout fails with path length errors on monorepos.

## Executable bit

Windows often ignores `+x`. For shell scripts needed in Linux CI:

```powershell
git update-index --chmod=+x scripts/build.sh
```

## Paths with spaces

```powershell
git -C 'C:\work\my repo' status
git add -- 'src/my file.ts'
```

## Credentials

- Modern Git for Windows uses **Git Credential Manager** (browser login)
- For HTTPS with `gh`:

```powershell
gh auth setup-git
```

Do not embed PATs in remote URLs in files the agent commits.

## Git Bash vs PowerShell

| Context | Advice |
|---------|--------|
| Agent default on Windows | Use **PowerShell** + `git.exe` |
| Project scripts are bash-only | Run under Git Bash or WSL deliberately |
| Path in bash | `/c/Users/...` not `C:\Users\...` |

```powershell
# Call git.exe explicitly if wrappers confuse PATH
& 'C:\Program Files\Git\bin\git.exe' --version
```

## Submodules and symlinks

- Symlinks on Windows may require Developer Mode or admin — avoid creating symlinks unless required
- Submodules: same commands, watch path separators in nested scripts

## Hooks

Hooks may be bash scripts. On Windows:

1. Ensure Git Bash is installed, or
2. Rewrite hooks to `pwsh` with a shebang Git understands, or
3. Use `husky`/`pre-commit` configs that spawn node/pwsh

If a hook fails with `/usr/bin/env: bad interpreter`, install Git for Windows or convert the hook.

## Agent checklist for commits

1. `git --no-pager status` / `diff`
2. Confirm no CRLF-only churn
3. Do not commit `.env`, `*.pfx`, `*.snk`, Azure publish profiles
4. Quote paths with spaces
5. Message in complete sentences (user preference may vary)