Windows에서 Husky pre-commit이 /bin/bash 에러로 실패할 때

Windows에서 커밋할 때 Husky의 pre-commit 훅이 npx를 찾지 못하거나, /bin/bash: not found 류의 에러로 실패한 경험을 정리했다.

1. npx를 찾지 못할 때

npx -v

에러가 나면 Node.js 설치 경로(C:\Program Files\nodejs\)가 PATH에 있는지 확인한다.

Windows 검색에서 "시스템 환경 변수 편집"
환경 변수 → 시스템 변수 → Path → 편집
Node.js 경로가 없으면 추가

GUI Git 클라이언트(SourceTree, IDE 내장 Git 등)는 터미널과 다른 PATH로 실행되는 경우가 많다. 터미널에서는 커밋이 되는데 GUI에서만 실패한다면 이 차이를 의심한다. nvm 같은 버전 관리자를 쓴다면 Husky의 시작 스크립트(~/.config/husky/init.sh)에서 PATH를 보정할 수 있다.

2. /bin/bash 에러

Git 훅은 셸 스크립트이므로 Windows에서는 Git for Windows에 포함된 sh/bash 로 실행된다. 그런데 PATH에서 WSL의 bash.exe(C:\Windows\System32\bash.exe)가 먼저 잡히면, 훅이 WSL(Linux) 쪽에서 실행되려다 Windows 경로나 node를 찾지 못해 실패한다.

where bash

결과의 첫 줄이 C:\Windows\System32\bash.exe라면 이 경우다. PATH에서 Git for Windows의 경로(C:\Program Files\Git\usr\bin, C:\Program Files\Git\bin)가 System32보다 앞에 오도록 순서를 조정한다.

예전 Husky(v4 이하)나 직접 작성한 훅 파일의 첫 줄이 #!/bin/bash처럼 특정 경로를 가리키는 경우에도 같은 문제가 생길 수 있다. Husky v9는 훅 파일에 shebang 없이 명령만 적는 방식이라 이런 문제가 줄었다.

3. core.hooksPath를 해제하면?

Husky는 git config core.hooksPath .husky/_처럼 훅 경로를 .husky 쪽으로 바꿔서 동작한다.

git config --unset core.hooksPath

이 설정을 지우면 Git은 기본 경로인 .git/hooks/ 를 다시 사용한다. 그곳에는 보통 실행 가능한 훅이 없으므로 결과적으로 Husky 훅이 실행되지 않고 에러도 사라진다. 다만 이것은 원인을 고친 것이 아니라 훅을 끈 것이다. npm install(Husky의 prepare 스크립트)을 다시 실행하면 설정이 되돌아온다.

훅을 일시적으로 건너뛰는 공식 방법은 다음과 같다.

# 한 번만 건너뛰기
git commit --no-verify -m "..."

# 환경 변수로 Husky 끄기
$env:HUSKY = "0"

4. 훅 대신 빌드·CI에서 검사하기

팀원 환경 차이로 훅을 유지하기 어렵다면, 같은 검사를 빌드나 CI에서 강제한다.

{
  "scripts": {
    "lint": "eslint \"src/**/*.{js,ts,vue}\" --cache",
    "prettier:check": "prettier --check \"src/**/*.{js,ts,vue,json,css}\"",
    "check:code": "npm run lint && npm run prettier:check",
    "build": "npm run check:code && vite build"
  }
}

검사용 스크립트에서는 --fix를 빼서, 빌드가 파일을 몰래 고치지 않고 실패로 알리게 한다. 가장 확실한 방법은 PR마다 CI에서 같은 스크립트를 돌리는 것이다. 로컬 훅은 우회할 수 있지만 CI는 우회할 수 없다.