github-changelog-generator/man/git-generate-changelog.md

220 lines
5.1 KiB
Markdown
Raw Normal View History

2015-10-01 20:50:48 +00:00
git-generate-changelog(1) - Generate changelog from github
================================
## SYNOPSIS
`git generate-changelog` [-h|--help] [-u|--user] [-p|--project]
## DESCRIPTION
2017-12-13 21:06:00 +00:00
Automatically generate changelog from your tags, issues, labels and pull requests on GitHub.
2015-10-01 20:50:48 +00:00
## OPTIONS
-u, --user [USER]
Username of the owner of target GitHub repo
-p, --project [PROJECT]
Name of project on GitHub
-t, --token [TOKEN]
To make more than 50 requests per hour your GitHub token is required. You can generate it at: https://github.com/settings/tokens/new
-f, --date-format [FORMAT]
Date format. Default is %Y-%m-%d
-o, --output [NAME]
Output file. Default is CHANGELOG.md
-b, --base [NAME]
Optional base file to append generated changes to.
--bugs-label [LABEL]
Setup custom label for bug-fixes section. Default is "**Fixed bugs:**
--enhancement-label [LABEL]
Setup custom label for enhancements section. Default is "**Implemented enhancements:**"
--issues-label [LABEL]
Setup custom label for closed-issues section. Default is "**Closed issues:**"
--header-label [LABEL]
2017-12-13 21:06:00 +00:00
Setup custom header label. Default is "# Changelog"
2015-10-01 20:50:48 +00:00
2016-11-01 20:39:03 +00:00
--front-matter [JSON]
Add YAML front matter. Formatted as JSON because it's easier to add on the command line
2015-10-01 20:50:48 +00:00
--pr-label [LABEL]
Setup custom label for pull requests section. Default is "**Merged pull requests:**"
--[no-]issues
Include closed issues in changelog. Default is true
--[no-]issues-wo-labels
Include closed issues without labels in changelog. Default is true
--[no-]pr-wo-labels
Include pull requests without labels in changelog. Default is true
--[no-]pull-requests
Include pull-requests in changelog. Default is true
--[no-]filter-by-milestone
Use milestone to detect when issue was resolved. Default is true
--[no-]author
Add author of pull-request in the end. Default is true
2016-11-01 20:39:03 +00:00
--usernames-as-github-logins
Use GitHub tags instead of Markdown links for the author of an issue or pull-request.
2015-10-01 20:50:48 +00:00
--unreleased-only
Generate log from unreleased closed issues only.
--[no-]unreleased
Add to log unreleased closed issues. Default is true
--unreleased-label [label]
2016-11-04 21:53:49 +00:00
Setup custom label for unreleased closed issues section. Default is "**Unreleased:**"
2015-10-01 20:50:48 +00:00
--[no-]compare-link
Include compare link (Full Changelog) between older version and newer version. Default is true
--include-labels x,y,z
Only issues with the specified labels will be included in the changelog.
--exclude-labels x,y,z
Issues with the specified labels will be always excluded from changelog. Default is 'duplicate,question,invalid,wontfix'
--bug-labels x,y,z
Issues with the specified labels will be always added to "Fixed bugs" section. Default is 'bug,Bug'
--enhancement-labels x,y,z
Issues with the specified labels will be always added to "Implemented enhancements" section. Default is 'enhancement,Enhancement'
--exclude-tags x,y,z
2017-12-13 21:06:00 +00:00
Changelog will exclude specified tags
2015-10-01 20:50:48 +00:00
2016-11-01 20:39:03 +00:00
--exclude-tags-regex [REGEX]
Apply a regular expression on tag names so that they can be excluded, for example: --exclude-tags-regex ".*\+\d{1,}"
2015-10-01 20:50:48 +00:00
--since-tag x
2017-12-13 21:06:00 +00:00
Changelog will start after specified tag
2015-10-01 20:50:48 +00:00
--due-tag x
2017-12-13 21:06:00 +00:00
Changelog will end before specified tag
2015-10-01 20:50:48 +00:00
--max-issues [NUMBER]
Max number of issues to fetch from GitHub. Default is unlimited
--release-url [URL]
The URL to point to for release links, in printf format (with the tag as variable).
--github-site [URL]
The Enterprise Github site on which your project is hosted.
--github-api [URL]
The enterprise endpoint to use for your Github API.
--simple-list
Create simple list from issues and pull requests. Default is false.
--future-release [RELEASE-VERSION]
Put the unreleased changes in the specified release number.
2016-11-01 20:39:03 +00:00
--release-branch [RELEASE-BRANCH]
Limit pull requests to the release branch, such as master or release
--http-cache
Use HTTP Cache to cache Github API requests (useful for large repos) Default is true.
--[no-]cache-file [CACHE-FILE]
Filename to use for cache. Default is github-changelog-http-cache in a temporary directory.
2016-11-01 20:39:03 +00:00
--cache-log [CACHE-LOG]
Filename to use for cache log. Default is github-changelog-logger.log in a temporary directory.
2016-11-01 20:39:03 +00:00
--ssl-ca-file [PATH]
Path to cacert.pem file. Default is a bundled lib/github_changelog_generator/ssl_certs/cacert.pem. Respects SSL_CA_PATH.
--require file1.rb,file2.rb
Paths to Ruby file(s) to require before generating changelog.
2015-10-01 20:50:48 +00:00
--[no-]verbose
Run verbosely. Default is true
Refactor generation code and allow custom sections There's a lot in this PR. - Added a Section class to more easily make the other changes and hopefully add flexibility for the future - Added an option called `configure_sections` that allows you create your own custom sections. It blows away all other sections and uses only the ones you give it. - Added an option called `add_sections` that allows you to add_sections to the default section set - Added an option called `include_merged` that can be used when configure_sections is defined. Configure sections blows away any and all default sections so to get this one back, you have to set this option. - Added tests for this stuff @HAIL9000 was a co-author. Because of a little git snafu, I accidentally squashed all of our work into one so it looks like it was just me. --- Refactor details: Before this change, the code in generator.rb and generator_generation.rb was conflated and method call flow went back and forth between the two files seemingly randomly. They also both defined the exact same class, which is un-ruby-ish. I tried to separate methods used for the whole changelog generation from methods used for specific parts of the changelog and move them into specific classes. I reasoned that a changelog is a series of "entries" of all tagged releases plus an extra entry for the unreleased entry. Each entry is comprised of a header and a series of "sections" for that entry. Each section is comprized of a list of issues and/or pull requests for that entry. So the log contains entries, entries contain sections, and sections contain issues & prs. I have structured the classes around this idea. - lib/github_changelog_generator/generator/generator.rb is for code related to generating the entire changelog. - lib/github_changelog_generator/generator/entry.rb is for code related to generating entries. - lib/github_changelog_generator/generator/section.rb is for code relating to geneating entry sections. Issues and PRs are already special objects, so it doesn't make sense to break those out into their own class.
2017-11-07 05:19:49 +00:00
--configure-sections [HASH, STRING]
2015-10-01 20:50:48 +00:00
Refactor generation code and allow custom sections There's a lot in this PR. - Added a Section class to more easily make the other changes and hopefully add flexibility for the future - Added an option called `configure_sections` that allows you create your own custom sections. It blows away all other sections and uses only the ones you give it. - Added an option called `add_sections` that allows you to add_sections to the default section set - Added an option called `include_merged` that can be used when configure_sections is defined. Configure sections blows away any and all default sections so to get this one back, you have to set this option. - Added tests for this stuff @HAIL9000 was a co-author. Because of a little git snafu, I accidentally squashed all of our work into one so it looks like it was just me. --- Refactor details: Before this change, the code in generator.rb and generator_generation.rb was conflated and method call flow went back and forth between the two files seemingly randomly. They also both defined the exact same class, which is un-ruby-ish. I tried to separate methods used for the whole changelog generation from methods used for specific parts of the changelog and move them into specific classes. I reasoned that a changelog is a series of "entries" of all tagged releases plus an extra entry for the unreleased entry. Each entry is comprised of a header and a series of "sections" for that entry. Each section is comprized of a list of issues and/or pull requests for that entry. So the log contains entries, entries contain sections, and sections contain issues & prs. I have structured the classes around this idea. - lib/github_changelog_generator/generator/generator.rb is for code related to generating the entire changelog. - lib/github_changelog_generator/generator/entry.rb is for code related to generating entries. - lib/github_changelog_generator/generator/section.rb is for code relating to geneating entry sections. Issues and PRs are already special objects, so it doesn't make sense to break those out into their own class.
2017-11-07 05:19:49 +00:00
Define your own set of sections which overrides all default sections") do |v|
2015-10-01 20:50:48 +00:00
Refactor generation code and allow custom sections There's a lot in this PR. - Added a Section class to more easily make the other changes and hopefully add flexibility for the future - Added an option called `configure_sections` that allows you create your own custom sections. It blows away all other sections and uses only the ones you give it. - Added an option called `add_sections` that allows you to add_sections to the default section set - Added an option called `include_merged` that can be used when configure_sections is defined. Configure sections blows away any and all default sections so to get this one back, you have to set this option. - Added tests for this stuff @HAIL9000 was a co-author. Because of a little git snafu, I accidentally squashed all of our work into one so it looks like it was just me. --- Refactor details: Before this change, the code in generator.rb and generator_generation.rb was conflated and method call flow went back and forth between the two files seemingly randomly. They also both defined the exact same class, which is un-ruby-ish. I tried to separate methods used for the whole changelog generation from methods used for specific parts of the changelog and move them into specific classes. I reasoned that a changelog is a series of "entries" of all tagged releases plus an extra entry for the unreleased entry. Each entry is comprised of a header and a series of "sections" for that entry. Each section is comprized of a list of issues and/or pull requests for that entry. So the log contains entries, entries contain sections, and sections contain issues & prs. I have structured the classes around this idea. - lib/github_changelog_generator/generator/generator.rb is for code related to generating the entire changelog. - lib/github_changelog_generator/generator/entry.rb is for code related to generating entries. - lib/github_changelog_generator/generator/section.rb is for code relating to geneating entry sections. Issues and PRs are already special objects, so it doesn't make sense to break those out into their own class.
2017-11-07 05:19:49 +00:00
--add-sections [HASH, STRING]
2015-10-01 20:50:48 +00:00
Refactor generation code and allow custom sections There's a lot in this PR. - Added a Section class to more easily make the other changes and hopefully add flexibility for the future - Added an option called `configure_sections` that allows you create your own custom sections. It blows away all other sections and uses only the ones you give it. - Added an option called `add_sections` that allows you to add_sections to the default section set - Added an option called `include_merged` that can be used when configure_sections is defined. Configure sections blows away any and all default sections so to get this one back, you have to set this option. - Added tests for this stuff @HAIL9000 was a co-author. Because of a little git snafu, I accidentally squashed all of our work into one so it looks like it was just me. --- Refactor details: Before this change, the code in generator.rb and generator_generation.rb was conflated and method call flow went back and forth between the two files seemingly randomly. They also both defined the exact same class, which is un-ruby-ish. I tried to separate methods used for the whole changelog generation from methods used for specific parts of the changelog and move them into specific classes. I reasoned that a changelog is a series of "entries" of all tagged releases plus an extra entry for the unreleased entry. Each entry is comprised of a header and a series of "sections" for that entry. Each section is comprized of a list of issues and/or pull requests for that entry. So the log contains entries, entries contain sections, and sections contain issues & prs. I have structured the classes around this idea. - lib/github_changelog_generator/generator/generator.rb is for code related to generating the entire changelog. - lib/github_changelog_generator/generator/entry.rb is for code related to generating entries. - lib/github_changelog_generator/generator/section.rb is for code relating to geneating entry sections. Issues and PRs are already special objects, so it doesn't make sense to break those out into their own class.
2017-11-07 05:19:49 +00:00
Add new sections but keep the default sections"
-v, --version
Print version number
-h, --help
Displays Help
2015-10-01 20:50:48 +00:00
## EXAMPLES
## AUTHOR
Written by Petr Korolev sky4winder@gmail.com
## REPORTING BUGS
&lt;<https://github.com/skywinder/github-changelog-generator/issues>&gt;
## SEE ALSO
&lt;<https://github.com/skywinder/github-changelog-generator/>&gt;