Git range-diff 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Git range-diff 사용법

git range-diff는 같은 작업 브랜치의 두 버전이 어떻게 달라졌는지 비교할 때 쓰는 명령이다. 2026년 7월 14일 기준 git-scm.com의 최신 git-range-diff 매뉴얼은 2.55.0이며, 이 명령을 "두 commit range, 특히 패치 시리즈의 두 버전"을 비교하는 도구로 설명한다.

실무에서 핵심은 세 가지다. rebase 뒤에 무엇이 바뀌었는지 확인하려는지, 두 범위를 어떤 문법으로 지정할지, 그리고 출력 결과를 사람이 읽는 검토용으로만 쓸지다. 이 글은 Git 공식 문서를 기준으로 range-diff의 기본 개념, 자주 쓰는 문법, 옵션 선택 기준을 정리한다.

Git range-diff는 언제 쓰면 될까?

일반적인 git diff는 두 트리 상태의 차이를 보여 주지만, rebase나 commit 분할 이후에는 "어떤 커밋이 유지됐고 무엇이 바뀌었는지"까지 읽어내기 어렵다. git range-diff는 각 커밋의 작성자 정보, commit message, patch diff를 비교해 서로 대응되는 커밋을 찾아 주기 때문에, 패치 시리즈를 다시 정리한 뒤 검토하기에 맞다.

특히 코드 리뷰 전 마지막 self-review, rebase 직후 변경 검증, 메일 기반 패치 시리즈의 v1과 v2 비교에서 유용하다. 반대로 기계적으로 파싱해야 하는 보고서가 필요하다면 이 명령은 맞지 않다.

가장 먼저 알아둘 기준은 무엇일까?

공식 문서는 range-diff 출력을 안정적인 기계 판독 형식으로 보지 말라고 명시한다. 출력은 사람이 읽는 porcelain 성격이며, 버전 간 텍스트 형식이 바뀔 수 있다. 따라서 CI 산출물의 고정 포맷이나 스크립트 파이프라인 입력으로 기대하기보다, 사람이 검토하는 비교 보고서로 이해하는 편이 안전하다.

범위 지정 문법은 어떻게 고르면 될까?

공식 문서에는 세 가지 입력 형식이 있다. 선택 기준은 비교 대상이 얼마나 명확한지에 따라 달라진다.

• git range-diff <old-range> <new-range>: 두 범위를 이미 알고 있을 때 가장 직접적이다.
• git range-diff <rev1>...<rev2>: 두 끝점만 알고 있고, 공통 조상 기준 양쪽 차이를 비교하고 싶을 때 맞다.
• git range-diff <base> <old-tip> <new-tip>: 같은 base에서 파생된 두 버전을 비교할 때 가장 읽기 쉽다.

공식 예시처럼 rebase 직후에는 git range-diff @{u} @{1} @가 자주 쓰인다. 현재 브랜치의 upstream, rebase 직전 HEAD, 현재 HEAD를 나란히 비교해 "rebase 때문에 어떤 patch가 달라졌는지"를 바로 볼 수 있기 때문이다.

git range-diff @{u} @{1} @

출력은 어떻게 읽으면 될까?

공식 예시를 보면 각 줄은 이전 범위의 커밋과 새 범위의 커밋이 어떤 관계인지 보여 준다. 완전히 대응되면 =, 수정된 대응이면 !, 새로 추가된 커밋이나 제거된 커밋은 별도 표식으로 나온다.

중요한 점은 이 명령이 단순히 commit hash를 비교하지 않는다는 것이다. Git은 patch 크기 대비 차이가 충분히 작으면 "같은 의도의 커밋"으로 대응시킨다. 그래서 rebase, commit message 수정, 작은 코드 정리 이후에도 검토 포인트를 비교적 자연스럽게 묶어 준다.

--creation-factor는 언제 조정할까?

기본값은 60이다. 공식 문서 설명대로 큰 수정이 들어간 커밋을 Git이 "기존 커밋의 수정본"이 아니라 "기존 커밋 삭제 + 새 커밋 추가"로 오인한다면 이 값을 더 크게 볼 수 있다. 반대로 서로 다른 커밋을 억지로 같은 계열로 묶는 느낌이 들면 더 작게 잡는 편이 맞다.

대부분의 저장소에서는 기본값으로 시작하는 것이 무난하다. 이 옵션은 패치 시리즈를 자주 크게 고쳐 보내는 흐름에서만 의미가 커진다.

merge commit까지 비교해야 할까?

기본적으로 공식 문서는 merge commit을 무시한다고 설명한다. 다만 --diff-merges=<format> 또는 축약형 --remerge-diff를 쓰면 merge commit도 비교에 포함할 수 있다.

공식 문서는 일반적인 경우 remerge 모드가 가장 자연스럽다고 본다. 충돌 없이 만들어진 merge라면 빈 diff로 보일 수 있고, 실제로 merge 결과에 손으로 조정한 부분이 있을 때만 차이가 드러나기 때문이다. 주제 브랜치가 merge commit을 포함하고 그 변경 의미까지 검토해야 할 때만 켜는 편이 좋다.

 

 

--left-only와 --right-only는 왜 필요할까?

전체 대응 관계보다 한쪽에만 남은 커밋을 빠르게 보고 싶을 때 쓴다. 공식 문서 기준으로 --left-only는 첫 번째 범위에만 남은 쪽을, --right-only는 두 번째 범위에만 남은 쪽을 강조한다.

예를 들어 rebase 뒤에 "무엇이 새로 들어왔는가"만 보고 싶다면 --right-only가 편하다. 반대로 drop된 커밋만 찾고 싶다면 --left-only가 더 직접적이다.

색상 출력은 그대로 두는 편이 좋을까?

공식 문서는 기본적으로 dual coloring을 사용한다고 설명한다. diff의 원래 색을 유지하면서 바깥쪽 변화 표시를 함께 보여 주므로, 단순한 빨강/초록 전체 라인 강조보다 읽기 쉽다.

터미널 색상 처리나 로그 저장 방식 때문에 이 표시가 오히려 복잡하게 보인다면 --no-dual-color로 단순화할 수 있다. 다만 사람 눈으로 세밀하게 검토할 때는 기본 동작이 더 유리한 편이다.

실무에서는 어떤 흐름이 무난할까?

패치 시리즈를 rebase하거나 commit을 재배열한 직후라면 먼저 git range-diff @{u} @{1} @처럼 이전 상태와 현재 상태를 비교한다. 여기서 삭제된 커밋, 예상보다 크게 바뀐 커밋, commit message 수정 여부를 먼저 본다.

그다음 merge commit이 있는 브랜치라면 필요할 때만 --remerge-diff를 추가한다. 결과를 팀 채팅이나 리뷰 설명에 옮길 때는 "새 커밋 추가", "기존 커밋 수정", "커밋 제거"처럼 사람이 이해할 수 있는 요약으로 풀어 쓰는 편이 낫다. 공식 문서가 말하듯 출력 포맷 자체는 고정 API가 아니기 때문이다.

FAQ

Q. git diff와 무엇이 가장 다른가?

git diff는 최종 파일 차이에 집중한다. git range-diff는 두 커밋 범위 안에서 어떤 커밋이 서로 대응되는지까지 계산하므로, rebase나 patch series 업데이트 검토에 더 적합하다.

Q. rebase 전에 꼭 upstream이 있어야 하나?

꼭 그렇지는 않다. 공식 문서의 세 번째 문법처럼 명시적인 <base> <old-tip> <new-tip>를 주면 된다. 다만 upstream과 reflog를 쓸 수 있는 브랜치라면 @{u}, @{1}, @ 조합이 가장 간단하다.

Q. 자동화 스크립트에서 결과를 파싱해도 될까?

권장하기 어렵다. 공식 문서는 출력이 기계 판독용 안정 포맷이 아니라고 분명히 설명한다. 자동화가 필요하다면 별도 Git plumbing 명령이나 diff 통계를 조합하는 쪽이 더 안전하다.

정리

git range-diff는 같은 브랜치의 "이전 패치 시리즈"와 "현재 패치 시리즈"를 비교하는 검토 도구다. 특히 rebase 직후 self-review에서 가치가 크다.

대부분의 경우에는 기본 문법부터 쓰고, merge commit이 있을 때만 --remerge-diff, 대응 판정이 어색할 때만 --creation-factor를 조정하면 된다. 핵심은 최종 파일 차이보다 "커밋 단위로 무엇이 유지됐고 무엇이 바뀌었는지"를 확인하는 데 있다.

참고 자료

• Git Documentation: git-range-diff
• Git Documentation: gitrevisions