[개발환경/STS] Git 원격 브랜치(dev)가 있는데 로컬에서 안 보일 때

이 글은 개발 환경/형상관리 설정 이슈를 정리한 기록이다.

브랜치 전환 과정 정리 (확인 → 원인 → 해결)한 것으로

바쁜 사람들은 이곳만 보시오.

🚨 Git 원격 dev가 있는데 안 보일 때 (fetch 설정 문제)

git branch -r 에 origin/dev가 안 나올 때 실행

오류났을 때 실행 순서

git config --unset-all remote.origin.fetch
git config --add remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin
git switch -c dev origin/dev
git branch -vv

✔ * dev [origin/dev] 나오면 정상 복구

✅ Git 기본 브랜치(dev)로 전환 – 빠른 실행용

🔹 오류 없을 때 (보통 이거면 끝)

git fetch origin
git switch -c dev origin/dev
git branch -vv

✔ 결과에 * dev [origin/dev] 나오면 완료

1. 상황 요약

오픈을 얼마 앞두고, 팀에서 기존의 default 브랜치에서 dev 브랜치를 사용하라고 얘기가 나왔다.

이전에 브랜치 변경은 vscode에서는 해봤는데 sts로는 안해봐서 약간의 당혹감과 긴장함이 들었다.

1.1 생략) 현재 브랜치 확인하는 방법(추가 예정)

1.2) STS에서 터미널 열기.

그동안 프로젝트에서 git을 사용했음에도 처음 받았던 프로젝트 브랜치를 변경하는 일이 없었던 터라

이클립스 기반의 환경에서 terminal을 연적이 없었는데

이 터미널을 어떻게 여는지 잠시 생각해보다가 다음과 같이 추가하였다.

2. 먼저 확인해야 할 기본 개념

2.1. git branch 명령어는 무엇을 보여주는 걸까?

git branch

: 로컬에 있는 브랜치만 출력하여 보여준다.

2.2.그렇다면 로컬이 아닌 github의 다른 브랜치, 즉 원격 브랜치를 확인하려면 어떤 명령어를 사용해야 할까?

$ git branch -r
  origin/default

: 위 명령은 로컬을 제외한 원격에 있는 브랜치들만 보여준다.

또는

$ git branch -a
* default
  remotes/origin/default

: 로컬을 포함한 모든 브랜치들을 출력한다.

여기서는 내가 받아야 하는 origin.dev가 보여야 정상이다.

하지만 나는 보이지 않았다...;;;

분명 gitlab에는 존재했음에도.

3. 원격에는 dev가 있는데, 로컬에는 안 보일 때

있어야 할게 없다..? 그럼 뭐부터 해야하냐

원격 정보를 갱신해야한다!

user@DESKTOP ~/git/폴더명 (default)
$ git fetch origin

remote: Enumerating objects: 242, done.
remote: Counting objects: 100% (187/187), done.
remote: Compressing objects: 100% (106/106), done.
remote: Total 125 (delta 77), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (125/125), 24.44 KiB | 1.06 MiB/s, done.
Resolving deltas: 100% (77/77), completed with 30 local objects.
From http://git.계정주소/프로젝트/폴더명
   cbb214dd4..389c6908c  default    -> origin/default

그런데도 여전히 보이지 않는다면??

여기서부터가 핵심 문제..

웹(Git 서버)에서는 dev 브랜치가 분명히 보임

그런데 로컬에서:

git branch
git branch -r

👉 dev 브랜치가 안 보임

처음엔:

STS 문제인가?
권한 문제인가?
캐시인가?

별 생각을 다 했는데, 원인은 전혀 다른 데 있었다.

4. 진짜 원인: fetch 설정(refspec)이 제한돼 있었다.

원인 확인을 위해 아래 명령어를 실행하여 출력되는 내용을 확인한다 :

git config --get-all remote.origin.fetch

문제였던 출력

+refs/heads/default:refs/remotes/origin/default

이게 의미하는 것

원격(origin)에서 default 브랜치만 fetch 하도록 강제 제한 → dev 브랜치는 구조적으로 내려올 수 없음.

그래서 :

웹에는 dev가 보이는데
git fetch를 해도
로컬에는 안 나타났던 것

사실 나는 내가 저렇게 설정한것 같지 않은데, 처음 받을때 다른 사람 도움을 받아서 single로 받았엇는지.
리파지토리 설정이 그렇게 되어있었는지는 잘 모르겠지만.

로컬 설정이 그렇다 하니 뭐..

5. 해결 방법 (로컬 설정만 변경, 안전)

⚠️ 아래 설정은 내 로컬 저장소에만 적용됨
원격 저장소 / 다른 사람 환경에는 전혀 영향 없음

1) 기존 fetch 제한 제거

git config --unset-all remote.origin.fetch

2) 전체 브랜치 fetch 설정 추가

git config --add remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"

3) 다시 fetch

git fetch origin

4) 확인

git branch -r

제대로 적용이 되었다면

Receiving objects: 100% (394/394), 236.04 KiB | 5.25 MiB/s, done.
Resolving deltas: 100% (311/311), completed with 208 local objects.
From http://git.계정주소/프로젝트/폴더명
 * [new branch]          dev                -> origin/dev
 * [new branch]          fix/default-suyong -> origin/fix/default-suyong
 * [new branch]          ksa_reference      -> origin/ksa_reference
 * [new branch]          main               -> origin/main
 * [new branch]          prod               -> origin/prod
 * [new branch]          sta                -> origin/sta
Auto packing the repository for optimum performance.
See "git help gc" for manual housekeeping.
Enumerating objects: 141313, done.
Counting objects: 100% (141313/141313), done.
Delta compression using up to 12 threads
Compressing objects: 100% (44338/44338), done.
Writing objects: 100% (141313/141313), done.
Total 141313 (delta 85102), reused 137283 (delta 81418), pack-reused 0 (from 0)
Enumerating cruft objects: 27, done.
Traversing cruft objects: 27, done.
Counting objects: 100% (27/27), done.
Delta compression using up to 12 threads
Compressing objects: 100% (27/27), done.
Writing objects: 100% (27/27), done.
Total 27 (delta 12), reused 0 (delta 0), pack-reused 0 (from 0)
Unlink of file '.git/objects/pack/pack-0d366bf497df1dee769675b0a6df1e23fbd07dbd.pack' failed. Should I try again? (y/n)

origin/default
origin/dev
origin/main
origin/prod
origin/sta

6. dev 브랜치로 전환

로컬 dev 브랜치 생성 + 이동

방법 1)

git switch -c dev origin/dev

: 아래 명령과 기능은 동일하다.

방법 2)

git checkout -b dev origin/dev

7. 전환 확인(중요)

전환을 했는가? 그것보다 더 중요한게 있다.

제대로 전환되었는지 확인하는것!

git branch -vv

전환이 제대로 되었다면

출력 예 :

* dev     abc1234 [origin/dev] test
  default def5678 [origin/default: behind 10]

* dev → 현재 브랜치가 dev
[origin/dev] → 원격 dev와 연결됨

👉 이 상태면 dev 브랜치 사용 준비 완료

8. 정리

이 이슈의 핵심은: 로컬 Git의 fetch 설정(refspec)이 제한돼 있었던 것

특히:

--single-branch로 clone한 저장소
회사에서 초기 세팅된 레포지토리

에서 자주 발생할 수 있는 케이스

9. 한 줄 요약

dev 브랜치가 안 보인 게 아니라
Git이 보지 말라고 설정돼 있었던 것

gnosis90의 서재