Git Hooks

Git는 Git Hooks를 통해 git 명령 실행 중 스크립트를 실행할 수 있습니다.
예를 들어, 커밋하거나 푸시하기 전에 파일을 포맷팅하고 정리할 수 있습니다.
Git Hooks 관리를 간편하게 해주는 여러 도구가 있습니다.
다음 섹션에서는 그 중 일부와 Biome와의 사용 방법을 소개합니다.

Lefthook

Lefthook는 빠르고 다중 플랫폼, 의존성 없는 훅 관리 도구입니다.
로컬에서 NPM을 통해 설치할 수 있습니다.

프로젝트 루트에 lefthook.yml이라는 파일을 추가하세요.
다음은 몇 가지 Lefthook 설정 예시입니다:

커밋 전 포맷 및 린트 검사

1
pre-commit:
2
  commands:
3
    check:
4
      glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
5
      run: npx @biomejs/biome check --no-errors-on-unmatched --files-ignore-unknown=true --colors=off {staged_files}

커밋 전 코드를 포맷팅하고 수정하며 안전한 수정 사항을 적용

1
pre-commit:
2
  commands:
3
    check:
4
      glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
5
      run: npx @biomejs/biome check --write --no-errors-on-unmatched --files-ignore-unknown=true --colors=off {staged_files}
6
      stage_fixed: true

stage_fixed: true는 수정된 파일을 다시 스테이징합니다.

푸시 전 포맷과 린트 검사

1
pre-push:
2
  commands:
3
    check:
4
      glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
5
      run: npx @biomejs/biome check --no-errors-on-unmatched --files-ignore-unknown=true --colors=off {push_files}

glob과 --files-ignore-unknown=true를 모두 사용할 필요는 없습니다.
단순히 --files-ignore-unknown=true만 사용하면 현재와 미래에 Biome가 지원하는 파일을 처리할 수 있습니다.
더 구체적인 파일 제어가 필요하다면 glob을 사용해야 합니다.

--no-errors-on-unmatched는 파일이 처리되지 않았을 경우 발생할 수 있는 오류를 무시합니다.

설정이 완료되면 lefthook install을 실행하여 훅을 구성하세요.

Husky

Husky는 자바스크립트 생태계에서 널리 사용되는 훅 관리 도구입니다.
Husky는 스테이징되지 않은 변경사항을 숨기지 않으며, 스테이징된 파일 목록을 제공하지 못합니다.
이러한 이유로 보통 lint-staged 또는 git-format-staged 같은 다른 도구와 함께 사용됩니다.

프로젝트에 package.json이 있다면, scripts.prepare를 통해 자동으로 훅을 설정할 수 있습니다.:

1
{
2
  "scripts": {
3
    "prepare": "husky"
4
  }
5
}

lint-staged

lint-staged는 자바스크립트 생태계에서 가장 많이 사용되는 도구 중 하나입니다.

다음과 같이 husky 설정을 추가하세요:

1
lint-staged

lint-staged 설정은 직접 package.json 내부에 포함됩니다.
다음은 깃 훅을 실행할 때 유용할 수 있는 몇 가지 예시입니다:

1
{
2
  "lint-staged": {
3
    // js, ts, jsx, tsx, json, jsonc 확장자를 가진 스테이징된 파일에 대해 Biome 실행
4
    "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}": [
5
      "biome check --files-ignore-unknown=true", // 포맷 검사 및 오류 확인
6
      "biome check --write --no-errors-on-unmatched", // 포맷팅, 임포트 정리, 오류 확인, 안전한 수정 적용
7
      "biome check --write --organize-imports-enabled=false --no-errors-on-unmatched", // 포맷팅 및 안전한 수정 적용
8
      "biome check --write --unsafe --no-errors-on-unmatched", // 포맷팅, 임포트 정렬, 오류 확인, 안전/비안전 수정 적용
9
      "biome format --write --no-errors-on-unmatched", // 포맷팅
10
      "biome lint --write --no-errors-on-unmatched", // 오류 확인 및 안전한 수정 적용
11
    ],
12
    // 또는 모든 파일을 대상으로 하되, 알 수 없는 확장자 무시 가능
13
    "*": [
14
      "biome check --no-errors-on-unmatched --files-ignore-unknown=true", // 포맷 검사 및 오류 확인
15
    ],
16
  },
17
}

파일이 처리되지 않았을 경우 발생할 수 있는 오류를 무시하려면 커맨드라인 옵션 --no-errors-on-unmatched를 사용하세요.

