It's really simple!

If your git remote origin refers to your GitHub repo, then either…

• run github_changelog_generator in your project folder; OR
• run github_changelog_generator github_username/github_project from anywhere

You’ll get a pretty, markdown-formatted CHANGELOG.md file.

• user [USER]

  Username of the owner of target GitHub repo.

  • github_changelog_generator -u github_username

• project [PROJECT]

  Name of project on GitHub.

  • github_changelog_generator -u github_username -p github_project

• 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.

  • github_changelog_generator --token 1234567890abcdef

• date-format [FORMAT]

  Date format.

  Default: %Y-%m-%d

  For example, you can use US date format like this:

  • github_changelog_generator --date-format "%m/%d/%Y" It will output (11/06/2015).

• output [NAME]

  Output file. To print to STDOUT instead, use blank as path.

  Default: CHANGELOG.md

  • github_changelog_generator --output My_change_log_name.MD

• base [NAME]

  Optional base file to append generated changes to.

• header-label [LABEL]

  Set up custom header label.

  Default: "# Changelog"

• configure-sections [HASH, STRING]

  Define your own set of sections which overrides all default sections.

• add-sections [HASH, STRING]

  Add new sections but keep the default sections.

  For example, you can add a "Documentation updates" section for things labelled documentation:

  • github_changelog_generator --add-sections '{"documentation":{"prefix":"**Documentation updates:**","labels":["documentation"]}}'

• front-matter [JSON]

  Add YAML front matter. Formatted as JSON because it's easier to add on the command line.

• [no-]issues

  Include closed issues in changelog.

  Default: true

• [no-]issues-wo-labels

  Include closed issues without labels in changelog.

  Default: true

• [no-]pull-requests

  Include pull-requests in changelog.

  Default: true

• [no-]pr-wo-labels

  Include pull requests without labels in changelog.

  Default: true

• [no-]filter-by-milestone

  Use milestone to detect when issue was resolved.

  Default: true

• [no-]author

  Add author of pull request at the end.

  Default: true

• usernames-as-github-logins

  Use GitHub tags instead of Markdown links for the author of an issue or pull-request.

• unreleased-only

  Generate log from unreleased closed issues only.

• [no-]unreleased

  Add to log unreleased closed issues.

  Default: true

• unreleased-label [label]

  Set up custom label for unreleased closed issues section.

  Default: "Unreleased:"

• [no-]compare-link

  Include compare link (Full Changelog) between older version and newer version.

  Default: true

• include-labels x,y,z

  Of the labeled issues, only include the ones with the specified labels.

• exclude-labels x,y,z

  Issues with the specified labels will be excluded from changelog.

  Default: 'duplicate,question,invalid,wontfix'

• issue-line-labels x,y,z

  The specified labels will be shown in brackets next to each matching issue. Use "ALL" to show all labels. Example: Update README.md to include new stuff #213 [Documentation][Enhancement]

  Default: []

• exclude-tags x,y,z

  Changelog will exclude specified tags.

• exclude-tags-regex [REGEX]

  Apply a regular expression on tag names so that they can be excluded. Example: --exclude-tags-regex ".*\+\d{1,}"

• since-tag x

  Changelog will start after specified tag.

• due-tag x

  Changelog will end before specified tag.

• max-issues [NUMBER]

  Maximum number of issues to fetch from GitHub.

  Default: 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 where your project is hosted.

  • github_changelog_generator --github-site http(s)://[hostname]

• github-api [URL]

  The enterprise endpoint to use for your GitHub API.

  • github_changelog_generator --github-api http(s)://[hostname]/api/v3

• simple-list

  Create a simple list from issues and pull requests.

  Default: false

• future-release [RELEASE-VERSION]

  Put the unreleased changes in the specified release number.

  This will replace Unreleased section with the specified tag. Handy for generating change logs before tagging.

• 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: true

• [no-]cache-file [CACHE-FILE]

  Filename to use for cache.

  Default: github-changelog-http-cache in a temporary directory

• cache-log [CACHE-LOG]

  Filename to use for cache log.

  Default: github-changelog-logger.log in a temporary directory

• ssl-ca-file [PATH]

  Path to cacert.pem file.

  Default: 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.

• config-file .my_custom_special_config

  Path to configuration file, which otherwise defaults to ".github_changelog_generator".

• [no-]verbose

  Run verbosely.

  Default: true

• version

  Print version number.

• help

  Displays Help.

• breaking-label [LABEL]

  Set up custom label for breaking changes section.

  Default: "Breaking changes:"

• breaking-labels x,y,z

  Issues with these labels will be added to a new section, called "Breaking changes".

  Default: 'backwards-incompatible,breaking'

• enhancement-label [LABEL]

  Set up custom label for enhancements section.

  Default: "Implemented enhancements:"

• enhancement-labels x,y,z

  Issues with the specified labels will be added to "Implemented enhancements" section.

  Default: 'enhancement,Enhancement'

• bugs-label [LABEL]

  Set up custom label for bug-fixes section.

  Default: "Fixed bugs:"

• bug-labels x,y,z

  Issues with the specified labels will be added to "Fixed bugs" section.

  Default: 'bug,Bug'

• deprecated-label [LABEL]

  Set up custom label for deprecated section.

  Default: "Deprecated:"

• deprecated-labels x,y,z

  Issues with the specified labels will be added to a section called "Deprecated".

  Default: 'deprecated,Deprecated'

• removed-label [LABEL]

  Set up custom label for removed section.

  Default: "Removed:"

• removed-labels x,y,z

  Issues with the specified labels will be added to a section called "Removed".

  Default: 'removed,Removed'

• security-label [LABEL]

  Set up custom label for security section.

  Default: "Security:"

• security-labels x,y,z

  Issues with the specified labels will be added to a section called "Security fixes".

  Default: 'security,Security'

• issues-label [LABEL]

  Set up custom label for closed-issues section.

  Default: "Closed issues:"

• pr-label [LABEL]

  Set up custom label for pull requests section.

  Default: "Merged pull requests:"