帮酷LOGO
0 0 评论
  • 显示原文与译文双语对照的内容
文章标签:变更记录  历史  GIT  log  Git Log  
Creates a changelog from git log history.

  • 源代码名称:gitchangelog
  • 源代码网址:http://www.github.com/vaab/gitchangelog
  • gitchangelog源代码文档
  • gitchangelog源代码下载
  • Git URL:
    git://www.github.com/vaab/gitchangelog.git
  • Git Clone代码到本地:
    git clone http://www.github.com/vaab/gitchangelog
  • Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/vaab/gitchangelog
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
    
  • gitchangelog Latest PyPI versionNumber of PyPI downloadsTravis CI build statusAppveyor CI build statusTest coverage

    使用提交日志来创建beautifull和可以配置日志文件文件。

    特性

    • 完全由一个配置文件驱动,可以用你的变更日志策略进行定制。 ( 参见参考配置文件 )
    • 根据正则表达式匹配筛选出提交/标记
    • 使用替换正则表达式重新构造提交摘要或者提交正文
    • 将提交消息分类为节( IE: 新建,修复,更改。
    • 支持模板的任何输出格式,你甚至可以选择你自己的首选模板引擎( mako,mustache,完全 python。)。
    • 支持你的合并或者rebase工作流和复杂的git历史
    • 支持完全或者增量的日志记录生成,以便 MATCH 你的需求。
    • 支持轻松访问拖车键值( 如果你使用它们)
    • 支持多个作者通过 Co-Authored-By拖车键值值进行一次提交。
    • 支持标准 python 安装或者dep免费单一可执行文件。 ( 最后一个特性还没有在 Windows 上完全免费使用)

    要求

    gitchangelog 兼容 Linux/BSD/MacOSX 和 Windows 上的python 2和 python 3。

    如果遇到不兼容问题,请提交问题。

    安装

    完整软件包

    Gitchangelog在PyPI上发布,因此:

    pip安装 gitchangelog

    "。是在任何平台上安装完整软件包的方式。

    如果你正在从源代码安装,请注意,开发工具还没有完全在 Windows 上工作。

    完整包提供了 gitchangelog.py 可执行文件,只要:

    • 为所有值提供系统宽默认值的引用配置文件
    • mustachemako 模板语言中的一些模板模板。 适合 Bootstrap的变化。

    来自源的

    如果你宁愿从源代码库工作,它支持在你的系统上安装它的通用习惯用法:

    python setup.py install

    注意,对于 linux/bsd,在源代码的root 中有一个指向可以执行文件的链接。 这是一种方便的方法来处理源代码版本。

    单一可以执行安装

    文件 gitchangelog.py 是完全吹出的可执行文件,无需任何其他文件即可使用。 这在 linux/bsd系统上更容易使用。 例如你可以键入:

    curl -sSL https://raw.githubusercontent.com/vaab/gitchangelog/master/src/gitchangelog/gitchangelog.py>/usr/local/bin/gitchangelog &&
    chmod +x/usr/local/bin/gitchangelog

    它将安装 gitchangelog 供所有用户访问,并将使用运行会话的默认 python 解释器。

    请注意:如果你选择在这个独立模式下安装它,那么你必须确保配置文件中的所有配置密钥。 作为一个好的开始,你应该复制引用配置文件( 如你在基本配置文件中所做的那样)。

    这是由于 gitchangelog 不能再到达引用配置文件来获得默认值。

    示例

    默认输出是重组的文本,所以它在ASCII中应该是可以读的。

    下面是 gitchangelog 变更日志的一个小示例。

    当前 git log 输出,这样你就可以了解日志历史记录的概念:

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

    下面是 gitchangelog 输出:

    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]

    呈现的完整结果直接用于生成PyPI页面的 changelog的HTML页面。

    用法

    gitchangelog 包中传递引用配置文件,并用于设置默认设置。 如果未安装包并使用独立文件,则 gitchangelog 可能无法访问这些默认值。 只要你在配置文件中提供了所有必需的值,这就不是问题。

    gitchangelog 文件的推荐位置是当前git存储库的root,带有 NAME .gitchangelog.rc。 你可以将它的放在其他位置,这里是选中的位置( 第一个 MATCH 将优先):

    • 在给定环境变量 GITCHANGELOG_CONFIG_FILENAME的情况下,
    • 在配置 gitchangelog.rc-path的git条目中存储的路径( 可以存储在系统位置或者每个存储库中)
    • ( 推荐) 使用 NAME .gitchangelog.rc 在当前git存储库的root 中

    然后,你可以在GIT存储库中调用 gitchangelog,它将在它的标准输出上打印变更日志。

    配置文件格式

    引用配置文件非常commented注释,并且非常简单。 你应该能够根据需要使用它。

    gitchangelog的变更日志由自己生成,并带有引用配置文件。 你将在PyPI页面的日志文件中看到输出。

    输出引擎

    在配置文件的末尾,你将看到一个名为 output_engine的变量。 默认情况下,它设置为 rest_py,它是产生重构文本输出格式的遗留 python 引擎,在 上面 示例中显示。 如果这个引擎适合你的需要,你就不需要摆弄这个选项。

    为了呈现模板,gitchangelog 将生成一个数据结构,该结构将根据输出引擎呈现。 这应该能帮助你得到你需要的精确输出。

    由于人们可能有不同的需求和知识,使用 mustache的模板化系统。 提供了 mustache 模板来呈现经过重组的文本或者 Markdown 格式。 如果你知道 mustache 模板,那么你可以轻松地添加或者修改这些现有模板。

    还提供了 mako 模板引擎。 你会发现 mako 模板产生的重构文本输出与传统模板相同。 如果你愿意使用 mako 模板,它提供了参考和/或者进一步的调整。

    mustache

    mustache 输出引擎使用 mustache 模板。

    通过 pystache插件( python 实现)的实现,可以使用mustache 插件模板。 因此,只有当你的python 环境中有 pystache插件 MODULE 时,才可以使用mustache 输出引擎。

    mustache 模板捆绑包,默认安装 gitchangelog。 可以通过向 mustache(..) output_engine提供一个简单的标签来调用这些,例如( 在你的.gitchangelog.rc 中):

    output_engine = mustache("markdown")

    或者可以通过指定绝对路径( 或者在默认情况下从项目的git顶部开始) 提供你自己的mustache 模板,或者如果设置了一个路径。 git config gitchangelog.template-path 在你的模板文件中,例如:

    output_engine = mustache(".gitchangelog.tpl")

    你可以随意复制捆绑的模板以作为你自己的变化的基础。 在源代码中,它们位于 src/gitchangelog/templates/mustache 目录,一旦安装,它们就在 templates/mustache 目录中,从安装 gitchangelog.py的位置开始。

    Mako Mako

    gitchangelogmakotemplate 输出引擎模板通过 mako python 模板系统供电。 因此,只有在你的环境中有 mako MODULE 时,才可以使用 mako。

    mako 模板与gitchangelog默认安装捆绑在一起。 可以通过向 makotemplate(..) output_engine提供一个简单的标签来调用这些,例如( 在你的.gitchangelog.rc 中):

    output_engine = makotemplate("markdown")

    或者可以通过指定绝对路径( 或者在默认情况下从项目的git顶部开始) 提供你自己的mustache 模板,或者如果设置了一个路径。 git config gitchangelog.template-path 在你的模板文件中,例如:

    output_engine = makotemplate(".gitchangelog.tpl")

    你可以随意复制捆绑的模板以作为你自己的变化的基础。 在源代码中,这些都位于 src/gitchangelog/templates/mako 目录中,一旦安装它们,它们就位于从你的gitchangelog.py 安装的templates/mako 目录。

    日志记录数据树

    这是发送到输出引擎的当前数据结构的示例:

    {'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'}]}]}
    合并分支历史记录支持

    对特定版本提交属性可能很棘手。 假设你有典型的合并树( 标记标签): !

    * 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)

    下面是gitchangelog的最小草稿,以说明提交是如何归因于版本的:

    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.

    便笺

    你可以使用 .gitchangelog.rc 文件中的include_merge = False 自动删除来自gitchangelog输出的所有合并提交。

    用例

    没有 sectionning

    如果要删除sectionning但保留其他任何内容,则应该使用:

    section_regexps = [
     ('', None)
    ]
    subject_process = (strip | ucfirst | final_dot)

    这将禁用 sectionning,并且不会从提交的摘要中删除sectionning所使用的前缀。

    增量更新日志

    功能也可以生成更新日志文件,并结合可以配置发布操作,你可以将结果文件插入到已有的变更日志中,从而生成变更日志文件。 这通常是有意义的:

    • 当希望 switch 到 gitchangelog 时,或者更改你的约定:
      • 你的历史部分没有遵循惯例。
      • 你有以前要合并的更新日志。
    • 你宁愿将更改提交到每个版本的日志文件文件中:
      • 出于性能原因,你可以只为新提交生成变更日志,并保存结果。
      • 因为你希望能够编辑它,以便在需要时进行一些次要版本。

    生成部分变更日志与 gitchangelog REVLIST 一样简单。 示例如下:

    ## will output only tags between 0.0.2 (excluded) and 0.0.3 (included)
    gitchangelog 0.0.2..0.0.3
    ## will output only tags since 0.0.3 (excluded)
    gitchangelog ^0.0.3 HEAD
    ## will output all tags up to 0.0.3 (included)
    gitchangelog 0.0.3

    另外,gitchangelog 可以自动找出哪个版本是( 用一些小小的帮助) 最后一个版本。 这是通过指定 revs 配置选项完成的。 这里配置文件选项将像在 命令行 上指定的那样使用。

    下面是一个符合当前变更日志格式的示例:

    revs = [
     Caret(
     FileFirstRegexMatch(
    "CHANGELOG.rst",
     r"(?P<rev>[0-9]+.[0-9]+(.[0-9]+))s+([0-9]+-[0-9]{2}-[0-9]{2})n--+n")),
    ]

    这将查看给定 正规表达式的第一个 MATCH的文件 CHANGELOG.rst,并将 rev 正规表达式 子模式的MATCH 作为字符串返回。 Caret 函数将只使用 ^ 前缀给给定的字符串。 因此,这里代码将阻止重新创建以前生成的变更日志部分( 有关 REVLIST语法插件的更多信息来自参数。)

    注意,如果没有通过命令行或者配置文件( 或者将REVLIST等效设置为 ["HEAD", ] ) 提供 REVLIST,那么提供给模板的数据结构将将 title 设置为 None。 这是一个让模板检测它的好方法。

    默认情况下,这将只输出到新的更新日志的新部分,你可以能希望直接在现有的更新中插入。 这是 publish 参数帮助你的地方。 默认情况下它设置为 stdout,你可能希望将它的设置为:

    publish = FileInsertIntoFirstRegexMatch(
    "CHANGELOG.rst",
     r'/(?P<rev>[0-9]+.[0-9]+(.[0-9]+)?)s+([0-9]+-[0-9]{2}-[0-9]{2})n--+n/',
     idx=lambda m: m.start(1)
    )

    完整的配方可能是:

    OUTPUT_FILE ="CHANGELOG.rst"
    INSERT_POINT = r"b(?P<rev>[0-9]+.[0-9]+)s+([0-9]+-[0-9]{2}-[0-9]{2})n--+n"
    revs = [
     Caret(FileFirstRegexMatch(OUTPUT_FILE, INSERT_POINT)),
    "HEAD"
    ]
    action = FileInsertAtFirstRegexMatch(
     OUTPUT_FILE, INSERT_POINT,
     idx=lambda m: m.start(1)
    )

    或者,使用 FileRegexSubst 可以使用它的他菜谱,如果已经生成了新的提交或者修改了新提交,则添加新的优势。

    OUTPUT_FILE ="CHANGELOG.rst"
    INSERT_POINT_REGEX = r'''(?isxu)
    ^
    (
     s*Changelogs*(n|rn|r) ## ``Changelog`` line
     ==+s*(n|rn|r){2} ## ``=========`` rest underline
    )
    ( ## Match all between changelog and release rev
     (
     (?!
     (?<=(n|r)) ## look back for newline
     %(rev)s ## revision
     s+
     ([0-9]+-[0-9]{2}-[0-9]{2})(n|rn|r) ## date
     --+(n|rn|r) ## ``---`` underline
     )
    . 
     )*
    )
    (?P<rev>%(rev)s)
    ''' % {'rev': r"[0-9]+.[0-9]+(.[0-9]+)?"}
    revs = [
     Caret(FileFirstRegexMatch(OUTPUT_FILE, INSERT_POINT_REGEX)),
    "HEAD"
    ]
    publish = FileRegexSubst(OUTPUT_FILE, INSERT_POINT_REGEX, r"1og<rev>")

    下面是 mustache Markdown 格式的一个示例:

    OUTPUT_FILE ="CHANGELOG.rst"
    INSERT_POINT_REGEX = r'''(?isxu)
    ^
    (
     s*#s+Changelogs*(n|rn|r) ## ``Changelog`` line
    )
    ( ## Match all between changelog and release rev
     (
     (?!
     (?<=(n|r)) ## look back for newline
     ##s+%(rev)s ## revision
     s+
     ([0-9]+-[0-9]{2}-[0-9]{2})(n|rn|r) ## date
     )
    . 
     )*
    )
    (?P<tail>##s+(?P<rev>%(rev)s))
    ''' % {'rev': r"[0-9]+.[0-9]+(.[0-9]+)?"}
    revs = [
     Caret(FileFirstRegexMatch(OUTPUT_FILE, INSERT_POINT_REGEX)),
    "HEAD"
    ]
    publish = FileRegexSubst(OUTPUT_FILE, INSERT_POINT_REGEX, r"1ong<tail>")

    欢迎任何建议或者问题。 推送请求非常欢迎,请查看指南。

    请求指南

    你可以发送任何代码。 我将看到它并将它自己集成在代码库中,并将它的作为提交作者。 如果遵循以下准则,这里过程可能需要花费时间,并且将花费更少的时间:

    • 使用PEP8或者pylint检查代码。 尝试 stick 80列。
    • 每个最小关注点分隔提交
    • 每个功能/修正的提交应该包含代码。测试和文档。
    • 每个提交都应该通过测试( 允许很容易地进行
    • prior或者代码修饰的次要承诺是非常受欢迎的。 应该在 minor的提交摘要中标记它们。!
    • 提交消息应遵循gitchangelog规则( 检查git日志以获得示例)
    • 如果提交修复了某个问题或者完成了某个特性的实现,请在摘要中提到它。

    如果你有关于这里未回答的指南的问题,请检查当前的git log,你可能会发现如何处理问题。 否则,只要发送你的公关并询问你的问题。 我不会咬的。

    许可证

    版权所有( c ) 2012 -2015 Valentin实验室。

    许可证在 BSD许可协议下。



    文章标签:GIT  log  历史  变更记录  Git Log  

    Copyright © 2011 HelpLib All rights reserved.    知识分享协议 京ICP备05059198号-3  |  如果智培  |  酷兔英语