Git for-each-ref 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

git for-each-ref는 branch, tag, remote-tracking branch 같은 Git ref를 원하는 형식으로 나열하는 저수준 명령입니다. 단순히 현재 branch 목록만 보면 git branch가 더 편하지만, ref 이름, object ID, upstream 상태, 날짜, tag 정보처럼 여러 필드를 스크립트용 출력으로 만들 때는 git for-each-ref가 더 직접적입니다.

2026년 8월 13일 기준 Git 공식 문서에서 git-for-each-ref 매뉴얼은 Git 2.54.0에서 마지막으로 갱신되었고, Git 2.55.0에서는 내용 변경이 없습니다. 공식 설명의 핵심은 선택한 pattern에 맞는 ref를 순회하고, 정렬한 뒤, --format에 지정한 field 값으로 출력한다는 점입니다.

무엇을 나열하는 명령인가

Git에서 ref는 object를 가리키는 이름입니다. 예를 들어 local branch는 보통 refs/heads/ 아래에 있고, tag는 refs/tags/, remote-tracking branch는 refs/remotes/ 아래에 있습니다. git for-each-ref는 이런 ref들을 대상으로 동작합니다.

pattern을 주면 해당 pattern에 맞는 ref만 출력합니다. 공식 문서는 pattern이 fnmatch 방식으로 맞거나, 문자 그대로 전체 또는 slash 경계까지의 앞부분과 맞을 수 있다고 설명합니다. 그래서 전체 ref를 한 번에 훑기보다 범위를 좁혀 쓰는 편이 결과를 읽기 쉽습니다.

git for-each-ref refs/heads
git for-each-ref refs/tags
git for-each-ref refs/remotes/origin

--format은 왜 중요한가

git for-each-ref의 기본 출력은 object 이름, object type, ref 이름을 보여줍니다. 하지만 이 명령의 실무 가치는 --format에서 나옵니다. %(refname), %(objectname), %(objecttype) 같은 field를 조합해서 필요한 정보만 출력할 수 있기 때문입니다.

ref 이름은 %(refname:short)처럼 짧게 만들 수 있고, object ID도 %(objectname:short)처럼 줄일 수 있습니다. upstream이 설정된 branch라면 %(upstream:short), %(upstream:track), %(upstream:trackshort) 같은 field로 추적 상태를 출력할 수 있습니다.

git for-each-ref refs/heads \
  --format='%(refname:short) %(objectname:short) %(upstream:track)'

필터는 어떤 기준으로 고를까

ref 목록은 많아질수록 먼저 필터를 정하고, 그 다음 출력 형식을 정하는 편이 안정적입니다. 공식 문서 기준으로 --merged는 지정한 commit에서 도달 가능한 tip을 가진 ref를 고르고, --no-merged는 도달 가능하지 않은 ref를 고릅니다. 기준 commit을 생략하면 HEAD가 기준이 됩니다.

--contains는 지정한 commit을 포함하는 ref를 찾을 때 쓰고, --points-at은 특정 object를 직접 가리키는 ref만 찾을 때 씁니다. 같은 commit을 "포함하는가"와 "정확히 가리키는가"는 다르므로, branch 정리나 tag 확인에서 이 차이를 구분해야 합니다.

옵션	확인하는 것	대표 상황
--merged	ref tip이 기준 commit에서 도달 가능한가	이미 main에 합쳐진 branch 후보 확인
--no-merged	ref tip이 기준 commit에서 도달 불가능한가	아직 합쳐지지 않은 branch 확인
--contains	지정한 commit이 ref 이력에 포함되는가	특정 수정이 들어간 branch나 tag 찾기
--points-at	ref가 특정 object를 직접 가리키는가	같은 commit을 가리키는 tag나 branch 확인

정렬은 마지막 key가 우선이다

--sort=<key>는 field 이름을 기준으로 정렬합니다. 앞에 -를 붙이면 내림차순입니다. 공식 문서는 --sort를 여러 번 줄 수 있고, 이때 마지막 key가 primary key가 된다고 설명합니다.

git for-each-ref refs/tags \
  --sort=-creatordate \
  --format='%(creatordate:short) %(refname:short)'

