git pre-commit 훅, 작업 디렉터리가 아니라 index를 검사해야 하는 이유

git pre-commit 훅은 커밋될 내용을 검사하려고 만들지만, 흔한 작성법대로 쓰면 실제로는 작업 디렉터리의 파일을 검사합니다. git add 한 뒤에 파일을 더 고쳤다면 검사받는 내용과 커밋되는 내용이 달라집니다. 임시 저장소에서 문법 오류가 있는 코드가 훅을 통과해 커밋되는 것을 재현했고, index를 검사하도록 고친 훅이 얼마나 느려지는지도 쟀습니다.

먼저 결론

  • stage된 파일의 이름을 얻어 그 경로를 검사하는 훅은 작업 디렉터리의 내용을 읽습니다. stage된 내용이 깨져 있어도 작업 디렉터리가 멀쩡하면 통과시키고, 반대의 경우에는 멀쩡한 커밋을 막습니다.
  • git checkout-index로 index를 임시 디렉터리에 풀어 거기서 검사하면 두 경우 모두 맞게 판정했습니다. git commit -a와 경로를 지정한 커밋에서도 맞았습니다.
  • 비용은 파일 1,000개에 67ms, 10,000개에 552ms였습니다. stage된 파일만 풀면 10,000개짜리 저장소에서도 15ms입니다.
  • 훅 안에서 다른 저장소에 git 명령을 쓴다면 GIT_INDEX_FILE을 지워야 합니다. 그대로 두면 바깥 저장소의 index가 오염돼 커밋이 실패합니다.

실험 환경

macOS 27.2.1(Apple M4 Pro, APFS SSD)에서 git 2.54.0(Apple Git-157)으로 실험했습니다. 훅 안에서 부르는 python3는 Command Line Tools에 들어 있는 3.9.6입니다. 개인 git 설정이 결과에 섞이지 않도록 GIT_CONFIG_GLOBAL=/dev/null, GIT_CONFIG_SYSTEM=/dev/null을 주고 새로 만든 저장소에서 돌렸습니다.

작업 디렉터리를 검사하는 git pre-commit 훅

직접 쓴 훅에서 자주 보이는 형태입니다. stage된 파이썬 파일의 목록을 얻어 검사 도구에 넘깁니다. 검사는 문법 확인 한 줄로 대신했습니다. 린터나 테스트를 넣어도 구조는 같습니다.

#!/bin/sh
# stage 된 파일의 "이름"을 얻어 그 경로를 검사한다.
files=$(git diff --cached --name-only --diff-filter=ACM -- '*.py')
[ -z "$files" ] && exit 0
python3 -c 'import ast,sys
for f in sys.argv[1:]: ast.parse(open(f).read(), f)' $files

git diff --cached --name-only가 돌려주는 것은 파일의 이름뿐입니다. 그 이름으로 파일을 열면 읽히는 것은 index에 올라간 내용이 아니라 지금 디스크에 있는 내용입니다.

재현: 문법 오류가 훅을 통과해 커밋된다

# 상황 1: 콜론이 빠진 코드를 stage 한 뒤, 작업 디렉터리에서만 고친다
printf 'def total(prices)\n    return sum(prices)\n' > app.py
git add app.py
printf 'def total(prices):\n    return sum(prices)\n# 주석 한 줄\n' > app.py

$ git status --short
MM app.py
$ git commit -q -m "가격 합계"      # 훅 통과, 종료 코드 0
$ git show HEAD:app.py | python3 -c 'import ast,sys; ast.parse(sys.stdin.read())'
  File "<unknown>", line 1
    def total(prices)
                     ^
SyntaxError: invalid syntax

MM은 stage한 변경과 stage하지 않은 변경이 한 파일에 같이 있다는 표시입니다. 훅은 고쳐 놓은 작업 디렉터리의 파일을 읽고 통과시켰고, 커밋에는 콜론이 빠진 코드가 들어갔습니다. 반대 상황도 만들어 봤습니다. 정상인 코드를 stage하고 작업 디렉터리에서는 작업 중이라 문법이 깨진 상태입니다.

