git-journal 📖

Build Status

master doc gitjournal

License MIT

Join the chat at https://gitter.im/git-journal/Lobby

Git 커밋 메시지 및 변경 로그 생성 프레임워크

TL;DR
설치
사용법
현재 기능
계획된 기능 및 개선 사항
기여하기

TL;DR

변경 로그(changelogs)를 유지 관리하는 것은 시간이 많이 걸릴 수 있으며, 특히 여러 사람이 같은 프로젝트에서 작업할 때 더욱 그렇습니다. 별도의 파일을 유지 관리한다면 병합 충돌(merge conflicts)과 추가적인 릴리스 작업이 필연적으로 뒤따릅니다.

때로는 병합 충돌 해결 과정에서 전체 항목이 손실되기도 하고, 사람들이 무언가를 언급하는 것을 잊거나 이슈와 실제 커밋 간의 링크가 누락되는 경우가 있습니다.

만약 추가적인 작업 없이 git의 커밋 기록을 사용하여 아름다운 변경 로그를 생성할 수 있다면 좋을 것입니다.

여기서 git-journal이 등장합니다.

이 자동 생성을 위해서는 더 합리적인 커밋 메시지를 작성할 수 있는 프레임워크가 필요합니다. 단일 커밋 메시지는 프로젝트의 하나의 논리적 변경 사항을 포함해야 하며, 이는 표준화된 방식으로 설명되어야 합니다. 이렇게 하면 훨씬 깔끔한 git 히스토리가 만들어지고 기여자들에게 실제 변경 사항에 대한 더 많은 정보를 제공할 수 있습니다.

이론적 기반은 두 개의 RFC로 구성됩니다:

설치 (Installation)

_git-journal_를 git 확장으로 사용하려면 패키지 관리자인 cargo를 포함한 Rust 설치가 필요합니다. 다른 패키지 관리자들도 이를 제공할 수 있으며, 예를 들어 Arch Linux에서는 Pacman을 통해 가능합니다:

sudo pacman -S rust cargo

매우 쉽게 설치하는 방법으로는 rustup을 사용할 수도 있습니다. 이 두 가지 종속성이 설치되면, _git-journal_는 다음 명령어를 통해 설치할 수 있습니다:

cargo install git-journal

$PATH 변수를 수정하여 ~/.cargo/bin 내부도 검색하도록 설정한 후에는 git journal을 호출하여 실행하는 것이 가능해야 합니다.

사용법 (Usage)

바이너리인 git-journal는 Rust 라이브러리 gitjournal에 의존하며, 이 라이브러리는 바이너리 애플리케이션과 독립적으로 사용되어 맞춤형 솔루션을 작성할 수도 있습니다. 이 저장소가 다음 설명의 예시로 사용될 것입니다.

기본 출력 (Default output)

이 저장소 내부 어디에서든 git journal을 실행하면, 해당 저장소의 git log를 기반으로 보기 좋은 Markdown 형식의 변경 로그가 출력됩니다:

모든 커밋은 시간순으로 정렬되며, 가장 최신 항목이 상단에 나타납니다. 커밋 메시지 파싱은 커밋 메시지 내의 다양한 구문 요소를 설명하는 RFC0001을 기반으로 수행됩니다. 카테고리([Added], [Fixed] 등)는 사용 가능한 경우 자동으로 대괄호로 묶입니다. 또한 설정 파일 내에서 자체 카테고리를 정의하는 것도 가능합니다. 이 저널은 마지막 릴리스부터 미출시된 항목까지 로그를 자동으로 나열합니다.

커밋 메시지의 푸터(RFC0001에 설명됨)는 자동으로 누적되어 값별로 정렬된 변경 로그 목록 뒤에 출력됩니다. 또한 미출시 항목을 건너뛸 수도 있습니다:

> git journal -u
[git-journal] [OKAY] Parsing done.

...

REV..REV 형식으로 특정 커밋 범위를 사용하거나 HEAD가 아닌 다른 시작 지점을 파싱에 사용할 수도 있습니다:

> git journal v1
> git journal v2
> git journal v1...HEAD^

-a 옵션을 사용하여 모든 릴리스(git tags)를 출력하거나, -n <COUNT>를 통해 지난 n개의 릴리스를 확인할 수 있습니다:

