[clang-format][Windows] git-clang-format requires the py launcher
- Dominant language
- LLVM
- Stars
- 40.5k
- Forks
- 18.7k
- PR merge metrics
- PR metrics pending
Description
### Description
The Windows installation of `git-clang-format` does not work when Python 3 is available as `python.exe` but the optional `py.exe` launcher and `python3.exe` alias are not installed.
There are two failure paths:
1. `git clang-format` selects the installed extensionless `git-clang-format` script, whose shebang requires `python3`.
2. Invoking `git-clang-format.bat` directly requires `py -3`.
### Reproduction
Environment:
- Windows
- Git 2.54.0
- LLVM 22.1.8
- Python 3.8 or newer available as `python.exe` on `PATH`
- No `py.exe` or `python3.exe` on `PATH`
Run:
```
❯ git clang-format --diff
/usr/bin/env: ‘python3’: No such file or directory
[🔍NOTFOUND] ✘ git-clang-format --diff
C:\Users\ofek\Desktop\code\coincurve>py -3 "C:\Users\ofek\scoop\apps\llvm\current\bin\git-clang-format" --diff
'py' is not recognized as an internal or external command,
operable program or batch file.
[ERROR] ✘ which -a git-clang-format | first | get path
C:\Users\ofek\scoop\apps\llvm\current\bin\git-clang-format.bat
❯ head -n 5 (which -a git-clang-format | first | get path | path parse | get parent stem | path join)
#!/usr/bin/env python3
#
# ===- git-clang-format - ClangFormat Git Integration -------*- python -*--=== #
#
# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
```
### Expected behavior
`git clang-format` should work when any supported Python 3 installation is available, including installations that expose only `python.exe`.
If no compatible interpreter is available, the launcher should report that Python 3.8 or newer is required.
### Proposed solution
On native Windows:
- Retain an extensionless `git-clang-format` entry point or provide a `git-clang-format.exe` launcher, because Git does not resolve `git-clang-format.bat`.
- Make both the Git-discoverable entry point and the batch launcher run the implementation using an available supported Python interpreter, including installations exposing only `python.exe`.
- Have the entry point locate a compatible interpreter, using one of the following approaches.
1. Consider `python` followed by `py -3`. There is no need to check `python3` as the versionless variant is the more stable identifier e.g. the former would rarely exist outside of virtual environments. For example, its absence can be seen in [cpython-3.14.7+20260807-x86_64-pc-windows-msvc-install_only_stripped.tar.gz](https://github.com/astral-sh/python-build-standalone/releases/download/20260807/cpython-3.14.7+20260807-x86_64-pc-windows-msvc-install_only_stripped.tar.gz) from the primary source of prebuilt distributions.
2. (my recommendation) Consider only `python`. Most folks manage their own global environment on `PATH` rather than using (or often even installing) the `py` launcher. For those who do not, `python` is a default app execution alias which triggers an installation from the Microsoft Store.
### Related work
#69643 and #69228 added the Windows batch wrapper. The absence of `py.exe` was [raised](https://github.com/llvm/llvm-project/pull/69228#discussion_r1367400671) during review of #69228, but the wrapper still requires it.
Subsequent fixes #75268, #107041, and #114078 addressed script location, quoting, and drive-letter handling, respectively.
### Notes
I mentioned Python 3.8 as the minimum supported version only because that's what the script [says](https://github.com/llvm/llvm-project/blob/llvmorg-22.1.8/clang/tools/clang-format/git-clang-format#L22). I think we should update that to the latest non-[EOL](https://devguide.python.org/versions/) version, which is 3.10 as of today.
Contributor guide
Research direction
Start with clang/tools/clang-format/git-clang-format and the related Windows batch wrapper, then reproduce both failures on Windows with only python.exe available. Trace how Git discovers each entry point and verify that both invocation paths work with a supported interpreter, while an unsupported or missing interpreter reports the required Python version.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100