This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

Use your commit log to make beautifull and configurable changelog file.

Feature

  • fully driven by a config file that can be tailored with your changelog policies. (see for example the sample configuration file)
  • filter out commits/tags based on regexp matching
  • refactor commit summary, or commit body on the fly with replace regexp
  • classify commit message into sections (ie: New, Fix, Changes…)
  • any output format supported thanks to templating, you can even choose your own preferred template engine (mako, mustache, full python …).
  • support your merge or rebase workflows and complicated git histories
  • support full or incremental changelog generation to match your needs.

Requirements

gitchangelog is compatible Python 2 and Python 3.

It should work on Linux/BSD/MacOSX and any help with Windows compatibility would be appreciated.

Please submit an issue if you encounter incompatibilies.

Sample

The default output is ReSTructured text, so it should be readable in ASCII.

Here is a small sample of the gitchangelog changelog at work.

Current git log output so you can get an idea of the log history:

* 59f902a Valentin Lab new: dev: sections in changelog are now in the order given in ``gitchangelog.rc`` in the ``section_regexps`` option.  (0.1.2)
* c6f72cc Valentin Lab chg: dev: commented code to toggle doctest mode.
* a9c38f3 Valentin Lab fix: dev: doctests were failing on this.
* 59524e6 Valentin Lab new: usr: added ``body_split_regexp`` option to attempts to format correctly body of commit.
* 5883f07 Valentin Lab new: usr: use a list of tuple instead of a dict for ``section_regexps`` to be able to manage order between section on find match.
* 7c1d480 Valentin Lab new: dev: new ``unreleased_version_label`` option in ``gitchangelog.rc`` to change label of not yet released code.
* cf29c9c Valentin Lab fix: dev: bad sorting of tags (alphanumerical). Changed to commit date sort.
* 61d8f80 Valentin Lab fix: dev: support of empty commit message.
* eeca31b Valentin Lab new: dev: use ``gitchangelog`` section in ``git config`` world appropriately.
* 6142b71 Valentin Lab chg: dev: cosmetic removal of trailing whitespaces
* 3c3edd5 Valentin Lab fix: usr: ``git`` in later versions seems to fail on ``git config <key>`` with errlvl 255, that was not supported.
* 3f9617d Valentin Lab fix: usr: removed Traceback when there were no tags at all in the current git repository.
* e0db9ae Valentin Lab new: usr: added section classifiers (ie: New, Change, Bugs) and updated the sample rc file.  (0.1.1)
* 0c66d59 Valentin Lab fix: dev: Fixed case where exception was thrown if two tags are on the same commit.
* d2fae0d Valentin Lab new: usr: added a succint ``--help`` support.

And here is the gitchangelog output:

0.1.2 (2011-05-17)
------------------

New
~~~

- Sections in changelog are now in the order given in ``git-
  changelog.rc`` in the ``section_regexps`` option. [Valentin Lab]

- Added ``body_split_regexp`` option to attempts to format correctly
  body of commit. [Valentin Lab]

- Use a list of tuple instead of a dict for ``section_regexps`` to be
  able to manage order between section on find match. [Valentin Lab]

- New ``unreleased_version_label`` option in ``gitchangelog.rc`` to
  change label of not yet released code. [Valentin Lab]

- Use ``gitchangelog`` section in ``git config`` world appropriately.
  [Valentin Lab]

Changes
~~~~~~~

- Commented code to toggle doctest mode. [Valentin Lab]

- Cosmetic removal of trailing whitespaces. [Valentin Lab]

Fix
~~~

- Doctests were failing on this. [Valentin Lab]

- Bad sorting of tags (alphanumerical). Changed to commit date sort.
  [Valentin Lab]

- Support of empty commit message. [Valentin Lab]

- ``git`` in later versions seems to fail on ``git config <key>`` with
  errlvl 255, that was not supported. [Valentin Lab]

- Removed Traceback when there were no tags at all in the current git
  repository. [Valentin Lab]

0.1.1 (2011-04-07)
------------------

New
~~~

- Added section classifiers (ie: New, Change, Bugs) and updated the
  sample rc file. [Valentin Lab]

- Added a succint ``--help`` support. [Valentin Lab]

Fix
~~~

- Fixed case where exception was thrown if two tags are on the same
  commit. [Valentin Lab]

And the rendered full result is directly used to generate the HTML webpage of the changelog of the PyPI page.

Usage

