Husky를 사용해 commit 메세지에 이슈 번호 추가 자동화하기

들어가며

Github에서는 커밋 메세지에 이슈 번호를 언급하면 해당 커밋이 이슈와 자동으로 링크 된다.

하지만 매번 커밋 메세지 뒤에 이슈 번호를 추가하는 것은 번거롭고 실수가 발생할 수도 있다. 일단 나부터가 프로젝트를 시작하고 단 두 번째 커밋에 이슈 번호를 링크하지 않아 아래와 같이 불편한 그림이 생겼다. (심지어 띄어쓰기 간격도 틀렸다.)

직전에 커밋 메세지에 이슈 번호를 적어두어야지! 하고 야심차게 다짐 했어도 돌아서면 바로 까먹게 되는 게 보통의 사람 아닐까? 나만 그런 거라면 상당히 유감이지만 다행히도 나같은 사람이 많은지 이런 과정을 자동화 할 수 있는 방법이 몇 가지 있다. 알아보자.

브랜치 생성 규칙

내가 지금부터 소개할 방법은 브랜치명에 이슈 번호가 기재되어 있다는 전제 하에 적용 가능하다. 이슈 번호를 기준으로 브랜치를 생성하고, 브랜치에 기재되어 있는 이슈 번호를 커밋 메시지에 자동으로 추가하는 방법이기 때문이다.

이를 위해 feature/issue-123과 같은 형식으로 브랜치를 생성할 수 있다.

• feature/issue-123: 새로운 기능을 개발할 때
• fix/issue-123: 버그 수정할 때
• hotfix/issue-123: 긴급한 수정이 필요할 때
• chore/issue-123: 코드 리팩토링이나 유지보수 작업일 때

커밋 메세지에 이슈 번호 자동 추가

커밋 메세지 뒤에 자동으로 이슈 번호를 추가하려면 Git Hooks 중 prepare-commit-msg 스크립트를 사용하면 된다.

Git hooks는 특정 이벤트가 발생할 때 Git이 자동으로 실행하는 스크립트다. Git 저장소의 .git/hooks 디렉터리에 있으며 기본적으로 예제 파일 형태로 존재한다. 필요한 경우에 이 파일들을 수정해 커스터마이징 할 수 있다. 이 중에서 우리가 사용할 prepare-commit-msg는 커밋 메시지를 입력하기 전에 실행되는 hooks로, 자동으로 커밋 메시지에 이슈 번호나 템플릿을 추가할 때 사용된다.

1. Git Hook 폴더로 이동: 프로젝트의 .git/hooks 디렉터리로 이동한다.

2. .git/hooks/prepare-commit-msg 파일을 생성하고 아래 내용을 추가한다

#!/bin/sh

# 1. 브랜치 이름 가져오기
BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)

# 2. 브랜치 이름에 'issue-' 뒤의 번호를 추출
ISSUE_NUMBER=$(echo $BRANCH_NAME | grep -o 'issue-[0-9]*' | sed 's/issue-//')

# 3-1. 이슈 번호가 없으면 스크립트 종료
if [ -z "$ISSUE_NUMBER" ]; then
    exit 0
fi

# 3-2. 이슈 번호가 있다면 커밋 메시지 파일에 이슈 번호를 추가
echo "[#$ISSUE_NUMBER] " >> "$1"

 

