diff --git a/README.md b/README.md new file mode 100644 index 00000000..16bd9aea --- /dev/null +++ b/README.md @@ -0,0 +1,522 @@ +# git-chglog + +![git-chglog](https://raw.githubusercontent.com/git-chglog/artwork/master/repo-banner%402x.png) + +[![godoc.org](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](https://godoc.org/github.com/git-chglog/git-chglog) +[![Travis](https://img.shields.io/travis/git-chglog/git-chglog.svg?style=flat-square)](https://travis-ci.org/git-chglog/git-chglog) +[![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/git-chglog/git-chglog/blob/master/LICENSE) + +> CHANGELOG generator implemented in Go (Golang). +> _Anytime, anywhere, Write your CHANGELOG._ + + + + +## Table of Contents + +* [Features](#features) +* [How it works](#how-it-works) +* [Getting Started](#getting-started) + - [Installation](#installation) + + [Homebrew (for macOS users)](#homebrew-for-macos-users) + + [Go users](#go-users) + - [Test Installation](#test-installation) + - [Quick Start](#quick-start) +* [CLI Usage](#cli-usage) + - [`tag query`](#tag-query) +* [Configuration](#configuration) + - [`bin`](#bin) + - [`style`](#style) + - [`template`](#template) + - [`info`](#info) + - [`options`](#options) +* [Templates](#templates) +* [Supported Styles](#supported-styles) +* [FAQ](#faq) +* [TODO](#todo) +* [Thanks](#thanks) +* [Contributing](#contributing) + - [Development](#development) + - [Feedback](#feedback) +* [CHANGELOG](#changelog) +* [Related Projects](#related-projects) +* [License](#license) + + + + +## Features + +* :recycle: High portability + - It works with single binary. Therefore, any project (environment) can be used. +* :beginner: Simple usability + - The CLI usage is very simple and has low learning costs. + - For example, the simplest command is `$ git-chglog`. +* :rocket: 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. +1. Get the commit contained between `tagA` and `tagB`. +1. Execute with all tags corresponding to [tag query](# 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) + +```bash +$ brew tap git-chglog/git-chglog +$ brew install git-chglog +``` + +#### Go users + +```bash +$ 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](https://github.com/git-chglog/git-chglog/releases) 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`. + +```bash +$ 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 :+1: + +```bash +$ git-chglog --init +``` + +![init option demo](./docs/assets/init.gif) + +--- + +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. + +```bash +$ git-chglog +``` + +Use `-o` (`--output`) option if you want to output to file instead of stdout. + +```bash +$ 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 + +```bash +$ git-chglog --help + +USAGE: + git-chglog [options] + + There are the following specification methods for . + + 1. .. - Commit contained in tags from . + 2. .. - Commit from the to the latest tag. + 3. .. - Commit from the oldest tag to . + 4. - Commit contained in . + +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 + --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 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 adove 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 ``. +The table below shows Query patterns and summaries, and Query examples. + +| Query | Description | Example | +|:---------------|:-----------------------------------------------|:----------------------------| +| `..` | Commit contained in `` tags from ``. | `$ git-chglog 1.0.0..2.0.0` | +| `..` | Commit from the `` to the latest tag. | `$ git-chglog 1.0.0..` | +| `..` | Commit from the oldest tag to ``. | `$ git-chglog ..2.0.0` | +| `` | Commit contained in ``. | `$ 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`. + +```yaml +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: "" + 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"` `"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](#todo). | + +#### `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](#todo). | +| `sort_by` | N | String | `"Title"` | Property name to use for sorting `CommitGroup`. See [CommitGroup](#todo). | +| `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](#todo). | + +#### `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](#todo). | + +#### `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 `:` (e.g. `BREAKING CHANGE`). | + + + + +## Templates + +The `git-chglog` template uses the `text/template` package. For basic usage please refer to the following. + +> [text/template](https://golang.org/pkg/text/template/) + +If you are not satisfied with the prepared template please try customizing. + +--- + +The basic templates are as follows. + +**Example:** + +```markdown +{{range .Versions}} + +## {{if .Tag.Previous}}[{{.Tag.Name}}]({{$.Info.RepositoryURL}}/compare/{{.Tag.Previous.Name}}...{{.Tag.Name}}){{else}}{{.Tag.Name}}{{end}} ({{datetime "2006-01-02" .Tag.Date}}) +{{range .CommitGroups}} +### {{.Title}} +{{range .Commits}} +* {{if ne .Scope ""}}**{{.Scope}}:** {{end}}{{.Subject}}{{end}} +{{end}}{{if .RevertCommits}} +### Reverts +{{range .RevertCommits}} +* {{.Header}}{{end}} +{{end}}{{if .MergeCommits}} +### Pull Requests +{{range .MergeCommits}} +* {{.Header}}{{end}} +{{end}}{{range .NoteGroups}} +### {{.Title}} +{{range .Notes}} +{{.Body}} +{{end}} +{{end}} +{{end}} +``` + +See godoc [RenderData](#todo) for available variables. + + + +## Supported Styles + +| Name | Status | Features | +|:-------------------------------------------|:----------------------|:-------------------------------------------------------| +| [GitHub](https://github.com/) | :white_check_mark: | Mentions automatic link. Automatic link to references. | +| [GitLab](https://about.gitlab.com/) | :white_medium_square: | - | +| [Bitbucket](https://bitbucket.org/product) | :white_medium_square: | - | + +> :memo: 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. +
+ + + + +## TODO + +* [ ] More styles (GitLab, Bitbucket, and others ...) +* [ ] Snippetization of configuration files (improvement of reusability) +* [ ] Windows Support +* [ ] More test test test ... (and example) + + + + +## Thanks + +`git-chglog` is inspired by [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog). Thank you! + + + + +## Contributing + +We are always welcoming your contribution :clap: + + +### Development + +1. Fork (https://github.com/git-chglog/git-chglog) :tada: +1. Create a feature branch :coffee: +1. Run test suite with the `$ make test` command and confirm that it passes :zap: +1. Commit your changes :memo: +1. Rebase your local changes against the `master` branch :bulb: +1. Create new Pull Request :love_letter: + +Bugs, feature requests and comments are more than welcome in the [issues](https://github.com/git-chglog/git-chglog/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 :heart: + + + + +## CHANGELOG + +See [CHANGELOG.md](./CHANGELOG.md) + + + + +## Related Projects + +* [git-chglog/artwork](https://github.com/git-chglog/artwork) - Assets for `git-chglog`. + + + + +## License + +[MIT © tsuyoshiwada](./LICENSE) diff --git a/cmd/git-chglog/initializer.go b/cmd/git-chglog/initializer.go index 19946b39..7c03a30c 100644 --- a/cmd/git-chglog/initializer.go +++ b/cmd/git-chglog/initializer.go @@ -80,7 +80,7 @@ func (init *Initializer) Run() int { success := color.CyanString("✔") emoji.Fprintf(os.Stdout, ` -:sparkles:%s +:sparkles: %s %s %s %s %s diff --git a/cmd/git-chglog/main.go b/cmd/git-chglog/main.go index a2faca12..25090787 100644 --- a/cmd/git-chglog/main.go +++ b/cmd/git-chglog/main.go @@ -13,29 +13,46 @@ func main() { cli.AppHelpTemplate = fmt.Sprintf(` %s - {{.Name}} [options] [tag revision] + {{.Name}} [options] + + There are the following specification methods for . + + 1. .. - Commit contained in tags from . + 2. .. - Commit from the to the latest tag. + 3. .. - Commit from the oldest tag to . + 4. - Commit contained in . %s - {{.Version}}{{if .Author}} + {{range .Flags}}{{.}} + {{end}} +%s -%s - {{.Author}}{{end}} + $ {{.Name}} -%s - {{range .Flags}}{{.}} - {{end}} -%s - {{.Name}} - {{.Name}} 1.0.0..5.0.0-rc.10 - {{.Name}} 1.0.0.. - {{.Name}} ..5.0.0-rc.10 - {{.Name}} 1.0.0 - {{.Name}} --output CHANGELOG.md - {{.Name}} --config dir/path/config.yml + If is not specified, it corresponds to all tags. + This is the simplest example. + + $ {{.Name}} 1.0.0..2.0.0 + + The above is a command to generate CHANGELOG including commit of 1.0.0 to 2.0.0. + + $ {{.Name}} 1.0.0 + + The above is a command to generate CHANGELOG including commit of only 1.0.0. + + $ {{.Name}} $(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. + + $ {{.Name}} --output CHANGELOG.md + + The above is a command to output to CHANGELOG.md instead of standard output. + + $ {{.Name}} --config custom/dir/config.yml + + The adove is a command that uses a configuration file placed other than ".chglog/config.yml". `, ttl("USAGE:"), - ttl("VERSION:"), - ttl("AUTHOR:"), ttl("OPTIONS:"), ttl("EXAMPLE:"), ) @@ -62,7 +79,7 @@ func main() { // output cli.StringFlag{ Name: "output, o", - Usage: "output path and filename for the changelogs (default: output to stdout)", + Usage: "output path and filename for the changelogs. If not specified, output to stdout", }, // silent diff --git a/docs/assets/init.gif b/docs/assets/init.gif new file mode 100644 index 00000000..9ece0fdc Binary files /dev/null and b/docs/assets/init.gif differ