사람들은 커널 git 로그의 품질을 다른 프로젝트들과 비교해 보고, 울면서 잠들어야 한다.

– 리누스 토르발스

당신 프로젝트의 커밋 가이드라인은 절대 외울 수 없다.

프로젝트마다 요구하는 게 모두 다르다:

• Conventional Commits
• Problem/Solution 형식
• Gitmoji
• 미로 같은 리눅스 커널의 trailer

하지만 git 커밋 템플릿이 도움이 된다. 커밋 템플릿은 커밋 메시지를 위한 뼈대를 제공해, 꼭 필요한 곳—바로 커밋 메시지를 작성하는 에디터 안에서—가이드를 보여준다.

git 커밋 템플릿이란?

git commit을 입력하면 git이 텍스트 에디터를 열어준다¹. git은 에디터를 커밋 템플릿으로 미리 채워둘 수 있는데, 마치 작성해야 할 양식과 같다.

커밋 템플릿을 만드는 건 간단하다.

• 일반 텍스트 파일을 하나 만든다 — 내 파일은 ~/.config/git/message.txt에 있다
• git이 이 파일을 사용하도록 설정한다:

git config --global \
    commit.template '~/.config/git/message.txt'

내 기본 템플릿에는 커밋 작성에 대해 내가 아는 모든 것이 담겨 있다.

IncludeIf로 프로젝트별 템플릿 사용하기

커밋 템플릿의 진짜 마법은 프로젝트마다 다른 템플릿을 쓸 수 있다는 점이다.

git의 includeIf 설정으로 프로젝트마다 다른 템플릿을 적용할 수 있다².

리눅스 커널, git, MediaWiki 같은 대형 프로젝트들은 각자 고유의 커밋 가이드라인을 가지고 있다.

Wikimedia 관련 작업을 할 때는 git 저장소를 ~/Projects/Wikimedia에 모아두고, 전역 git 설정 파일(~/.config/git/config) 맨 아래에 이렇게 적어둔다:

[includeIf "gitdir:~/Projects/Wikimedia/**"]
    path = ~/.config/git/config.wikimedia

config.wikimedia에서는 Wikimedia 전용 커밋 템플릿을 지정한다. user.email이나 core.hooksPath 같은 다른 git 설정도 함께 덮어쓴다.

예시: 나의 전역 템플릿

내 기본 커밋 템플릿은 세 섹션으로 이루어져 있다:

1. 제목(Subject) — 50자 이내, 대문자로 시작, 마침표 없음.
2. 본문(Body) — 72자에서 줄 바꿈하고, 제목과는 빈 줄로 구분.
3. Trailer — 표준 형식을 따르며, 본문과는 빈 줄로 구분.

각 섹션마다 형식³과 내용에 대한 힌트를 넣어두었다.

헤더에 대한 가이드는 간단하다:

# 50ch. wide ----------------------------- SUBJECT
#                                                |
#     "If applied, this commit will..."          |
#                                                |
#     Change / Add / Fix                         |
#     Remove / Update / Document                 |
#                                                |
# ------- ↓ LEAVE BLANK LINE ↓ ---------- /SUBJECT

본문에서는 스스로에게 기본적인 질문들에 답하도록 상기시킨다:

# 72ch. wide ------------------------------------------------------ BODY
#                                                                      |
#     - Why should this change be made?                                |
#       - What problem are you solving?                                |
#       - Why this solution?                                           |
#     - What's wrong with the current code?                            |
#     - Are there other ways to do it?                                 |
#     - How can the reviewer confirm it works?                         |
#                                                                      |

그리고 남은 건 git trailer뿐이다.

미로 같은 git trailer

내 템플릿에는 내가 참여하는 프로젝트들에서 사용하는 trailer를 위한 섹션이 있다.

#     TRAILERS                                                         |
#     --------                                                         |
#     (optional) Uncomment as needed.                                  |
#     Leave a blank line before the trailers.                          |
#                                                                      |
# Bug: #xxxx
# Acked-by: Example User <[email protected]>
# Cc: Example User <[email protected]>
# Co-Authored-by: Example User <[email protected]>
# Requested-by: Example User <[email protected]>
# Reported-by: Example User <[email protected]>
# Reviewed-by: Example User <[email protected]>
# Suggested-by: Example User <[email protected]>
# Tested-by: Example User <[email protected]>
# Thanks: Example User <[email protected]>

이 trailer들은 유용한 문서화의 흔적이 된다. git은 표준 명령어로 trailer를 파싱할 수 있다.

예를 들어 커밋과 관련 태스크를 탭으로 구분한 목록을 만들고 싶다면, git log로 Bug trailer를 찾을 수 있다:

$ TAB=%x09
$ BUG_TRAILER='%(trailers:key=Bug,valueonly=true,separator=%x2C )'
$ SHORT_HASH=%h
$ SUBJ=%s
$ FORMAT="${SHORT_HASH}${TAB}${BUG_TRAILER}${TAB}${SUBJ}"
$ git log --topo-order --no-merges \
      --format="$FORMAT"
d2b09deb12f     T359762 Rewrite Kurdish (ku) Latin to Arabic converter
28123a6a262     T332865 tests: Remove non-static fallback in HookRunnerTestBase
4e919a307a4     T328919 tests: Remove unused argument from data provider in PageUpdaterTest
bedd0f685f9             objectcache: Improve `RESTBagOStuff::handleError()`
2182a0c4490     T393219 tests: Remove two data provider in RestStructureTest

커밋 메시지 가이드라인 외우기를 그만두자

git 커밋 템플릿은 무엇을 써야 할지 기억해야 하는 부담에서 머리를 해방시켜, 전달해야 할 이야기에 집중하게 해준다.

머리는 잘하는 일에 아껴 쓰자.