Git notes 사용법

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

git notes는 커밋 메시지를 고치지 않고 커밋에 추가 설명을 붙이고 싶을 때 쓰는 기능입니다. 커밋 객체 자체를 다시 만들지 않기 때문에 이미 공유된 커밋의 해시를 바꾸지 않는다는 점이 핵심입니다.

결론부터 말하면 공개 이력의 의미를 바꾸는 내용은 새 커밋이나 문서로 남기는 편이 맞고, 빌드 번호, 리뷰 메모, 외부 시스템 식별자처럼 커밋에 덧붙여 읽으면 유용하지만 커밋 메시지에 넣기 애매한 정보에는 git notes가 맞습니다. 다만 notes는 일반 브랜치와 별도 ref에 저장되므로 공유, 표시, rewrite 정책을 따로 확인해야 합니다.

git notes는 무엇을 바꿀까

공식 Git 문서 기준으로 git notes는 객체에 붙은 note를 추가, 삭제, 조회합니다. 중요한 점은 note가 붙는 대상 객체를 직접 수정하지 않는다는 것입니다. 커밋 메시지를 수정하는 commit --amend와 달리 커밋 객체의 해시는 그대로 유지됩니다.

기본 notes ref는 refs/notes/commits입니다. 이 ref가 없더라도 note를 처음 저장할 때 필요하면 만들어집니다. 즉 notes는 작업 트리 파일처럼 저장되는 것이 아니라 Git 객체와 ref 안에 별도 이력으로 저장됩니다.

git notes add -m "reviewed in build 142" HEAD
git notes show HEAD
git log --show-notes

위 명령은 현재 커밋에 note를 붙이고, 해당 note를 직접 조회한 뒤, 로그에서 note까지 함께 표시하는 기본 흐름입니다.

언제 쓰면 좋을까

git notes는 커밋 메시지를 정정하는 기능이라기보다 커밋 바깥에 부가 정보를 붙이는 기능입니다. 그래서 커밋 자체의 의미를 설명하는 핵심 내용에는 적합하지 않고, 커밋을 읽는 도구나 운영 흐름에서 필요한 보조 정보에 더 적합합니다.

목적	적합한 선택	이유
커밋 설명을 근본적으로 고침	commit --amend 또는 새 커밋	이력 자체의 의미가 달라지기 때문
이미 공유된 커밋에 빌드 결과를 덧붙임	git notes	커밋 해시를 바꾸지 않고 보조 정보를 붙일 수 있음
리뷰나 배포 시스템의 외부 ID를 연결	git notes 또는 별도 추적 시스템	커밋 내용보다 외부 맥락에 가까움
팀 전체가 반드시 알아야 하는 변경 이유	커밋 메시지, PR, 문서	notes 표시 설정에 따라 보이지 않을 수 있음

따라서 notes는 읽히지 않아도 코드 이력이 깨지지 않는 정보에 쓰는 편이 안전합니다. 배포 승인 상태나 보안 예외처럼 반드시 보존되고 검토되어야 하는 내용은 notes에만 의존하지 않는 것이 좋습니다.

notes는 git log에 항상 보일까

기본 notes는 git log 출력에서 커밋 메시지 아래에 Notes: 형태로 표시될 수 있습니다. 하지만 어떤 notes ref를 표시할지는 명령 옵션, 설정, 환경 변수의 영향을 받습니다.

공식 문서 기준으로 notes.displayRef 설정은 git log 계열 명령에서 추가로 읽을 notes ref를 지정합니다. GIT_NOTES_DISPLAY_REF 환경 변수로도 표시 대상을 바꿀 수 있고, --no-notes나 --notes=<ref> 옵션으로 명령 단위 제어도 가능합니다.

git log --show-notes
git log --notes=refs/notes/review
git config notes.displayRef refs/notes/review

여러 종류의 notes를 운영한다면 기본 refs/notes/commits 하나에 모두 섞기보다 목적별 ref를 나누는 편이 읽기 쉽습니다. 예를 들어 리뷰 결과와 빌드 메타데이터를 같은 note에 누적하면 충돌과 표시 정책이 복잡해질 수 있습니다.

추가, 수정, 삭제 명령은 어떻게 나뉠까

자주 쓰는 하위 명령은 add, append, edit, show, remove입니다. 이미 note가 있는 객체에 add를 쓰면 기본적으로 중단되며, 덮어쓰려면 -f를 씁니다. 기존 note에 문단을 더하려면 append가 더 명확합니다.

