CHANGELOG generator implemented in Go (Golang).
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.chglog chore: Update CHANGELOG template format May 4, 2018
.github docs: Add contributing guide and Issues/PR templates Feb 20, 2018
cmd/git-chglog release: Release 0.7.1 Nov 10, 2018
docs/assets docs: Update `--init` gif animation Apr 14, 2018
scripts chore: Fix release flow (retry) Feb 28, 2018
testdata test: Change output test of chglog to keep-a-changelog May 5, 2018
vendor feat: Supports vim like `j/k` keybind with item selection of `--init` Feb 28, 2018
.appveyor.yml chore: Add AppVeyor config Feb 28, 2018
.editorconfig chore(editor): Add Editorconfig Feb 14, 2018
.gitignore chore: Add release process Feb 18, 2018
.travis.yml chore: Fix release flow (retry) Feb 28, 2018
CHANGELOG.md release: Release 0.7.1 Nov 10, 2018
CONTRIBUTING.md docs: Add contributing guide and Issues/PR templates Feb 20, 2018
Gopkg.lock feat: Supports vim like `j/k` keybind with item selection of `--init` Feb 28, 2018
Gopkg.toml feat: Supports vim like `j/k` keybind with item selection of `--init` Feb 28, 2018
LICENSE docs: Add license Feb 14, 2018
Makefile chore: Update `changelog` task in Makefile May 6, 2018
README.md docs: Fix typo Nov 9, 2018
chglog.go fix: Panic occured when exec --next-tag with HEAD with tag Nov 9, 2018
chglog_test.go feat: Add `--next-tag` flag (experimental) May 5, 2018
commit_extractor.go feat: Add MergeCommits and RevertCommits Feb 10, 2018
commit_extractor_test.go fix: Fix parsing of revert and body Feb 16, 2018
commit_filter.go feat: First implement Feb 10, 2018
commit_filter_test.go feat: First implement Feb 10, 2018
commit_parser.go fix: Fix parsing of revert and body Feb 16, 2018
commit_parser_test.go fix: Fix parsing of revert and body Feb 16, 2018
errors.go docs: Add godoc Feb 17, 2018
example_test.go docs: Add godoc Feb 17, 2018
fields.go fix: Remove accidentally added `Unreleased.Tag` May 5, 2018
mock_test.go feat: First implement Feb 10, 2018
processor.go feat: Add support for Bitbucket Apr 14, 2018
processor_test.go feat: Add support for Bitbucket Apr 14, 2018
tag_reader.go feat: Supports annotated git-tag and adds `Tag.Subject` field #3 Feb 25, 2018
tag_reader_test.go feat: Supports annotated git-tag and adds `Tag.Subject` field #3 Feb 25, 2018
tag_selector.go docs: Add godoc Feb 17, 2018
tag_selector_test.go feat: First implement Feb 10, 2018
utils.go docs: Add godoc Feb 17, 2018
utils_test.go feat: First implement Feb 10, 2018

README.md

git-chglog

git-chglog

godoc.org Travis AppVeyor Coverage Status MIT License

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

Table of Contents

Features

  • ♻️ 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-chglog.
  • 🚀 High flexibility
    • Commit message format and ...
    • CHANGELOG's style (Template) and ...
    • etc ...

How it works

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

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

Getting Started

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

Installation

Please install git-chglog in a way that matches your environment.

Homebrew (for macOS users)

$ brew tap git-chglog/git-chglog
$ brew install git-chglog

Go users

$ go get -u github.com/git-chglog/git-chglog/cmd/git-chglog

If you are in another platform, you can download binary from release page and place it in $PATH directory.

Test Installation

You can check with the following command whether the git-chglog command was included in a valid $PATH.

$ git-chglog --version
# output the git-chglog version

Quick Start

git-chglog requires configuration files and templates to generate CHANGELOG.
However, it is a waste of time to create configuration files and templates with scratch.

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

$ git-chglog --init

init option demo


You are now ready for configuration files and templates!

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

$ git-chglog

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

$ git-chglog -o CHANGELOG.md

This is how basic usage is over!
In order to make better CHANGELOG, please refer to the following document and customize it.

CLI Usage

$ git-chglog --help

USAGE:
  git-chglog [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-chglog configuration file in interactive
  --config value, -c value  specifies a different configuration file to pick up (default: ".chglog/config.yml")
  --output value, -o value  output path and filename for the changelogs. 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]
  --help, -h                show help
  --version, -v             print the version

