Back to Details

changelog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Changelog Generator

变更日志生成器

Generate changelogs from git commits and manage release notes.
从Git提交记录生成变更日志并管理发布说明。

Prerequisites

前置条件

bash
undefined
bash
undefined

Git

Git

git --version
git --version

GitHub CLI (for release notes)

GitHub CLI（用于发布说明）

brew install gh gh auth login
brew install gh gh auth login

Gemini (for AI summaries)

Gemini（用于AI摘要）

pip install google-generativeai export GEMINI_API_KEY=your_api_key
undefined
pip install google-generativeai export GEMINI_API_KEY=your_api_key
undefined

CLI Reference

CLI参考

Git History Commands

Git历史记录命令

bash
undefined
bash
undefined

Recent commits

最近的提交

git log --oneline -20
git log --oneline -20

Since last tag

自上一个标签以来的提交

git log $(git describe --tags --abbrev=0)..HEAD --oneline
git log $(git describe --tags --abbrev=0)..HEAD --oneline

Between tags

两个标签之间的提交

git log v1.0.0..v1.1.0 --oneline
git log v1.0.0..v1.1.0 --oneline

With full messages

包含完整提交信息

git log v1.0.0..v1.1.0 --pretty=format:"%h %s%n%b"
git log v1.0.0..v1.1.0 --pretty=format:"%h %s%n%b"

By author

按作者筛选

git log --author="name" --oneline -10
git log --author="name" --oneline -10

With dates

包含日期

git log --format="%h %ad %s" --date=short
undefined
git log --format="%h %ad %s" --date=short
undefined

Finding Tags

查找标签

bash
undefined
bash
undefined

List all tags

列出所有标签

git tag
git tag

List tags with dates

列出带日期的标签

git tag --sort=-creatordate --format='%(refname:short) %(creatordate:short)'
git tag --sort=-creatordate --format='%(refname:short) %(creatordate:short)'

Latest tag

最新标签

git describe --tags --abbrev=0
git describe --tags --abbrev=0

Tags matching pattern

匹配指定模式的标签

git tag -l "v1.*"
undefined
git tag -l "v1.*"
undefined

Generating Changelogs

生成变更日志

From Git Log

从Git日志生成

bash
undefined
bash
undefined

Simple changelog since tag

自指定标签以来的简易变更日志

git log v1.0.0..HEAD --oneline > CHANGELOG_DRAFT.md
git log v1.0.0..HEAD --oneline > CHANGELOG_DRAFT.md

Categorized by conventional commits

按规范提交类型分类

git log v1.0.0..HEAD --oneline | grep "^[a-f0-9]* feat:" git log v1.0.0..HEAD --oneline | grep "^[a-f0-9]* fix:" git log v1.0.0..HEAD --oneline | grep "^[a-f0-9]* chore:"
undefined
git log v1.0.0..HEAD --oneline | grep "^[a-f0-9]* feat:" git log v1.0.0..HEAD --oneline | grep "^[a-f0-9]* fix:" git log v1.0.0..HEAD --oneline | grep "^[a-f0-9]* chore:"
undefined

Using GitHub CLI

使用GitHub CLI生成

bash
undefined
bash
undefined

Generate release notes

生成发布说明

gh release create v1.1.0 --generate-notes
gh release create v1.1.0 --generate-notes

View release notes draft

查看发布说明草稿

gh release create v1.1.0 --generate-notes --notes-start-tag v1.0.0 --dry-run
gh release create v1.1.0 --generate-notes --notes-start-tag v1.0.0 --dry-run

From existing release

从现有发布查看说明

gh release view v1.0.0
undefined
gh release view v1.0.0
undefined

AI-Generated Changelog

AI生成的变更日志

bash
undefined
bash
undefined

Get commits since last tag

获取自上一个标签以来的提交记录

