doc/vcs-to-changelog.texi

   1 @node VCS To ChangeLog
   2 @section VCS To ChangeLog
   3
   4 @c Copyright (C) 2020 Free Software Foundation, Inc.
   5
   6 @c Permission is granted to copy, distribute and/or modify this document
   7 @c under the terms of the GNU Free Documentation License, Version 1.3 or
   8 @c any later version published by the Free Software Foundation; with no
   9 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
  10 @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
  11
  12 @cindex VCS To ChangeLog
  13 @findex vcs-to-changelog
  14
  15 Gnulib provides the @samp{vcs-to-changelog} module to generate an output
  16 similar to the GNU ChangeLog format from metadata of source control software
  17 such as git.  Here's an example of using @samp{vcs-to-changelog}:
  18
  19 @example
  20 build-aux/vcs_to_changelog.py <from_ref> <to_ref>
  21 @end example
  22
  23 where @code{<from_ref>} and @code{<to_ref>} refer to the range of commits to
  24 generate the output.
  25
  26 VCS To ChangeLog currently recognises changes in C source code and can traverse
  27 commits in git.  Additional source frontends and source control backends may be
  28 added to the module. @samp{vcs-to-changelog} takes the following optional
  29 arguments:
  30
  31 @itemize
  32 @item @code{-d}: Run the parser debugger, used for debugging
  33 @samp{vcs-to-changelog}
  34 @item @code{-q filename}: Load @var{filename} as the quirks file for the
  35 project.
  36 @end itemize
  37
  38 The quirks file is a python module that must minimally implement a
  39 @code{get_project_quirks} function that returns an object of type
  40 @code{ProjectQuirks} or its subclass.  The subclass may override the following
  41 members of @code{ProjectQuirks}:
  42
  43 @itemize @bullet
  44 @item @code{repo}: Specify the project repo source control.  The default value
  45 is @code{git}.
  46 @item @code{IGNORE_LIST}: A list of files to ignore in the changesets.
  47 @item @code{MACRO_QUIRKS}: A list of dictionary entries with indexes as
  48 @code{orig} and @code{sub} where @code{orig} is a Python regular expression
  49 pattern to match and @code{sub} is the substitution.
  50 @item @code{C_MACROS}: A list of C preprocessor macro definitions.
  51 @end itemize