git-journal 📖

Git 提交消息和变更日志生成框架

目录

• TL;DR
• 安装
• 用法
  • 默认输出
  • 模板输出
  • 提交消息准备和验证
• 当前功能
• 计划功能和改进
• 贡献

TL;DR

维护变更日志可能很耗时，尤其是当多个人在同一项目上工作时。如果你维护一个单独的文件，合并冲突和额外的发布工作一定会随之而来。

有时在解决合并冲突时，完整的条目会丢失，人们可能忘记提及某些内容，或者缺少问题和实际提交之间的链接。

如果我们可以使用 git 的提交历史来生成一个无需额外工作即可使用的美丽变更日志，那会非常好。

这就是 git-journal 发挥作用的地方。

为了确保这种自动生成，需要一个框架来编写更合理的提交消息。单个提交消息应包含项目的一个逻辑更改，并以标准化的方式进行描述。这会使得 git 历史更加清晰，并为贡献者提供更多有关实际更改的信息。

理论基础包括两个 RFC

• RFC0001 提交消息语法扩展
• RFC0002 输出模板引擎

安装

要使用 git-journal 作为 git 扩展，需要一个 Rust 安装，包括包管理器 cargo。不同的包管理器也会提供这些，例如在 Arch Linux 上的 Pacman

sudo pacman -S rust cargo

对于超级简单的安装，也可以使用 rustup。一旦安装了这两个依赖项，可以通过以下方式安装 git-journal

cargo install git-journal

在调整 $PATH 变量以在 ~/.cargo/bin 中搜索后，可以通过调用 git journal 来运行它。

用法

二进制文件 git-journal 依赖于 Rust 库 gitjournal，该库也可以独立于二进制应用程序使用来编写定制解决方案。以下解释将以 此存储库 为例。

默认输出

如果在存储库内部任何位置运行 git journal，输出将是一个基于您的存储库 git 日志的漂亮的 Markdown 格式变更日志。

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

# Unreleased (2016-09-18):
- [Added] file4 again
    This paragraph explains the change in detail
    - [Fixed] multiple issues
    - [Removed] not needed things
- [Removed] file4.txt
- [Added] file4.txt
- [Added] file1.txt again
- [Removed] file1.txt

Fixes:
#1, #2

# v2 (2016-09-12):
- [Added] file3.txt

所有提交按时间排序，这意味着最新元素位于顶部。提交信息的解析将根据 RFC0001 进行，该 RFC 描述了提交信息内的不同语法元素。如果存在，类别（如 [Added]、[Fixed]）会自动用方括号括起来。也可以在配置文件中定义自己的类别。日志会自动列出上次发布和未发布的条目。

提交信息的页脚（在 RFC0001 中描述）将自动累积并按其值排序后打印在变更日志列表之后。也可以跳过未发布的条目。

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

# v2 (2016-09-12):
- [Added] file3.txt

还可以使用特定格式的提交范围 REV..REV 或不同于 HEAD 的起始点来解析。

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

还可以使用 -a 打印所有版本（git 标签），通过 -n <COUNT> 打印过去 n 个版本。

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

# Unreleased (2016-09-18):
- [Added] file4 again
    This paragraph explains the change in detail
    - [Fixed] multiple issues
    - [Removed] not needed things
- [Removed] file4.txt
- [Added] file4.txt
- [Added] file1.txt again
- [Removed] file1.txt

# v2 (2016-09-12):
- [Added] file3.txt

# v1 (2016-09-12):
- [Added] file2.txt
- [Added] file1.txt

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

# v2 (2016-09-12):
- [Added] file3.txt

除了常用的详细日志外，还存在一个简短版本（-s），它只使用提交摘要。

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

# Unreleased (2016-09-18):
- [Added] file4 again
- [Removed] file4.txt
- [Added] file4.txt
- [Added] file1.txt again
- [Removed] file1.txt

# v2 (2016-09-12):
- [Added] file3.txt

# v1 (2016-09-12):
- [Added] file2.txt
- [Added] file1.txt

还可以将日志输出追加到文件中（-o），每个 git journal 调用将使用换行符（---）分隔。具有特定模式（如 rc）的 Git 标签将自动排除，这可以通过 -e 进行自定义。

有关更多信息，请参阅帮助 git journal -h。

模板输出

提交信息模板的设计在 RFC0002 中描述。从现在起，我们将使用此模板为测试存储库。

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

[[tag]]
tag = "tag1"
name = "Section 1"

[[tag]]
[[tag.subtag]]
tag = "tag2"
name = "Subsection 1"
footers = ["Fixes"]

要使用此类模板，请使用 -t 选项。

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

# Unreleased (2016-09-21):
## Default
- [Removed] file3.txt
- [Removed] file4.txt
- [Removed] file5.txt
- [Added] new .gitjournal
- [Improved] file5.txt
- [Fixed] this
- [Removed] that
- [Added] .gitjournal.toml file
- [Removed] not needed things
- [Removed] file4.txt
- [Added] file4.txt
- [Added] file1.txt again
- [Removed] file1.txt