명령	역할	주의할 점
git notes add	새 note 추가	기존 note가 있으면 기본적으로 중단
git notes append	기존 note에 문단 추가	누적 로그처럼 길어지지 않게 관리 필요
git notes edit	편집기로 note 수정	자동화에서는 편집기 호출을 피하는 편이 좋음
git notes remove	대상 객체의 note 삭제	삭제도 notes ref의 이력으로 남을 수 있음
git notes prune	존재하지 않거나 도달 불가능한 객체의 note 정리	먼저 -n으로 확인하는 편이 안전

메시지를 명령행에서 줄 때는 -m, 파일에서 읽을 때는 -F를 씁니다. 여러 -m 또는 -F 값을 주면 문단 구분자가 들어갈 수 있으며, 최신 문서에는 --separator와 --no-stripspace 같은 옵션도 정의되어 있습니다.

 

 

rebase나 amend 뒤에는 notes가 따라올까

커밋을 rewrite하면 기존 커밋과 새 커밋은 서로 다른 객체가 됩니다. notes도 객체에 붙는 정보이므로 rewrite 뒤에 어떤 notes를 새 커밋으로 복사할지 정책을 봐야 합니다.

공식 문서 기준으로 notes.rewrite.<command> 설정은 amend나 rebase 같은 rewrite 과정에서 notes 복사 여부를 제어합니다. 기본값은 true지만, 실제로 어떤 notes ref를 복사할지는 notes.rewriteRef 설정이 중요합니다. 이 값은 기본값이 없으므로 필요한 ref를 명시해야 합니다.

git config notes.rewriteRef refs/notes/commits
git config notes.rewriteMode concatenate

notes.rewriteMode는 새 커밋에 이미 note가 있을 때 어떻게 처리할지 정합니다. 공식 문서에 정의된 값에는 overwrite, concatenate, cat_sort_uniq, ignore가 있습니다. 팀에서 notes를 자동으로 붙인다면 이 정책을 문서화해야 같은 커밋 흐름에서 예기치 않은 덮어쓰기를 줄일 수 있습니다.

팀과 공유하려면 무엇을 해야 할까

notes는 일반 브랜치와 별도 ref입니다. 그래서 저장소를 clone하거나 fetch한다고 해서 모든 notes ref가 항상 기대대로 오간다고 가정하면 안 됩니다. 팀에서 notes를 공유하려면 어떤 ref를 push하고 fetch할지 명시해야 합니다.

git push origin refs/notes/commits
git fetch origin refs/notes/commits:refs/notes/commits

목적별 notes ref를 나눴다면 해당 ref도 같은 방식으로 다뤄야 합니다. 반대로 개인 작업 메모라면 원격으로 push하지 않고 로컬 notes로만 유지할 수 있습니다. 이 선택은 notes에 담긴 정보의 소유자와 공개 범위에 따라 달라집니다.

자주 묻는 질문

notes를 붙이면 커밋 해시가 바뀔까

아닙니다. notes는 대상 객체를 수정하지 않고 별도 notes ref에 저장됩니다. 그래서 커밋 메시지를 amend할 때처럼 커밋 해시가 바뀌지 않습니다.

notes는 태그나 브랜치에도 붙일 수 있을까

공식 설명은 notes가 객체에 붙는 기능이라고 정의합니다. 일반적으로 커밋에 많이 쓰지만, Git 객체를 대상으로 note를 붙일 수 있습니다. 다만 팀 도구가 어떤 객체의 notes를 표시하는지는 별도로 확인해야 합니다.

notes를 커밋 메시지 대신 써도 될까

권장하지 않습니다. 커밋을 이해하는 데 반드시 필요한 내용은 커밋 메시지나 문서에 있어야 합니다. notes는 표시 설정과 ref 공유 여부에 영향을 받기 때문에 보조 정보로 보는 편이 맞습니다.

정리

git notes는 커밋 해시를 바꾸지 않고 커밋에 부가 정보를 붙이는 기능입니다. 기본 저장 위치는 refs/notes/commits이고, git log에서 표시할 ref는 설정이나 옵션으로 조정할 수 있습니다.

무난한 기준은 세 가지입니다. 커밋의 핵심 의미는 커밋 메시지에 남기고, notes에는 빌드 결과나 외부 시스템 ID 같은 보조 정보를 둡니다. 팀과 공유할 notes ref는 명시적으로 fetch와 push 정책을 정합니다. 마지막으로 rebase나 amend를 자주 쓰는 저장소라면 notes.rewriteRef와 notes.rewriteMode를 함께 확인합니다.