claude-code - 💡(How to fix) Fix [DOCS] Windows setup docs still say Git Bash is required despite PowerShell fallback [1 participants]

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

1. Update the terminal guide so installing Git for Windows is not presented as an unconditional first step.
2. 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.
3. 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:

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