Repository files navigation

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

• git-chglog
  • Table of Contents
  • Features
  • How it works
  • Getting Started
    • Installation
      • Homebrew (for macOS users)
      • Scoop (for Windows users)
      • asdf
      • Go users
    • Docker
    • Test Installation
    • Quick Start
  • CLI Usage
    • tag query
  • Configuration
    • bin
    • style
    • template
    • info
    • options
      • options.sort
      • options.commits
      • options.commit_groups
      • options.header
      • options.issues
      • options.refs
      • options.merges
      • options.reverts
      • options.notes
  • Templates
  • Supported Styles
  • Jira Integration
    • 1. Change the header parse pattern to recognize Jira issue id in the configure file
    • 2. Add Jira configuration to the configure file
    • 3. Update the template to show Jira data
  • FAQ
  • TODO
  • Thanks
  • Contributing
  • Development
  • Release Process
  • 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-chglog.
• 🚀 High flexibility
  • Commit message format and ...
  • CHANGELOG's style (Template) and ...
  • etc ...

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

1. Get all the tags.
2. Get the commits contained betweentagA andtagB.
3. Execute with all tags corresponding totag query that were specified in Step 1 and 2.

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

Please installgit-chglog in a way that matches your environment.

brew tap git-chglog/git-chglogbrew install git-chglog

scoop install git-chglog

asdf plugin-add git-chglog https://github.com/GoodwayGroup/asdf-git-chglog.gitasdf install git-chglog latest

go install github.com/git-chglog/git-chglog/cmd/git-chglog@latest

The compiled docker images are maintained onquay.io.We maintain the following tags:

• edge: Image that is build from the currentHEAD of the main line branch.
• latest: Image that is built from thelatest released version
• x.y.y (versions): Images that are build from the tagged versions within Github.

docker pull quay.io/git-chglog/git-chglog:latestdocker run -v"$PWD":/workdir quay.io/git-chglog/git-chglog --version

If you are using another platform, you can download a binary from thereleases pageand place it in a directory in your$PATH.

You can check with the following command whether thegit-chglog command wasincluded in a directory that is in your$PATH.

$ git-chglog --version# outputs the git-chglog version

git-chglog 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-chglog --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 displayedon stdout.

git-chglog

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

git-chglog -o CHANGELOG.md

You now know basic usage ofgit-chglog!

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

$ git-chglog --helpUSAGE:  git-chglog [options]<tag query>    There are the following specification methodsfor<tag query>.    1.<old>..<new> - Commit containedin<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 containedin<name>.OPTIONS:  --init                      generate the git-chglog configuration filein interactive (default: false)  --path value                Filter commits by path(s). Can use multiple times.  --config value, -c value    specifies a different configuration file to pick up (default:".chglog/config.yml")  --template value, -t value  specifies a template file to pick up. If not specified, use the onein config  --repository-url value      specifies git repo URL. If not specified, use'repository_url'in config  --output value, -o value    output path and filenamefor the changelogs. If not specified, output to stdout  --next-tag value            treat unreleased commits as specified tags (EXPERIMENTAL)  --silent                    disable stdout output (default: false)  --no-color                  disable color output (default: false) [$NO_COLOR]  --no-emoji                  disable emoji output (default: false) [$NO_EMOJI]  --no-case                   disablecase sensitive filters (default: false)  --tag-filter-pattern value  Regular expression of tag filter. Is specified, only matched tags will be picked  --jira-url value            Jira URL [$JIRA_URL]  --jira-username value       Jira username [$JIRA_USERNAME]  --jira-token value          Jira token [$JIRA_TOKEN]  --sort value                Specify how to sort tags; currently supports"date" or by"semver" (default: date)  --help, -h                  showhelp (default: false)  --version, -v               print the version (default: false)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 acommand to generate CHANGELOG including commit of 1.0.0 to 2.0.0.  $ git-chglog 1.0.0    The above is acommand 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 acommand to generate CHANGELOG with the commit includedin 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".  $ git-chglog --path path/to/my/component --output CHANGELOG.component.md    Filter commits by specific paths or files in git and output to a component specific changelog.

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.

Thegit-chglog configuration is a yaml file. The default location is.chglog/config.yml.

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

bin:gitstyle:""template:CHANGELOG.tpl.mdinfo:title:CHANGELOGrepository_url:https://github.com/git-chglog/git-chglogoptions:tag_filter_pattern:'^v'sort:"date"commits:filters:Type:        -featsort_by:Scopecommit_groups:group_by:Typesort_by:Titletitle_order:      -feattitle_maps:feat:Featuresheader:pattern:"<regexp>"pattern_maps:      -PropNameissues:prefix:      -#refs:actions:      -Closes      -Fixesmerges:pattern:"^Merge branch '(\\w+)'$"pattern_maps:      -Sourcereverts:pattern:"^Revert\"([\\s\\S]*)\"$"pattern_maps:      -Headernotes:keywords:      -BREAKING CHANGE

Git execution command.

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

Path for the template file. It is specified by a relative path from the settingfile. 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 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.

Thegit-chglog template uses thetext/template package and enhanced templating functions provided bySprig. For basic usage please refer to the following.

• text/template
• Sprig

We have implemented the following custom template functions. These override functions provided bySprig.

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

The basic templates are as follows.

Example:

{{ if .Versions -}}<aname="unreleased"></a>##[Unreleased]{{ if .Unreleased.CommitGroups -}}{{ range .Unreleased.CommitGroups -}}###{{ .Title }}{{ range .Commits -}}- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}{{ end }}{{ end -}}{{ end -}}{{ end -}}{{ range .Versions }}<aname="{{ .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 godocRenderData documentation for available variables.

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

Jira is a popular project management tool. When a project uses Jira to trackfeature development and bug fixes, it may also want to generate change log basedinformation stored in Jira. With embedding a Jira story id in git commit header,the git-chglog tool may automatically fetch data of the story from Jira, thosedata then can be used to render the template.

Take the following steps to add Jira integration:

Where Jira issue is identical Jira story.

The following is a sample pattern:

header:pattern:"^(?:(\\w*)|(?:\\[(.*)\\])?)\\:\\s(.*)$"pattern_maps:    -Type    -JiraIssueID    -Subject

This sample pattern can match both forms of commit headers:

• feat: new feature of something
• [JIRA-ID]: something

The following is a sample:

jira:info:username:utoken:purl:https://jira.comissue:type_maps:Task:fixStory:featdescription_pattern:"<changelog>(.*)</changelog>"

Here you need to define Jira URL, access username and token (password). If youdon't want to write your Jira access credential in configure file, you may definethem with environment variables:JIRA_URL,JIRA_USERNAME andJIRA_TOKEN.

You also needs to define a issue type map. In above sample, Jira issue typeTaskwill be mapped tofix andStory will be mapped tofeat.

As a Jira story's description could be very long, you might not want to includethe entire description into change log. In that case, you may definedescription_patternlike above, so that only content embraced with<changelog> ... </changelog>will be included.

In the template, if a commit contains a Jira issue id, then you may show Jiradata. For example:

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

Within aCommit, the following Jira data can be used in template:

• .JiraIssue.Summary - Summary of the Jira story
• .JiraIssue.Description - Description of the Jira story
• .JiraIssue.Type - Original type of the Jira story, and.Type will be mapped type.
• .JiraIssue.Labels - A list of strings, each is a Jira label.

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

git-chglog --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-chglog is inspired byconventional-changelog. Thank you!

We always welcome your contributions 👏

1. Use Golang version>= 1.24
2. Fork (https://github.com/git-chglog/git-chglog) 🎉
3. Create a feature branch ☕
4. Run test suite with the$ make test command and confirm that it passes ⚡
5. Run linters with the$ make lint command and confirm it passes 🧹
   • The project usesgolangci-lint
6. Commit your changes 📝
7. Rebase your local changes against themaster branch 💡
8. Create new Pull Request 💌

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

There is arelease target within the Makefile that wraps up the steps torelease a new version.

NOTE: Pass theVERSION variable when running the command to properly setthe tag version for the release.

$ VERSION=vX.Y.Z make release# EXAMPLE:$ VERSION=v0.11.3 make release

Once thetag has been pushed, thegoreleaser github action will take careof the rest.

I would like to makegit-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 ❤️

SeeCHANGELOG.md

• git-chglog/artwork - Assets forgit-chglog.

MIT © tsuyoshiwada