git-format-staged

다른 도구들인 lefthook, pre-commit, _lint-staged_와 달리,
git-format-staged는 내부적으로 git stash를 사용하지 않습니다.
이는 미스테이징된 변경사항과 스테이징된 변경사항 간 충돌이 발생했을 때 수동 개입을 방지합니다.
git-format-staged와 기타 도구의 비교를 참고하세요.

몇 가지 설정 예시:

커밋 전 포맷 및 오류 검사

1
git-format-staged --formatter 'biome check --files-ignore-unknown=true --no-errors-on-unmatched \"{}\"' .

커밋 전 코드 포맷팅, 오류 검사, 안전한 수정 적용

1
git-format-staged --formatter 'biome check --write --files-ignore-unknown=true --no-errors-on-unmatched \"{}\"' .

pre-commit

pre-commit는 다국어 훅 매니저입니다.
Biome는 biomejs/pre-commit 리포지토리를 통해 네 가지 pre-commit 훅을 제공합니다.

hook `id`	설명
`biome-ci`	포맷팅, 임포트 정리 여부 확인, 오류 검사
`biome-check`	포맷팅, 임포트 정리, 오류 검사, 커밋 파일에 안전한 수정 적용
`biome-format`	커밋 파일 포맷팅
`biome-lint`	오류 검사 및 커밋 파일에 안전한 수정 적용

다음 예제에서는 이미 pre-commit 설치되어 있고, 프로젝트 루트에서 pre-commit install을 실행했다고 가정합니다.
biome-check 훅을 사용하려면 .pre-commit-config.yaml라는 파일에 다음 설정을 추가하세요:

1
repos:
2
  - repo: https://github.com/biomejs/pre-commit
3
    rev: "v2.0.6" # 원하는 버전의 sha 또는 태그로 지정하세요
4
    hooks:
5
      - id: biome-check
6
        additional_dependencies: ["@biomejs/[email protected]"]

이 설정은 git commit을 실행할 때 biome check --write를 실행합니다.

additional_dependencies 옵션을 통해 어떤 버전의 Biome을 사용할지 명시해야 합니다.
pre-commit는 각 도구를 별도로 설치하며, 어떤 것을 설치할지 알아야 합니다.

만약 당신의 로컬 리포지토리에 이미 npm 패키지로서 Biome가 설치되어 있다면,
Biome가 업데이트될 때마다 package.json과 .pre-commit-config.yaml을 모두 업데이트하는 것이 번거로울 수 있습니다.
이런 경우, 제공되는 Biome 훅 대신 자신만의 로컬 훅을 지정할 수 있습니다.

예를 들어 npm을 사용한다면, 다음과 같이 .pre-commit-config.yaml에 훅을 작성할 수 있습니다:

1
repos:
2
  - repo: local
3
    hooks:
4
      - id: local-biome-check
5
        name: biome check
6
        entry: npx @biomejs/biome check --write --files-ignore-unknown=true --no-errors-on-unmatched
7
        language: system
8
        types: [text]
9
        files: "\\.(jsx?|tsx?|c(js|ts)|m(js|ts)|d\\.(ts|cts|mts)|jsonc?)$"

pre-commit의 files 옵션은 선택 사항이며,
Biome가 알 수 없는 파일을 무시할 수 있기 때문입니다 (옵션 --files-ignore-unknown=true 사용).

쉘 스크립트

또한 사용자 정의 쉘 스크립트를 사용할 수도 있습니다.
다양한 플랫폼 간 호환성 문제에 주의해야 합니다.
이전 섹션에서 소개한 도구를 사용하는 것이 권장됩니다.

몇 가지 쉘 스크립트 예시:

커밋 전 포맷 검사 및 오류 확인

1
#!/bin/sh
2
set -eu
3

4
npx @biomejs/biome check --staged --files-ignore-unknown=true --no-errors-on-unmatched

커밋 전 코드 포맷팅, 오류 검사, 안전한 수정 적용

1
#!/bin/sh
2
set -eu
3

4
if git status --short | grep --quiet '^MM'; then
5
  printf '%s\n' "ERROR: Some staged files have unstaged changes" >&2
6
  exit 1;
7
fi
8

9
npx @biomejs/biome check --write --staged --files-ignore-unknown=true --no-errors-on-unmatched
10

11
git update-index --again

이 훅은 스테이징된 파일에 미스테이징된 변경사항이 있을 경우 실패하도록 구성되었습니다.