github.com/BrandonManuel/git-chglog@v0.0.0-20200903004639-7a62fa08787a/README.md (about) 1 # git-chglog 2 3 ![git-chglog](https://raw.githubusercontent.com/git-chglog/artwork/master/repo-banner%402x.png) 4 5 [![godoc.org](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](https://godoc.org/github.com/BrandonManuel/git-chglog) 6 [![Travis](https://img.shields.io/travis/git-chglog/git-chglog.svg?style=flat-square)](https://travis-ci.org/git-chglog/git-chglog) 7 [![AppVeyor](https://img.shields.io/appveyor/ci/tsuyoshiwada/git-chglog/master.svg?style=flat-square)](https://ci.appveyor.com/project/tsuyoshiwada/git-chglog/branch/master) 8 [![Coverage Status](https://img.shields.io/coveralls/github/git-chglog/git-chglog.svg?style=flat-square)](https://coveralls.io/github/git-chglog/git-chglog?branch=master) 9 [![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/BrandonManuel/git-chglog/blob/master/LICENSE) 10 11 > CHANGELOG generator implemented in Go (Golang). 12 > _Anytime, anywhere, Write your CHANGELOG._ 13 14 15 ## Table of Contents 16 17 * [Features](#features) 18 * [How it works](#how-it-works) 19 * [Getting Started](#getting-started) 20 - [Installation](#installation) 21 + [Homebrew (for macOS users)](#homebrew-for-macos-users) 22 + [Go users](#go-users) 23 - [Test Installation](#test-installation) 24 - [Quick Start](#quick-start) 25 * [CLI Usage](#cli-usage) 26 - [`tag query`](#tag-query) 27 * [Configuration](#configuration) 28 * [Templates](#templates) 29 * [Supported Styles](#supported-styles) 30 * [FAQ](#faq) 31 * [TODO](#todo) 32 * [Thanks](#thanks) 33 * [Contributing](#contributing) 34 - [Development](#development) 35 - [Feedback](#feedback) 36 * [CHANGELOG](#changelog) 37 * [Related Projects](#related-projects) 38 * [License](#license) 39 40 41 42 43 ## Features 44 45 * :recycle: High portability 46 - It works with single binary. Therefore, any project (environment) can be used. 47 * :beginner: Simple usability 48 - The CLI usage is very simple and has low learning costs. 49 - For example, the simplest command is `$ git-chglog`. 50 * :rocket: High flexibility 51 - Commit message format and ... 52 - CHANGELOG's style (Template) and ... 53 - etc ... 54 55 ## How it works 56 57 `git-chglog` internally uses the `git` command to get data to include in the CHANGELOG. 58 The basic steps are as follows. 59 60 1. Get all the tags. 61 1. Get the commits contained between `tagA` and `tagB`. 62 1. Execute with all tags corresponding to [tag query](#tag-query) that were specified in Step 1 and 2. 63 64 ## Getting Started 65 66 We will start with installation and introduce the steps up to the automatic generation of the configuration file and template. 67 68 ### Installation 69 70 Please install `git-chglog` in a way that matches your environment. 71 72 #### [Homebrew](https://brew.sh) (for macOS users) 73 74 ```bash 75 $ brew tap git-chglog/git-chglog 76 $ brew install git-chglog 77 ``` 78 79 #### [Scoop](https://scoop.sh) (for Windows users) 80 81 ``` 82 $ scoop install git-chglog 83 ``` 84 85 #### Go users 86 87 ```bash 88 $ go get -u github.com/BrandonManuel/git-chglog/cmd/git-chglog 89 ``` 90 91 --- 92 93 If you are using another platform, you can download a binary from the [releases page](https://github.com/BrandonManuel/git-chglog/releases) and place it in a directory in your `$PATH`. 94 95 96 ### Test Installation 97 98 You can check with the following command whether the `git-chglog` command was included in a directory that is in your `$PATH`. 99 100 ```bash 101 $ git-chglog --version 102 # outputs the git-chglog version 103 ``` 104 105 106 ### Quick Start 107 108 `git-chglog` requires configuration files and templates to generate a CHANGELOG. 109 110 However, it is a waste of time to create configuration files and templates from scratch. 111 112 Therefore we recommend using the `--init` option which will create them interactively :+1: 113 114 ```bash 115 $ git-chglog --init 116 ``` 117 118 ![init option demo](./docs/assets/init.gif) 119 120 --- 121 122 You are now ready for configuration files and templates! 123 124 Let's immediately generate a CHANGELOG of your project. 125 By doing the following simple command, Markdown for your CHANGELOG is displayed on stdout. 126 127 ```bash 128 $ git-chglog 129 ``` 130 131 Use `-o` (`--output`) option if you want to output to a file instead of stdout. 132 133 ```bash 134 $ git-chglog -o CHANGELOG.md 135 ``` 136 137 --- 138 139 You now know basic usage of `git-chglog`! 140 141 In order to make a better CHANGELOG, please refer to the following document and customize it. 142 143 ## CLI Usage 144 145 ```bash 146 $ git-chglog --help 147 148 USAGE: 149 git-chglog [options] <tag query> 150 151 There are the following specification methods for <tag query>. 152 153 1. <old>..<new> - Commit contained in <old> tags from <new>. 154 2. <name>.. - Commit from the <name> to the latest tag. 155 3. ..<name> - Commit from the oldest tag to <name>. 156 4. <name> - Commit contained in <name>. 157 158 OPTIONS: 159 --init generate the git-chglog configuration file in interactive 160 --config value, -c value specifies a different configuration file to pick up (default: ".chglog/config.yml") 161 --output value, -o value output path and filename for the changelogs. If not specified, output to stdout 162 --next-tag value treat unreleased commits as specified tags (EXPERIMENTAL) 163 --silent disable stdout output 164 --no-color disable color output [$NO_COLOR] 165 --no-emoji disable emoji output [$NO_EMOJI] 166 --no-case disable case sensitive filters 167 --tag-filter-pattern value, -p value regular expression of tag filter. Is specified, only matched tags will be picked 168 --help, -h show help 169 --version, -v print the version 170 171 EXAMPLE: 172 173 $ git-chglog 174 175 If <tag query> is not specified, it corresponds to all tags. 176 This is the simplest example. 177 178 $ git-chglog 1.0.0..2.0.0 179 180 The above is a command to generate CHANGELOG including commit of 1.0.0 to 2.0.0. 181 182 $ git-chglog 1.0.0 183 184 The above is a command to generate CHANGELOG including commit of only 1.0.0. 185 186 $ git-chglog $(git describe --tags $(git rev-list --tags --max-count=1)) 187 188 The above is a command to generate CHANGELOG with the commit included in the latest tag. 189 190 $ git-chglog --output CHANGELOG.md 191 192 The above is a command to output to CHANGELOG.md instead of standard output. 193 194 $ git-chglog --config custom/dir/config.yml 195 196 The above is a command that uses a configuration file placed other than ".chglog/config.yml". 197 ``` 198 199 ### `tag query` 200 201 You can specify which commits to include in the generation of CHANGELOG using `<tag query>`. 202 203 The table below shows Query patterns and summaries, and Query examples. 204 205 | Query | Description | Example | 206 |:---------------|:-----------------------------------------------|:----------------------------| 207 | `<old>..<new>` | Commit contained in `<new>` tags from `<old>`. | `$ git-chglog 1.0.0..2.0.0` | 208 | `<name>..` | Commit from the `<name>` to the latest tag. | `$ git-chglog 1.0.0..` | 209 | `..<name>` | Commit from the oldest tag to `<name>`. | `$ git-chglog ..2.0.0` | 210 | `<name>` | Commit contained in `<name>`. | `$ git-chglog 1.0.0` | 211 212 ## Configuration 213 214 The `git-chglog` configuration is a yaml file. The default location is `.chglog/config.yml`. 215 216 Below is a complete list that you can use with `git-chglog`. 217 218 ```yaml 219 bin: git 220 style: "" 221 template: CHANGELOG.tpl.md 222 info: 223 title: CHANGELOG 224 repository_url: https://github.com/BrandonManuel/git-chglog 225 226 options: 227 commits: 228 filters: 229 Type: 230 - feat 231 sort_by: Scope 232 233 commit_groups: 234 group_by: Type 235 sort_by: Title 236 title_maps: 237 feat: Features 238 239 header: 240 pattern: "<regexp>" 241 pattern_maps: 242 - PropName 243 244 issues: 245 prefix: 246 - # 247 248 refs: 249 actions: 250 - Closes 251 - Fixes 252 253 merges: 254 pattern: "^Merge branch '(\\w+)'$" 255 pattern_maps: 256 - Source 257 258 reverts: 259 pattern: "^Revert \"([\\s\\S]*)\"$" 260 pattern_maps: 261 - Header 262 263 notes: 264 keywords: 265 - BREAKING CHANGE 266 ``` 267 268 ### `bin` 269 270 Git execution command. 271 272 | Required | Type | Default | Description | 273 |:---------|:-------|:--------|:------------| 274 | N | String | `"git"` | - | 275 276 ### `style` 277 278 CHANGELOG style. Automatic linking of issues and notices, initial value setting such as merges etc. are done automatically. 279 280 | Required | Type | Default | Description | 281 |:---------|:-------|:---------|:-------------------------------------------------------| 282 | N | String | `"none"` | Should be `"github"` `"gitlab"` `"bitbucket"` `"none"` | 283 284 ### `template` 285 286 Path for the template file. It is specified by a relative path from the setting file. Absolute paths are also ok. 287 288 | Required | Type | Default | Description | 289 |:---------|:-------|:---------------------|:------------| 290 | N | String | `"CHANGELOG.tpl.md"` | - | 291 292 ### `info` 293 294 Metadata for CHANGELOG. Depending on Style, it is sometimes used in processing, so it is recommended to specify it. 295 296 | Key | Required | Type | Default | Description | 297 |:-----------------|:---------|:-------|:--------------|:-----------------------| 298 | `title` | N | String | `"CHANGELOG"` | Title of CHANGELOG. | 299 | `repository_url` | N | String | none | URL of git repository. | 300 301 ### `options` 302 303 Options used to process commits. 304 305 #### `options.commits` 306 307 Options concerning the acquisition and sort of commits. 308 309 | Key | Required | Type | Default | Description | 310 |:----------|:---------|:------------|:----------|:--------------------------------------------------------------------------------------------------------------------| 311 | `filters` | N | Map in List | none | Filter by using `Commit` properties and values. Filtering is not done by specifying an empty value. | 312 | `sort_by` | N | String | `"Scope"` | Property name to use for sorting `Commit`. See [Commit](https://godoc.org/github.com/BrandonManuel/git-chglog#Commit). | 313 314 #### `options.commit_groups` 315 316 Options for groups of commits. 317 318 | Key | Required | Type | Default | Description | 319 |:-------------|:---------|:------------|:----------|:-------------------------------------------------------------------------------------------| 320 | `group_by` | N | String | `"Type"` | Property name of `Commit` to be grouped into `CommitGroup`. See [CommitGroup][doc-commit]. | 321 | `sort_by` | N | String | `"Title"` | Property name to use for sorting `CommitGroup`. See [CommitGroup][doc-commit-group]. | 322 | `title_maps` | N | Map in List | none | Map for `CommitGroup` title conversion. | 323 324 #### `options.header` 325 326 This option is used for parsing the commit header. 327 328 | Key | Required | Type | Default | Description | 329 |:---------------|:---------|:-------|:--------|:--------------------------------------------------------------------------------------------------------| 330 | `pattern` | Y | String | none | A regular expression to use for parsing the commit header. | 331 | `pattern_maps` | Y | List | none | A rule for mapping the result of `HeaderPattern` to the property of `Commit`. See [Commit][doc-commit]. | 332 333 #### `options.issues` 334 335 This option is used to detect issues. 336 337 | Key | Required | Type | Default | Description | 338 |:---------|:---------|:-----|:--------|:-------------------------------------------| 339 | `prefix` | N | List | none | Prefix used for issues. (e.g. `#`, `#gh-`) | 340 341 #### `options.refs` 342 343 This option is for parsing references. 344 345 | Key | Required | Type | Default | Description | 346 |:----------|:---------|:-----|:--------|:-----------------------------------------------| 347 | `actions` | N | List | none | Word list of `Ref.Action`. See [Ref][doc-ref]. | 348 349 #### `options.merges` 350 351 Options to detect and parse merge commits. 352 353 | Key | Required | Type | Default | Description | 354 |:---------------|:---------|:-------|:--------|:------------------------------------------| 355 | `pattern` | N | String | none | Similar to `options.header.pattern`. | 356 | `pattern_maps` | N | List | none | Similar to `options.header.pattern_maps`. | 357 358 #### `options.reverts` 359 360 Options to detect and parse revert commits. 361 362 | Key | Required | Type | Default | Description | 363 |:---------------|:---------|:-------|:--------|:------------------------------------------| 364 | `pattern` | N | String | none | Similar to `options.header.pattern`. | 365 | `pattern_maps` | N | List | none | Similar to `options.header.pattern_maps`. | 366 367 #### `options.notes` 368 369 Options to detect notes contained in commit bodies. 370 371 | Key | Required | Type | Default | Description | 372 |:-----------|:---------|:-----|:--------|:-----------------------------------------------------------------------------------------------------| 373 | `keywords` | N | List | none | Keyword list to find `Note`. A semicolon is a separator, like `<keyword>:` (e.g. `BREAKING CHANGE`). | 374 375 ## Templates 376 377 The `git-chglog` template uses the `text/template` package. For basic usage please refer to the following. 378 379 > [text/template](https://golang.org/pkg/text/template/) 380 381 If you are not satisfied with the prepared template please try customizing one. 382 383 --- 384 385 The basic templates are as follows. 386 387 **Example:** 388 389 ```markdown 390 {{ if .Versions -}} 391 <a name="unreleased"></a> 392 ## [Unreleased] 393 394 {{ if .Unreleased.CommitGroups -}} 395 {{ range .Unreleased.CommitGroups -}} 396 ### {{ .Title }} 397 {{ range .Commits -}} 398 - {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }} 399 {{ end }} 400 {{ end -}} 401 {{ end -}} 402 {{ end -}} 403 404 {{ range .Versions }} 405 <a name="{{ .Tag.Name }}"></a> 406 ## {{ if .Tag.Previous }}[{{ .Tag.Name }}]{{ else }}{{ .Tag.Name }}{{ end }} - {{ datetime "2006-01-02" .Tag.Date }} 407 {{ range .CommitGroups -}} 408 ### {{ .Title }} 409 {{ range .Commits -}} 410 - {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }} 411 {{ end }} 412 {{ end -}} 413 414 {{- if .RevertCommits -}} 415 ### Reverts 416 {{ range .RevertCommits -}} 417 - {{ .Revert.Header }} 418 {{ end }} 419 {{ end -}} 420 421 {{- if .MergeCommits -}} 422 ### Pull Requests 423 {{ range .MergeCommits -}} 424 - {{ .Header }} 425 {{ end }} 426 {{ end -}} 427 428 {{- if .NoteGroups -}} 429 {{ range .NoteGroups -}} 430 ### {{ .Title }} 431 {{ range .Notes }} 432 {{ .Body }} 433 {{ end }} 434 {{ end -}} 435 {{ end -}} 436 {{ end -}} 437 438 {{- if .Versions }} 439 [Unreleased]: {{ .Info.RepositoryURL }}/compare/{{ $latest := index .Versions 0 }}{{ $latest.Tag.Name }}...HEAD 440 {{ range .Versions -}} 441 {{ if .Tag.Previous -}} 442 [{{ .Tag.Name }}]: {{ $.Info.RepositoryURL }}/compare/{{ .Tag.Previous.Name }}...{{ .Tag.Name }} 443 {{ end -}} 444 {{ end -}} 445 {{ end -}} 446 ``` 447 448 See the godoc [RenderData][doc-render-data] documentation for available variables. 449 450 ## Supported Styles 451 452 | Name | Status | Features | 453 |:-------------------------------------------|:-------------------|:-------------------------------------------------------| 454 | [GitHub](https://github.com/) | :white_check_mark: | Mentions automatic link. Automatic link to references. | 455 | [GitLab](https://about.gitlab.com/) | :white_check_mark: | Mentions automatic link. Automatic link to references. | 456 | [Bitbucket](https://bitbucket.org/product) | :white_check_mark: | Mentions automatic link. Automatic link to references. | 457 458 > :memo: Even with styles that are not yet supported, it is possible to make ordinary CHANGELOG. 459 460 ## FAQ 461 462 <details> 463 <summary>Why do not you output files by default?</summary> 464 This is not for the purpose of completely automating the generation of CHANGELOG files, it is only for assisting generation. 465 466 It is ideal to describe everything included in CHANGELOG in your commits. But actually it is very difficult to do it perfectly. 467 468 There are times when you need to edit the generated output to write a great CHANGELOG. 469 470 By displaying it on the standard output, it makes it easy to change the contents. 471 </details> 472 473 <details> 474 <summary>Can I commit CHANGELOG changes before creating tags?</summary> 475 476 Yes, it can be solved by using the `--next-tag` flag. 477 478 For example, let's say you want to upgrade your project to `2.0.0`. 479 You can create CHANGELOG containing `2.0.0` as follows. 480 481 ```bash 482 $ git-chglog --next-tag 2.0.0 -o CHANGELOG.md 483 $ git commit -am "release 2.0.0" 484 $ git tag 2.0.0 485 ``` 486 487 The point to notice is that before actually creating a tag with `git`, it is conveying the next version with `--next-tag` :+1: 488 489 This is a step that is necessary for project operation in many cases. 490 </details> 491 492 <details> 493 <summary>Can I generate a CHANGELOG based on certain tags?</summary> 494 495 Yes, it can be solved by use the `--tag-filter-pattern` flag. 496 497 For example, the following command will only include tags starting with "v": 498 ```bash 499 $ git-chglog --tag-filter-pattern '^v' 500 ``` 501 </details> 502 503 ## TODO 504 505 * [x] Windows Support 506 * [x] More styles (GitHub, GitLab, Bitbucket :tada:) 507 * [ ] Snippetization of configuration files (improvement of reusability) 508 * [ ] More test test test ... (and example) 509 510 ## Thanks 511 512 `git-chglog` is inspired by [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog). Thank you! 513 514 ## Contributing 515 516 We alway welcome your contributions :clap: 517 518 ### Development 519 520 1. Fork (https://github.com/BrandonManuel/git-chglog) :tada: 521 1. Create a feature branch :coffee: 522 1. Run test suite with the `$ make test` command and confirm that it passes :zap: 523 1. Commit your changes :memo: 524 1. Rebase your local changes against the `master` branch :bulb: 525 1. Create new Pull Request :love_letter: 526 527 Bugs, feature requests and comments are more than welcome in the [issues](https://github.com/BrandonManuel/git-chglog/issues). 528 529 ### Feedback 530 531 I would like to make `git-chglog` a better tool. 532 The goal is to be able to use in various projects. 533 534 Therefore, your feedback is very useful. 535 I am very happy to tell you your opinions on Issues and PR :heart: 536 537 ## CHANGELOG 538 539 See [CHANGELOG.md](./CHANGELOG.md) 540 541 ## Related Projects 542 543 * [git-chglog/artwork](https://github.com/BrandonManuel/artwork) - Assets for `git-chglog`. 544 545 ## License 546 547 [MIT © tsuyoshiwada](./LICENSE) 548 549 [doc-commit]: https://godoc.org/github.com/BrandonManuel/git-chglog#Commit 550 [doc-commit-group]: https://godoc.org/github.com/BrandonManuel/git-chglog#Commit 551 [doc-ref]: https://godoc.org/github.com/BrandonManuel/git-chglog#Ref 552 [doc-render-data]: https://godoc.org/github.com/BrandonManuel/git-chglog#RenderData