Stop Letting Changelog Writing Drain Your Time
Imagine this: it’s 5 PM on a Friday, and your boss is pushing for an urgent hotfix release. Instead of heading home early, you’re stuck digging through git log, filtering out 50 messy commits to write a CHANGELOG.md file. Just the copy-pasting and formatting fixes alone are enough to waste at least 30 precious minutes.
I used to be stuck in that loop while working on an outsourcing project with over 20 developers. At the time, the changelog was a total mess: incorrect dates, missing features, and inconsistent formatting. After trying several tools, I chose git-cliff. It’s a toolset written in Rust, offering blazing-fast processing and nearly limitless customization.
If you want a professional release process like major open-source libraries, this article is the key for you.
Why git-cliff Outshines the Competition
git-cliff does more than just list commits. It analyzes Git history and renders data through professional templates. Compared to standard-version (now poorly maintained) or conventional-changelog, this tool offers several superior advantages.
- Incredible Speed: For a repo with 10,000 commits, it generates a changelog in less than a second.
- Single Binary: No need to install Node.js, Python, or Ruby. A single executable file is all you need.
- Flexible Templates: Uses the Tera engine (similar to Jinja2), allowing you to create Markdown, HTML, or even JSON files.
- Diverse Support: Works seamlessly with Conventional Commits, emojis, and complex custom rules defined by you.
Step 1: Lightning-Fast Installation
You can install git-cliff on all popular operating systems today.
# For macOS users
brew install git-cliff
# If Rust is already installed
cargo install git-cliff
# Windows using Scoop
scoop install git-cliffOnce finished, type git-cliff --version. If the version number appears, you’re ready for the next step.
Step 2: Configuring the “Brain” – cliff.toml
To start, navigate to your project directory and initialize the configuration file:
git-cliff --initThis command creates a cliff.toml file. This is where you teach the tool how to interpret your commits. Pay attention to the commit_parsers section, where we use Regex for categorization:
commit_parsers = [
{ message = "^feat", group = "🚀 New Features" },
{ message = "^fix", group = "🐛 Bug Fixes" },
{ message = "^perf", group = "⚡ Performance Optimizations" },
{ message = "^doc", group = "📚 Documentation" },
{ message = "^chore\\(release\\): prepare for", skip = true },
{ body = ".*security", group = "🛡️ Security" },
]This setup is very intuitive. As long as a commit message starts with “feat”, it will automatically fall under the “New Features” section in the final changelog.
Step 3: Standardizing Commit Messages
The tool is only as smart as its input data. You should adopt Conventional Commits. The ideal structure is: type(scope): description.
In my team’s experience, people often forgot at first. The solution was to install lefthook or husky to block commits like “fix bug” or “update code”. When Git history is clean, your changelog will automatically look great without manual editing.
Step 4: Publishing Your First Changelog
Now it’s time to enjoy the results. Run the following command to generate the file:
git-cliff -o CHANGELOG.mdIf you only want to extract changes from the latest tag (useful for writing GitHub Release Notes), use the --latest flag:
git-cliff --latest --strip headerThe output will be a highly professional list of changes, including shortened commit ID links (e.g., a1b2c3d) for easy reference.
Step 5: Full Automation with CI/CD
Don’t stop at manual commands. Integrate git-cliff into your CI/CD pipeline. In a real-world project I deployed, whenever someone pushes a new tag (e.g., v1.2.0), GitHub Actions triggers automatically.
The system runs git-cliff, updates the CHANGELOG.md file, and then automatically creates a GitHub Release with the rendered content. This entire process takes less than 10 seconds and requires zero human intervention. You can spend that time making a cup of coffee instead of typing Markdown.
Conclusion
Automating changelogs is a small step that brings major professionalism to your project. git-cliff not only frees up your hands but also fosters a habit of responsible commit writing for the whole team. It only takes 15 minutes to set up, but you’ll save dozens of hours every year. Give it a try on your project today!
