원커맨드 타임머신: Git Bisect로 말도 안 되는 버그 추적하기

어느 날 갑자기 일어날 수가 없는 버그를 마주하고, “어제까진 잘 됐는데…”라는 생각이 들었다면, 당신에게 부족했던 도구는 바로 git bisect일 가능성이 큽니다.

git bisect는 리포지토리용 타임머신과 같습니다. 프로젝트 히스토리를 앞뒤로 점프해 가며, 어느 커밋에서 버그가 처음 생겼는지 정확히 찾아낼 수 있게 해줍니다. 무작정 예전 커밋을 체크아웃하면서 찍어 맞추는 대신, 이 도구는 이분 탐색을 기반으로 한 체계적인 프로세스로 대규모·고변동 코드베이스에서도 빠르게 범인을 좁혀 갑니다.

이 글에서는 git bisect가 무엇인지, 어떻게 사용하는지, 그리고 **커밋 위생(commit hygiene)**을 잘 지키면 왜 이 도구가 훨씬 더 강력해지는지 살펴봅니다.

코드베이스가 커질수록 버그 추적이 고통스러워지는 이유

코드베이스가 커지면, “뭔가 망가졌다”는 상황이 더 이상 금방 풀리는 퍼즐이 아니라 꽤 심각한 문제가 됩니다.

“잘 되던 상태”와 “망가진 상태” 사이에 수백, 수천 개의 커밋
여러 기능 브랜치가 동시에 병합되는 상황
여러 개발자가 같은 서브시스템을 건드리는 구조

이런 상황에서 다음과 같은 방식으로 문제의 커밋을 찾으려고 하면:

예전 커밋을 하나씩 수동으로 체크아웃하고
테스트를 돌려 보고
다음에는 더 과거로 갈지, 더 최근으로 갈지 감으로 결정하는

…사실상 히스토리를 선형 탐색(linear search) 하고 있는 겁니다. 최악의 경우 수십, 수백 개의 커밋을 직접 확인해야 할 수도 있습니다.

git bisect는 이 과정을 **이분 탐색(binary search)**으로 바꿔 줍니다. 한 커밋씩 앞으로 걸어가는 대신, “정상”과 “비정상” 사이의 정확한 중간 지점을 골라 매번 탐색 공간을 절반으로 줄입니다.

차이는 압도적입니다.

선형 탐색으로 1,000개 커밋을 찾을 때 = 최대 1,000번 테스트
이분 탐색으로 1,000개 커밋을 찾을 때 ≈ 10번 테스트 (왜냐하면 log₂(1000) ≈ 10이기 때문)

이게 바로 git bisect의 힘입니다.

Git Bisect는 실제로 무엇을 하는가

본질적으로 git bisect는 커밋 히스토리에 대해 수행하는, 사람이 답을 알려 주는 가이드형 이분 탐색입니다.

당신이 제공해야 하는 것은:

bad 커밋: 버그가 존재하는 커밋 (보통 현재 HEAD)
good 커밋: 버그가 없던 것을 확실히 아는 커밋(태그, 브랜치, SHA 등)

그러면 Git은 다음 순서로 동작합니다.

good과 bad 사이의 중간 지점 커밋을 찾습니다.
그 커밋을 체크아웃합니다.
당신에게 묻습니다: 이 커밋은 good인가요, bad인가요?
당신의 답에 따라 검색 공간의 절반을 버리고 다시 반복합니다.

몇 번만 반복하면, 결국 첫 번째 bad 커밋—즉, 해당 회귀(regression)를 처음 도입한 정확한 커밋—만 남게 됩니다.

이 방식은 다음과 같이 신뢰성 있게 테스트할 수 있는 모든 종류의 버그에 적용할 수 있습니다.

깨지는 자동화 테스트
특정 명령을 실행할 때 나는 크래시
UI에서 발생하는 시각적 글리치
성능이 갑자기 나빠진 회귀 버그

매번 “good인가 bad인가”만 확실히 판별할 수 있으면, 나머지는 git bisect가 알아서 처리합니다.

최소한의 `git bisect` 워크플로우

가장 기본적인 사용법은 다음과 같습니다.

# 1. bisect 세션 시작
$ git bisect start

# 2. 현재 커밋을 bad로 표시 (여기에서 버그가 재현됨)
$ git bisect bad

# 3. 버그가 없던 커밋이나 태그를 good으로 표시
$ git bisect good v1.2.0

이렇게 하면 Git은:

v1.2.0과 현재 HEAD 사이의 중간 커밋을 자동으로 체크아웃하고,
그 커밋의 해시를 알려 준 뒤, 이 커밋이 good인지 bad인지 판단해 달라고 합니다.

이제 할 일은 테스트 후 라벨링뿐입니다.