You need to place a gitchangelog.rc file somewhere, the recommended location is the root of the current git repository with the name .gitchangelog.rc. However you could put it elsewhere, and here are the locations checked (first match will prevail):

  • in the path given thanks to the environment variable GITCHANGELOG_CONFIG_FILENAME
  • in the path stored in git config’s entry gitchangelog.rc-path (which could be stored in system location or per repository)
  • (RECOMMENDED) in the root of the current git repository with the name .gitchangelog.rc

Then, you’ll be able to call gitchangelog in a GIT repository and it’ll print changelog on its standard output.

Configuration file format

The sample configuration file is quite heavily commented and is quite simple. You should be able to use it as required.

The changelog of gitchangelog is generated with himself and with the sample configuration file. You’ll see the output in the changelog of the PyPI page.

Output Engines

At the end of the configuration file, you’ll notice a variable called output_engine. By default, it’s set to rest_py, which is the legacy python engine to produce the ReSTructured Text output format that is shown in above samples. If this engine fits your needs, you won’t need to fiddle with this option.

To render the template, gitchangelog will generate a data structure that will then be rendered thanks to the output engine. This should help you get the exact output that you need.

As people might have different needs and knowledge, a templating system using mustache is available. mustache templates are provided to render both ReSTructured Text or markdown formats. If you know mustache templating, then you could easily add or modify these existing templates.

A mako templating engine is also provided. You’ll find also a mako template producing the same ReSTructured Text output than the legacy one. It’s provided for reference and/or further tweak if you would rather use mako templates.

Mustache

The mustache output engine uses mustache templates.

The mustache templates for gitchangelog are located in templates/mustache and are powered via pystache the python implementation of the mustache specifications. So mustache output engine will only be available if you have pystache module available in your python environment.

Mako

The makotemplate output engine templates for gitchangelog are located in templates/mako and are powered via mako python templating system. So mako output engine will only be available if you have mako module available in your python environment.

Changelog data tree

This is a sample of the current data structure sent to output engines:

{'title': 'Changelog',
 'versions': [{'label': '%%version%% (unreleased)',
               'date': None,
               'tag': None
               'sections': [{'label': 'Changes',
                             'commits': [{'author': 'John doe',
                                          'body': '',
                                          'subject': 'Adding some extra values.'},
                                         {'author': 'John Doe',
                                          'body': '',
                                          'subject': 'Some more changes'}]},
                            {'label': 'Other',
                             'commits': [{'author': 'Jim Foo',
                                          'body': '',
                                          'subject': 'classic modification'},
                                         {'author': 'Jane Done',
                                          'body': '',
                                          'subject': 'Adding some stuff to do.'}]}]},
              {'label': 'v0.2.5 (2013-08-06)',
               'date': '2013-08-06',
               'tag': 'v0.2.5'
               'sections': [{'commits': [{'author': 'John Doe',
                                          'body': '',
                                          'subject': 'Updating Changelog installation.'}],
                             'label': 'Changes'}]}]}

Merged branches history support

Commit attribution to a specific version could be tricky. Suppose you have this typical merge tree (spot the tags!):

* new: something  (HEAD, tag: 0.2, develop)
*   Merge tag '0.1.1' into develop
|\
| * fix: out-of-band hotfix  (tag: 0.1.1)
* | chg: continued development
|/
* fix: something  (tag: 0.1)
* first commit  (tag: 0.0.1, master)

Here’s a minimal draft of gitchangelog to show how commit are attributed to versions:

0.2
  * new: something.
  * Merge tag '0.1.1' into develop.
  * chg: continued development.

0.1.1
  * fix: out-of-band hotfix.

0.1
  * fix: something.

Note

you can remove automatically all merge commit from gitchangelog output by using include_merge = False in the .gitchangelog.rc file.

Use cases

No sectionning

If you want to remove sectionning but keep anything else, you should probably use:

section_regexps = [
    ('', None)
]

subject_process = (strip | ucfirst | final_dot)

This will disable sectionning and won’t remove the prefixes used for sectionning from the commit’s summary.

Incremental changelog

Also known as partial changelog generation, this feature allows to generate only a subpart of your changelog. Usually this makes sense:

  • When wanting to switch to gitchangelog, or change your conventions:
    • part of your history is not following conventions.
    • you have a previous CHANGELOG you want to blend in.
  • You’d rather commit your changelog file:
    • For performance reason, you can then generate changelog only for the new commit and save the result.
    • Because you want to be able to edit it to make some minor edition if needed.

You can use then gitchangelog show REVLIST. Examples follows:

## will output only tags between 0.0.2 (excluded) and 0.0.3 (included)
gitchangelog show 0.0.2..0.0.3

## will output only tags since 0.0.3 (excluded)
gitchangelog show ^0.0.3

