GitHub 협업 가이드 - Commit Convention & Pre-commit

Commit Convention

Commit Convention이란 commit을 남기는 규칙을 의미한다. 일관적인 commit log를 통해 서로 다른 사람들이 작업한 내용을 쉽게 파악하고, 유지보수할 수 있도록 하기 위해 약속하는 commit convention에 대해 알아보자.

Header

일반적으로 Header에는 prefix가 붙으며, prefix 뒤로 작업의 대략적인 내용이 붙는다.

• feat: 새로운 기능
• fix: 버그 수정
• docs: 문서 내용 수정
• style: 코드의 의미가 바뀌지 않는 수정 (공백 처리, 코드 포매팅, 세미 콜론 추가 등)
• refactor: 코드 리팩토링
• perf: 코드 성능 개선
• test: 테스트 추가
• chore: 빌드 추가, 패키지 관리자 수정

ex) feat: add rest api code

 

Body

Header에서 한줄로 설명이 가능한 수준이라면 Body는 생략할 수 있다. 
Header와 구분될 수 있도록 한 줄을 비워두고 작성한다.

ex)

Case 1: Body가 생략되는 경우

    feat: add multiple function with two variables

Case 2: Body가 사용되는 경우

    refactor: modify api handler logic

    - change logic 1
    - change logic 2

 

Footer

해당 작업과 관련된 Issue의 tag를 적는다. Issue Tag를 추가하는 이유는 commit log에 Issue Tag를 남기면 GitHub에서 자동으로 해당 태그를 인식하여 Issue와 관련된 commit을 연결해준다. 이를 통해 하나의 Issue와 관련된 commit history를 한눈에 확인할 수 있다.

Issue Tag는 #{Issue 번호}로 적는다.

ex)

 

refactor: modify api handler logic

- change logic 1
- change logic 2

#1

 

Pre-commit

commit을 수행하기 이전에 정해진 스크립트들을 실행할 수 있게 하는 툴이다. 예를 들어, black, flake8과 같은 코드 포맷터를 등록하거나 unittest, pytest와 같은 testing tool을 등록할 수 있다.

1.  설치

pip install pre-commit # 파이썬이 설치되어 있는 경우
brew install pre-commit # 파이썬이 설치되어 있지 않고, Mac OS인 경우

 

2.  설정 파일 생성

pre-commit은 .pre-commit-config.yaml이라는 이름의 설정 파일에 commit 이전에 수행할 작업들을 정의한다.

아래의 pre-commit의 명령어를 통해 기본 설정 파일을 생성할 수 있다.

pre-commit은 .pre-commit-config.yaml이라는 이름의 설정 파일에 commit 이전에 수행할 작업들을 정의한다.

아래의 pre-commit의 명령어를 통해 기본 설정 파일을 생성할 수 있다.

 

.pre-commit-config.yaml 파일을 열어보면 아래와 같이 구성되어 있다.

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

파일의 내용을 자세히 뜯어보면

• repos: 어떤 레포지토리에서(repo) 어떤 버전의(rev) 작업들(hooks)을 수행할 것인지를 내부의 값으로 갖는다.
• repo: pre-commit은 git 저장소로부터 hook을 내려받아 실행하게 되는데, 이 때 우리가 실행하고 싶은 hook이 저장된 저장소 주소를 나타낸다.
• rev: 어떤 버전의 hook을 클론받을 것인지 나타낸다.
• hooks: 저장소에서 받아올 hook을 나타낸다.

 

위 파일에서 black을 추가하고 싶다면 아래와 같이 설정 파일을 수정할 수 있다.

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black

pre-commit 공식 홈페이지의 Supported hooks 페이지를 방문하면 pre-commit에서 제공하는 다양한 hook들을 찾아볼 수 있다.

 

3.  실행

가장 먼저 git local 저장소에서 pre-commit install 명령어를 실행하여 git hook script를 세팅해야 한다.

> pre-commit install
pre-commit installed at .git/hooks/pre-commit

이제 commit을 수행하기 전에 pre-commit이 자동으로 실행될 것이다. 참고로 위 작업은 새로운 git 저장소를 clone 받을 때마다 실행해줘야 한다.

 

이제 commit을 하게 되면

> git add .pre-commit-config.yaml
> git commit -m "create .pre-commit-config.yaml"
[INFO] Initializing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Installing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
Trim Trailing Whitespace.................................................Passed
Fix End of Files.........................................................Passed
Check Yaml...............................................................Passed
Check for added large files..............................................Passed
[main e3a00ec] create .pre-commit-config.yaml
 1 file changed, 10 insertions(+)
 create mode 100644 .pre-commit-config.yaml

모든 hook을 통과하고 성공적으로 commit이 되는것을 확인할 수 있다.

만약 파일이 hook을 통과하지 못한다면

> echo "Add unnecessary space " > test.txt
> git add test.txt
> git commit -m "create test.txt"
Trim Trailing Whitespace.................................................Failed
- hook id: trailing-whitespace
- exit code: 1
- files were modified by this hook

Fixing test.txt

Fix End of Files.........................................................Passed
Check Yaml...........................................(no files to check)Skipped
Check for added large files..............................................Passed

위와 같이 파일이 수정되고, commit이 진행되지 않는 것을 확인할 수 있다.

 

> git status
On branch main
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        new file:   test.txt

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   test.txt

$ git add test.txt
$ pre-commit run
Trim Trailing Whitespace.................................................Passed
Fix End of Files.........................................................Passed
Check Yaml...........................................(no files to check)Skipped
Check for added large files..............................................Passed
[main 342a98e] create test.txt
 1 file changed, 1 insertion(+)
 create mode 100644 test.txt

수정된 파일은 unstage 상태이므로, 수정된 파일을 git add 명령어를 통해 스테이지 영역에 추가해준 뒤, 다시 commit을 실행하면, 성공적으로 commit이 진행된다.

 

4. (옵션) 모든 파일에 대해 pre-commit 실행

기존에 파일이 존재하는데 뒤늦게 pre-commit을 도입하거나, pre-commit에 새로운 hook을 추가한 경우에는 모든 파일에 대해 pre-commit을 실행해주는 것이 좋다.

> pre-commit run --all-files

위 명령어를 통해 모든 파일에 pre-commit을 실행시킬 수 있다.