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

320 lines
5.6 KiB
Groff
Raw Permalink Normal View History

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
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
.TH "GIT\-GENERATE\-CHANGELOG" "1" "December 2017" "" ""
.
.SH "NAME"
\fBgit\-generate\-changelog\fR \- Generate changelog from github
.
.SH "SYNOPSIS"
\fBgit generate\-changelog\fR [\-h|\-\-help] [\-u|\-\-user] [\-p|\-\-project]
.
.SH "DESCRIPTION"
2017-12-13 21:06:00 +00:00
Automatically generate changelog from your tags, issues, labels and pull requests on GitHub\.
.
.SH "OPTIONS"
\-u, \-\-user [USER]
.
.P
2015-09-30 19:52:13 +00:00
Username of the owner of target GitHub repo
.
.P
\-p, \-\-project [PROJECT]
.
.P
Name of project on GitHub
.
.P
\-t, \-\-token [TOKEN]
.
.P
To make more than 50 requests per hour your GitHub token is required\. You can generate it at: https://github\.com/settings/tokens/new
.
.P
\-f, \-\-date\-format [FORMAT]
.
.P
Date format\. Default is %Y\-%m\-%d
.
.P
\-o, \-\-output [NAME]
.
.P
Output file\. Default is CHANGELOG\.md
.
.P
\-b, \-\-base [NAME]
.
.P
Optional base file to append generated changes to\.
.
.P
\-\-bugs\-label [LABEL]
.
.P
Setup custom label for bug\-fixes section\. Default is "\fBFixed bugs:\fR
.
.P
\-\-enhancement\-label [LABEL]
.
.P
Setup custom label for enhancements section\. Default is "\fBImplemented enhancements:\fR"
.
.P
\-\-issues\-label [LABEL]
.
.P
Setup custom label for closed\-issues section\. Default is "\fBClosed issues:\fR"
.
.P
\-\-header\-label [LABEL]
.
.P
2017-12-13 21:06:00 +00:00
Setup custom header label\. Default is "# Changelog"
.
.P
2016-11-01 20:39:03 +00:00
\-\-front\-matter [JSON]
.
.P
Add YAML front matter\. Formatted as JSON because it\'s easier to add on the command line
.
.P
\-\-pr\-label [LABEL]
.
.P
Setup custom label for pull requests section\. Default is "\fBMerged pull requests:\fR"
.
.P
\-\-[no\-]issues
.
.P
Include closed issues in changelog\. Default is true
.
.P
\-\-[no\-]issues\-wo\-labels
.
.P
Include closed issues without labels in changelog\. Default is true
.
.P
\-\-[no\-]pr\-wo\-labels
.
.P
Include pull requests without labels in changelog\. Default is true
.
.P
\-\-[no\-]pull\-requests
.
.P
Include pull\-requests in changelog\. Default is true
.
.P
\-\-[no\-]filter\-by\-milestone
.
.P
Use milestone to detect when issue was resolved\. Default is true
.
.P
\-\-[no\-]author
.
.P
Add author of pull\-request in the end\. Default is true
.
.P
2016-11-01 20:39:03 +00:00
\-\-usernames\-as\-github\-logins
.
.P
Use GitHub tags instead of Markdown links for the author of an issue or pull\-request\.
.
.P
\-\-unreleased\-only
.
.P
Generate log from unreleased closed issues only\.
.
.P
\-\-[no\-]unreleased
.
.P
Add to log unreleased closed issues\. Default is true
.
.P
\-\-unreleased\-label [label]
.
.P
2016-11-04 21:53:49 +00:00
Setup custom label for unreleased closed issues section\. Default is "\fBUnreleased:\fR"
.
.P
\-\-[no\-]compare\-link
.
.P
Include compare link (Full Changelog) between older version and newer version\. Default is true
.
.P
\-\-include\-labels x,y,z
.
.P
Only issues with the specified labels will be included in the changelog\.
.
.P
\-\-exclude\-labels x,y,z
.
.P
Issues with the specified labels will be always excluded from changelog\. Default is \'duplicate,question,invalid,wontfix\'
.
.P
\-\-bug\-labels x,y,z
.
.P
Issues with the specified labels will be always added to "Fixed bugs" section\. Default is \'bug,Bug\'
.
.P
\-\-enhancement\-labels x,y,z
.
.P
Issues with the specified labels will be always added to "Implemented enhancements" section\. Default is \'enhancement,Enhancement\'
.
.P
\-\-exclude\-tags x,y,z
.
.P
2017-12-13 21:06:00 +00:00
Changelog will exclude specified tags
.
.P
2016-11-01 20:39:03 +00:00
\-\-exclude\-tags\-regex [REGEX]
.
.P
Apply a regular expression on tag names so that they can be excluded, for example: \-\-exclude\-tags\-regex "\.*+\ed{1,}"
.
.P
\-\-since\-tag x
.
.P
2017-12-13 21:06:00 +00:00
Changelog will start after specified tag
.
.P
\-\-due\-tag x
.
.P
2017-12-13 21:06:00 +00:00
Changelog will end before specified tag
.
.P
\-\-max\-issues [NUMBER]
.
.P
Max number of issues to fetch from GitHub\. Default is unlimited
.
.P
\-\-release\-url [URL]
.
.P
The URL to point to for release links, in printf format (with the tag as variable)\.
.
.P
\-\-github\-site [URL]
.
.P
The Enterprise Github site on which your project is hosted\.
.
.P
\-\-github\-api [URL]
.
.P
The enterprise endpoint to use for your Github API\.
.
.P
\-\-simple\-list
.
.P
Create simple list from issues and pull requests\. Default is false\.
.
.P
\-\-future\-release [RELEASE\-VERSION]
.
.P
Put the unreleased changes in the specified release number\.
.
.P
2016-11-01 20:39:03 +00:00
\-\-release\-branch [RELEASE\-BRANCH]
.
.P
Limit pull requests to the release branch, such as master or release
.
.P
\-\-http\-cache
.
.P
Use HTTP Cache to cache Github API requests (useful for large repos) Default is true\.
.
.P
\-\-[no\-]cache\-file [CACHE\-FILE]
.
.P
Filename to use for cache\. Default is github\-changelog\-http\-cache in a temporary directory\.
2016-11-01 20:39:03 +00:00
.
.P
\-\-cache\-log [CACHE\-LOG]
.
.P
Filename to use for cache log\. Default is github\-changelog\-logger\.log in a temporary directory\.
2016-11-01 20:39:03 +00:00
.
.IP "" 4
.
.nf
\-\-ssl\-ca\-file [PATH]
.
.fi
.
.IP "" 0
.
.P
Path to cacert\.pem file\. Default is a bundled lib/github_changelog_generator/ssl_certs/cacert\.pem\. Respects SSL_CA_PATH\.
.
.P
\-\-require file1\.rb,file2\.rb
.
.P
Paths to Ruby file(s) to require before generating changelog\.
.
2016-11-01 20:39:03 +00:00
.P
\-\-[no\-]verbose
.
.P
Run verbosely\. Default is true
.
.P
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]
.
.P
Define your own set of sections which overrides all default sections") do |v|
.
.P
\-\-add\-sections [HASH, STRING]
.
.P
Add new sections but keep the default sections"
.
.P
\-v, \-\-version
.
.P
Print version number
.
.P
\-h, \-\-help
.
.P
Displays Help
.
.SH "EXAMPLES"
.
.SH "AUTHOR"
Written by Petr Korolev sky4winder@gmail\.com
.
.SH "REPORTING BUGS"
<\fIhttps://github\.com/skywinder/github\-changelog\-generator/issues\fR>
.
.SH "SEE ALSO"
<\fIhttps://github\.com/skywinder/github\-changelog\-generator/\fR>