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