CHANGELOG generator implemented in Go (Golang). Anytime, anywhere, Write your CHANGELOG.

• Features
• How it works
• Getting Started
  • Installation
  • Test Installation
  • Quick Start
• CLI Usage
  • tag query
• Configuration
• Templates
• Supported Styles
• FAQ
• TODO
• Thanks
• Contributing
  • Development
  • Feedback
• CHANGELOG
• Related Projects
• License

• ♻️ High portability
  • It works with single binary. Therefore, any project (environment) can be used.
• 🔰 Simple usability
  • The CLI usage is very simple and has low learning costs.
  • For example, the simplest command is $ git-changelog.
• 🚀 High flexibility
  • Commit message format and ...
  • CHANGELOG's style (Template) and ...
  • etc ...

git-changelog internally uses the git command to get data to include in the CHANGELOG. The basic steps are as follows.

1. Get all the tags.
2. Get the commits contained between tagA and tagB.
3. Execute with all tags corresponding to tag query that were specified in Step 1 and 2.

We will start with installation and introduce the steps up to the automatic generation of the configuration file and template.

$ go install github.com/rivy-go/git-changelog/cmd/git-changelog@latest

$ git clone github.com/rivy-go/git-changelog
$ cd git-changelog
$ go install ./cmd/git-changelog

If you are using another platform, you can download a binary from the releases page and place it in a directory in your $PATH.

You can check with the following command whether the git-changelog command was included in a directory that is in your $PATH.

$ git-changelog --version
# outputs the git-changelog version

git-changelog requires configuration files and templates to generate a CHANGELOG.

However, it is a waste of time to create configuration files and templates from scratch.

Therefore we recommend using the --init option which will create them interactively 👍

$ git-changelog --init

You are now ready for configuration files and templates!

Let's immediately generate a CHANGELOG of your project. By doing the following simple command, Markdown for your CHANGELOG is displayed on stdout.

$ git-changelog

Use -o (--output) option if you want to output to a file instead of stdout.

$ git-changelog -o CHANGELOG.md

You now know basic usage of git-changelog!

In order to make a better CHANGELOG, please refer to the following document and customize it.

$ git-changelog --help

USAGE:
  git-changelog [options] <tag query>

    There are the following specification methods for <tag query>.

    1. <old>..<new> - Commit contained in <old> tags from <new>.
    2. <name>..     - Commit from the <name> to the latest tag.
    3. ..<name>     - Commit from the oldest tag to <name>.
    4. <name>       - Commit contained in <name>.

OPTIONS:
  --init                                generate the git-changelog configuration file in interactive
  --config value, -c value              specifies a different configuration file to pick up (default: ".changelog/config.yml")
  --output value, -o value              output path and filename for the changelog; if not specified, output to stdout
  --next-tag value                      treat unreleased commits as specified tags (EXPERIMENTAL)
  --silent                              disable stdout output
  --no-color                            disable color output [$NO_COLOR]
  --no-emoji                            disable emoji output [$NO_EMOJI]
  --no-case                             disable case sensitive filters
  --tag-filter-pattern value, -p value  regular expression of tag filter; if specified, only matched tags will be picked
  --help, -h                            show help
  --version, -v                         print the version

EXAMPLE:

  $ git-changelog

    If <tag query> is not specified, it corresponds to all tags.
    This is the simplest example.

  $ git-changelog 1.0.0..2.0.0

    The above is a command to generate CHANGELOG including commit of 1.0.0 to 2.0.0.

  $ git-changelog 1.0.0

    The above is a command to generate CHANGELOG including commit of only 1.0.0.

  $ git-changelog $(git describe --tags $(git rev-list --tags --max-count=1))

    The above is a command to generate CHANGELOG with the commit included in the latest tag.

  $ git-changelog --output CHANGELOG.md

    The above is a command to output to CHANGELOG.md instead of standard output.

  $ git-changelog --config custom/dir/config.yml

    The above is a command that uses a configuration file placed other than ".changelog/config.yml".

You can specify which commits to include in the generation of CHANGELOG using <tag query>.

The table below shows Query patterns and summaries, and Query examples.

The git-changelog configuration is a yaml file. The default location is .changelog/config.yml.

Below is a complete list that you can use with git-changelog.

bin: git
style: ""
template: CHANGELOG.tpl.md
info:
  title: CHANGELOG
  repository_url: https://github.com/rivy-go/git-changelog