EXAMPLE:

  $ git-chglog

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

  $ git-chglog 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-chglog 1.0.0

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

  $ git-chglog $(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-chglog --output CHANGELOG.md

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

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

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

tag query

You can specify a commit to include in the generation of CHANGELOG using <tag query>.
The table below shows Query patterns and summaries, and Query examples.

Query Description Example
<old>..<new> Commit contained in <new> tags from <old>. $ git-chglog 1.0.0..2.0.0
<name>.. Commit from the <name> to the latest tag. $ git-chglog 1.0.0..
..<name> Commit from the oldest tag to <name>. $ git-chglog ..2.0.0
<name> Commit contained in <name>. $ git-chglog 1.0.0

Configuration

The git-chglog configuration is write with the yaml file. Default location is .chglog/config.yml.

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

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

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

bin

Git execution command.

Required Type Default Description
N String "git" -

style

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

Required Type Default Description
N String "none" Should be "github" "gitlab" "bitbucket" "none"

template

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

Required Type Default Description
N String "CHANGELOG.tpl.md" -

info

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

Key Required Type Default Description
title N String "CHANGELOG" Title of CHANGELOG.
repository_url N String none URL of git repository.

options

Options used to process commits.

options.commits

Option concerning acquisition and sort of commit.

Key Required Type Default Description
filters N Map in List none Filter by using Commit properties and values. Filtering is not done by specifying an empty value.
sort_by N String "Scope" Property name to use for sorting Commit. See Commit.

options.commit_groups

Option for groups of commits.

Key Required Type Default Description
group_by N String "Type" Property name of Commit to be grouped into CommitGroup. See CommitGroup.
sort_by N String "Title" Property name to use for sorting CommitGroup. See CommitGroup.
title_maps N Map in List none Map for CommitGroup title conversion.

options.header

This option is used for parsing the commit header.

Key Required Type Default Description
pattern Y String none A regular expression to use for parsing the commit header.
pattern_maps Y List none A rule for mapping the result of HeaderPattern to the property of Commit. See Commit.

options.issues

This option is used to detect issues.

Key Required Type Default Description
prefix N List none Prefix used for issues. (e.g. #, #gh-)

options.refs

This option is for parsing references.

Key Required Type Default Description
actions N List none Word list of Ref.Action. See Ref.

options.merges

Option to detect and parse merge commit.

Key Required Type Default Description
pattern N String none Similar to options.header.pattern.
pattern_maps N List none Similar to options.header.pattern_maps.

options.reverts

Option to detect and parse revert commit.

Key Required Type Default Description
pattern N String none Similar to options.header.pattern.
pattern_maps N List none Similar to options.header.pattern_maps.

options.notes

Option to detect notes contained in commit body.

Key Required Type Default Description
keywords N List none Keyword list to find Note. A semicolon is a separator, like <keyword>: (e.g. BREAKING CHANGE).

Templates

The git-chglog 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.


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 godoc RenderData for available variables.

Supported Styles

Name Status Features
GitHub Mentions automatic link. Automatic link to references.
GitLab Mentions automatic link. Automatic link to references.
Bitbucket Mentions automatic link. Automatic link to references.

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

FAQ

Why do not you output files by default? This is not for the purpose of completely automating the generation of CHANGELOG, because it is only for the purpose of assisting generation.

It is ideal to describe everything included in CHANGELOG in commit. But actually it is very difficult to do it perfectly.

There are times when you need your hands to write a great CHANGELOG.
By displaying it on the standard output, it makes it easy to change the contents.

Can I commit CHANGELOG changes before creating tags?

Yes, it can be solved by using the --next-tag flag.

For example, let's say you want to upgrade your project to 2.0.0.
You can create CHANGELOG containing 2.0.0 as follows.

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

The point to notice is that before actually creating a tag with git, it is conveying the next version with --next-tag 👍

This is a step that is necessary for project operation in many cases.

TODO

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

Thanks

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

Contributing

We are always welcoming your contribution 👏

Development

  1. Fork (https://github.com/git-chglog/git-chglog) 🎉
  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.

Feedback

I would like to make git-chglog 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 ❤️

CHANGELOG

See CHANGELOG.md

Related Projects

License

MIT © tsuyoshiwada