참고로 `echo` 명령어 대신 `sed` 명령어를 사용하여 커밋 메시지 맨 앞에 이슈 번호를 추가하는 것이 더 일반적이라고 한다. 하지만 내 경우 팀원들과 커밋 메시지를 `feat : 내용` 이런 식으로 하기로 합의 봤고, 갑자기 앞에 [#1] 같은 게 들어가면 가독성을 해칠 것 같아 뒷 부분에 추가해줬다.

 

3. 스크립트 권한 부여: 실행 권한을 추가해줘야 한다.

chmod +x .git/hooks/prepare-commit-msg

 

실행 권한을 추가하는 이유는 Git이나 터미널에서 해당 스크립트를 실행하려 할 때 "Permission denied" 오류가 나지 않도록 하기 위함이다. chmod +x를 통해 파일을 실행 가능한 상태로 만들어주면 스크립트가 자동으로 실행되도록 할 수 있다.

 

이제 commit message에 자동으로 issue 번호가 추가되는 것을 알 수 있다.

짜잔. 너무 간편하죠?

 

하지만 세상에 거저먹는 일은 없다. 이 방법은 나에게만 적용된다. 왜냐,.git/hooks 폴더 내의 Git Hook 파일은 Git의 버전 관리에 포함되지 않기 때문이다. 따라서 이렇게 열심히(?) Git Hook 파일을 수정해봤자 나 혼자만의 싸움이 된다.

이를 해결하기 위한 일반적인 방법이 두 가지 있는데, husky 라이브러리를 사용하는 것과 .githooks 폴더를 만들어서 저장하는 방법이다. 전자는 설정이 귀찮지만 팀원들이 별도의 설정없이 편하게 사용할 수 있고, 후자는 나는 편하지만 팀원들이 이 설정을 수동으로 적용해야 한다. 나는 백엔드 팀원 분들과 친하게 지내서 친절한 API 명세를 받고 싶으니 전자의 방법을 택했다.

husky

husky는 Git Hook을 코드베이스와 함께 관리할 수 있도록 도와주는 라이브러리다. husky를 사용하면 Git Hook 설정이 코드베이스에 포함되어 팀원 모두가 동일한 설정을 적용받을 수 있다.

1. husky 설치 및 설정:

yarn add husky --dev

혹은

npm install --save-dev husky

2. 초기화:

Git hooks 경로를 설정하기 위해 Husky를 초기화 해야 한다. 이 과정은 프로젝트의 .husky/ 폴더를 생성하기 위함이다.

yarn husky install

혹은

npx husky install

과거에는 Husky가 각 Git Hooks 파일에서 공통 설정을 불러오기 위해 _/husky.sh 파일을 참조했다. 하지만 최신 Husky는 package.json에 prepare 스크립트를 설정하여 Git hooks 경로를 자동으로 설정하기 때문에 별도의 _ 폴더를 참조하지 않는다. 따라서 _ 폴더가 없어도 상관 없다. 각 훅 파일은 #!/bin/sh와 함께 해당 훅이 실행할 명령어만 포함하도록 간단하게 작성하면 된다.

 

.husky/ 폴더가 생성되었으면, package.json의 prepare 스크립트에 Husky 초기화 명령어를 추가한다. 이는 팀원들이 저장소를 클론한 후에 yarn이나 npm install을 실행할 때 Husky가 자동으로 설정되도록 하기 위함이다. 또한 위에서 언급했듯 프로젝트의 .git/hooks 경로를 .husky/ 폴더로 설정함으로써 Git이 .husky/ 폴더에 있는 스크립트를 Git hook으로 인식하고 실행할 수 있도록 한다.

{
  "scripts": {
    "prepare": "husky install"
  }
}

3. Git Hook 추가:

.husky/ 디렉터리 아래에 다음과 같이 원하는 Hook을 추가해주면 된다.

Hook 스크립트 자체는 위에서 작성한 것과 똑같이 작성해도 되므로 생략하겠다. 필요한 스크립트를 넣어두면 된다.

4. 실행 권한 부여:

앞에서 했던 것처럼 .husky 폴더의 Git hook 스크립트가 실행 가능하도록 권한을 부여해준다.

chmod +x .husky/pre-commit

 

이제 끝이다!!! 커밋할 때 자동으로 이슈 번호가 추가되는 것을 확인할 수 있다.

[참고] install command is DEPRECATED 에러

공식 사이트에서 하라는대로 husky install을 하는데 계속 이런 에러가 발생했다. 알아보니 Husky 최신 버전에서는 install 명령어를 더 이상 사용하지 않고, prepare 스크립트를 통해 Git hooks 경로를 설정하고 자동 실행되도록 하기 때문에 발생하는 에러다. 에러가 떠도 .husky 폴더가 정상적으로 생성이 되어서 사용상의 문제는 없다.

[참고] prepare 스크립트에서도 install을 사용하고 있지 않나?

나는 근본적인 의문이 생겼다. install을 더이상 사용하지 않으니 prepare 스크립트를 사용하라면서, 막상 "prepare": "husky install"을 추가해 install을 하고 있다. 따라서 이 의문점에 대해 생성형 AI에게 질문했다. 그 답을 공유한다.

 

 

요약하자면 husky install 명령어 자체가 사용되지 않는다는 것은 아니다. 단, 직접 실행하는 것이 DEPRECATED이기 때문에 package.json의 prepare 스크립트에 해당 명령어를 넣어두고 패키지를 설치할 때 자동으로 설치되도록 하는 것이 최신 Husky에서 권장하는 방법이라고 한다.

이런 흐름은 프로젝트 초기 설정에서 프로젝트를 클론한 후 의존성을 설치하는 표준적인 작업 흐름에 맞춰, 개발자가 별도로 추가 명령어를 실행하지 않고도 간편하게 husky를 사용할 수 있도록 하기 위해서다. 팀원들에게 별도로 명령어를 실행해야 하는 번거로움을 안겨주지 말자!가 주된 목적인 것이다.

초기 세팅할 때는 방금 전에 husky를 설치해놓고, package.json에 스크립트 추가 한 뒤 다시 의존성을 설치하는 게 오히려 일반적이지 않은 흐름이라고 생각하여 공식 문서에서 설명한 설치법 그대로를 소개했다.

레퍼런스

• Husky 공식 문서