[DOCS] Windows setup docs still say Git Bash is required despite PowerShell fallback

[coygeek]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/setup

Section/Topic

Windows setup requirements, native Windows shell behavior, and Git Bash troubleshooting

Current Documentation

The setup page currently says:

Shell: Bash, Zsh, PowerShell, or CMD. Native Windows setups require Git for Windows. WSL setups do not.

It repeats the requirement in the install instructions:

Native Windows setups require Git for Windows. Install it first if you don't have it. WSL setups do not need it.

The Windows setup table and native Windows section also say:

| Native Windows | Git for Windows | Not supported | Windows-native projects and tools |

After installation, launch claude from PowerShell, CMD, or Git Bash. Claude Code uses Git Bash internally to execute commands regardless of where you launched it. If Claude Code can't find your Git Bash installation, set the path in your settings.json file:

The PowerShell tool reference still lists this preview limitation:

• On Windows, Git Bash is still required to start Claude Code

The troubleshooting guide treats the old startup error as a current install requirement:

Claude Code on native Windows needs Git for Windows, which includes Git Bash.

What's Wrong or Missing?

Changelog v2.1.120 says:

Windows: Git for Windows (Git Bash) is no longer required — when absent, Claude Code uses PowerShell as the shell tool

The current docs still describe Git for Windows/Git Bash as mandatory for native Windows startup and command execution. That is outdated after v2.1.120.

This leaves three concrete gaps:

A. Windows prerequisites are outdated

The setup and overview pages still tell users to install Git for Windows before using native Windows Claude Code, even though Claude Code can now fall back to PowerShell when Git Bash is absent.

B. Shell behavior is inaccurate

The setup page says Claude Code uses Git Bash internally "regardless of where you launched it." After v2.1.120, the docs should explain the actual selection behavior: use Git Bash when present/configured, otherwise use PowerShell as the shell tool.

C. Troubleshooting sends users to the wrong fix

The troubleshooting and terminal-guide pages still treat "requires git-bash" as an actionable current failure that should be fixed by installing Git for Windows or setting CLAUDE_CODE_GIT_BASH_PATH. Users on v2.1.120+ may instead need guidance about PowerShell fallback, when Git for Windows remains useful, and how to choose or configure the preferred shell.

Suggested Improvement

Update the Windows setup and troubleshooting docs to reflect the v2.1.120 behavior:

1. Change the native Windows prerequisite from "requires Git for Windows" to "Git for Windows is optional unless you specifically want Git Bash or need Git itself for repository workflows."
2. Explain the shell selection behavior for native Windows:

• if Git Bash is installed or CLAUDE_CODE_GIT_BASH_PATH is configured, Claude Code can use Git Bash
• if Git Bash is absent, Claude Code uses PowerShell as the shell tool
• users can still configure PowerShell-specific behavior through the PowerShell tool settings

3. Update the terminal guide so installing Git for Windows is not presented as an unconditional first step.
4. Update the troubleshooting entry for Claude Code on Windows requires git-bash to clarify whether it only applies to older Claude Code versions or specific configurations.
5. Remove "Git Bash is still required to start Claude Code" from the PowerShell tool limitations and replace it with current fallback behavior.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Line(s)	Context
https://code.claude.com/docs/en/setup	23, 62, 108, 112-128	Primary setup page says native Windows requires Git for Windows and that Claude Code uses Git Bash internally regardless of launch shell
https://code.claude.com/docs/en/overview	491-495, 677	Install card and install instructions say Windows terminal setup requires Git for Windows
https://code.claude.com/docs/en/terminal-guide	65-80, 256-270	Beginner Windows guide makes Git for Windows the first step and explains the git-bash error as missing Git
https://code.claude.com/docs/en/troubleshooting	27, 457-473	Troubleshooting table and section direct users to install/configure Git Bash for native Windows
https://code.claude.com/docs/en/tools-reference	98-132	PowerShell tool docs say Git Bash is still required to start Claude Code
https://code.claude.com/docs/en/desktop-quickstart	60	Desktop local-session tip says Git must be installed on Windows for local sessions to work

Total scope: 6 pages affected

Source: Changelog v2.1.120

Exact changelog entry: Windows: Git for Windows (Git Bash) is no longer required — when absent, Claude Code uses PowerShell as the shell tool

[Aaravanand00]

Hi @coygeek

I checked this repo but couldn’t find the referenced docs (setup, terminal-guide, etc.) looks like they’re hosted externally on code.claude.com. I also noticed the same issue in 2 other docs-related issues and left similar comments there seems like a broader docs-site inconsistency rather than something in this repo.
Could you point me to the correct repository for these docs?

[coygeek]

Hi @Aaravanand00 — Anthropic does not have a separate public GitHub repository for the code.claude.com docs as far as I know.

This repo is the public issue tracker Anthropic provides for Claude Code, including docs issues, even though Claude Code and the docs site source are not open source. That’s why I’m filing Claude Code docs issues here.

The docs I’m referencing are the live public pages at code.claude.com/docs/en/..., not files in this repository. For this issue specifically, the inconsistency is between the Claude Code changelog entry for v2.1.120 and the still-visible wording on some Windows setup/docs pages about Git for Windows / Git Bash being required.

[Aaravanand00]

Ok @coygeek since the docs aren’t in this repo, I’ve drafted the exact wording changes to align with the v2.1.120 behavior (PowerShell fallback vs Git Bash usage).

Proposed updates :-

1. Replace :-
   "Native Windows setups require Git for Windows"

With :-
"Git for Windows is optional. If not installed, Claude Code uses PowerShell as the shell tool."

2. Replace :-
   "Claude Code uses Git Bash internally regardless of where you launched it"

With :-
"Claude Code uses Git Bash if it is installed or configured. Otherwise, it falls back to PowerShell."

3. Update troubleshooting :-
   Remove guidance that treats Git Bash as required and instead explain when PowerShell fallback is used.

[coygeek]

Still relevant as of 2026-05-18. This documentation gap has not been addressed in the docs yet.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.