Finch 🐦

Finch 是一款可配置的工具，旨在使跟踪产品的历史和演变变得简单易行，并实现自动化。它将项目的 Git 提交消息转换为格式良好的版本更新日志，这些日志根据您团队的特定需求量身定制。

• 为什么叫“Finch”？
• 理念
• 安装
• 使用方法
• 配置
  • 配置文件位置
  • 配置格式
  • 配置合并和搜索行为
• 贡献
• 示例输出
• 许可证

名称 Finch 源于应用程序本身的目的——跟踪产品的演变。由于演变是 Finch 的核心，因此以进化论的里程碑——达尔文的雀类——来命名它似乎很合适。

我们坚信良好更新日志的重要性。我们也知道更新日志有时最终会 A) 被忽视/不及时，以及 B) 在样式/方法方面难以维护，因为不同的团队成员在管理给定的版本。正是这些问题，以及为我们的团队自动化这些问题的愿望，促成了 Finch 的创建。我们认为，格式良好且有意的 Git 提交消息可以作为驱动自动化和无忧更新日志系统的底层数据。通过使用一些相对较小的提交消息规范——并根据您的团队想要使用的任何约定——Finch 可以帮助您自动化内部和面向外部的更新日志，根据需要提供尽可能多的细节或润色。

Finch 可以通过多种安装方法获得

1. Homebrew
   1. 添加 tap brew tap namolnad/formulae
   2. 安装 finch brew install --formula finch
2. 可安装包
   1. 下载并运行最新的发布的 Finch.pkg 文件，并按照屏幕上的说明进行操作
3. Mint
   1. 安装 mint brew install mint
   2. 安装 finch mint install namolnad/finch
4. 从源代码
   1. 如果您想从源代码构建，您可以克隆此存储库并从克隆目录的根目录运行 make install。这将安装并链接 Finch 二进制文件，并将模板配置文件放置在以下位置 $HOME/.finch/template.config.yml

Finch 需要一个提交消息 [标签] 提交消息 约定（我们使用方括号包围我们的标签），它利用该约定来确定给定提交应放置的适当部分。

提交消息示例

[cleanup] 移除旧的 obj-c 代码
[feature][app-store] 添加瞬间移动功能

要生成更新日志，您必须运行 compare 命令。如果 compare 没有传递任何参数，Finch 将首先查找最近的两个语义版本分支，然后查找最近的两个语义版本 git 标签。您还可以使用 --versions 选项显式传递两个版本，并传递 2 个版本参数（分支或标签）。其他接受的参数有

1. 隐藏版本标题的功能 (--no-show-version)
2. 发布管理器 (--release-manager)
3. 项目目录 (--project-dir) 如果 Finch 不是从项目目录调用的
4. 手动 git 日志 (--git-log)。必须以以下格式接收：git log --left-right --graph --cherry-pick --oneline --format=format:'&&&%H&&& - @@@%s@@@###%ae###' --date=short OLD_VERSION...NEW_VERSION
5. 在自动生成更新日志之前不获取 origin (--no-fetch)。
6. 要包含在版本标题中的构建号字符串 (--build-number)。优先于配置中的构建号命令。示例输出：6.19.1 (6258)

在许多情况下，当您的 shell 启动文件被加载时，创建新的 shell 函数可能是最容易的，例如以下示例

project-changelog() {
  finch compare --project-dir="$HOME/Code/YourProject" --release-manager=$(git config --get user.email) $@
}

# Used in the following manner:
# project-changelog --versions '6.12.1 6.13.0'

在此配置模板中查看 Finch 的可配置组件。

Finch 搜索包含 config.yml 文件的隐藏 .finch 目录。.finch 目录可以放置在 home、current 或 project 目录中。或者，如果您通过 --config 参数或环境变量提供自定义路径，Finch 将在包含的路径中查找有效的配置文件。Finch 还允许使用私有配置文件，以防您希望将部分配置保留在版本控制系统之外。请参阅下面的搜索行为。

config.yml 应该是有效的 YAML 文件，格式与此配置模板相同。（注意：并非所有键都需要包含在内，因为 Finch 在需要时使用默认值。您可以通过运行 finch config show-example 随时查看示例配置。

Finch 将从默认配置开始，并将搜索多个路径以查找有效的配置文件来覆盖现有值。包含在后续配置文件中的任何非空元素都将覆盖其现有对应项。空或省略的配置文件组件将被忽略。

配置搜索路径将按以下方式执行

• --config 参数
• FINCH_CONFIG 环境变量 或
• 内置默认值被瀑布式技术覆盖（首先在每个目录中搜索 config.yml，然后搜索 config.private.yml）
  • Home 目录
  • Finch 的当前目录
  • --project-dir 参数

注意

• 部分应按您希望它们在输出中显示的顺序列出
• 如果包含的部分具有重复的标签，则具有给定标签的最后一个部分获胜。每个匹配的提交都将放置在其所属的部分中。
• 可以包含一个通配符部分。通过在部分的标签配置中包含 * 来实现。
• 提交将仅出现在一个部分中。首先搜索与第一个提交标签匹配的部分，然后搜索第二个，依此类推。
• 可以通过在部分配置中传递 excluded: true 来排除部分

请参阅 CONTRIBUTING.md

# 6.13.0 (3242)

### Release Manager

 - @User.2

### Features
 - |wip||custom-lib| initial work on incorporating 1.0.0 — [PR #912](https://github.com/your_repo/pull/912) — @User.3
 - |checkout| improved tracking + logging — [PR #958](https://github.com/your_repo/pull/958) - @User.2

### Bug Fixes
 - |cleanup| remove unused obj-c experiment, fix some warnings — [PR #949](https://github.com/your_repo/pull/949) — @User.1
 - |cleanup| remove unused Lib — [PR #947](https://github.com/your_repo/pull/947) - @User.3

### Platform Improvements
 - |tooling| re-enable new build system — [PR #959](https://github.com/your_repo/pull/959) — @User.1
 - |platform| move to incremental compilation and ensure we're using same swift version across the board — [PR #966](https://github.com/your_repo/pull/966) — @User.2

### Timeline
 - Begin development:
 - Feature cut-off / Start of bake / dogfooding:
 - Submission:
 - Release (expected):
 - Release (actual):

Finch 在 MIT 许可证下发布