## Section 1
- [Added] file4 again
- This paragraph explains the change in detail

### Subsection 1
- [Fixed] multiple issues

Fixes:
#1, #2, #1, #2, #3, #5, #6, #7

# v2 (2016-09-12):
## Default
- [Added] file3.txt

所有未标记的内容都将进入 default 部分。tag1 的名称将被映射到 Section 1，而 tag2 是 tag1 的子标签（见 markdown 标题）。这也意味着，由于模板引擎允许将提交拆分为多个部分，列表项现在可能没有分类。解析后的段落将被转换为单个列表项，以确保始终提供干净的 markdown。页脚被指定为一个字符串 toml 数组，将在日志的正确位置输出所选页脚键。请注意，页脚的累积与整个标签相关，而不仅仅是打印的章节。其他与默认输出相同的命令行选项也可用。

也可以为每个输出或每个标签添加自定义标题或页脚文本。有关更多信息，请阅读 RFC0002。

提交消息准备和验证

要使用自动提交消息准备和验证，必须在每个本地存储库上执行 git journal 设置。

> git journal setup
[git-journal] [OKAY] Defaults written to '.gitjournal.toml' file.
[git-journal] [OKAY] Git hook installed to '.git/hooks/commit-msg'.
[git-journal] [OKAY] Git hook installed to '.git/hooks/prepare-commit-msg'.
[git-journal] [OKAY] Installed bash completions to the path.
[git-journal] [OKAY] Installed fish completions to the path.
[git-journal] [OKAY] Installed zsh completions to the path.

如果已存在这些钩子 git-journal 将尝试追加所需的命令，之后需要手动验证。为 bash 和 fish 生成的命令行补全需要放在您 shell 的正确目录中。默认配置文件是一个 toml 文件，它表示 此结构。也可以在这里找到带有注释的默认配置 此处。

如果设置已完成，git-journal 将验证您插入的提交消息以及进行提交消息准备。例如，如果我们现在试图提交一些无法解析的内容

> touch my_file
> git add my_file
> git commit -m "This commit contains no cactegory"
[git-journal] [ERROR] Commit message preparation failed: GitJournal: Parser: Summary parsing: 'This commit contains no cactegory'

由于我们使用了 -m 标志，用户无法再编辑消息，并且 git-journal 将拒绝它。如果我们使用不带 -m 的常规 git commit 提交消息编辑器，我们将获得默认提交消息模板

JIRA-1234 Added ...

# Add a more detailed description if needed

# - Added ...
# - Changed ...
# - Fixed ...
# - Improved ...
# - Removed ...

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.
[master 1b1fcad] Added my_file
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 my_file

如果已配置默认模板，则 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 仓库中产生影响的地方：

当前功能

• 通用
  • 在设置期间为 bash、fish 和 zsh shell 生成补全。
  • 对提交准备、验证和输出支持自定义类别（categories）。
  • 自动支持多线程解析。
• 日记生成和输出
  • 如果指定了 Git 仓库的子路径，则自动进行升级级仓库搜索。
  • 自定义提交范围或不同的 Git 提交起始点进行解析。
  • 在当前工作目录以外的指定路径中运行（-p）。
  • 解析并打印完整的历史记录（-a）或最近的 n 个发布版本（-n）。
  • 根据提交消息摘要打印提交历史的简短版本（-s）。
  • 将解析后的日志以有效的 Markdown 格式输出到命令行或文件（-o）。
  • 自定义 Git 标签排除模式，例如 rc 标签（-e）。
  • 启用/禁用调试消息输出（enable_debug）。
  • 通过命令行启用/禁用彩色输出（colored_output）。
  • 自动在方括号中包裹提交消息类别。
  • 支持模板，包括标签和名称映射（default_template）。
  • 支持累积页脚数据（也用于模板引擎）。
  • 默认输出和基于模板的输出的不同排序方法（sort_by），包括 "date" 和 "name"）。
  • 支持模板中包含多个或单个输出的自定义页眉和页脚字段。
  • 根据解析结果生成默认模板（-g）。
  • 在标准输出和模板输出中为提交生成提交哈希链接（show_commit_hash）。
  • 支持自定义类别分隔符（category_delimiters）。
• 准备和验证提交消息。
  • 在本地仓库内自动安装 Git 钩子。
  • 在设置过程中生成默认配置文件。
  • 基于实现的解析器进行提交消息验证。
  • 使用自定义提交前缀（template_prefix）准备消息。
  • 区分修正提交和新提交。
  • 在提交消息验证中使用默认模板中的标签。

计划功能和改进

• 目前还没有计划添加更多功能。

贡献

你想为此项目做出贡献？哇，太感谢了！所以请只分叉它并发送我一个拉取请求。