훅 상황 1: stage는 깨짐, 작업 디렉터리는 고침 상황 2: stage는 정상, 작업 디렉터리는 깨짐
A. 작업 디렉터리 검사 커밋됨. 커밋된 파일에 문법 오류 커밋 막힘
B. index 검사 커밋 막힘 커밋됨. 커밋된 파일 정상

훅 A는 두 상황 모두 틀렸습니다. 상황 2는 불편한 정도지만 상황 1은 검사를 통과했다고 믿은 커밋이 깨져 있다는 점에서 더 나쁩니다. 일부만 골라 git add -p로 stage하는 습관이 있으면 자주 만나는 상태입니다.

index를 검사하는 훅

훅 B는 index의 내용을 임시 디렉터리에 풀고 그 안에서 같은 검사를 합니다.

#!/bin/sh
# index 의 내용을 임시 디렉터리에 풀고 거기서 검사한다.
tmp=$(mktemp -d) || exit 1
trap 'rm -rf "$tmp"' EXIT
git checkout-index --all --prefix="$tmp/"
files=$(git diff --cached --name-only --diff-filter=ACM -- '*.py')
[ -z "$files" ] && exit 0
cd "$tmp" && python3 -c 'import ast,sys
for f in sys.argv[1:]: ast.parse(open(f).read(), f)' $files

git checkout-index는 index에 있는 파일을 꺼내는 명령입니다. --prefix 끝의 슬래시는 꼭 있어야 합니다. 없으면 디렉터리가 아니라 파일 이름 앞에 붙는 문자열로 쓰입니다. 작업 디렉터리는 건드리지 않으므로 에디터가 파일을 다시 읽거나 빌드 캐시가 무효가 되는 일도 없습니다.

git commit -a 와 경로 지정 커밋에서도 맞는가

git commit -a나 git commit app.py는 git add 없이 커밋하므로 “index를 검사한다”는 말이 맞는지 의심스러웠습니다. 훅에서 환경 변수를 찍어 봤습니다.

명령 훅이 받은 GIT_INDEX_FILE
git commit .git/index
git commit -a (저장소 절대 경로)/.git/index.lock
git commit app.py (저장소 절대 경로)/.git/next-index-4914.lock (숫자는 실행마다 다름)

git은 이 두 경우에 커밋용 index를 따로 만들고 그 경로를 GIT_INDEX_FILE로 훅에 넘깁니다. checkout-index는 이 변수를 따르므로 꺼낸 내용은 실제로 커밋될 내용이었습니다. 작업 디렉터리의 깨진 app.py를 -a로 커밋하려 했을 때도, 다른 파일이 stage된 상태에서 git commit app.py를 했을 때도 index에서 꺼내 검사하는 훅은 커밋을 막았습니다.

훅 안에서 다른 저장소를 만지면 커밋이 깨진다

환경 변수를 찍다가 하나를 더 확인했습니다. 테스트가 임시 git 저장소를 만드는 프로젝트라면 훅에서 테스트를 돌릴 때 GIT_INDEX_FILE이 그대로 상속됩니다. 훅 안에서 임시 저장소를 만들어 git add를 해 봤습니다.

#!/bin/sh
tmp=$(mktemp -d) || exit 1
trap 'rm -rf "$tmp"' EXIT
(
  cd "$tmp" && git init -q inner && cd inner && echo hi > inner.txt && git add inner.txt
  echo "[환경 변수 그대로] 임시 저장소의 stage: $(git diff --cached --name-only | tr '\n' ' ')"
)
(
  unset GIT_INDEX_FILE GIT_DIR GIT_WORK_TREE GIT_PREFIX
  cd "$tmp" && rm -rf inner && git init -q inner && cd inner && echo hi > inner.txt && git add inner.txt
  echo "[unset 한 뒤]      임시 저장소의 stage: $(git diff --cached --name-only | tr '\n' ' ')"
)
exit 0
$ git commit -q -a -m "inner 실험"
[환경 변수 그대로] 임시 저장소의 stage: app.py inner.txt
[unset 한 뒤]      임시 저장소의 stage: inner.txt
error: invalid object 100644 45b983be36b73c0788dc9cbcb76cbb80fc7bb057 for 'inner.txt'
error: Error building trees

