main 을 master 로 바꾸기 전에, 기본 브랜치 이름 변경 점검 목록

이 목록은 이름을 바꾸는 버튼을 누르기 전에 폅니다

기본 브랜치 이름 변경은 GitHub 쪽 작업만 보면 1분이면 끝납니다. 시간이 드는 건 그 이름을 쓰고 있던 바깥 자리를 찾는 일입니다. 워크플로 파일, 배포 스크립트, 크론, 문서 속 주소, 팀원 노트북의 로컬 클론이 다 여기에 들어갑니다.

바꾼 뒤에 하나씩 터지면서 찾으면 어디가 끊겼는지 원인을 거꾸로 짚어야 합니다. 바꾸기 전에 목록을 만들어 두면 당일에는 버튼 하나 누르고 목록을 위에서부터 고치면 됩니다. 리포가 여러 개라면 리포마다 이 목록을 한 번씩 돌립니다.

GitHub 가 알아서 고쳐 주는 것과 안 고쳐 주는 것을 먼저 갈라 두면, 확인할 자리가 절반으로 줄어듭니다.

누가 바꿀 수 있는지부터 확인합니다

일반 브랜치는 쓰기 권한만 있으면 이름을 바꿀 수 있습니다. 기본 브랜치이거나 브랜치 보호 규칙, 저장소 룰셋이 걸린 브랜치는 저장소 관리자만 바꿉니다. 조직이나 엔터프라이즈 룰셋에 걸려 있으면 그쪽 관리자가 손대야 하는 경우가 많고, 새 이름도 같은 규칙을 통과해야 합니다.

작업 당일에 권한이 없어서 멈추는 일이 의외로 흔합니다. 설정 화면의 Branches 메뉴에서 이름 옆 연필 아이콘이 보이는지, 룰셋이 브랜치 이름 패턴으로 걸려 있지는 않은지 미리 봐 둡니다. 룰셋이 main 이라는 이름으로 지정돼 있다면 새 이름에도 같은 보호가 걸리는지 따로 확인해야 합니다.

# 지금 기본 브랜치 이름과 보호 규칙 여부를 확인한다 (gh CLI)
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name
gh api repos/{owner}/{repo}/branches/main --jq .protected

protected 가 true 면 관리자 권한이 있어야 이름을 바꿀 수 있다

GitHub 가 따라 바꿔 주는 것과 그대로 두는 것

이름을 바꾸면 GitHub 는 옛 이름이 들어간 웹 주소를 새 이름으로 넘겨 줍니다. 브랜치 보호 정책도 새 이름으로 옮겨 가고, 이 브랜치를 base 로 삼던 열린 PR 과 초안 릴리스도 새 이름을 보게 됩니다. 포크에서 올라온 PR 까지 포함입니다.

따라오지 않는 것도 분명합니다. raw 파일 주소는 넘겨 주지 않습니다. 옛 이름으로 하는 git pull 도 넘겨 주지 않습니다. GitHub Actions 워크플로도 이름 변경을 따라가지 않습니다. 그리고 바꾸려는 브랜치가 어떤 열린 PR 의 head 브랜치라면 그 PR 은 닫힙니다. 기본 브랜치를 head 로 둔 PR 은 드물지만, 릴리스 브랜치로 PR 을 여는 팀이라면 한 번 봐 둡니다.

# 옛 이름을 head 로 쓰는 열린 PR 이 있는지 본다
gh pr list --state open --head main

# 옛 이름을 base 로 쓰는 PR 은 자동으로 옮겨지므로 개수만 기록해 둔다
gh pr list --state open --base main --json number --jq length

head 쪽 목록이 비어 있어야 이름을 바꿔도 PR 이 닫히지 않는다

브랜치 이름을 문자열로 들고 있는 파일을 먼저 찾습니다

워크플로의 on.push.branches, 배포 스크립트의 git pull origin main, Dockerfile 이나 설치 스크립트 속 raw.githubusercontent.com 주소, README 의 배지 링크가 대표적입니다. 이 자리들은 이름이 바뀌어도 오류를 내지 않고 조용히 아무 일도 안 합니다. 워크플로는 트리거가 안 맞으니 안 돌 뿐이고, 크론은 실패 로그를 아무도 안 보는 곳에 남깁니다.

