Skip to main content

​
Template Overview

git-cliff uses Tera as its template engine to generate changelogs. Tera is a powerful template language based on Jinja2 and Django templates, allowing you to create highly customizable changelog formats.

​
What is Tera Templating?

Tera is a template engine that processes text with embedded expressions and control structures. In git-cliff, templates define how your changelog looks by transforming Git commit data into formatted output. Key features:
  • Variable interpolation - Insert dynamic data like commit messages, authors, and dates
  • Control flow - Use conditionals and loops to format output based on data
  • Filters - Transform data with built-in and custom filters
  • Macros - Create reusable template components

​
How Templates Work in git-cliff

git-cliff processes your Git history and provides a context (commit data, release information, etc.) to your templates. The templates transform this context into your final changelog. The basic flow:
  1. Git data extraction - git-cliff parses commits, tags, and repository metadata
  2. Context building - Data is organized into a structured format (releases, commits, groups)
  3. Template rendering - Tera processes your templates with the context
  4. Changelog output - Final formatted changelog is generated

​
Template Sections

A git-cliff configuration defines three main template sections: Rendered once at the beginning of the changelog. Perfect for titles, descriptions, and introduction text. 
[changelog]
header = """
# Changelog

All notable changes to this project will be documented in this file.
"""
Output: 
# Changelog

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

​
Body

Rendered for each release in your changelog. This is where you iterate over commits, groups, and format individual entries. 
body = """
{% if version %}
    ## [{{ version }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}
    ## [Unreleased]
{% endif %}
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}
        - {{ commit.message }}
    {% endfor %}
{% endfor %}
"""
Output: 
## [1.0.0] - 2024-03-15

### Features
- Add user authentication
- Implement API endpoints

### Bug Fixes
- Fix login redirect issue
Rendered once at the end of the changelog. Useful for comparison links, metadata, or signatures. 
footer = """
{% for release in releases %}
    {% if release.version %}
        [{{ release.version }}]: https://github.com/owner/repo/compare/{{ release.previous.version }}..{{ release.version }}
    {% endif %}
{% endfor %}

<!-- generated by git-cliff -->
"""
Output: 
[1.0.0]: https://github.com/owner/repo/compare/v0.9.0..v1.0.0
[0.9.0]: https://github.com/owner/repo/compare/v0.8.0..v0.9.0

<!-- generated by git-cliff -->

​
Template Configuration

Templates are defined in your cliff.toml configuration file: 
[changelog]
header = """Your header template"""
body = """Your body template"""
footer = """Your footer template"""
trim = true  # Remove leading/trailing whitespace

​
Next Steps

Now that you understand the basics, explore:
  • Syntax - Learn Tera syntax and custom filters
  • Context - Understand available template variables
  • Examples - See real-world template configurations

Build docs developers (and LLMs) love

Get started for freeTalk to us