git

CHANGELOG 자동으로 생성하기 (git-cliff)

Seonghyeon Cho

2023년 11월 24일 • 6 min read

changelog는 프로젝트의 버전별 변경사항을 정리한 것이다. 이게 없다면 라이브러리나 프로그램 버전을 올릴 때 git diff를 직접 봐야 하는데 매우 불편하기 때문에 changelog를 잘 만들어놔야 한다.

직접 changelog를 작성하는 것은 번거로운데, git-cliff 등의 changelog 생성기를 이용해 자동으로 만들 수 있다.

이 글에서는 git-cliff를 이용해 changelog를 자동으로 만드는 방법을 알아보자

git-cliff

docs: https://git-cliff.org/
repository: https://github.com/orhun/git-cliff

changelog를 생성하는 유틸리티가 git-cliff 말고도 많이 있지만, git-cliff는 유지보수가 잘 되고 있으며 커스터마이징도 용이하고 속도가 빨라 추천한다.

참고로 git-cliff는 Rust로 작성되었다.

설치는 여러 방법으로 할 수 있는데, 예를 들어 homebrew를 사용해 설치하려면 아래 명령어를 사용한다.

brew install git-cliff

다른 설치방법은 installation 페이지를 참고한다.

git-cliff 실행은 git cliff로 하면 된다.

git-cliff를 이용한 CHANGELOG.md 생성

아래는 예시 프로젝트 링크이다.

아래처럼 tag를 x.x.x 형식으로 만들어 놓았다.

프로젝트에서 git-cliff를 이용하려면 먼저 설정 파일(cliff.toml)을 생성하고, 그 다음 git-cliff 를 실행해야 한다.

--init 옵션을 넣고 git-cliff를 실행하면 기본 설정 파일이 생성된다.

git cliff --init

설정 파일 형식은 TOML이다. 옵션이 상당히 많은데, 전체 옵션별 설명은 Configuration 문서를 참고한다.

changelog를 생성하기 위한 템플릿 엔진은 Tera를 사용하고 있으며, Jinja2와 비슷한 형식으로 사용할 수 있다. Tera 템플릿에 대한 자세한 설명은 문서를 참고한다.

기본적으로 conventional commit 형식에 맞춰 커밋 메시지를 파싱해 changelog를 파싱하기 때문에, 커밋 메시지가 해당 형식으로 작성되지 않았다면 git.conventional_commits, git.filter_unconventional 항목을 false로 설정해줘야 한다.

나머지 항목은 리파지토리나 커밋 형식에 맞춰 적절히 수정해준다.

# git-cliff ~ default configuration file
# https://git-cliff.org/docs/configuration
#
# Lines starting with "#" are comments.
# Configuration options are organized into tables and keys.
# See documentation for more information on available options.

[changelog]
# changelog header
header = """
# Changelog\n
All notable changes to this project will be documented in this file.\n
"""
# template for the changelog body
# https://keats.github.io/tera/docs/#introduction
body = """
{% if version %}\
    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}\
    ## [unreleased]
{% endif %}\
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}
        - {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}\
    {% endfor %}
{% endfor %}\n
"""
# remove the leading and trailing whitespace from the template
trim = true
# changelog footer
footer = """
<!-- generated by git-cliff -->
"""
# postprocessors
postprocessors = [
  # { pattern = '<REPO>', replace = "https://github.com/orhun/git-cliff" }, # replace repository URL
]
[git]
# parse the commits based on https://www.conventionalcommits.org
conventional_commits = true
# filter out the commits that are not conventional
filter_unconventional = true
# process each line of a commit as an individual commit
split_commits = false
# regex for preprocessing the commit messages
commit_preprocessors = [
  # { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](<REPO>/issues/${2}))"}, # replace issue numbers
]
# regex for parsing and grouping commits
commit_parsers = [
  { message = "^feat", group = "Features" },
  { message = "^fix", group = "Bug Fixes" },
  { message = "^doc", group = "Documentation" },
  { message = "^perf", group = "Performance" },
  { message = "^refactor", group = "Refactor" },
  { message = "^style", group = "Styling" },
  { message = "^test", group = "Testing" },
  { message = "^chore\\(release\\): prepare for", skip = true },
  { message = "^chore\\(deps\\)", skip = true },
  { message = "^chore\\(pr\\)", skip = true },
  { message = "^chore\\(pull\\)", skip = true },
  { message = "^chore|ci", group = "Miscellaneous Tasks" },
  { body = ".*security", group = "Security" },
  { message = "^revert", group = "Revert" },
]
# protect breaking changes from being skipped due to matching a skipping commit_parser
protect_breaking_commits = false
# filter out the commits that are not matched by commit parsers
filter_commits = false
# regex for matching git tags
tag_pattern = "v[0-9].*"
# regex for skipping tags
skip_tags = "v0.1.0-beta.1"
# regex for ignoring tags
ignore_tags = ""
# sort the tags topologically
topo_order = false
# sort the commits inside sections by oldest/newest order
sort_commits = "oldest"
# limit the number of commits included in the changelog.
# limit_commits = 42