options:
  commits:
    filters:
      Type:
        - feat
    sort_by: Scope

  commit_groups:
    group_by: Type
    sort_by: Title
    title_maps:
      feat: Features

  header:
    pattern: "<regexp>"
    pattern_maps:
      - PropName

  issues:
    prefix:
      - #

  refs:
    actions:
      - Closes
      - Fixes

  merges:
    pattern: "^Merge branch '(\\w+)'$"
    pattern_maps:
      - Source

  reverts:
    pattern: "^Revert \"([\\s\\S]*)\"$"
    pattern_maps:
      - Header

  notes:
    keywords:
      - BREAKING CHANGE

Git execution command.

CHANGELOG style. Automatic linking of issues and notices, initial value setting such as merges etc. are done automatically.

Path for the template file. It is specified by a relative path from the setting file. Absolute paths are also ok.

Metadata for CHANGELOG. Depending on Style, it is sometimes used in processing, so it is recommended to specify it.

Options used to process commits.

Options concerning the acquisition and sort of commits.

Options for groups of commits.

This option is used for parsing the commit header.

This option is used to detect issues.

This option is for parsing references.

Options to detect and parse merge commits.

Options to detect and parse revert commits.

Options to detect notes contained in commit bodies.

The git-changelog template uses the text/template package. For basic usage please refer to the following.

text/template

If you are not satisfied with the prepared template please try customizing one.

The basic templates are as follows.

Example:

{{ if .Versions -}}
<a name="unreleased"></a>
## [Unreleased]

{{ if .Unreleased.CommitGroups -}}
{{ range .Unreleased.CommitGroups -}}
### {{ .Title }}
{{ range .Commits -}}
- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
{{ end }}
{{ end -}}
{{ end -}}
{{ end -}}

{{ range .Versions }}
<a name="{{ .Tag.Name }}"></a>
## {{ if .Tag.Previous }}[{{ .Tag.Name }}]{{ else }}{{ .Tag.Name }}{{ end }} - {{ datetime "2006-01-02" .Tag.Date }}
{{ range .CommitGroups -}}
### {{ .Title }}
{{ range .Commits -}}
- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
{{ end }}
{{ end -}}

{{- if .RevertCommits -}}
### Reverts
{{ range .RevertCommits -}}
- {{ .Revert.Header }}
{{ end }}
{{ end -}}

{{- if .MergeCommits -}}
### Pull Requests
{{ range .MergeCommits -}}
- {{ .Header }}
{{ end }}
{{ end -}}

{{- if .NoteGroups -}}
{{ range .NoteGroups -}}
### {{ .Title }}
{{ range .Notes }}
{{ .Body }}
{{ end }}
{{ end -}}
{{ end -}}
{{ end -}}

{{- if .Versions }}
[Unreleased]: {{ .Info.RepositoryURL }}/compare/{{ $latest := index .Versions 0 }}{{ $latest.Tag.Name }}...HEAD
{{ range .Versions -}}
{{ if .Tag.Previous -}}
[{{ .Tag.Name }}]: {{ $.Info.RepositoryURL }}/compare/{{ .Tag.Previous.Name }}...{{ .Tag.Name }}
{{ end -}}
{{ end -}}
{{ end -}}

See the godoc RenderData documentation for available variables.

📝 Even with styles that are not yet supported, it is possible to make ordinary CHANGELOG.

$ git-changelog --next-tag 2.0.0 -o CHANGELOG.md
$ git commit -am "release 2.0.0"
$ git tag 2.0.0

$ git-changelog --tag-filter-pattern '^v'

• Windows Support
• More styles (GitHub, GitLab, Bitbucket 🎉)
• Snippetization of configuration files (improvement of reusability)
• More test test test ... (and example)

git-changelog is inspired by conventional-changelog. Thank you!

We alway welcome your contributions 👏

1. Fork https://github.com/rivy-go/git-changelog 🎉
2. Create a feature branch ☕
3. Run test suite with the $ make test command and confirm that it passes ⚡
4. Commit your changes 📝
5. Rebase your local changes against the master branch 💡
6. Create new Pull Request 💌

Bugs, feature requests and comments are more than welcome in the issues.

I would like to make git-changelog a better tool. The goal is to be able to use in various projects.

Therefore, your feedback is very useful. I am very happy to tell you your opinions on Issues and PR ❤️

See CHANGELOG.md

• git-chglog/artwork - Assets for git-changelog from git-chglog.

MIT © tsuyoshiwada