tag처럼 버전 이름을 정렬해야 하는 경우에는 version:refname 또는 별칭인 v:refname을 검토할 수 있습니다. 단순 문자열 정렬과 버전 정렬은 결과가 달라질 수 있으므로, 릴리스 tag 목록을 만들 때는 정렬 key를 명시하는 편이 좋습니다.

 

 

상위 명령과 어떻게 구분하나

git branch는 사람이 branch 상태를 확인하고 관리하기 좋게 만든 상위 명령입니다. 반면 git for-each-ref는 ref 전체를 대상으로 일정한 형식의 출력을 만들기 좋습니다. branch뿐 아니라 tag, remote-tracking branch, 특수 ref까지 같은 방식으로 다뤄야 한다면 for-each-ref가 더 잘 맞습니다.

git show-ref도 ref와 object ID를 보여주는 명령입니다. 다만 출력 형식이나 field 조합이 목적이라면 for-each-ref가 더 유연합니다. 반대로 단순히 ref가 존재하는지, 어떤 object ID를 가리키는지만 확인한다면 show-ref가 더 단순할 수 있습니다.

목적	먼저 볼 명령	for-each-ref가 맞는 경우
현재 branch 목록 확인	git branch	branch별 upstream, 날짜, object ID를 한 줄로 만들 때
ref 존재 여부 확인	git show-ref	조건별 ref 목록을 정렬하고 가공해야 할 때
tag 리포트 작성	git tag	tag가 가리키는 object 정보와 날짜를 함께 출력할 때
스크립트용 출력 생성	git for-each-ref	정해진 format atom으로 안정적인 줄 단위 출력을 만들 때

스크립트에서 주의할 점

공식 문서는 --shell, --perl, --python, --tcl 옵션을 제공하며, format 값이 해당 언어의 문자열 리터럴로 quote될 수 있다고 설명합니다. 이 기능은 결과를 바로 평가하는 scriptlet을 만들기 위한 것이지만, 출력 내용을 실행하는 구조는 입력과 ref 이름을 신뢰할 수 있는지 먼저 따져야 합니다.

object 크기 field도 주의가 필요합니다. 공식 문서의 caveat에 따르면 디스크상 object 크기는 정확히 보고되지만, pack 내부 delta base 선택은 repack 과정에서 달라질 수 있습니다. 따라서 특정 ref가 저장소 용량을 얼마나 차지하는지 단정하는 용도로 objectsize:disk만 보는 것은 적절하지 않습니다.

선택 기준

• 사람이 branch만 확인한다면 git branch를 먼저 사용합니다.
• ref 이름과 object ID만 단순 확인하면 git show-ref가 충분할 수 있습니다.
• branch, tag, remote-tracking branch를 같은 규칙으로 나열해야 하면 git for-each-ref를 선택합니다.
• 스크립트 출력은 --format으로 필요한 field만 명시합니다.
• 목록이 많으면 pattern, --merged, --contains, --points-at로 먼저 줄입니다.
• 릴리스 tag나 오래된 branch를 다룰 때는 정렬 key를 명시합니다.

핵심은 git for-each-ref를 "branch 목록 명령"이 아니라 "ref 데이터에 대한 보고서 생성 명령"으로 보는 것입니다. 출력 형식과 필터 조건이 필요할수록 상위 명령보다 이 명령의 장점이 커집니다.

FAQ

refs/heads와 refs/heads/는 어떻게 봐야 하나

둘 다 local branch 영역을 가리키는 의도로 자주 쓰입니다. 다만 pattern 매칭과 shell 처리에서 오해를 줄이려면 명령 예시는 범위를 명확히 작성하는 편이 좋습니다.

%(refname:short)는 항상 안전한 이름인가

짧은 이름은 읽기 좋지만, 이름이 모호할 수 있는 저장소에서는 전체 ref 이름이 더 안전합니다. 공식 문서는 짧은 이름의 엄격한 축약 방식에 core.warnAmbiguousRefs 설정이 관여한다고 설명합니다.

여러 --contains와 --no-contains를 같이 쓰면 어떻게 되나

공식 문서에 따르면 --contains 조건 중 적어도 하나를 만족하고, --no-contains 조건은 하나도 포함하지 않는 ref만 출력됩니다. --merged와 --no-merged 조합도 같은 방식으로 reachable 조건을 합쳐 판단합니다.

참고 문서

• Git: git-for-each-ref Documentation
• Git: git-show-ref Documentation
• Git: Revisions Documentation