Git check-ref-format 사용법

git check-ref-format은 브랜치명이나 태그 이름이 Git의 ref 규칙에 맞는지 미리 검사할 때 쓰는 명령입니다. 브랜치를 자동으로 만들거나 사용자 입력을 받아 ref를 생성하는 도구를 만들 때 특히 중요합니다. 이름 규칙을 모르고 문자열을 그대로 쓰면 push, checkout, refspec 해석, reflog 표기와 충돌할 수 있기 때문입니다.

2026년 8월 2일 기준 Git 공식 문서에 따르면 이 명령은 일반 ref 이름 검사와 브랜치 이름 검사 모드를 따로 제공합니다. 실무에서는 refs/heads/... 같은 전체 ref를 다룰지, 사용자가 입력하는 브랜치 shorthand를 다룰지부터 구분하는 것이 핵심입니다.

왜 ref 이름 검사가 필요한가

Git의 ref는 단순한 임의 문자열이 아닙니다. Git glossary는 ref namespace가 계층 구조이며, 로컬 브랜치는 refs/heads/, 태그는 refs/tags/ 아래에 저장된다고 설명합니다. 그래서 이름에 허용되지 않는 문자를 넣으면 단순 표시 문제가 아니라 Git 내부 해석과 충돌할 수 있습니다.

공식 매뉴얼은 금지 규칙의 이유도 함께 제시합니다. 예를 들어 ..는 revision range 표기와 겹치고, ~와 ^는 부모 commit 표기와 겹치며, :는 fetch·push의 refspec과 <rev>:<path> 문법에 쓰입니다. @{도 reflog 표기와 충돌하므로 ref 이름에 넣을 수 없습니다.

어떤 이름이 거부되나

Git 공식 문서 기준으로 일반 ref 이름은 다음 같은 규칙을 지켜야 합니다.

• 슬래시로 계층을 나눌 수 있지만, 각 구성 요소는 .으로 시작할 수 없고 .lock으로 끝날 수 없습니다.
• 기본 동작에서는 최소 한 번의 /가 필요합니다. 그래서 보통 refs/heads/main처럼 category를 포함한 이름을 검사합니다.
• .., 공백, ~, ^, :, ?, *, [, \, @{는 허용되지 않습니다.
• 이름 시작이나 끝의 /, 연속된 //, 마지막의 ., 단독 @도 허용되지 않습니다.

이 규칙만 보면 엄격해 보이지만, 목적은 분명합니다. shell 확장과 명령 해석의 모호성을 줄이고 ref를 안전하게 파싱하기 위함입니다.

--branch는 언제 써야 하나

사용자가 새 브랜치 이름을 입력하는 화면이나 CLI라면 일반 검사보다 git check-ref-format --branch가 더 맞습니다. 공식 문서는 이 모드가 branch name shorthand를 받으며, 어떤 경우에는 refs/heads/$name을 직접 검사하는 것보다 더 엄격할 수 있다고 설명합니다.

대표적인 예가 앞에 대시가 오는 이름입니다. 일반 ref 구성 요소에는 가능한 경우가 있어도, 브랜치 이름 검사는 이런 입력을 금지할 수 있습니다. 즉 브랜치 생성 UX를 만들 때는 ref 전체 경로를 붙여서 검사하기보다 --branch로 사용자의 실제 입력을 검증하는 편이 안전합니다.

또 공식 문서에 따르면 repository 안에서 --branch를 쓰면 @{-1} 같은 previous checkout syntax가 먼저 확장됩니다. 이 표기는 마지막으로 checkout 또는 switch 했던 대상을 뜻하므로, 도구가 이 문법까지 받아들여야 하는지 여부를 의식해야 합니다.

--normalize는 무엇을 해주나

--normalize는 앞쪽 슬래시를 제거하고 중간의 연속 슬래시를 하나로 줄인 뒤, 정규화된 이름이 유효하면 그 값을 표준 출력으로 돌려줍니다. 입력 정리를 자동화할 때 유용하지만, 허용되지 않는 문자를 합법적으로 바꿔 주는 기능은 아닙니다.

따라서 폼 입력을 받아서 refs/heads//feature//demo 같은 실수를 정리하는 용도로는 쓸 수 있지만, feature:demo나 topic..v2처럼 문법 충돌이 있는 이름을 살리는 용도로 기대하면 안 됩니다.

name="feature/login"
git check-ref-format --branch "$name"

ref=$(git check-ref-format --normalize "refs/heads/$name") || {
  echo "invalid branch name" >&2
  exit 1
}

이 패턴은 사용자 입력 검증과 실제 저장 ref 계산을 분리한다는 점에서 실무적으로 깔끔합니다.

선택 기준은 어떻게 잡으면 되나

• 브랜치 생성 입력 검증이면 git check-ref-format --branch를 우선 봅니다.
• 자동화 스크립트가 실제 ref 경로를 직접 만들면 refs/heads/... 또는 refs/tags/... 전체 경로를 검사합니다.
• 잘못된 슬래시만 정리하면 되는 입력이면 --normalize를 함께 씁니다.
• refspec 패턴처럼 *가 필요한 경우에만 --refspec-pattern을 검토합니다.

핵심은 "사용자에게 브랜치명을 받는가"와 "도구가 완성된 ref를 직접 다루는가"를 나눠 생각하는 것입니다. 이 구분이 되면 어떤 옵션을 써야 하는지 거의 바로 결정됩니다.

FAQ

브랜치 이름은 결국 refs/heads/이름 아닌가

저장 구조는 그렇지만, 입력 검증은 동일하지 않을 수 있습니다. Git 공식 문서는 --branch가 일반 ref 검사보다 더 엄격할 수 있다고 분명히 설명합니다. 브랜치 생성용 입력이라면 shorthand 기준 검사를 따르는 편이 맞습니다.

왜 @{나 ..가 금지되나

둘 다 Git이 이미 다른 의미로 쓰는 문법이기 때문입니다. @{는 reflog entry 표기, ..는 revision range 표기에 사용됩니다. 이런 표기와 ref 이름이 섞이면 명령 해석이 모호해질 수 있습니다.

--normalize만 쓰면 안전한가

아닙니다. 이 옵션은 슬래시 정리에만 가깝습니다. 금지 문자나 예약 문법 충돌까지 해결해 주지 않으므로, 입력을 받아 ref를 만들 때는 여전히 명시적 검사가 필요합니다.