# 여기서 테스트를 수행 (수동이든 자동이든 상관 없음)
# 버그가 재현되면:
$ git bisect bad

# 버그가 재현되지 않으면:
$ git bisect good

커밋에 good/bad 라벨을 붙일 때마다 Git은 다시 중간 지점을 골라 체크아웃합니다. 이 과정을 반복하다 보면, Git이 다음과 같은 메시지를 출력합니다.

<commit-sha> is the first bad commit

이 시점에서 바로 그 커밋이 범인입니다.

bisect 세션을 종료하고 원래 작업하던 브랜치/커밋으로 돌아가려면:

$ git bisect reset

이 명령으로 작업 트리와 HEAD가 원래 상태로 복원됩니다.

자동화: 진짜 의미의 “원커맨드” 만들기

매 커밋을 수동으로 테스트하는 것도 가능하지만, git bisect의 진가가 발휘되는 순간은 테스트 단계를 자동화했을 때입니다.

다음 조건을 만족하는 스크립트나 명령이 있다면:

정상일 때 종료 코드(exit code)가 0을 반환하고
버그가 있을 때 0이 아닌 값을 반환한다면

…Git이 bisect 과정을 처음부터 끝까지 자동으로 수행할 수 있습니다.

예시: 자동화된 Bisect

$ git bisect start
$ git bisect bad
$ git bisect good v1.2.0
$ git bisect run ./run_regression_check.sh

git bisect run은 다음을 수행합니다.

중간 지점 커밋을 체크아웃합니다.
해당 커밋에서 ./run_regression_check.sh를 실행합니다.
스크립트의 종료 코드를 해석합니다.
- 0 → good
- 0이 아님 → bad
이 과정을, 첫 번째 bad 커밋을 찾거나 더 이상 진행할 수 없을 때까지 반복합니다.

이제 정말로 원커맨드 타임머신처럼 동작합니다. 명령 한 번 실행해 두고 커피 한 잔 마시고 오면, 어느 커밋에서 문제가 시작됐는지 정확히 찍혀 있습니다.

run에 자주 사용하는 명령 예시는 다음과 같습니다.

특정 테스트만 돌리는 포커스드 테스트 스위트: npm test some-suite, pytest tests/test_bug.py
서비스들을 띄우고 특정 엔드포인트를 호출한 뒤 종료하는 커스텀 스크립트
기준값을 넘으면 실패하도록 만든 성능 벤치마크

커밋 위생이 Bisect 효율을 좌우하는 이유

git bisect는 단순히 “첫 번째 bad 커밋”을 찾는 것이 아니라, 당신의 테스트 관점에서 처음으로 ‘나쁘다’고 판단되는 커밋을 찾아 줍니다.

즉, bisect의 유용성은 곧 커밋 히스토리의 품질과 직결됩니다.

작고 목적이 분명한 커밋 → 해당 커밋이 실제로 버그와 관련됐을 가능성이 크고, 원인 파악이 쉽습니다.
여러 변경이 뒤섞인 거대한 커밋 → 첫 bad 커밋이 나오더라도, 그 안에 서로 상관없는 변경이 잔뜩 있어서 분석이 어려워집니다.
빌드가 안 되거나 기본 테스트가 깨지는 커밋이 자주 등장 → bisect 도중에 자꾸 막혀서 사실상 사용이 불가능해집니다.

그래서 커밋 위생을 잘 지키면 장기적으로 다음과 같은 이득이 생깁니다.

커밋을 작고 포커스 있게 만들기
- 각 커밋은 하나의 논리적 변경만 담는 것이 좋습니다.
- diff를 이해하기 쉽고, revert도 쉽고, bisect 결과도 해석하기 쉬워집니다.
메인 브랜치를 항상 “녹색” 상태로 유지하기
- 메인 브랜치(main, master 등)는 항상 빌드가 성공하고 테스트가 통과하는 상태로 두는 것이 이상적입니다.
- 이렇게 하면 bisect에서 “good”의 기준이 명확해집니다.
rebase와 squash를 전략적으로 사용하기
- 인터랙티브 리베이스(git rebase -i)를 활용하면:
  - 시끄러운 WIP 커밋들을 하나의 의미 있는 커밋으로 합치고,
  - 커밋 순서를 재배치해 더 읽기 좋은 히스토리를 만들 수 있습니다.
- PR 머지 시 “Squash and merge”를 사용하면, 지저분한 브랜치 히스토리를 하나 혹은 소수의 의미 있는 커밋으로 정리할 수 있습니다.
설명력 있는 커밋 메시지 작성하기
- bisect 결과로 지목된 커밋의 메시지가 왜 그 변경을 했는지 잘 설명하고 있다면, 버그의 원인도 빠르게 짐작할 수 있습니다.

반대로 커밋 히스토리가 다음처럼 생겼다면:

“Fix tests”
“More fixes”
“WIP”
“Oops”

…bisect 자체는 여전히 동작하지만, 걸려 나온 커밋마다 작은 고고학 발굴을 해야 할 수 있습니다.

반면 히스토리가 이렇게 생겼다면:

“사용자 인증을 JWT 기반으로 리팩터링”
“회원가입 폼에 입력 검증 추가”
“created_at 인덱스를 추가해 상품 검색 쿼리 최적화”

…bisect로 특정 커밋을 찾는 순간, “아, 이 변경 때문에 그럴 수 있겠다”라는 이해가 바로 따라옵니다.

팀 환경에서 Git Bisect 활용하기

팀 단위, 특히 크거나 빠르게 변하는 코드베이스를 가진 팀에서는 git bisect가 단순한 개인 디버깅 도구를 넘어, 운영(operational) 레벨의 도구가 됩니다.

팀 입장에서의 주요 이점은 다음과 같습니다.

회귀(regression) 대응 속도 향상: “뭔가 망가졌다”에서 “이 커밋, 이 사람이 작업한 변경에서 시작됐다”까지를 몇 분~몇 시간 안에 좁힐 수 있습니다(며칠이 아니라).
책임 소재의 명확화: 누군가를 탓하기 위함이 아니라, 해당 변경을 가장 잘 이해하는 사람을 빠르게 찾기 위해서입니다.
코드 품질 향상: 팀이 bisect를 적극 활용한다는 인식이 자리 잡으면, 자연스럽게 커밋을 깨끗이 유지하고, 테스트를 신뢰할 수 있도록 만들며, 메인 브랜치를 안정적으로 유지하려는 문화가 생깁니다.

실무적인 팁 몇 가지:

버그를 고칠 때마다 작고 명확한 테스트를 하나씩 추가하도록 권장하세요. 나중에 같은 버그가 재발했을 때, 이 테스트가 git bisect run의 핵심이 됩니다.
인시던트 대응 플레이북에 bisect를 포함하세요. 프로덕션에서 회귀가 발생하면, 초기에 해야 할 작업 목록에 “마지막 정상 릴리스와 현재 릴리스 태그 사이를 bisect한다”를 넣는 식입니다.
Feature flag와 일관된 배포 전략을 사용해, 항상 신뢰할 수 있는 “known good” 기준점(태그, 릴리스, 커밋 등)을 확보해 두는 것도 중요합니다.

Git Bisect가 빛을 발하는 순간 (그리고 그렇지 않은 순간)

git bisect가 특히 효과적인 경우:

버그가 안정적으로 재현 가능할 때
명확한 패스/페일 기준을 정의할 수 있을 때
코드베이스가 커져서 수동으로 추적하기가 힘들 때

반면 사용이 까다로운 경우도 있습니다.

버그가 플레이키(flaky) 할 때 (예: 레이스 컨디션, 비결정적 동작 등)
중간 커밋들 중 상당수가 빌드가 안 되거나 실행이 불가능할 때
예전 커밋을 실행하는 데 필요한 환경을 맞추기 어려울 때(마이그레이션, 외부 서비스 의존성 등)

그래도 이런 상황에서도 시도해 볼 만한 경우가 많습니다. 예를 들어:

Docker나 재현 가능한 개발 환경을 써서 환경을 최대한 안정화하고,
버그 재현률을 높여 주는 테스트 하네스를 작성해, flakiness를 줄일 수 있습니다.

마무리: “말도 안 된다” 싶은 버그를 풀어낼 수 있는 퍼즐로 바꾸기

git bisect는 지긋지긋한 선형 버그 추적을, 빠르고 구조화된 이분 탐색 기반 히스토리 탐색으로 바꿔 줍니다. 패턴은 단순합니다.

git bisect start
git bisect bad
git bisect good <known-good-commit-or-tag>
# 이후: git bisect good / bad  (또는 git bisect run <command>)

이 패턴만 알면, 리포지토리를 타임머신처럼 다루면서 정확히 언제부터 일이 잘못되기 시작했는지 곧바로 찾아갈 수 있습니다.

그리고 진짜 마법은 git bisect를 좋은 커밋 위생과 함께 사용할 때 일어납니다.

작고 포커스된 의미 있는 커밋
항상 깨끗하게 유지되는 메인 브랜치
계획적인 rebase와 squash 활용

이런 습관은 단지 히스토리를 보기 좋게 만들기 위한 것이 아니라, 미래의 디버깅 속도와 효율을 극적으로 끌어올리기 위한 투자입니다.

다음에 “이건 진짜 말이 안 되는데…” 싶은 버그를 만난다면, 더 이상 찍어 맞추지 마세요. bisect 세션을 시작하고, 간단한 테스트를 정의한 다음, Git이 당신을 문제의 순간까지 안내하도록 맡겨 두면 됩니다.