git 브랜치 관리 전략

 

브랜치 버전 관리 전략의 핵심 구조

브랜치명	역할	수명	설명
main (master)	제품 출시 가능한 상태	영구적	현재 배포되어 고객이 사용 중인 안정적인 버전
develop	다음 버전을 위한 개발	영구적	개발 중인 코드들이 모이는 메인 통합 브랜치
feature/	새로운 기능 개발	임시	develop에서 갈라져 나와 기능 완성 후 다시 develop으로 병합
bugfix/	개발 중 발견된 버그 수정	임시	아직 배포되지 않은 개발 단계의 버그를 고치기 위해 develop에서 분기
hotfix/	실서비스 긴급 버그 수정	임시	이미 배포된 운영(production) 환경의 치명적 오류를 고치기 위해 main에서 직접 분기
release/	배포전 통합 테스트 및 수정	임시	배포 직전 develop이 완료된 후 개발을 중지하고 통합 테스트와 버그 수정용 버전

 

 

버전 관리의 흐름(git flow)

Case A: 개발 중 버그 발견 (bugfix)

다음 출시를 준비 개발하는 도중에 버그가 발생한 경우입니다.

아직 사용자에게 배포되지 않은 상태입니다.

1.develop 브랜치로부터 브랜치 생성

develop 브랜치 최신 상태에서 bugfix/issue-123 형태로 브랜치를 생성합니다.

이슈 트래킹 도구(예: JIRA, tello, 칸반보드 등)를 사용중이 아니라면, 마크다운 문서 (.md)으로 이슈 설명을 적어주면 협업에 좋습니다.

2.버그 수정 및 테스트.

해당 브랜치에서 문제를 해결하고 로컬/QA 환경에서 정상 동작하는지 검증합니다.

3.Pull Request (PR) 및 병합

코드 리뷰를 거쳐 develop 브랜치로 다시 병합(Merge)하고 수정 완료된 브랜치는 삭제합니다.

 

Case B: 실서비스 장애 발생 (hotfix)

현재 사용자가 쓰고 있는 서비스에서 즉각 해결해야 하는 심각한 오류가 터진 경우입니다.

1. Main(master) 브랜치로부터 분기

현재 배포본인 브랜치에서 hotfix/v1.0.1 형태로 직접 브랜치를 생성합니다.

2. 수정 및 태깅

오류를 해결한 뒤 버전 태그(예: v1.0.1)를 달아줍니다.

3. 양방향 병합 및 배포.

수정한 코드를 배포용 브랜치에 병합하고 즉시 실서비스에 재배포합니다.

동일한 버그가 다음 개발 버전에도 남아있지 않도록, 수정 사항을 develop 브랜치에도 반드시 병합합니다.

 

효율적인 관리를 위한 실무 팁

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 (개발중 버그 수정) 예제

bugfix 브랜치 생성: 자동으로 develop에서 분기.

git flow bugfix start profile-error

이 명령어를 실행하면 자동으로 develop 브랜치 기준으로 bugfix/profile-error 브랜치가 생성되고, 그 브랜치로 이동(checkout)합니다.

 

코드 수정 및 커밋: 일반적인 Git 작업으로 문제가 되는 프로필 코드를 수정하고 커밋합니다.

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 "커밋 메시지"

 

hotfix 완료 (핵심 마술):main/develop 양방향 병합 및 태깅합니다.

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