COMMITS=$(git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%s%n%b")
COMMITS=$(git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%s%n%b")

Generate polished changelog

生成优化后的变更日志

gemini -m pro -o text -e "" "Generate a changelog from these commits:
$COMMITS
Format as:
gemini -m pro -o text -e "" "Generate a changelog from these commits:
$COMMITS
Format as:

[Version] - Date

[Version] - Date

Added

Added

  • New features
  • New features

Changed

Changed

  • Modifications
  • Modifications

Fixed

Fixed

  • Bug fixes
  • Bug fixes

Breaking Changes

Breaking Changes

  • Any breaking changes
Write user-friendly descriptions, not raw commit messages."
undefined
  • Any breaking changes
Write user-friendly descriptions, not raw commit messages."
undefined

Workflow Patterns

工作流模式

Release Preparation

发布准备

bash
#!/bin/bash
VERSION=$1
LAST_TAG=$(git describe --tags --abbrev=0)

echo "# Release $VERSION"
echo ""
echo "Changes since $LAST_TAG:"
echo ""
bash
#!/bin/bash
VERSION=$1
LAST_TAG=$(git describe --tags --abbrev=0)

echo "# Release $VERSION"
echo ""
echo "Changes since $LAST_TAG:"
echo ""

Categorize commits

分类提交记录

echo "## Features" git log $LAST_TAG..HEAD --oneline | grep -i "feat:" | sed 's/^[a-f0-9]* feat: /- /'
echo "" echo "## Fixes" git log $LAST_TAG..HEAD --oneline | grep -i "fix:" | sed 's/^[a-f0-9]* fix: /- /'
echo "" echo "## Other" git log $LAST_TAG..HEAD --oneline | grep -v -i "feat:|fix:" | sed 's/^[a-f0-9]* /- /'
undefined
echo "## Features" git log $LAST_TAG..HEAD --oneline | grep -i "feat:" | sed 's/^[a-f0-9]* feat: /- /'
echo "" echo "## Fixes" git log $LAST_TAG..HEAD --oneline | grep -i "fix:" | sed 's/^[a-f0-9]* fix: /- /'
echo "" echo "## Other" git log $LAST_TAG..HEAD --oneline | grep -v -i "feat:|fix:" | sed 's/^[a-f0-9]* /- /'
undefined

Breaking Changes Detection

破坏性变更检测

bash
undefined
bash
undefined

Find breaking changes in commit messages

在提交信息中查找破坏性变更

git log v1.0.0..HEAD --oneline | grep -i "breaking|BREAKING"
git log v1.0.0..HEAD --oneline | grep -i "breaking|BREAKING"

Find in commit bodies

在提交正文中查找破坏性变更

git log v1.0.0..HEAD --grep="BREAKING" --pretty=format:"%h %s"
undefined
git log v1.0.0..HEAD --grep="BREAKING" --pretty=format:"%h %s"
undefined

Maintaining CHANGELOG.md

维护CHANGELOG.md

Standard format (Keep a Changelog):
markdown
undefined
标准格式（遵循Keep a Changelog规范）：
markdown
undefined

Changelog

Changelog

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

[Unreleased]

[Unreleased]

Added

Added

  • New feature X
  • New feature X

Changed

Changed

  • Updated Y
  • Updated Y

Fixed

Fixed

  • Bug in Z
  • Bug in Z

[1.1.0] - 2024-01-15

[1.1.0] - 2024-01-15

Added

Added

  • Feature A
  • Feature B
  • Feature A
  • Feature B

Fixed

Fixed

  • Issue #123
undefined
  • Issue #123
undefined

Update Script

更新脚本

bash
#!/bin/bash
VERSION=$1
DATE=$(date +%Y-%m-%d)
bash
#!/bin/bash
VERSION=$1
DATE=$(date +%Y-%m-%d)

Generate new section

生成新的版本章节

NEW_SECTION="## [$VERSION] - $DATE
$(git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"- %s") "
NEW_SECTION="## [$VERSION] - $DATE
$(git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"- %s") "

Prepend to changelog (after header)

将新章节插入到变更日志头部（标题之后）

head -7 CHANGELOG.md > CHANGELOG_NEW.md echo "" >> CHANGELOG_NEW.md echo "$NEW_SECTION" >> CHANGELOG_NEW.md echo "" >> CHANGELOG_NEW.md tail -n +8 CHANGELOG.md >> CHANGELOG_NEW.md mv CHANGELOG_NEW.md CHANGELOG.md
undefined
head -7 CHANGELOG.md > CHANGELOG_NEW.md echo "" >> CHANGELOG_NEW.md echo "$NEW_SECTION" >> CHANGELOG_NEW.md echo "" >> CHANGELOG_NEW.md tail -n +8 CHANGELOG.md >> CHANGELOG_NEW.md mv CHANGELOG_NEW.md CHANGELOG.md
undefined

Statistics

统计信息

bash
undefined
bash
undefined

Commits by author since tag

自指定标签以来按作者统计提交数

git shortlog -sn v1.0.0..HEAD
git shortlog -sn v1.0.0..HEAD

Files changed

变更的文件统计

git diff --stat v1.0.0..HEAD | tail -1
git diff --stat v1.0.0..HEAD | tail -1

Commits per day

每日提交数统计

git log --format="%ad" --date=short v1.0.0..HEAD | sort | uniq -c
git log --format="%ad" --date=short v1.0.0..HEAD | sort | uniq -c

Most changed files

变更最频繁的文件

git diff --stat v1.0.0..HEAD | sort -k3 -n -r | head -10
undefined
git diff --stat v1.0.0..HEAD | sort -k3 -n -r | head -10
undefined

GitHub Releases

GitHub 发布

bash
undefined
bash
undefined

Create release with notes

创建带说明的发布版本

gh release create v1.1.0 --title "v1.1.0" --notes-file RELEASE_NOTES.md
gh release create v1.1.0 --title "v1.1.0" --notes-file RELEASE_NOTES.md

Create from tag with auto-notes

从标签创建并自动生成说明

gh release create v1.1.0 --generate-notes
gh release create v1.1.0 --generate-notes

Edit existing release

编辑现有发布版本

gh release edit v1.1.0 --notes-file UPDATED_NOTES.md
gh release edit v1.1.0 --notes-file UPDATED_NOTES.md

List releases

列出所有发布版本

gh release list
gh release list

Download release assets

下载发布资产

gh release download v1.1.0
undefined
gh release download v1.1.0
undefined

Best Practices

最佳实践

  1. Use conventional commits - Enables automatic categorization
  2. Tag releases - Clean boundaries for changelogs
  3. Write for users - Translate technical to user impact
  4. Note breaking changes - Prominently marked
  5. Include issue references - Link to related issues
  6. Date your releases - Clear timeline
  7. Keep unreleased section - Track ongoing work
  1. 使用规范提交格式 - 支持自动分类提交记录
  2. 为发布打标签 - 为变更日志划分清晰的边界
  3. 面向用户编写 - 将技术内容转化为用户能理解的影响说明
  4. 标注破坏性变更 - 显著标记此类变更
  5. 包含问题引用 - 关联相关的问题
  6. 为发布添加日期 - 清晰展示时间线
  7. 保留未发布章节 - 跟踪正在进行的工作