Cocogitto

Appearance

Changelog template reference ​

For a detailed guide on how to write a template changelog refer to tera's documentation.

You can also take a look at the built-in templates in cocogitto repository.

Built-in macros ​

Cocogitto provides built-in Tera macros to help format changelog entries in your templates. All macros are available in a single macros.tera file located in src/conventional/changelog/template/macro/.

Available macro functions:

  • simple(commit) — minimal format with short hash
  • remote(commit) — format with links to commits and authors
  • fullhash(commit) — format with full commit hash

Import the macros in your template with:

tera
{% import "macros" as macros %}

Then use, for example:

tera
{{ macros::remote(commit=commit) }}
{{ macros::simple(commit=commit) }}
{{ macros::fullhash(commit=commit) }}

Context ​

Release ​

  • commits :

    • Type: Array<Commit>
    • Description: commits contained in the release
    • Nullable: false

  • version :

    • Type: GitRef
    • Description: tag name or/and git oid of the current release tip
    • Nullable: false

  • from

    • Type: GitRef
    • Description: tag name or/and git oid of the commit preceding the release
    • Nullable: false

  • date

    • Type: Date
    • Description: date of the release
    • Nullable: false

Commit ​

  • id:

    • Type: String, SHA-1
    • Description: commit SHA-1
    • Nullable: false

  • author:

    • Type: String
    • Description: the name of the commit author on the remote platform
    • Nullable: true

  • signature:

    • Type: String
    • Description: the git signature of the commit author
    • Nullable: false

  • type:

    • Type: String
    • Description: the conventional commit type of the commit
    • Nullable: false

  • date:

    • Type: Date
    • Description: the date of the commit
    • Nullable: false

  • scope:

    • Type: String
    • Description: the scope of the commit
    • Nullable: true

  • summary:

    • Type: String
    • Description: the conventional commit message summary
    • Nullable: false

  • body:

    • Type: String
    • Description: the conventional commit message body
    • Nullable: true

  • breaking_change:

    • Type: boolean
    • Description: is the commit marked as a breaking change
    • Nullable: false

  • footer:

    • Type: Array<Footer>
    • Description: the conventional commit footers
    • Nullable: false

GitRef ​

  • tag:

    • Type: String
    • Description: a SemVer tag name, with an optional tag_prefix. null if the version is pointing to unreleased changes.
    • Nullable: true

  • id:

    • Type: Sting, SHA-1
    • Description: the id of the latest commit in the release. This can be null only when using cog bump, because it generates a changelog before creating the target version.
    • Nullable: true

Footers can be either generic footers or GitHub-specific trailers. Cocogitto automatically recognizes and parses the following GitHub trailers:

  • footer:
    • Type: Object
    • Description: a generic conventional commit footer
    • Fields:
      • token (String): the footer token (e.g., "Reviewed-by", "Signed-off-by")
      • content (String): the footer content

GitHub Co-authored-by ​

Recognized from trailers like: Co-authored-by: Name <email@example.com>

  • github_co_authored_by:
    • Type: Object
    • Description: a GitHub co-author trailer
    • Fields:
      • user (String): the original name from the git trailer (e.g., "Paul Delafosse")
      • username (String, nullable): the username mapped from changelog authors configuration. If the user is found in the authors mapping, this contains the corresponding username (e.g., "oknozor"). Otherwise, it is null.

Usage in templates:

tera
{%- if footer.github_co_authored_by -%}
  {%- if footer.github_co_authored_by.username -%}
    , @{{ footer.github_co_authored_by.username }}
  {%- else -%}
    , {{ footer.github_co_authored_by.user }}
  {%- endif -%}
{%- endif -%}

GitHub Closes ​

Recognized from trailers like: Closes #123, Fixes #456, Resolves #789

  • github_closes:
    • Type: Object
    • Description: a GitHub issue/PR reference trailer
    • Fields:
      • gh_reference (String): the issue or PR number (e.g., "123")

Usage in templates:

tera
{%- if footer.github_closes -%}
  Closes #{{ footer.github_closes.gh_reference }}
{%- endif -%}

Remote ​

Filters ​

In addition to the tera built-in filters, you can use the following:

  • unscoped
    • Description: filter unscoped commits from releases commits. Example:
    • Example:
    tera
        {% for commit in commits | unscoped %}
        {% if commit.author %}
            {% set author = "@" ~ commit.author %}
        {% else %}
            {% set author = commit.signature %}
        {% endif %}
            - {{ commit.id }} - {{ commit.summary }} - {{ author }}
    {% endfor %}
    • group_by_type
      • Description: group commits by their conventional commit type and sort order
      • Example:
      tera
         {% for type_group in commits | group_by_type %}
       ### {{ type_group.0 | upper_first }}
       {% for commit in type_group.1 %}
           - {{ commit.summary }}
       {% endfor %}
   {% endfor %}
  • upper_first
    • Description: capitalize the first letter of a string
    • Example:
    tera
       {% for commit_by_type in commits | group_by_type %}
    #### {{ commit_by_type.0 | upper_first }}
   {% endfor %}