임시 저장소에 한 git add가 바깥 저장소의 index에 기록됐습니다. 임시 저장소의 stage 목록에 바깥의 app.py가 보이고, 바깥 커밋은 존재하지 않는 객체를 가리키는 inner.txt 때문에 실패했습니다. 변수를 지운 뒤에는 inner.txt만 보입니다.

같은 훅을 일반 git commit으로 돌리면 아무 문제 없이 지나갔습니다. 이때는 값이 상대 경로 .git/index라서 임시 저장소 안에서는 자기 index를 가리키기 때문입니다. 절대 경로를 받는 git commit -a에서만 깨졌고, 경로 지정 커밋도 절대 경로를 받으므로 조건이 같습니다. 평소에는 멀쩡하다가 -a를 쓴 날에만 커밋이 깨지는 훅이 되는 셈입니다. 훅에서 다른 저장소를 다루는 명령을 부를 때는 unset GIT_INDEX_FILE을 먼저 해 두는 편이 안전합니다.

비용: checkout-index와 stash 비교

index를 통째로 푸는 것이 느리지 않은지 쟀습니다. 0.7KB짜리 파이썬 파일로 저장소를 만들고 10개는 stage한 변경, 다른 10개는 stage하지 않은 변경을 둔 상태입니다. 값은 5회 중앙값입니다.

파일 수 checkout-index로 전체 풀기 stash --keep-index 왕복
100 23ms 84ms
1,000 67ms 70ms
10,000 552ms 144ms

풀어 놓은 임시 디렉터리를 지우는 시간까지 더하면 10,000개에서 949ms였습니다. 파일이 많아지면 git stash push --keep-index로 작업 디렉터리를 index 상태로 만들었다가 git stash pop으로 되돌리는 쪽이 빠릅니다. 대신 이 방식은 작업 디렉터리를 건드립니다. 왕복 한 번에 변경이 있던 파일 20개의 수정 시각이 모두 바뀌었습니다. 그리고 같은 줄에 stage한 변경과 stage하지 않은 변경이 겹쳐 있으면 되돌리다가 충돌이 납니다. 상황 1처럼 같은 줄에 두 변경이 겹친 상태에서 해 본 결과입니다.

$ git status --short
MM app.py
$ git stash push --keep-index -q
$ git stash pop
Auto-merging app.py
CONFLICT (content): Merge conflict in app.py
The stash entry is kept in case you need it again.
$ git status --short
UU app.py

훅은 검사만 하고 끝나야 하는데 작업 디렉터리의 파일에 충돌 표시가 들어갔고 파일 상태도 MM에서 충돌을 뜻하는 UU로 바뀌었습니다. pre-commit 프레임워크처럼 이 처리를 대신 해 주는 도구를 쓰는 것이 아니라면, 직접 쓰는 훅에서는 작업 디렉터리를 건드리지 않는 쪽을 권합니다.

10,000개를 다 푸는 0.5초가 부담이면 stage된 파일만 풀 수 있습니다. 같은 10,000개짜리 저장소에서 15ms가 걸렸고 10개가 풀렸습니다.

git diff --cached --name-only -z --diff-filter=ACM |
  git checkout-index -z --stdin --prefix="$tmp/"

파일 하나만 보고 판단하는 린터에는 이것으로 충분합니다. 다른 파일을 import해서 확인하는 검사나 테스트는 프로젝트 전체가 있어야 하므로 전체를 풀어야 합니다.

이 실험의 한계

작은 텍스트 파일만 있는 저장소에서 잰 값이라 큰 파일이 많은 저장소에서는 시간이 더 걸립니다. checkout-index는 git이 추적하는 파일만 꺼냅니다. 가상환경이나 node_modules처럼 추적하지 않는 디렉터리는 임시 디렉터리에 없으므로, 검사 도구는 원래 저장소에 있는 것을 절대 경로로 불러야 합니다. 훅이 받는 환경 변수의 값은 git 2.54.0에서 확인한 것이고 다른 버전이나 워크트리 구성에서는 다를 수 있습니다. 환경 변수에 관한 일반적인 설명은 githooks 문서에 있습니다.

함께 읽으면 좋은 글

Similar Posts

One Comment

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다