Husky, Lint-staged를 이용한 Pre-commit Hook 구현

Eslint를 사용하면 사전에 설정한대로 프로젝트 내 코드 스타일을 강제해주어 코드에 일관성이 생기고 결과적으로는 프로젝트 내 코드 품질이 향상된다. 이는 특히 협업 환경에서 더욱 도드라진다. 

일반적으로 다음의 명령어를 수행하여 코드 스타일에 대한 검사를 수행한다.

# --fix 옵션은 Eslint가 자발적으로 수정할 수 있는 수준의 스타일 오류에 대해서는 
# 자동으로 수정을 하는 것을 의미한다. 
eslint --fix

 

보통, 협업 시에는 프로젝트 저장소에 제약을 두어 Merge 시 Lint 테스트를 자동으로 수행하고 테스트를 통과하지 못할 시 코드가 Merge되지 않도록 설정하는데, 이에 따라 로컬에서 작성한 코드를 원격 저장소로 push할 때 Lint 테스트를 계속해서 수행해주어야 한다. 이는 물론 큰 작업 단위는 아니지만 매번 수행하기에는 꽤나 번거로운 작업이고, 또 간혹 테스트를 잊어버리는 경우도 존재한다. 

이를 위해 개발자는 Husky의 도입을 고려할 수 있다.

 

 

Husky

Husky는 협업 환경에서 Git Hooks을 쉽게 공유할 수 있게 도와주는 NodeJS 기반 모듈이다.

여기서 Git Hooks는 특정 Git 이벤트 실행 전, 후에 추가적인 작업을 자동적으로 수행하는 기능을 제공하는 도구이다. Git Hooks의 종류로는 클라이언트 훅, 서버 훅으로 나뉘며 그 안에서도 커밋 워크플로우 훅, 이메일 워크플로우 훅, 서버 훅 등으로 나뉜다. 여기에서는 커밋 시 자동으로 Lint 체크를 수행하는 로직을 작성해야하기 때문에 커밋 워크플로우 훅에 대해서만 조금 더 알아보자.

Commit Workflow Hooks

커밋 워크플로우 훅을 통하면 커밋 이벤트 전, 후로 훅을 작동시킬 수 있다. 커밋 워크플로우 훅의 종류는 다음과 같다.

• pre-commit (커밋 시 가장 먼저 실행)
• prepare-commit-msg (git이 커밋 메시지를 생성하고 편집기를 실행하기 직전 실행)
• commit-msg (커밋이 발생하기 직전 실행)
• post-commit (커밋이 발생한 직후 실행)

이 중 pre-commit 훅을 통하면 커밋 이벤트 발생 시 먼저 특정 테스트를 강제하고, 테스트 실패 시 해당 커밋 이벤트를 취소시키는 것이 가능하다. 

이를 작성하는 것도 어렵지 않은데, 자동으로 프로젝트 폴더에 생성되는 .git 디렉터리 내부의 hooks 디렉터리를 사용하면 된다. 해당 경로에 가보면 Git에서 자동으로 생성한 샘플 훅 파일들이 존재한다. 이를 적용하고 싶다면 단순히 파일명에서 .sample을 빼주면 된다. 로직을 작성하는 것도 어렵지 않은데, shell, Perl 뿐 아니라 Ruby, Python으로도 작성할 수 있다.

git에서 자동으로 생성한 sample 파일들

지금까지의 내용만 놓고 봤을 때, Husky까지 갈 필요 없이 단순 Git Hook만으로도 충분해보인다. 하지만 기본 Git Hook에는 큰 문제점이 존재한다. 바로, 위와 같이 작성된 Git Hook 파일을 Git을 통해 원격 저장소, 혹은 다른 사용자와 공유할 수 없다는 문제다. Git 명령어들을 통해서는 .git 디렉터리의 파일들을 공유할 수 없기 때문인데, 해당 문제를 해결하기 위해 Husky가 쓰인다.

 

 

Husky를 통한 Git Hook 공유

Husky를 통하면 협업 환경에서 Git Hook 관련 세팅을 굉장히 편하게 수행할 수 있다. Husky 세팅을 수행한 프로젝트가 Git 명령어를 통해 공유되면, 다른 환경에서 의존성 세팅(npm i) 시 저절로 Git Hook이 적용되는 방식이다.

프로젝트에 Husky를 적용해보자. 최종적으로는 Husky와 Lint-staged를 이용하여 매 커밋마다 eslint --fix 명령을 강제하고 테스트가 실패할 시 커밋을 반려하는 것을 목표로 한다.

우선, Husky가 사용되는 환경은 크게 2개로 나뉜다. 각각의 경우에 대해 Husky와 Lint-staged 설정이 조금씩 다르게 진행된다.

1. .git 디렉터리와 package.json 파일이 동일 디렉터리에 위치하는 경우
2. .git 디렉터리와 package.json 파일이 서로 다른 디렉터리에 위치하는 경우

 

.git 디렉터리와 package.json 파일이 동일 디렉터리에 위치

해당 경우에는 설정 과정이 간단해진다. 

먼저, 다음의 명령어를 통해 Husky의 설치와 설정을 수행하자.

npx husky-init -y && npm install