> git journal -a
[git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch''
[git-journal] [OKAY] Parsing done.
...

> git journal -un1
[git-journal] [OKAY] Parsing done.
...

일반적인 상세 로그 외에 커밋 요약만 사용하는 간략 버전(-s)도 존재합니다:

> git journal -as
[git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch''
[git-journal] [OKAY] Parsing done.
...

또한 journal의 출력을 파일에 추가할 수도 있습니다 (-o). 이 경우 각 git journal 호출마다 개행 문자(---)로 구분됩니다. rc와 같은 특정 패턴을 가진 Git 태그는 자동으로 제외되며, 이는 -e를 통해 사용자 정의할 수 있습니다.

더 자세한 정보는 help git journal -h를 참조하십시오.

템플릿 출력

커밋 메시지 템플릿의 설계는 RFC0002에 설명되어 있습니다. 지금부터 우리는 테스트 저장소에서 이 템플릿을 사용합니다:

[[tag]]
tag = "default"
name = "Default"
...

이러한 템플릿을 사용하려면 -t 옵션을 사용하기만 하면 됩니다:

> git journal -t CHANGELOG.toml
[git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch''
[git-journal] [OKAY] Parsing done.
...

태그가 지정되지 않은 모든 내용은 default 섹션으로 들어갑니다. tag1의 이름은 Section 1로 매핑되며, tag2는 tag1의 하위 태그입니다 (마크다운 헤더 참조). 이는 또한 커밋을 여러 조각으로 분할할 수 있는 가능성을 제공하기 때문에 목록 항목이 분류되지 않을 수도 있음을 의미합니다. 구문 분석된 단락은 항상 깔끔한 마크다운을 제공하도록 단일 목록 항목으로 변환됩니다. 푸터는 문자열의 toml 배열로 지정되며, 로그의 올바른 위치에 선택된 푸터 키를 출력합니다. 푸터의 누적은 단순히 해당 섹션이 아니라 전체 태그와 관련된다는 점을 고려하십시오. 기본 출력에서와 같은 다른 명령줄 옵션도 사용할 수 있습니다.

또한 모든 출력 또는 모든 태그에 사용자 정의 헤더나 푸터 텍스트를 추가하는 것도 가능합니다. 더 자세한 정보는 RFC0002를 읽어보십시오.

커밋 메시지 준비 및 검증

자동 커밋 메시지 준비 및 검증을 사용하려면 git journal 설정을 모든 로컬 저장소에서 실행해야 합니다:

> git journal setup
[git-journal] [OKAY] 기본값이 '.gitjournal.toml' 파일에 작성되었습니다.
[git-journal] [OKAY] Git hook이 '.git/hooks/commit-msg'에 설치되었습니다.
...

이미 이러한 훅(hook)이 존재하는 경우, _git-journal_은 필요한 명령어를 추가하려고 시도하며, 이는 나중에 수동으로 확인해야 합니다. bash와 fish를 위한 생성된 명령어 라인 완성 파일은 셸의 올바른 디렉토리에 배치되어야 합니다. 기본 설정 파일은 toml 파일이며, 이 구조를 나타냅니다(this structure). 주석이 포함된 기본 구성 파일도 여기서 찾을 수 있습니다.

설정이 완료되면 _git-journal_은 커밋 메시지 준비를 수행하는 것 외에도 사용자가 입력한 커밋 메시지를 검증합니다. 예를 들어, 현재 파싱할 수 없는 내용을 커밋하려고 한다고 가정해 봅시다:

> touch my_file
> git add my_file
> git commit -m "This commit contains no cactegory"
...

-m 플래그를 사용했기 때문에 사용자가 메시지를 편집할 기회가 없으며, _git-journal_은 이를 거부합니다. -m 없이 일반적인 git commit을 통해 커밋 메시지 편집기를 사용하는 경우, 기본 커밋 메시지 템플릿을 받게 됩니다:

JIRA-1234 Added ...

# 필요한 경우 더 자세한 설명을 추가하세요
...

JIRA-1234 접두사는 단지 기본값이며 .gitjournal.toml 파일을 통해 구성할 수 있습니다. 제출된 커밋 메시지가 유효하지 않은 경우 다음과 같은 오류가 발생합니다:

[git-journal] [ERROR] Commit message invalid: GitJournal: Parser: Summary parsing: 'This commit message is also invalid'

모든 것이 순조롭게 진행되면 다음과 같이 보일 것입니다:

> git commit -m "Added my_file"
[git-journal] [OKAY] Commit message prepared.
[git-journal] [OKAY] Commit message valid.
...

만약 기본 템플릿이 구성되어 있다면, _git-journal_은 커밋 메시지 태그와 사용 가능한 템플릿의 태그를 함께 확인합니다. 따라서 커밋 메시지에 포함된 태그 중 하나라도 정의된 템플릿 내에 존재하지 않으면 오류가 발생할 것입니다:

[git-journal] [WARN] These tags are not part of the default template: 'tag1'.
[git-journal] [ERROR] Commit message invalid: GitJournal: Verify: Not all tags exists in the default template.

이것은 자세히 말해 _git-journal_이 사용자가 커밋을 수행하는 동안 두 개의 게이트(준비 및 검증)를 구축한다는 의미입니다. 이 그래픽은 _git-journal_이 로컬 git 저장소에 영향을 미치는 지점을 요약합니다:
<img src="https://raw.githubusercontent.com/saschagrunert/git-journal/HEAD/.github/flow.png" width="100%">

git-journal: Git 커밋 메시지 및 변경 로그 생성 프레임워크

요약

핵심 포인트