Tracking branch와 Upstream

트래킹 브랜치(tracking branch)와 업스트림(upstream)는 Git에서 로컬 브랜치와 원격 브랜치 간의 연결(연관 관계)을 나타내는 핵심 개념입니다. 이 개념들은 fetch, pull, push와 같은 원격 저장소와의 상호작용에서 자동화와 명확성을 제공합니다. 이 두 용어는 밀접하게 연관되어 있으며, 경우에 따라 서로 동의어처럼 사용되기도 하지만, 엄밀히는 약간의 차이가 존재합니다.

 

🔑 요약

용어	정의	예시
Tracking Branch	로컬 브랜치에 연결된 원격 브랜치	my-feature → origin/my-feature
Upstream Branch	현재 체크아웃된 브랜치가 기본적으로 push/pull할 대상으로 설정된 원격 브랜치	main → origin/main

 

 

🧠 트래킹 브랜치(Tracking Branch)

정의:

트래킹 브랜치는 로컬 브랜치가 연결된 원격 브랜치의 참조입니다. 로컬 브랜치는 이 참조를 기반으로 git pull이나 git status 등의 명령어를 실행할 수 있습니다.

# 예: 로컬 브랜치 feature/login이 원격의 origin/feature/login을 트래킹할 때
$ git branch -vv
* feature/login  f3c92d2 [origin/feature/login] 로그인 기능 구현 중

• origin/feature/login이 트래킹 대상입니다.
• Git은 로컬 브랜치의 HEAD가 이 트래킹 브랜치에 비해 앞서 있는지, 뒤쳐져 있는지 등을 계산합니다.

 

📡 업스트림 브랜치(Upstream Branch)

정의:

업스트림 브랜치는 트래킹 브랜치와 동일한 개념으로 볼 수 있지만, 특정 로컬 브랜치가 push/pull 시 기본 대상(branch)을 갖도록 설정한 브랜치를 지칭합니다.

즉,

• 로컬 브랜치가 어떤 원격 브랜치를 업스트림으로 지정해두면,
• git pull, git push 명령어에 추가 아규먼트 없이도 작동합니다.

$ git push
# 자동으로 origin/main으로 push됨 (업스트림 설정되어 있을 경우)

 

🔁 관계 정리: Tracking vs Upstream

항목	트래킹 브랜치	업스트림 브랜치
연결 대상	원격 브랜치	원격 브랜치
설정 위치	로컬 브랜치의 메타데이터	로컬 브랜치의 메타데이터
용도	상태 비교, 로그 추적	기본 pull/push 대상
설정 명령	git branch --track	git push -u, --set-upstream-to

➡️ 대부분의 경우 동일한 브랜치를 가리킵니다.

 

 

⚙️ 설정 방법

1. 브랜치 생성 시 자동 설정

$ git checkout -b feature/login origin/feature/login

• 로컬 브랜치 feature/login이 자동으로 origin/feature/login을 트래킹하게 됨.

2. 수동 설정

# 트래킹 대상 설정
$ git branch --set-upstream-to=origin/main main

# 혹은 push할 때 업스트림과 트래킹 브랜치를 동시에 설정
$ git push -u origin main

-u는 --set-upstream의 축약어입니다.

 

🔍 확인 방법

$ git branch -vv
# 트래킹 브랜치를 확인

$ git for-each-ref --format='%(refname:short) %(upstream:short)'
# 업스트림 브랜치 확인

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

$ git config --get branch.main.merge
# refs/heads/main

 

이 설정들은 .git/config 파일에 다음처럼 저장됩니다:

[branch "main"]
    remote = origin
    merge = refs/heads/main

 

📊 Git 내부 동작 흐름

1. git fetch 실행 시:
   • 원격 저장소의 브랜치 정보를 refs/remotes/origin/*으로 갱신
2. 트래킹 브랜치가 설정되어 있으면:
   • git status로 현재 브랜치와 트래킹 브랜치의 앞/뒤 커밋 수 차이 확인 가능
3. git pull은:
   • 현재 브랜치의 업스트림을 대상으로 fetch + merge/rebase를 수행
4. git push는:
   • 업스트림 브랜치로 자동 푸시 수행 (-u 설정된 경우)

 

🧪 실습 예제

$ git checkout -b my-feature
$ git push -u origin my-feature

• 로컬 브랜치 my-feature는 이제:
  • 트래킹 브랜치: origin/my-feature
  • 업스트림 브랜치: origin/my-feature

 

이제부터는 아래 명령어만으로 자동 동작:

$ git pull   # origin/my-feature에서 pull
$ git push   # origin/my-feature로 push

 

⚠️ 주의 사항

• 트래킹 브랜치는 read-only입니다. 직접 수정하지 않습니다.
• 업스트림을 설정하지 않은 상태에서 git pull하면 다음 오류 발생:

fatal: The current branch my-feature has no upstream branch.

• git branch --unset-upstream으로 연결 해제 가능

 

✅ 결론

개념	핵심 기능
Tracking Branch	원격 브랜치를 로컬 브랜치가 감시(ref)하는 관계
Upstream Branch	기본 pull/push 대상 브랜치 지정
설정 명령	git push -u, git branch --set-upstream-to

 

이 두 개념은 함께 사용되며, 올바르게 설정할 경우 Git 워크플로우가 간결하고 안전하게 유지됩니다.