저장소 안은 grep 한 번이면 거의 다 나옵니다. 저장소 밖이 더 까다롭습니다. 서버의 크론탭, 배포 훅, 다른 저장소에서 이 저장소의 raw 주소를 끌어다 쓰는 스크립트는 직접 서버에 들어가 찾아야 합니다. 찾은 자리는 바꾸기 전에 목록으로 남겨 둡니다.

# 저장소 안에서 옛 이름을 쓰는 자리
git grep -nE '\bmain\b' -- .github/ '*.sh' '*.yml' '*.yaml' Dockerfile README.md

# 서버 쪽 크론과 배포 스크립트
crontab -l | grep -n 'origin main'
grep -rn 'origin main\|/main/' /etc/cron.d /opt/deploy 2>/dev/null

main 은 흔한 단어라 결과가 많다. 브랜치를 가리키는 줄만 골라 목록에 옮긴다

팀원 로컬 클론은 네 줄이면 따라옵니다

이름을 바꾼 뒤에도 각자의 노트북에는 옛 이름의 로컬 브랜치와 origin/main 추적 참조가 남아 있습니다. 로컬 브랜치 이름을 바꾸고, 새 원격 브랜치를 받아 오고, 추적 대상을 새 이름으로 걸고, origin/HEAD 를 원격의 실제 기본 브랜치에 맞추면 끝납니다.

마지막 set-head 를 빼먹는 경우가 많습니다. origin/HEAD 는 원격의 기본 브랜치를 가리키는 심볼릭 참조라서, 이걸 안 고치면 origin 이라고만 쓴 명령이 계속 사라진 브랜치를 찾습니다. -a 옵션은 원격에 HEAD 를 물어 그대로 맞추는데, 새 이름의 추적 참조가 로컬에 이미 있어야 동작합니다. 그래서 fetch 가 앞에 와야 합니다.

git branch -m main master
git fetch origin
git branch -u origin/master master
git remote set-head origin -a

# 옛 이름의 추적 참조 정리 (먼저 --dry-run 으로 지울 목록을 본다)
git remote prune --dry-run origin
git remote prune origin

set-head -a 는 origin/master 가 받아져 있어야 성공한다. fetch 를 먼저 한다

새로 만드는 저장소도 같은 이름으로 맞춰 둡니다

기존 저장소를 다 바꿔 놓고도 새 저장소를 만들 때마다 다른 이름이 섞여 들어오는 경우가 있습니다. git init 이 쓰는 기본 이름은 init.defaultBranch 설정을 따르고, 설정이 없으면 Git 의 기본값을 씁니다. 지금 기본값은 master 이고, Git 3.0 부터는 main 으로 바뀔 예정입니다.

그러니 설정을 비워 두면 Git 을 올리는 날 새 저장소의 이름이 바뀝니다. 팀이 쓰기로 한 이름을 init.defaultBranch 에 명시해 두면 버전과 상관없이 같은 이름으로 시작합니다. GitHub 에서 저장소를 만들 때 쓰는 기본 이름은 계정이나 조직 설정에 따로 있으니 그쪽도 같이 맞춥니다.

git config --global init.defaultBranch master
git init demo && git -C demo symbolic-ref --short HEAD

두 번째 줄이 master 를 출력하면 설정이 먹은 것이다

이 정도면 통과라고 볼 수 있는 상태

새 이름으로 푸시했을 때 워크플로가 실제로 한 번 돌고, 서버의 배포 스크립트가 새 이름으로 pull 해서 끝까지 갑니다. 문서 속 raw 주소는 새 이름으로 바꿔서 직접 열어 봤을 때 200 이 나옵니다.

로컬 쪽은 git status 에 새 이름이 보이고, git rev-parse --abbrev-ref origin/HEAD 가 새 이름을 가리키면 됩니다. 옛 이름을 바깥에서 오래 써 온 저장소라면 옛 이름의 브랜치를 하나 남겨 두고, 이름이 바뀌었다는 안내 커밋을 올려 두는 방법도 있습니다. 끊긴 쪽이 어디로 가야 하는지 알 수 있게 해 주는 장치입니다.

조치 후 확인할 것

브랜치 이름 변경은 바꾸는 작업보다 찾는 작업입니다. 그 이름을 문자열로 들고 있는 자리를 미리 다 적어 두면, 당일에는 버튼 하나 누르고 목록을 지워 나가기만 하면 됩니다.