git branch 사용법

Git으로 작업하다 보면 브랜치(branch)를 다룰 일이 정말 많죠. git branch 명령어를 사용하면 브랜치를 만들고 목록을 확인하고 이름을 바꾸거나 삭제할 수 있는데요.

이번 글에서는 git branch 명령어의 기본 사용법부터 실전 활용법까지 함께 살펴보겠습니다.

브랜치란?

Git에서 브랜치는 특정 커밋을 가리키는 가벼운 포인터입니다. 새 커밋을 만들 때마다 현재 브랜치의 포인터가 자동으로 최신 커밋으로 이동하죠.

보통 Git 저장소를 처음 만들면 main(또는 master)이라는 기본 브랜치가 생성됩니다. 여기서 새로운 브랜치를 만들면 현재 커밋을 기준으로 갈라져 나온 별도의 작업 공간이 만들어지는 것입니다.

      A---B---C  feature
     /
D---E---F---G  main

위 그림에서 feature 브랜치는 main 브랜치의 커밋 E에서 갈라져 나와 A, B, C 커밋을 따로 쌓고 있습니다. 그동안 main 브랜치에서는 F, G 커밋이 추가되었고요. 이처럼 브랜치를 활용하면 서로 영향을 주지 않고 여러 기능을 동시에 개발할 수 있습니다.

Git에서 현재 어떤 브랜치에 있는지를 나타내는 HEAD 포인터에 대해서도 함께 이해하면 브랜치 작동 방식을 더 깊이 파악할 수 있습니다.

브랜치 목록 조회

현재 로컬 저장소에 있는 브랜치 목록을 확인하려면 git branch를 인자 없이 실행하면 됩니다.

$ git branch
  develop
  feature/login
* main

* 표시가 있는 브랜치가 현재 작업 중인 브랜치입니다. 위 결과에서는 main 브랜치에서 작업하고 있다는 뜻이죠.

-v 옵션을 추가하면 각 브랜치의 마지막 커밋 정보도 함께 볼 수 있습니다.

$ git branch -v
  develop       a1b2c3d API 리팩토링
  feature/login e4f5g6h 로그인 페이지 구현
* main          i7j8k9l 배포 설정 업데이트

원격 브랜치 조회

git branch는 기본적으로 로컬 브랜치만 보여줍니다. 원격 저장소의 브랜치까지 확인하려면 -r 옵션을 사용합니다.

$ git branch -r
  origin/develop
  origin/feature/login
  origin/main

로컬 브랜치와 원격 브랜치를 한꺼번에 보고 싶다면 -a 옵션을 쓰면 됩니다.

$ git branch -a
  develop
  feature/login
* main
  remotes/origin/develop
  remotes/origin/feature/login
  remotes/origin/main

원격 브랜치 정보가 오래되었다면 git fetch 명령어로 먼저 최신 정보를 가져온 후 조회하는 것이 좋습니다.

$ git fetch origin
$ git branch -r

브랜치 트래킹 확인

리모트 저장소가 origin 하나일 때는 별로 신경 쓸 일이 없는데요. 오픈소스 프로젝트에 기여하다 보면 origin과 upstream 같이 리모트가 여러 개인 경우가 생기죠.

$ git remote
origin
upstream

이럴 때 git pull이나 git push를 리모트 인자 없이 실행하면 어느 리모트가 사용될까요? 정답은 현재 브랜치의 트래킹(upstream) 설정에 의해 결정됩니다.

git branch -vv 명령어를 사용하면 각 브랜치가 어떤 원격 브랜치를 트래킹하고 있는지 한눈에 확인할 수 있습니다.

$ git branch -vv
* main              a1e18813 [origin/main] Merge pull request #2346 from user/main
  sponsorkit        4cbd1a04 add sponsors section
  update-sponsorkit c6f47505 [origin/update-sponsorkit] ci: skip binary files in newline check

여기서 [origin/main] 같은 부분이 해당 브랜치의 트래킹 정보입니다. main 브랜치는 origin/main을 트래킹하고 있으므로 git pull이나 git push를 인자 없이 실행하면 origin 리모트가 사용됩니다.

반면 sponsorkit 브랜치에는 대괄호 표시가 없죠? 트래킹이 설정되지 않은 브랜치에서는 git push나 git pull 시 리모트를 명시해야 합니다.

$ git push origin sponsorkit

트래킹을 설정하고 싶다면 -u 옵션을 사용하면 됩니다.

$ git push -u origin sponsorkit

리모트가 여러 개 있어도 브랜치별로 트래킹이 독립적이라는 점도 기억해두세요. origin과 upstream 두 개의 리모트가 있더라도, 어떤 리모트가 “디폴트”인지는 각 브랜치의 설정에 따라 다릅니다.

특정 브랜치의 리모트 설정만 확인하고 싶다면 다음 명령어를 사용할 수도 있습니다.

$ git config --get branch.main.remote
origin

브랜치 생성

새로운 브랜치를 만들려면 git branch 뒤에 브랜치 이름을 지정합니다.

$ git branch <브랜치명>

feature/user-profile이라는 브랜치를 만들어 볼까요?

$ git branch feature/user-profile

한 가지 주의할 점이 있는데요. git branch로 브랜치를 생성하면 브랜치만 만들어지고 해당 브랜치로 자동 전환되지 않습니다. 여전히 기존 브랜치에 머물러 있죠.

$ git branch feature/user-profile
$ git branch
  feature/user-profile
* main

브랜치를 생성한 후 바로 전환하려면 별도로 git switch 명령어를 사용해야 합니다.

$ git branch feature/user-profile
$ git switch feature/user-profile
Switched to branch 'feature/user-profile'

브랜치를 만들면서 동시에 전환까지 하고 싶다면 git switch -c 명령어를 사용하는 것이 더 편리합니다.

$ git switch -c feature/user-profile
Switched to a new branch 'feature/user-profile'

브랜치 전환에 대한 자세한 내용은 git switch 사용법을 참고하세요.

예전에는 git checkout -b 명령어로 브랜치를 생성하면서 전환했는데, 지금은 git switch -c를 쓰는 것이 권장됩니다. git checkout은 브랜치 전환 외에도 파일 복원 등 여러 기능이 섞여 있어서 혼란스러울 수 있거든요. 자세한 내용은 git checkout 사용법을 참고하세요.

특정 지점에서 브랜치 생성

기본적으로 git branch는 현재 HEAD가 가리키는 커밋을 기준으로 브랜치를 생성합니다. 하지만 다른 커밋이나 태그를 기준으로 브랜치를 만들고 싶을 때도 있겠죠?

이럴 때는 브랜치 이름 뒤에 시작 지점을 명시하면 됩니다.

$ git branch <브랜치명> <시작-지점>

v2.0.0 태그를 기반으로 유지보수 브랜치를 만들 수 있고요.

$ git branch maintenance/v2 v2.0.0

특정 커밋 해시를 기반으로 브랜치를 만들 수도 있고요.

$ git branch fix/typo a1b2c3d

다른 브랜치의 최신 커밋을 기준으로 새 브랜치를 만들 수도 있습니다.

# develop 브랜치를 기준으로 feature 브랜치 생성
$ git branch feature/payment develop

브랜치 이름 변경

이미 만든 브랜치의 이름을 바꾸고 싶을 때가 있습니다. 오타가 났거나 네이밍 컨벤션이 바뀌었을 때 -m 또는 --move 옵션을 사용하면 됩니다.

$ git branch -m <기존-이름> <새-이름>

feature/logn이라는 브랜치 이름에 오타가 났다면 이렇게 고치면 됩니다.

$ git branch -m feature/logn feature/login

현재 작업 중인 브랜치의 이름을 바꾸려면 기존 이름을 생략하고 새 이름만 입력하면 됩니다.

# 현재 feature/logn 브랜치에 있는 상태에서
$ git branch -m feature/login

이미 동일한 이름의 브랜치가 존재하면 이름 변경이 거부되는데요. 강제로 덮어쓰려면 대문자 -M 옵션을 사용합니다.

$ git branch -M feature/login

원격 저장소에도 반영하려면 기존 원격 브랜치를 삭제하고 새 이름으로 다시 푸시해야 합니다.

# 원격의 기존 브랜치 삭제
$ git push origin --delete feature/logn

# 새 이름으로 푸시
$ git push -u origin feature/login

브랜치 삭제

더 이상 필요 없는 브랜치는 -d 또는 --delete 옵션으로 삭제할 수 있습니다.

$ git branch -d <브랜치명>

main 브랜치에 이미 병합된 feature/login 브랜치를 지우려면 이렇게 하면 됩니다.

$ git branch -d feature/login
Deleted branch feature/login (was e4f5g6h).

만약 해당 브랜치가 아직 다른 브랜치에 병합되지 않았다면 Git이 경고를 보여주면서 삭제를 거부합니다.

$ git branch -d feature/experiment
error: The branch 'feature/experiment' is not fully merged.
If you are sure you want to delete it, run 'git branch -D feature/experiment'.

병합 여부와 관계없이 강제로 삭제하고 싶다면 대문자 -D 옵션을 사용합니다.

$ git branch -D feature/experiment
Deleted branch feature/experiment (was c3d4e5f).

강제 삭제를 하면 해당 브랜치에만 있던 커밋을 찾기 어려워질 수 있으니 주의하세요.

원격 저장소의 브랜치를 삭제하려면 git push 명령어에 --delete 옵션을 사용합니다.

$ git push origin --delete feature/login
To https://github.com/user/repo.git
 - [deleted]         feature/login

원격 저장소에 코드를 올리는 방법에 대해서는 git push 사용법에서 자세히 다루고 있으니 참고하세요.

병합된 브랜치 확인

프로젝트를 진행하다 보면 브랜치가 점점 쌓이게 되는데요. 이미 병합이 끝난 브랜치를 파악해서 정리하면 저장소를 깔끔하게 유지할 수 있습니다.

--merged 옵션을 사용하면 현재 브랜치에 이미 병합된 브랜치만 볼 수 있습니다.

$ git branch --merged
  feature/login
  fix/typo
* main

여기에 나오는 브랜치들은 이미 현재 브랜치에 병합된 것이므로 삭제해도 작업 내용이 손실되지 않습니다.

반대로 아직 병합되지 않은 브랜치를 확인하려면 --no-merged 옵션을 사용합니다.

$ git branch --no-merged
  feature/payment
  feature/dashboard

이 브랜치들은 아직 작업 중이거나 리뷰 대기 중인 브랜치일 가능성이 높습니다.

특정 브랜치 기준으로 병합 여부를 확인할 수도 있습니다.

# develop 브랜치에 병합된 브랜치 확인
$ git branch --merged develop

이 기능을 활용하면 다음과 같이 병합된 브랜치를 한꺼번에 정리할 수 있습니다.

# main에 병합된 브랜치 중 main 자체를 제외하고 삭제
$ git branch --merged main | grep -v "main" | xargs git branch -d

브랜치 네이밍 컨벤션

팀으로 작업할 때 브랜치 네이밍 컨벤션을 맞춰두면 저장소 관리가 훨씬 편해집니다. 널리 쓰이는 패턴을 소개해드릴게요.

feature/login-page      # 새로운 기능 개발
fix/auth-token-expired  # 버그 수정
hotfix/critical-crash   # 긴급 수정
release/v2.1.0          # 릴리스 준비
chore/update-deps       # 유지보수 작업

슬래시(/)를 구분자로 사용하면 브랜치가 어떤 용도인지 바로 알 수 있고, 일부 GUI 도구에서는 폴더처럼 그룹화해서 보여주기도 합니다.

브랜치 이름에 이슈 번호를 포함하는 팀도 있습니다.

feature/42-user-profile
fix/108-login-redirect

이렇게 하면 브랜치와 관련 이슈를 쉽게 연결할 수 있어서 편리합니다.

브랜치 작업 흐름

실제로 브랜치를 활용해서 기능을 개발하는 흐름을 살펴볼까요?

# 1. main 브랜치를 최신 상태로 업데이트
$ git switch main
$ git pull origin main

# 2. 새로운 기능 브랜치 생성 및 전환
$ git switch -c feature/search

# 3. 기능 개발 및 커밋
$ git add .
$ git commit -m "검색 기능 구현"

# 4. 원격 저장소에 푸시
$ git push -u origin feature/search

# 5. GitHub에서 Pull Request 생성 후 코드 리뷰

# 6. 병합 완료 후 로컬 브랜치 정리
$ git switch main
$ git pull origin main
$ git branch -d feature/search

작업 도중에 급한 일이 생기면 현재 변경사항을 git stash로 임시 저장한 후 다른 브랜치로 전환할 수 있습니다. 여러 브랜치를 동시에 작업해야 한다면 git worktree를 써보는 것도 괜찮고요.

마치며

git branch는 Git을 쓰면서 거의 매일 사용하게 되는 명령어입니다. 이번 글에서 다룬 주요 명령어를 정리해볼게요.

작업	명령어
브랜치 목록 조회	git branch
원격 브랜치 조회	git branch -r
모든 브랜치 조회	git branch -a
트래킹 정보 확인	git branch -vv
브랜치 생성	git branch <이름>
특정 지점에서 생성	git branch <이름> <시작-지점>
브랜치 이름 변경	git branch -m <기존> <새이름>
브랜치 삭제	git branch -d <이름>
강제 삭제	git branch -D <이름>
병합된 브랜치 확인	git branch --merged

브랜치를 잘 활용하면 여러 기능을 동시에 개발하면서도 코드베이스를 안정적으로 유지할 수 있습니다. git switch로 브랜치 전환을, git push로 원격 저장소 동기화를 함께 익혀두시면 Git 협업이 훨씬 편해질 거예요. 브랜치를 합치는 방법은 git merge 사용법과 git rebase 사용법을 참고하시고, 여러 브랜치를 동시에 작업해야 한다면 git worktree 사용법도 살펴보세요.

더 자세한 내용은 Git 공식 문서를 참고하세요.