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