Metadata-Version: 2.1
Name: gitchangelog
Version: 2.2.0
Summary: gitchangelog generates a changelog thanks to git log.
Home-page: http://github.com/vaab/gitchangelog
Author: Valentin LAB
Author-email: valentin.lab@kalysto.org
License: UNKNOWN
Description: ============
        gitchangelog
        ============
        
        .. image:: http://img.shields.io/pypi/v/gitchangelog.svg?style=flat
           :target: https://pypi.python.org/pypi/gitchangelog/
           :alt: Latest PyPI version
        
        .. image:: http://img.shields.io/pypi/dm/gitchangelog.svg?style=flat
           :target: https://pypi.python.org/pypi/gitchangelog/
           :alt: Number of PyPI downloads
        
        .. image:: http://img.shields.io/travis/vaab/gitchangelog/master.svg?style=flat
           :target: https://travis-ci.org/vaab/gitchangelog/
           :alt: Travis CI build status
        
        .. image:: http://img.shields.io/coveralls/vaab/gitchangelog/master.svg?style=flat
           :target: https://coveralls.io/r/vaab/gitchangelog
           :alt: Test coverage
        
        
        Translate commit message history to a changelog.
        
        
        Feature
        =======
        
        - fully driven by a small configuration file to match 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...)
        - templating system for easy tailoring your output (markdown, ReST, etc)
        - support straight and merging history.
        
        
        Requirements
        ============
        
        Each commit are tested regularly on Python 2.7 and Python 3.2.
        
        It should work on Linux/BSD/MacOSX and it should work under cygwin on Windows.
        
        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, these are the location
        checked in the given order (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)
        - 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 as 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.
        
        .. _sample configuration file: http://github.com/vaab/gitchangelog/blob/master/gitchangelog.rc.reference
        
        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`_.
        
        .. _changelog of the PyPI page: http://pypi.python.org/pypi/gitchangelog
        
        
        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.
        
        .. _mustache: http://mustache.github.io
        .. _pystache: https://pypi.python.org/pypi/pystache
        .. _mustache templates: http://mustache.github.io/mustache.5.html
        
        
        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.
        
        .. _mako: http://www.makotemplates.org
        
        
        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.
        
        
        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 and leave you as the 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 commit should pass the tests (to allow easy bisect)
        - each functionality/bugfix commit should contain the code, tests,
          and doc.
        - 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.
        
        
        License
        =======
        
        Copyright (c) 2012-2015 Valentin Lab.
        
        Licensed under the `BSD License`_.
        
        .. _BSD License: http://raw.github.com/vaab/gitchangelog/master/LICENSE
        
        Changelog
        =========
        
        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]
        
        
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control
Classifier: Programming Language :: Python :: 2.5
Classifier: Topic :: Software Development
Provides-Extra: Mako
Provides-Extra: test
Provides-Extra: Mustache