changelog는 기본적으로 stdout에 출력되며, 파일로 출력하려면 -o 옵션을 넣어준다.

# stdout 출력
git cliff

# CHANGELOG.md 파일로 출력
git cliff -o CHANGELOG.md

설정을 약간 수정하고, 출력한 예시는 아래와 같다

# Changelog

All notable changes to this project will be documented in this file.

## [unreleased]

### Miscellaneous Tasks

- Update readme ([#1](https://github.com/vince-test-org/changelog-generator-example/issues/1)) ([5f71f69](https://github.com/vince-test-org/changelog-generator-example/commit/5f71f697e63b200066ee999b4748af412b446210))

## [0.3.0] - 2023-11-24

### Features

- Replace issue link, add commit hash in changelog ([7cb35c9](https://github.com/vince-test-org/changelog-generator-example/commit/7cb35c9735b3955b88d226f7f2340819b7fde059))

### Miscellaneous Tasks

- On push tags ([4a3310f](https://github.com/vince-test-org/changelog-generator-example/commit/4a3310f4b8ea0eb711d9e53f6c24a5b42af36812))

## [0.2.0] - 2023-11-24

### Bug Fixes

- Tag pattern ([92e66a6](https://github.com/vince-test-org/changelog-generator-example/commit/92e66a6da435b425b77c8b58a25e4b7393e201fd))

### Features

- Add changelog workflow ([6f64c17](https://github.com/vince-test-org/changelog-generator-example/commit/6f64c176e61e94cc3a1854902e6bc7035480844d))

## [0.1.0] - 2023-11-24

### Miscellaneous Tasks

- Init ([a3be969](https://github.com/vince-test-org/changelog-generator-example/commit/a3be9697e3b36229190c99da04f9519fab2e069f))

<!-- generated by git-cliff -->

아래처럼 github actions workflow를 만들어서 자동으로 업데이트 할 수도 있다

(아래 예시는 모든 커밋마다 업데이트를 시도해서 실제로 프로젝트에 적용한다면 릴리즈시에만 작동하게 하는 등 수정이 좀 필요하다)

name: Update CHANGELOG

on:
  push:
    tags:
      - '*'
    branches:
      - main

permissions:
  contents: write

jobs:
  git-cliff-action:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Generate a changelog
        uses: orhun/git-cliff-action@v2
        id: git-cliff
        with:
          config: cliff.toml
          args: --verbose
        env:
          OUTPUT: CHANGELOG.md

      - name: Set github-actions bot config
        run: |
          git config user.name 'github-actions[bot]'
          git config user.email 'github-actions[bot]@users.noreply.github.com'

      - name: Commit and push CHANGELOG, only if there are any changes
        run: |
          if [[ -n $(git status -s) ]]; then
            git add CHANGELOG.md
            git commit -m "Update CHANGELOG"
            git push origin HEAD
          fi