## will output all tags up to 0.0.3 (included)
gitchangelog show 0.0.3

Contributing

Any suggestion or issue is welcome. Push request are very welcome, please check out the guidelines.

Push Request Guidelines

You can send any code. I’ll look at it and will integrate it myself in the code base while leaving you as the commit(s) author. This process can take time and it’ll take less time if you follow the following guidelines:

  • check your code with PEP8 or pylint. Try to stick to 80 columns wide.
  • separate your commits per smallest concern
  • each functionality/bugfix commit should contain the code, tests, and doc.
  • each commit should pass the tests (to allow easy bisect)
  • prior minor commit with typographic or code cosmetic changes are very welcome. These should be tagged in their commit summary with !minor.
  • the commit message should follow gitchangelog rules (check the git log to get examples)
  • if the commit fixes an issue or finished the implementation of a feature, please mention it in the summary.

If you have some questions about guidelines which is not answered here, please check the current git log, you might find previous commit that would show you how to deal with your issue. Otherwise, just send your PR and ask your question. I won’t bite. Promise.

License

Copyright (c) 2012-2015 Valentin Lab.

Licensed under the BSD License.

Changelog

2.4.0 (2015-11-10)

New

  • Add optional positional argument REVLIST to allow incremental changelog output (fixes #26) [Valentin Lab]

    See use cases documentations for more information.

2.3.0 (2015-09-25)

Fix

  • Nasty hidden bug that would break python3 (fixes #27) [Valentin Lab]

    Actually this bug was revealed by python3 random hashes (thanks to @rschoon for the hint) and could be reproduced on python2.7 with -R mode.

    The git show command actually will behave differently if given a tag reference and print random unexpected information before using the format string. This would prefix a lot of mess to the first field being asked in the format string.

    And this first field is dependent on the internal order of a dict, and this order is not important as such, and so nothing was done on this part.

    On python2.7, somehow, it would always be the same order that revealed to have no consequence (probably one of the rare field not used in current changelogs).

    Python3 or Python2.7 -R would shuffle this order and then trigger the error whenever this prefix would be appended to actually important fields that went into some further processing (as casted to int for the timestamp for instance).

2.2.1 (2015-06-09)

Fix

  • Fix: doc: ìnclude_merge options was wrongly typed in sample config files (reported by @tuukkamustonen, fixed #29). [Valentin Lab]

  • Updated doc to reflec that there are no support of windows for now. (fixes #28) [Valentin Lab]

    Actually windows will fail on subprocess call. (see #28)

  • Remove commit’s meta-information footer from changelog output. (fixes #25) [Valentin Lab]

    Some various tools (thinking of Gerrit) might leave some meta-information in the footer of your commit message’s body that you do not want to be repeated in your changelog. So all values in the footer are removed (This concerns Change-Id, Acked-by, CC, Signed-off-by, Bug … and any other value).

2.2.0 (2015-01-27)

New

  • Provide support for older config file format. [Valentin Lab]

  • Added ‘octobercms-plugin’ mako template. (fixes #16) [Valentin Lab]

  • Added body_process and subject_process options. (fixes #22) [Valentin Lab]

    These options superseeds replace_regexps and body_split_regexp as they provide a full control over text transformation of the subject or the body of the commit before they get included in the changelog.

  • Added include_merge option to filter out merge commit. [Casey Duquette]

Changes

  • Produce a more linear commit history (fixes #14) [Casey Duquette]

    Instead of retrieving the git log ordered by date, retrieve the log as a difference between tags to produce a more accurate view of changes between releases.

    For instance, imagine this git graph:

    * 6c0fd62 (HEAD, tag: sprint-6, origin/smoke, smoke, develop)
    *   5292a28 Merge back to develop
    |\
    | * 6612fce (tag: sprint-5.1, origin/master, origin/HEAD, master) super important hotfix
    * | 7d6286f more development work
    * | 8c1e3d6 continued development work
    * | fa3d4bd development work
    |/
    * ec1a19c (tag: sprint-5)
    

    Previously, commits fa3d4bd, 8c1e3d6, 7d6286f that occurred on the develop branch before the hotfix that led to tagging sprint-5.1, were captured in the changelog under release sprint-5.1 because of the order of the commits. But it is obvious that these commits were not included in a release until sprint-6. The new method of calculating the changelog will capture this and reflect it properly, assigning those changes to sprint-6.

Fix

  • Last commit was omitted (fixes #23). [Valentin Lab]

  • Bogus messages when template didn’t exist. [Valentin Lab]

    Refactored out the common code and corrected the bad error message.

  • Removed hypothetical memory exhaust while parsing git log. [Valentin Lab]

    Parse stdout as it’s produced by git log by chunks.

2.1.2 (2014-04-25)

Fix

  • Fail with error message when config path exists but is not a file. (fixes #11) [Casey Duquette]

    For example, the config file could be a directory.

2.1.1 (2014-04-15)

Fix

  • Removed exception if you had file which name that matched a tag’s name. (fixes #9) [Valentin Lab]

2.1.0 (2014-03-25)

New

  • Python3 compatibility. [Valentin Lab]

  • Much greater performance on big repository by issuing only one shell command for all the commits. (fixes #7) [Valentin Lab]

  • Add init argument to create a full .gitchangelog.rc in current git repository. [Valentin Lab]

  • Remove optional first argument that could specify the target git repository to consider. [Valentin Lab]

    This is to remove duplicate way to do things. gitchangelog should be run from within a git repository.

    Any usage of gitchangelog MYREPO can be written (cd MYREPO; gitchangelog).

  • Use a standard formatting configuration by default. [Valentin Lab]

    A default standard way of formatting is used if you don’t provide any configuration file. Additionaly, any option you define in your configuration file will be added “on-top” of the default configuration values. This can reduce config file size or even remove the need of one if you follow the standard.

    And, thus, you can tweak the standard for your needs by providing only partial configuration file. See tests for examples.

  • Remove user or system wide configuration file lookup. [Valentin Lab]

    This follows reflexion that you build a changelog for a repository and that the rules to make the changelog should definitively be explicit and thus belongs to the repository itself.

    Not a justification, but removing user and system wide configuration files also greatly simplifies testability.

Fix

  • Encoding issues with non-ascii chars. [Valentin Lab]

  • Avoid using pipes for windows compatibility and be more performant by avoiding to unroll full log to get the last commit. [Valentin Lab]

  • Better support of exotic features of git config file format. (fixes #4) [Valentin Lab]

    git config file format allows ambiguous keys:

    [a “b.c”]

    d = foo

    [a.b “c”]

    e = foo

    [a.b.c]

    f = foo

    Are all valid. So code was simplified to use directly git config. This simplification will deal also with cases where section could be attributed values:

    [a “b”]

    c = foo

    [a]

    b = foo

    By avoiding to parse the entire content of the file, and relying on git config implementation we ensure to remain compatible and not re-implement the parsing of this file format.

  • Gitchangelog shouldn’t fail if it fails to parse your git config. [Michael Hahn]

2.0.0 (2013-08-20)

New

  • Added a mako output engine with standard ReSTructured text format for reference. [Valentin Lab]
  • Added some information on path lookup scheme to find gitchangelog.rc configuration file. [Valentin Lab]
  • Added templating system and examples with mustache template support for restructured text and markdown output format. [David Loureiro]

Changes

  • Removed pkg and dev commits from default sample changelog output. [Valentin Lab]

Fix

  • Some error message weren’t written on stderr. [Valentin Lab]

1.1.0 (2012-05-03)

New

  • New config file lookup scheme which adds a new possible default location .gitchangelog.rc in the root of the git repository. [Valentin Lab]
  • Added a new section to get a direct visual of gitchangelog output. Reworded some sentences and did some other minor additions. [Valentin Lab]

Changes

  • Removed old gitchangelog.rc.sample in favor of the new documented one. [Valentin Lab]

Fix

  • The sample file was not coherent with the doc, and is now accepting ‘test’ and ‘doc’ audience. [Valentin Lab]

1.0.2 (2012-05-02)

New

  • Added a new sample file heavily documented. [Valentin Lab]

Fix

  • ignore_regexps where bogus and would match only from the beginning of the line. [Valentin Lab]
  • Display author date rather than commit date. [Valentin Lab]

0.1.2 (2011-05-17)

New

  • Added body_split_regexp option to attempts to format correctly body of commit. [Valentin Lab]
  • Use a list of tuple instead of a dict for section_regexps to be able to manage order between section on find match. [Valentin Lab]

Fix

  • git in later versions seems to fail on git config <key> with errlvl 255, that was not supported. [Valentin Lab]
  • Removed Traceback when there were no tags at all in the current git repository. [Valentin Lab]

0.1.1 (2011-04-07)

New

  • Added section classifiers (ie: New, Change, Bugs) and updated the sample rc file. [Valentin Lab]
  • Added a succint --help support. [Valentin Lab]
Release History

Release History

2.4.1

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.4.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.3.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.2.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.2.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.1.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.1.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
gitchangelog-2.4.1.tar.gz (42.0 kB) Copy SHA256 Checksum SHA256 Source Oct 14, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting