Git Bisect: 버그를 유발한 커밋 찾기
어제는 정상적으로 작동하던 기능이 오늘은 실패합니다. Git bisect를 사용해 회귀(regression)를 유발한 커밋을 정확히 짚어내고, 리비전을 자동으로 테스트하며, 결과를 안전하게 조사하는 방법을 배워봅니다.
지난주만 해도 정상적으로 작동했던 웹사이트가, 오늘은 결제 금액 계산 오류, 자바스크립트 컴포넌트 비응답, 또는 PHP 엔드포인트의 예상치 못한 데이터 반환으로 문제가 발생했습니다.
버그가 Git 기록 어딘가에 존재한다는 것은 알고 있지만, 마지막 정상 버전 이후 저장소에는 수십 또는 수백 개의 커밋이 쌓여 있습니다. 모든 커밋을 열고 모든 diff를 읽는 것은 거의 가장 빠른 해결책이 아닙니다.
Git에는 바로 이러한 상황을 해결하기 위해 설계된 도구가 있습니다: git bisect. 모든 커밋을 검사하는 대신, 이 도구는 이진 검색을 통해 문제를 처음 일으킨 커밋을 식별합니다. 신뢰할 수 있는 테스트를 통해 이 과정을 자동화할 수 있습니다.
이 튜토리얼에서는 작은 PHP 프로젝트를 만들고, 고의로 회귀를 일으킨 다음, Git bisect를 사용하여 이를 찾고, 동일한 기술을 실제 프로젝트에 적용하는 방법을 배웁니다.
1. Git bisect의 작동 원리
애플리케이션이 커밋 A에서는 정상적으로 작동했지만 커밋 H에서는 실패한다고 가정해 보겠습니다. Git bisect는 두 개의 기준점이 필요합니다: 기능이 확실히 작동한 좋은 커밋과 버그가 확실히 존재하는 나쁜 커밋.
Git은 중간 버전을 체크아웃합니다. 사용자는 이를 테스트하고, 작동 여부를 보고하며, Git은 나머지 검색 범위를 줄입니다. 행동이 일관되게 분류될 수 있다고 가정할 때, 약 128개의 후보 커밋에 대해 이진 검색은 일반적으로 모든 128개를 검사하는 대신 약 7번의 테스트가 필요합니다.
공식 Git 문서는 이 프로세스와 그 한계에 대해 설명합니다.
2. 재현 가능한 PHP 회귀 발생시키기
작은 가격 계산 함수를 만들 것입니다. 프레임워크, 데이터베이스, Composer 패키지 또는 웹 서버는 필요하지 않습니다. Git과 PHP CLI가 설치되어 있어야 하며, Git은 커밋을 위해 사용자 이름과 이메일이 구성되어 있어야 합니다.
디렉토리를 만들고 저장소를 초기화하세요:
mkdir git-bisect-demo
cd git-bisect-demo
git init
price.php을 생성하세요:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price - $discount;
}
예상 동작은 간단합니다: finalPrice(100, 20)은 80을 반환합니다.
이 정상 버전을 커밋하세요:
git add price.php
git commit -m "Add working price calculation"
다음으로, 관련 없는 변경 사항을 만드세요:
echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"
마지막으로, price.php에서 계산을 변경하여 버그를 일으키세요:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price + $discount;
}
깨진 버전을 커밋하세요:
git add price.php
git commit -m "Refactor price calculation"
이제 프로젝트에는 세 개의 커밋이 있으며, 마지막 커밋에는 고의로 회귀가 발생했습니다.
3. 수동으로 회귀 찾기
먼저 작업 트리가 깨끗한지 확인하세요:
git status --short
이 명령은 출력을 생성하지 않아야 합니다. 미커밋된 작업이 있는 경우, 시작하는 전에 적절히 커밋하거나 stash하세요.
이제 Git bisect를 시작하세요:
git bisect start
git bisect bad HEAD
git bisect good HEAD~2

여기서 HEAD은 나쁜 커밋이고, HEAD~2은 첫 번째 정상 커밋을 가리킵니다. Git은 중간 커밋을 체크아웃합니다.
계산 테스트를 수행하세요:
php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'
출력이 80이면, 해당 버전을 좋은 것으로 표시하세요:
git bisect good
120이면, 나쁜 것으로 표시하세요:
git bisect bad
Git은 첫 번째 나쁜 커밋을 식별할 때까지 커밋을 선택하기를 계속합니다. 이 세 커밋 시연에서는 하나의 중간 커밋만 테스트하면 됩니다.
완료되면 원래 브랜치로 돌아오세요:
git bisect reset
bisect 중에는 Git이 일반적으로 분리된 HEAD 상태에서 역사적 버전을 체크아웃합니다. git bisect reset은 조사를 시작하기 전에 사용하던 버전으로 돌아갑니다.
4. git bisect run으로 조사 자동화하기
버그가 시각적 검사를 필요로 하는 경우 수동 테스트가 유용합니다. 그러나 행동이 명령으로 확인될 수 있는 경우, 자동화가 더 효율적입니다.
Git은 git bisect run <command>를 지원합니다. 이 명령은 종료 코드를 사용하여 결과를 전달합니다:
| 종료 코드 | 의미 |
|---|---|
0 |
좋은 커밋 |
1–124 또는 126–127 |
나쁜 커밋 |
125 |
이 커밋을 테스트할 수 없음 |
| 기타 값 | 조사 중단 |
이러한 규칙은 공식 Git bisect 매뉴얼에서 유래합니다.
저장소 외부에 테스트 스크립트를 만드세요. 예를 들어, ../check-price.php이 있습니다:
<?php
declare(strict_types=1);
require __DIR__ . '/git-bisect-demo/price.php';
exit(finalPrice(100, 20) === 80 ? 0 : 1);
이 스크립트는 프로젝트 폴더가 git-bisect-demo이고 check-price.php 옆에 있다고 가정합니다. 프로젝트 폴더 내부에서 다음 명령을 실행하세요:
git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset
Git은 선택된 역사적 버전에서 테스트를 실행하여 첫 번째 나쁜 커밋을 식별할 때까지 계속합니다. 테스트 스크립트가 저장소 외부에 있으므로, 이전 버전을 체크아웃해도 스크립트가 제거되지 않습니다.
실제 프로젝트에서는 안정적인 테스트 명령이나 조사 중인 역사적 버전과 호환되는 외부 테스트 스크립트를 사용하세요.
5. 실제 웹 프로젝트에 이 기술 적용하기
이 워크플로는 워드프레스 플러그인, 조마 확장 프로그램, 자바스크립트 애플리케이션 또는 PHP 라이브러리에도 동일하게 적용됩니다.
체크아웃 기능이 최신 버전에서 깨졌지만, v1.4.0에서 작동했다고 가정해 보겠습니다. 먼저 해당 릴리스가 실제로 좋은지 확인한 다음 시작하세요:
git bisect start HEAD v1.4.0
프로젝트에 선택한 모든 버전에 걸쳐 작동하는 PHPUnit 테스트가 있는 경우, 수동으로 실행할 수 있습니다:
vendor/bin/phpunit tests/CheckoutTest.php
각 테스트 후, git bisect good 또는 git bisect bad을 보고하세요.
테스트가 신뢰할 수 있게 자동화되면:
git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset
역사적 커밋은 다른 PHP 버전, 의존성, 데이터베이스 스키마 또는 빌드 도구를 필요로 할 수 있습니다. 환경이 호환되지 않아 테스트가 실패하는 것은 반드시 회귀를 나타내지 않습니다. 테스트 환경이 관련 역사적 버전을 재현할 수 있는지 확인하세요.

6. 오래된 커밋을 테스트할 수 없는 경우 어떻게 해야 합니까?
때때로 역사적 버전이 관련 없는 이유로 빌드되지 않을 수 있습니다. 이를 자동으로 나쁜 것으로 표시하지 마세요.
다음 명령을 사용하세요:
git bisect skip
Git은 다른 후보를 시도합니다. 자동화된 테스트의 경우, 종료 코드 125는 Git에게 해당 버전을 건너뛰도록 알립니다.
너무 많은 커밋을 건너뛰면 정밀도가 떨어집니다. 테스트할 수 없는 커밋이 회귀와 인접한 경우, Git은 하나의 정확한 커밋이 아닌 여러 가능한 원인을 보고할 수 있습니다.
장기적인 좋은 관행은 재현 가능한 개발 환경을 유지하고, 의존성 버전을 고정하며, 중요한 회귀 테스트를 관련 없는 인프라와 독립적으로 유지하는 것입니다.
7. 버그를 유발한 커밋 검사하기
Git이 첫 번째 나쁜 커밋을 식별한 후, 이를 검사하세요:
git show <commit-hash>
변경된 파일을 보려면:
git show --stat <commit-hash>
특정 파일을 검사하려면:
git show <commit-hash> -- price.php
첫 번째 나쁜 커밋은 반드시 버그의 유일한 원인은 아닙니다. 커밋은 이전에 숨겨진 문제를 드러내거나, 다른 변경 사항과 상호작용하거나, 이후 변경된 외부 서비스에 의존할 수 있습니다.
식별된 커밋을 사용하여 근본 원인을 조사하세요. 해당 커밋의 모든 줄이 잘못된 증거로 간주되지 않도록 하세요.
8. 일반적인 문제와 해결책
버그가 일관되지 않게 나타남
테스트가 동일한 버전에서 때로는 통과하고 때로는 실패하는 경우, bisect 결과가 신뢰할 수 없게 됩니다. 테스트를 여러 번 실행하고, 가능한 경우 타이밍 의존성을 제거하며, 외부 입력을 제어하세요. 반복적인 테스트는 신뢰성을 향상시키지만, 조사 시간을 증가시킵니다.
테스트가 모든 역사적 버전에서 실패함
알려진 좋은 커밋이 실제로 좋은지 확인하세요. 새로운 bisect 세션을 시작하기 전에 해당 버전을 별도로 체크아웃하고 테스트를 실행하세요. 그곳에서도 실패하면, 테스트 또는 환경이 잘못된 것일 수 있습니다.
Git이 버전 전환을 거부함
미커밋된 변경 사항은 체크아웃을 방해할 수 있습니다. git status을 확인하고, 변경 사항을 보존한 후 재시작하세요. git reset --hard과 같은 파괴적인 명령을 사용하지 마세요. 정확히 무엇을 버리는지 이해하지 못하는 경우.
기록에 많은 병합 커밋이 포함됨
복잡한 저장소의 경우, Git은 ```bash git bisect start --first-parent HEAD v1.4.0
이는 첫 번째 부모 기록을 따르며, 병합을 통해 발생한 회귀를 조사하는 데 도움이 될 수 있습니다. 그러나 이는 고려되는 커밋을 변경하므로, 일반적인 bisect를 위한 보편적인 대체 수단은 아닙니다.
### 버그가 프로덕션 데이터에 의존함
역사적 애플리케이션 코드를 라이브 프로덕션 데이터베이스에 절대 실행하지 마세요. sanitize된 fixtur와 재현 가능한 스키마를 갖춘 격리된 테스트 환경을 사용하세요. 이전 버전에는 프로덕션과 호환되지 않는 마이그레이션이나 가정이 포함될 수 있습니다.
## 9. 실용적인 디버깅 체크리스트
- 버그가 재현 가능한지 확인하세요.
- 작동하는 것으로 알려진 한 커밋과 실패하는 것으로 알려진 한 커밋을 식별하세요.
- 미커밋된 작업을 보존하세요.
- 명확한 통과/실패 결과를 가진 신뢰할 수 있는 테스트를 정의하세요.
- 외부 서비스와 테스트 데이터를 일관되게 유지하세요.
- 실제로 테스트할 수 없는 커밋의 경우 `git bisect skip`를 사용하세요.
- 식별된 커밋을 검사하고 근본 원인을 확인하세요.
- `git bisect reset`로 마무리하세요.
## 결론
Git bisect는 불확실한 디버깅 작업을 구조화된 조사로 변환합니다. 최근 변경 사항 중 어느 것이 애플리케이션을 깨뜨렸는지 추측하는 대신, 작동하는 버전과 깨진 버전을 식별하고 Git이 기록을 좁히도록 하세요.
이 기술은 자동화된 테스트와 결합될 때 특히 강력해집니다. 수백 개의 커밋 사이에 숨겨진 회귀는 종종 몇 가지 테스트만으로 국한될 수 있습니다.
장기적인 PHP 프로젝트, 워드프레스 플러그인, 조마 확장 프로그램 또는 자바스크립트 애플리케이션을 유지 관리하는 개발자에게 `git bisect`는 일상적인 브랜칭과 병합을 넘어 가장 유용한 Git 명령 중 하나입니다.