[ Git ] 커밋 히스토리를 깔끔하게 관리하기 위한 전략 ( feat. Squash, Rebase )

코그룸 프로젝트를 새로 시작하면서, 이전 프로젝트들을 진행하며 느꼈던 커밋 히스토리 관리의 아쉬움이 다시 떠올랐다. 이번에는 그런 문제들을 보완하고, 처음부터 커밋 히스토리를 좀 더 명확하고 깔끔하게 관리해보고 싶었다. 그래서 고민했던 방식들과 그 과정을 정리해보았다!

 

 

3-way merge

---

처음 협업을 제대로 시작했을 당시에는 아직 체계가 명확히 정립되지 않은 상태였고, 기본적인 3-way merge 방식으로 브랜치를 병합했다. 기능 단위로 브랜치를 만들고, 개발이 끝나면 main 브랜치에 그대로 머지하는 구조였다. 문제는 깃 그래프가 점점 복잡해졌다는 점이다.
특히 머지 전략이 명확히 정해지지 않았던 만큼, 아래의 사진처럼 머지 커밋과 다양한 브랜치가 얽히면서 그래프는 점점 난잡해졌고, 커밋 히스토리도 한눈에 파악하기 어려운 상태가 되었다.

 

 

 

Rebase and Merge

---

앞선 문제를 해결하기 위해 이후 프로젝트들에서는 Rebase and Merge 방식을 사용했다. rebase를 적용하니 커밋 그래프가 직선으로 정리되면서 전체 흐름이 훨씬 깔끔하게 보였다!
병합 커밋이 생기지 않기 때문에 커밋 히스토리도 정돈된 느낌이 들었고, 마치 하나의 브랜치에서 일관되게 작업한 것처럼 로그가 구성되어 있어 작업 흐름을 파악하기 훨씬 수월해졌다.

 

물론 단점도 있었다. 브랜치 간 작업 내역의 차이가 클 경우 rebase 중 충돌이 자주 발생했고, 그만큼 충돌 해결 과정도 번거로웠다.
하지만 이전에 merge를 사용할 때 발생했던 복잡한 그래프 문제나, 커밋 히스토리에 쌓이던 불필요한 병합 커밋 문제는 확실히 해소되었다. 충돌 문제 역시 역할을 명확하게 나눠서 작업하니, 실제 개발 과정에서 큰 장애가 되지는 않았다.

 

그런데 또 다른 문제가 있었다.

 

기능 하나를 개발하는 동안 'fix: 스타일 수정', 'refactor: 변수명 변경', 'feat: 사용자 정보 수정 훅 구현' 처럼 다양한 중간 커밋이 쌓이게 된다. 이처럼 작업 중 커밋을 자유롭게 남기다 보면, 나중에 커밋 로그에 같은 기능에 대한 커밋이 여러 개로 흩어지게 된다.

 

문제는, 기능 개발이 실제로 완료된 커밋이 어느 시점인지 바로 파악하기 어려웠고 작업 이력을 되짚어보려 할 때 중간 커밋들이 오히려 방해가 되어 히스토리가 읽기 어렵게 되었다.

결국 커밋 히스토리에 있는 여러 중간 커밋들은 정보가 아니라 노이즈처럼 느껴지기 시작했다.

 

 

 

Squash and Merge + Rebase and Merge

---

이 문제를 해결하기 위해 선택한 방법이 바로 Squash Merge였다. squash는 여러 개의 커밋을 하나로 합쳐서 병합하는 방식이다.

 

PR을 올릴 때는 자유롭게 중간 커밋을 쌓을 수 있지만, 리뷰가 끝난 후 squash로 머지하면 메인 브랜치에는 하나의 의미 있는 커밋만 남게 된다. 예를 들어 feat: 로그인 기능 구현 (#12)처럼, 기능 단위로 정리된 깔끔한 커밋 하나만 기록되는 식이다.

 

현재 사용하고있는 워크플로우를 통해 조금 더 자세하게 살펴보자!

 

현재의 커밋 히스토리 관리 워크플로우

1. 기능 단위 브랜치 생성 후 자유롭게 커밋
개발 중에는 오타 수정이든 리팩토링이든 자유롭게 커밋한다.

예시)
feat: Next.js 프로젝트 생성
chore: 필요한 의존성 패키지 설치
chore: 디렉토리 구조 설정
chore: ESLint + Prettier 설정
chore: Issue & PR 템플릿 생성
chore: Storybook 설정 및 버튼 예시 컴포넌트 추가

 

2. PR 생성 및 코드 리뷰 진행
작업 흐름을 커밋 단위로 확인할 수 있기 때문에, 중간 커밋이 많아도 리뷰에는 큰 문제가 없다.

 

3. 리뷰 승인 후 Squash Merge로 커밋 합치기
리뷰가 끝나면 중간 커밋들을 하나로 squash해서 의미 있는 커밋 메시지로 정리한다.

[ Squash 과정 ]

1. rebase 해주기

git rebase -i HEAD~N  # N은 squash 하고 싶은 최근 커밋 개수

git rebase -i HEAD~6 # 예) 최근 6개의 커밋을 하나로 만들고 싶을 때

 

2. 그 후, 커밋 목록에서 pick → squash 또는 s 로 수정해준다.

• 가장 위 커밋은 pick
• 나머지는 squash 또는 s

pick   a1b2c3 feat: Next.js 프로젝트 생성
squash d4e5f6 chore: 필요한 의존성 패키지 설치
squash g7h8i9 chore: 디렉토리 구조 설정
squash j8sg0e chore: ESLint + Prettier 설정
squash gw09ew chore: Issue & PR 템플릿 생성
squash lv0rs9 chore: Storybook 설정 및 버튼 예시 컴포넌트 추가

 

3. 커밋 메시지 정리 화면에서 메시지 수정하기

chore: 프로젝트 초기 세팅 #1 (#2)    # 첫 줄을 최종 커밋 메시지의 제목으로 인식

feat: Next.js 프로젝트 생성

chore: 필요한 의존성 패키지 설치

chore: 디렉토리 구조 설정

chore: ESLint + Prettier 설정

chore: Issue & PR 템플릿 생성

chore: Storybook 설정 및 버튼 예시 컴포넌트 추가

 

4. squash 완료 후, 강제 푸시 : 이미 원격에 push된 커밋이라면 강제 푸시가 필요합니다.

git push --force

 

5. 결과 확인

 

4. Rebase and merge로 메인 브랜치에 병합
rebase 전략을 유지해 그래프가 직선으로 정리되고, 머지 커밋 없이 깔끔하게 관리된다.