위 명령어를 수행하면 프로젝트 의존성에 Husky가 추가됨과 동시에, .husky 경로가 생성되고 그 안에 pre-commit 파일이 생성된다. 자동으로 생성된 파일의 내용물은 다음과 같다.

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm test

이 때 npm test 명령어는 Husky가 자동으로 추가한 명령어이다. Husky를 통해 또 다른 명령어를 추가하고 싶다면 다음의 명령어를 사용할 수 있다.

npx husky add {Husky 파일의 경로} "{수행할 명령어}"

커밋 시 Shell에 Hello, Husky! 라는 문자열을 출력하도록, 다음과 같이 명령어를 사용할 수 있다.

npx husky add .husky/pre-commit "echo 'Hello, Husky!'"

명령어 수행 후 다시 .husky/pre-commit 파일에 가보면, 다음과 같이 명령어가 추가된 것을 확인할 수 있다.

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm test
echo 'Hello, Husky!'

이제 커밋을 실행하면 위 로직이 수행된다. 

이 때, 만약 package.json의 npm test 명령어를 따로 건들지 않았다면 일괄적으로 exit 1 이 수행되기 때문에 그 뒤의 echo 문은 실행되지 않고 곧바로 커밋이 반려되는 것을 볼 수 있다.

Lint-staged 적용

Lint-staged를 이용하면 현재 staging 상태의 코드들에 대해서만 Lint 체크를 수행할 수 있다. 즉, 특정 커밋의 변동 사항에 대해서만 Lint 체크가 수행되는 것이다. 매 커밋 시 전체 코드에 대한 Lint 체크가 수행되면 이미 룰을 통과한 코드들에 대한 재검사가 이루어져 엄청난 비효율이 발생하는데, Lint-staged는 이러한 비효율을 제거해준다. 

또한 Lint-staged를 통해 eslint --fix 명령어를 사용할 경우, eslint가 --fix 옵션에 의해 수정한 사항도 자동으로 커밋에 포함시켜준다.

Lint-staged를 설치하기 앞서, 먼저 해당 프로젝트에 eslint와 prettier 의존성을 추가하고 설정을 완료해주어야 한다.

그 다음, Lint-staged를 설치해주자.

npm i -D lint-staged

그 후 package.json 내 lint-staged를 추가해준다.

{
  ...,
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix"
    ]
  }
}

마지막으로, .husky/pre-commit 파일을 다음과 같이 수정해주면 Husky, Lint-staged를 통한 pre-commit 훅 설정이 완료된다.

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged

여담으로, 위 모든 설정은 아래의 명령어 한줄을 통해서도 가능하다. 단, 아래 명령어는 .git 디렉터리와 package.json 파일이 같은 경로에 존재할 때만 정상 작동한다.

npx mrm@2 lint-staged

 

.git 디렉터리와 package.json 파일이 서로 다른 디렉터리에 위치

해당 경우는 위에서 언급한 npx mrm@2 lint-staged 명령어를 통해 husky와 lint-staged를 한번에 설정할 수 없고, 각각 설정해주어야한다. 

더 쉬운 설명을 위해 프로젝트는 다음의 디렉터리 구조를 따른다고 가정하겠다.

/project
  /.git
  /client
    ...
    /package.json
  /server
    ...
    /package.json

또한 앞으로 Shell에 작성하는 모든 명령어는 .git 디렉터리가 존재하는 project 디렉터리를 기준으로 이루어진다고 가정한다.

먼저 Husky를 설치해주자. client 디렉터리와 server 디렉터리 중 하나를 선택하여 한 곳에만 설치를 진행한다. 여기에서는 server 디렉터리를 선택하겠다.

# /project 경로에서 실행
cd server && npm install -D husky

그 후 다음 명령어를 통해 Husky 설정을 수행한다.

# 앞선 명령어 때문에 해당 명령이 수행되는 디렉터리는 /project/server
cd .. && npx husky install server/.husky

그 뒤엔 /server/package.json 파일 내 scripts 부분에 다음을 추가한다.

{
  "scripts": {
    ...,
    "prepare": "cd .. && husky install server/.husky"
  }
}

다음은 Lint-staged 관련 설정이다. 

Lint-staged를 설치하기에 앞서 /client 디렉터리와 /server 디렉터리에 각각 eslint, prettier를 설치해주고, 설정도 완료해준다.

설정이 완료되었다면, 각각의 경로에 모두 Lint-staged를 설치와 설정을 해주어야 한다.

Lint-staged를 /server, /client 디렉터리에 모두 설치해주자.

npm i -D lint-staged

 그 뒤에, 역시 마찬가지로 /server, /client 디렉터리 내 package.json에 다음을 추가해주자.

{
  ...,
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix"
    ]
  }
}

마지막으로, /server/.husky/pre-commit 파일을 다음과 같이 수정해주자.

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

cd client && echo 'Client Check' && npx lint-staged && cd ..
cd server && echo 'Server Check' && npx lint-staged && cd ..

위 설정을 통해, 커밋 시 client, server 경로에 대해 각각 Lint 테스트를 자동으로 수행하고 테스트가 실패하지 않는다면 커밋이 수행되고 그렇지 않을 경우 커밋이 반려되는 pre-commit 훅이 작동하게 된다.