git 브랜치 관리 전략
브랜치 버전 관리 전략의 핵심 구조
| 브랜치명 | 역할 | 수명 | 설명 |
| main (master) |
제품 출시 가능한 상태 | 영구적 | 현재 배포되어 고객이 사용 중인 안정적인 버전 |
| develop | 다음 버전을 위한 개발 | 영구적 | 개발 중인 코드들이 모이는 메인 통합 브랜치 |
| feature/ | 새로운 기능 개발 | 임시 | develop에서 갈라져 나와 기능 완성 후 다시 develop으로 병합 |
| bugfix/ | 개발 중 발견된 버그 수정 | 임시 | 아직 배포되지 않은 개발 단계의 버그를 고치기 위해 develop에서 분기 |
| hotfix/ | 실서비스 긴급 버그 수정 | 임시 | 이미 배포된 운영(production) 환경의 치명적 오류를 고치기 위해 main에서 직접 분기 |
| release/ | 배포전 통합 테스트 및 수정 | 임시 | 배포 직전 develop이 완료된 후 개발을 중지하고 통합 테스트와 버그 수정용 버전 |
버전 관리의 흐름(git flow)
Case A: 개발 중 버그 발견 (bugfix)
다음 출시를 준비 개발하는 도중에 버그가 발생한 경우입니다.
아직 사용자에게 배포되지 않은 상태입니다.
develop 브랜치 최신 상태에서 bugfix/issue-123 형태로 브랜치를 생성합니다.
이슈 트래킹 도구(예: JIRA, tello, 칸반보드 등)를 사용중이 아니라면, 마크다운 문서 (.md)으로 이슈 설명을 적어주면 협업에 좋습니다.
해당 브랜치에서 문제를 해결하고 로컬/QA 환경에서 정상 동작하는지 검증합니다.
코드 리뷰를 거쳐 develop 브랜치로 다시 병합(Merge)하고 수정 완료된 브랜치는 삭제합니다.
Case B: 실서비스 장애 발생 (hotfix)
현재 사용자가 쓰고 있는 서비스에서 즉각 해결해야 하는 심각한 오류가 터진 경우입니다.
현재 배포본인 브랜치에서 hotfix/v1.0.1 형태로 직접 브랜치를 생성합니다.
오류를 해결한 뒤 버전 태그(예: v1.0.1)를 달아줍니다.
효율적인 관리를 위한 실무 팁
1. 명확한 브랜치 네이밍 규칙(Naming Convention)
- 종류/이슈번호-간단한설명 형식을 추천합니다. (예: bugfix/login-error-chrome, hotfix/payment-crash)
2. hotfix는 이후 반드시 develop 병합 잊지 않기
- main에만 hotfix를 반영하고 develop에 병합하지 않으면, 다음 배포 때 옛날 버그가 다시 살아나서 배포(Regression)되는 참사가 일어납니다.
3. Git-Flow CLI 도구 활용하기
- 일일이 브랜치를 따고 합치는 타이핑을 줄이기 위해 git-flow 패키지를 설치해 사용하는 것도 좋은 방법입니다.
이슈 관리용 마크다운 문서 예
### 1. 관련 이슈 및 링크
- **Issue Link**: #이슈번호 (예: #123)
- **Ticket Link**: [Jira/Trello 링크](url)
---
### 2. 버그 현상 및 원인
- **현상**: 어떤 조건에서 어떤 오류가 발생했는지 구체적으로 적어주세요.
- **원인**: 버그가 왜 발생했는지 코드 수준이나 로직 관점에서 짧게 요약해 주세요.
---
### 3. 해결 방안
- 문제를 해결하기 위해 수정한 핵심 로직이나 변경 사항을 설명합니다.
---
### 4. 재현 및 검증 방법
리뷰어가 로컬에서 직접 확인해 볼 수 있도록 가이드를 제공합니다.
#### 재현 시나리오
#### 검증 결과 (Screenshots / Screen Record)
- 전(Before) / 후(After) 사진이나 GIF를 첨부해 주세요.
---
### 5. 체크리스트
- [ ] 코딩 컨벤션 및 린터(Linter) 규칙을 준수했나요?
- [ ] 기존 기능에 영향을 주지 않는지 영향도 분석을 했나요?
git bash 에서 Branch 관리 예
1. 현재 작업중인 브랜치를 분리해야할 브랜치(예: main 또는 master)에서 최신 코드로 갱신
git pull origin main
2. 로컬 저장소에서 새 브랜치를 생성(예: hotfix/v1.0.1)하고 그 브랜치로 이동.
git checkout -b hotfix/v1.0.1
3. 코드 수정 후 모든 변경 파일 내역을 로컬 스테이징(준비 영역)에 올리기
git add -A
4. 로컬 저장소에 커밋 메시지와 함께 커밋
git commit -m "커밋용 메시지"
5. 새 로컬 브랜치는 원격 저장소에는 존재하지 않기 때문에 git push하면 에러가 발생하므로, 원격 브랜치와 동기화 설정(-u 또는 --set-upstream). 브랜치를 새로 생성하고 처음에만 한 번 -u 옵션을 붙여 push하면 다음 부터는 git push나 git pull로도 동기화되어 매칭됩니다.
git push -u origin hotfix/v1.0.1
6. 배포용 브랜치(main)로 이동
git checkout main
7. 원격 저장소 최신 상태 반영
git pull origin main
8. 변경 사항을 배포용 브랜치(main)에 병합
git merge hotfix/v1.0.1
9. 병합 완료되어 배포 준비가 된 최신 커밋에 태그 작성
git tag -a v1.0.1 -m "운영 서버 긴급 버그 수정 버전 1.0.1"-a는 주석 태그 생성, -m은 태그 메시지 지정
10. 원격 저장소에 태그 반영
# 특정 태그만 원격에 올리기 (안전한 방법)
git push origin v1.0.1
# 로컬에 있는 모든 태그를 한 번에 올리고 싶을 때
git push origin --tags
11. (선택) 로컬 및 원격 브랜치 삭제
# 1. 로컬 hotfix 브랜치 삭제
git branch -d hotfix/v1.0.1
# 2. 원격 hotfix 브랜치 삭제
git push origin --delete hotfix/v1.0.1
GIT FLOW CLI 도구
직접 hotfix 브랜치를 관리하려면 브랜치를 분기하고, 코드를 수정하고, main에 병합하고, 태그 달고, 다시 develop에 병합하는 과정을 거쳐야 하지만 git-flow CLI를 쓰면 이 모든 과정이 명령어 몇 개로 처리할 수 있습니다.
1. 설치
- macOS: brew install git-flow-avh
- Windows (Git Bash): 최근 Git for Windows에는 기본 내장되어 있습니다.
2. 초기화
git flow init실행하면 브랜치 이름 규칙을 물어보는 질문들이 나옵니다.
엔터(Enter)만 계속 쳐서 기본값으로 세팅하시면 됩니다.
(기본값: main, develop, feature/, bugfix/, release/, hotfix/ 등)
3. bugfix (개발중 버그 수정) 예제
git flow bugfix start profile-error이 명령어를 실행하면 자동으로 develop 브랜치 기준으로 bugfix/profile-error 브랜치가 생성되고, 그 브랜치로 이동(checkout)합니다.
git add -A
git commit -m "커밋 메시지"버그 수정 완료 및 병합: 버그 수정이 완료되면 자동으로 develop에 합치고 삭제합니다..
git flow bugfix finish profile-error
이 명령어 하나로 develop 브랜치로 이동해 bugfix/profile-error 브랜치의 수정 사항을 develop에 병합(Merge)한 뒤 로컬 bugfix/profile-error 브랜치를 삭제하는 작업을 한 번에 처리 합니다.
4. hotfix(서비스 긴급 장애 대응) 예제
현재 배포 버전이 v1.0.0 이라고 가정합니다.
hotfix 브랜치 생성: 자동으로 main에서 분기 합니다.
git flow hotfix start v1.0.1배포할 다음 버전 이름(v1.0.1)으로 시작합니다.
자동으로 main 브랜치에서 갈라져 나온 hotfix/v1.0.1 브랜치가 생성되고 이동합니다.
git add -A
git commit -m "커밋 메시지"git flow hotfix finish v1.0.1이 명령어로 main 브랜치에 코드를 병합하고 버그 수정본의 식별을 위해 v1.0.1이라는 Git Tag를 main에 자동으로 생성하고 develop 브랜치에도 자동으로 병합한뒤 로컬 hotfix/v1.0.1 브랜치를 삭제하는 작업을 모두 실행합니다.
5. 충돌 해결 절차(bugfix/profile-error 브랜치 기준) 예제
1단계: 어떤 파일에서 충돌이 났는지 확인합니다.
git status빨간색으로 충돌이 발생한 파일들이 표시됩니다.
2단계: 충돌을 해결합니다.
<<<<<<< HEAD
// 현재 develop 브랜치에 있던 기존 코드
=======
// 내가 bugfix 브랜치에서 수정한 코드
>>>>>>> bugfix/profile-error어떤 코드를 반영할지 결정하고 충돌 표시 기호는 삭제한 뒤 저장합니다.
3단계: git에 해결 완료 작업과 병합작업을 직접 마무리 합니다.
# 1. 해결된 파일 올리기
git add -A
# 2. git-flow 대신 git bash에서 직접 커밋
git commit -m "Merge branch 'bugfix/profile-error' into develop (resolved conflicts)"
4단계: 남은 브랜치 정리. 이미 develop 브랜치에 합쳐졌으므로 삭제
git branch -d bugfix/profile-error
만약 충돌 해결하다가 코드가 엉망이 되어 일단 충돌 해결을 미루고 이전 상태로 돌아가고 싶다면 병합 작업을 취소 할 수 있습니다.
git merge --abort그러면 git flow finish를 입력하기 전 브랜치 상태로 돌아갑니다.
hotfix에서는 main과 develop 두 브랜치에 모두 병합을 시도하기 때문에 main 부터 해결한 뒤 main에 커밋하고 이어서 develop이르 이동해 한번더 병합 및 충돌 해결 작업을 진행합니다.
6. 원격 저장소에 반영하기
git flow ... finish를 하면 로컬에는 완료되지만 최종적으로 원격 저장소에 반영하려면 로컬의 브랜치와 태그를 원격 저장소에 push해야 합니다.
# 로컬에서 합쳐진 develop과 main을 서버로 전송
git push origin develop
git push origin main
# hotfix 때 생성된 태그도 서버로 전송 (이 태그를 보고 CI/CD 도구가 자동 배포를 수행함)
git push origin --tags
