Changelog generator based on github milestones or tags.
Latest commit 40212d1 Jan 16, 2017 @goanpeca goanpeca committed on GitHub Merge pull request #51 from goanpeca/feature/qc-ignore
PR: Update ignore file to ignore versioneer files
Failed to load latest commit information.
conda.recipe Update dependencies Dec 6, 2016
.checkignore Update ignore file Jan 17, 2017
.ciocheck Fix isort not detecting mimetypes Dec 15, 2016
.coveragerc Exclude checks for external folder Nov 3, 2016
.gitignore Add git ignore file Nov 3, 2016
LICENSE.txt Remove year Nov 3, 2016 Add versioneer Jan 16, 2017
README.rst Readme: Update AppVeyor badge because of move to org account Jan 16, 2017 Add release process Nov 3, 2016
circle.yml Update circleci deps Dec 15, 2016
setup.cfg Add versioneer Jan 16, 2017



Build status

Travis-CI build status Appveyor build status Circle-CI build status Code Coverage Quantified Code issues Scrutinizer Code Quality

Project information

License Latest PyPI version Join the chat at


Changelog generator based on milestone or tags for github.


Using pip

pip install loghub

Using conda

conda install loghub -c conda-forge


loghub can be used to generate changelog based on milestones or on tags.

In projects where milestones are used to track a release we can use for example:

loghub spyder-ide/spyder -m v3.0

In projects where milestones are used to track chunks of work but not releases, we can use tags to get the changes after the latest release, for example:

loghub spyder-ide/spyder -st v3.0.0b7

Or if loghub is used to generate old changelogs (or update changelogs), we can also use tags to limit the range , for example:

loghub spyder-ide/spyder -st v3.0.0b7 -ut v3.0.0

For private repos, just add the username and password arguments, for example:

loghub spyder-ide/spyder -st v3.0.0b7 -ut v3.0.0 -u <username> -p <password>

Or, just add the username and a password prompt will appear, for example:

loghub spyder-ide/spyder -st v3.0.0b7 -ut v3.0.0 -u <username>

Or generate a Github access token and use that instead, for example:

loghub spyder-ide/spyder -st v3.0.0b7 -ut v3.0.0 -t <token>


Because of the Github API rate limitations it is advised to always use authentication by either access token or user and password.

Advanced Usage

Filter PR base branch

Pull requests to display can be filtered depending on the branch they were merge against (base branch):

loghub spyder-ide/spyder -b 3.x

Filter issues/PRs by labels

To filter issues to display, we can use a regular expression:

loghub spyder-ide/spyder -ilr "Type.*" -m v3.1

This will filter all the issues that start with Type

The same can be done with PRs

loghub spyder-ide/spyder -ipr "<some-regex>" -m v3.1

Group issues by label

Issues displayed can be grouped by labels:

loghub spyder-ide/spyder -ilg "Type-Bug" "Bugs Fixed" "Type-Enhancement" "New Features" -m v3.1

This will result in issues being grouped in two sections with the headings Bugs Fixed and New Features respectively.

Output format

Loghub provides two formats:

  • 'changelog', which is the default and includes links to issues and PRs
  • 'release', which does not include links
loghub spyder-ide/spyder -m v3.1 -f release

Custom templates

Loghub uses Jinja2 templates to format the output. If the current template does not your needs, you can copy the default templates and create a new one and provide the path to it as:

loghub spyder-ide/spyder -m v3.1 --template <PATH_TO_TEMPLATE>

Detailed CLI arguments

usage: loghub [-h] [-m MILESTONE]
              [-ilg ISSUE_LABEL_GROUPS [ISSUE_LABEL_GROUPS ...]]
              [-ilr ISSUE_LABEL_REGEX] [-plr PR_LABEL_REGEX] [-st SINCE_TAG]
              [-ut UNTIL_TAG] [-b BRANCH] [-f OUTPUT_FORMAT]
              [--template TEMPLATE] [-u USER] [-p PASSWORD] [-t TOKEN]

Script to print the list of issues and pull requests closed in a given
milestone, tag including additional filtering options.

positional arguments:
  repository            Repository name to generate the Changelog for, in the
                        form user/repo or org/repo (e.g. spyder-ide/spyder)

optional arguments:
  -h, --help
                        Show this help message and exit

  -m MILESTONE, --milestone MILESTONE
                        Github milestone to get issues and pull requests for

  -st SINCE_TAG, --since-tag SINCE_TAG
                        Github issues and pull requests since tag

  -ut UNTIL_TAG, --until-tag UNTIL_TAG
                        Github issues and pull requests until tag

                        Groups the generated issues by the specified label.
                        This option takes 1 or 2 arguments, where the first one
                        is the label to match and the second one is the label
                        to print on the final output

  -ilr ISSUE_LABEL_REGEX, --issue-label-regex ISSUE_LABEL_REGEX
                        Label issue filter using a regular expression filter

  -plr PR_LABEL_REGEX, --pr-label-regex PR_LABEL_REGEX
                        Label pull requets filter using a regular expression

  -b BRANCH, --branch BRANCH
                        Filter merged PRs on base branch

                        Format for print, either 'changelog' (for
                        file) or 'release' (for the Github Releases page).
                        Default is 'changelog'. The 'release' option doesn't
                        generate Markdown hyperlinks.

  -te, --template TEMPLATE
                        Use a custom Jinja2 template file

  -u USER, --user USER
                        Github user name

  -p PASSWORD, --password PASSWORD
                        Github user password

  -t TOKEN, --token TOKEN
                        Github access token