xenial (1) gbp-dch.1.gz

Provided by: git-buildpackage_0.7.2_all bug

NAME

       gbp-dch - Generate the Debian changelog from git commit messages

SYNOPSIS

       gbp  dch [ --version ] [ --help ] [ --verbose ] [ --color=[auto|on|off] ] [ --color-scheme=COLOR_SCHEME ]
       [  --debian-branch=branch_name  ]  [  --debian-tag=tag-format  ]  [  --upstream-branch=branch_name  ]   [
       --upstream-tag=tag-format ] [ --ignore-branch ] [ --snapshot | --release ] [ --auto | --since=commitish ]
       [ --new-version=version ] [ --bpo |  --nmu  |  --qa  |  --team  ]  [  --distribution=name  ]  [  --force-
       distribution  ]  [  --urgency=level  ] [ --[no-]full ] [ --[no-]meta ] [ --meta-closes=bug-close-tags ] [
       --meta-closes-bugnum=bug-number-format ] [ --snapshot-number=expression ] [ --id-length=number ] [ --git-
       log=git-log-options  ] [ --[no-]git-author ] [ --[no-]multimaint ] [ --[no-]multimaint-merge ] [ --spawn-
       editor=[always|snapshot|release]    ]    [    --commit-msg=msg-format    ]     [     --commit     ]     [
       --customizations=customization-file ] [path1 path2]

DESCRIPTION

       gbp  dch reads git commit messages and generates the Debian changelog from it. If no arguments are given,
       gbp dch starts from the last tagged Debian package version up to the current tip of the  current  branch.
       If  the distribution of the topmost section in debian/changelog is UNRELEASED, the changelog entries will
       be inserted into this section. Otherwise, a new section will be created.

       If --auto is given gbp dch, tries to guess the last Git commit documented in the changelog  -  this  only
       works  in snapshot mode. Otherwise, --since can be used to tell gbp dch at which point it should start in
       the Git history.

       The additional path arguments can be used to restrict the repository paths gbp dch looks at. Setting path
       to  debian/  is a good choice if upstream uses Git and all Debian packaging changes are restricted to the
       debian/ subdir. In more sophisticated cases (like backports), you  can  use  --git-log  to  restrict  the
       generated changelog entries further, e.g. by using --git-log="--author=Foo Bar".

OPTIONS

       --version
              Print version of the program, i.e. version of the git-buildpackage suite

       -v

       --verbose
              Verbose execution

       -h

       --help Print help and exit

       --color=[auto|on|off]
              Whether to use colored output.

       --color-scheme=COLOR_SCHEME
              Colors   to   use   in   output   (when   color  is  enabled).  The  format  for  COLOR_SCHEME  is
              '<debug>:<info>:<warning>:<error>'.  Numerical values and color names are accepted,  empty  fields
              imply  the default color. For example, --git-color-scheme='cyan:34::' would show debug messages in
              cyan, info messages in blue and other messages in default (i.e.  warning  and  error  messages  in
              red).

       --debian-branch=branch_name
              The branch in the Git repository the Debian package is being developed on, default is master.

       --upstream-branch=branch_name
              Branch to determine the upstream version from.  Default is upstream.

       --git-upstream-tag=TAG-FORMAT
              use this tag format when looking for tags of upstream versions, default is upstream/%(version)s.

       --ignore-branch
              Don't check if the current branch matches debian-branch.

       --debian-tag=tag-format
              tag format used, when tagging debian versions, default is debian/%(version)s

       --since=committish
              Start reading commit messages at committish.

       --auto, -a
              Guess  the  last commit documented in the changelog from the snapshot banner (or from the last tag
              if no snapshot banner exists).

       --[no-]meta
              Parse meta tags like Closes:, Thanks: and Gbp-Dch:. See META TAGS below.

       --meta-closes=bug-close-tags
              What meta tags to look for to generate bug-closing changelog entries.  The default is  'Closes|LP'
              to support Debian and Launchpad.

       --meta-closes-bugnum=bug-number-format
              What   regular  expression  should  be  used  to  parse  out  the  bug  number.   The  default  is
              '(?:bug|issue)?\#?\s?\d+'. Note: the regex should suppress all portions of the bug number that are
              not wanted using "(?:)", see Python regex manual for details.

              Example: --meta-closes-bugnum="(?:bug)?\s*ex-\d+" would match all of the following:

                               Possible Txt  Match?    Result
                               ------------  ------    ------
                               bug EX-12345    Y       EX-12345
                               ex-01273        Y       ex-01273
                               bug ex-1ab      Y       ex-1
                               EX--12345       N

       --[no-]full
              Include the full commit message in the changelog output.

       --snapshot, -S
              Create  a  snapshot release entry. This adds a snapshot release number and a warning banner to the
              changelog entry. The release version number is being auto  incremented  with  every  new  snapshot
              release to avoid packages downgrades during snapshot testing.

       --snapshot-number=expression
              Python expression that gets eval()ed to the new snapshot number.

       --release, -R
              Remove  any  snapshot  release  banners  and  version  suffixes,  set  the current distribution to
              unstable, and open the changelog for final tweaking.

       --new-version=version, -N version
              Add a new changelog section with version newversion. Together with --snapshot, the snapshot number
              will be appended to newversion.

       --team Create a Team upload changelog entry.

       --bpo  Increment  the  Debian  release  number  for  an  upload  to  backports, and add a backport upload
              changelog comment.

       --nmu  Increment  the  Debian  release  number  for a non-maintainer upload.

       --qa   Increment the Debian release number for a Debian QA Team upload, and add  a  QA  upload  changelog
              comment.

       --distribution=name
              Set the distribution field to name.

       --force-distribution
              Force the distribution specified with --distribution to be used, even if it doesn't match the list
              of known distributions.

       --urgency=level
              Set the urgency field to level.

       --git-log=git-log-options
              Options passed on verbatim to git-log(1).

       --id-length=N
              Include N digits of the commit id in the changelog entry. Default is to not include any commit ids
              at all.

       --ignore-regex=regex
              Ignore commit lines matching regex when generating the changelog.

       --git-author
              Use user.name and user.email from git-config(1) for changelog trailer.

       --[no-]multimaint-merge
              Merge commits by maintainer.

       --spawn-editor=[always|snapshot|release]
              Whether to spawn an editor: always, when doing snapshots or when doing a release.

       --commit-msg=msg-format
              use  this  format string for the commit message when committing the generated changelog file (when
              --commit is given).  Default is Update changelog for %(version)s release

       --commit
              Commit the generated changelog.

       --customizations=customization-file
              Load Python code from customization-file.  At the moment, the only useful thing the code can do is
              define a custom format_changelog_entry() function.

SNAPSHOT MODE

       Snapshot mode can be used for quick test and install cycles without having to worry about version numbers
       or changelog entries.

       When using --snapshot or -S, gbp dch uses a pseudo header in the Debian changelog to  remember  the  last
       git   commit   it   added   a   changelog   entry   for.   It  also  sets  a  version  number  ending  in
       ~<snaspshotnumber>.gbp<commitid>.   It  automatically  increments  the  snapshot  number  on   subsequent
       invocations  of  gbp  dch -S so that later snapshots automatically have a higher version number. To leave
       snapshot mode, invoke gbp dch with the --release option. This removes the pseudo header and unmangles the
       version number so the released version has a higher version number than the snapshots.

META TAGS

       Additional to the above options, the formatting of the commit message in debian/changelog can be modified
       by special tags (called Meta Tags) given in the git commit message. Meta Tag processing can be  activated
       via  the --meta option. The tags must start at the first column of a commit message but can appear on any
       line.  They are of the form Tagname: value. Valid Meta Tags are:

          Gbp-Dch: action
              Supported actions are: Ignore which will ignore  this  commit  when  generating  debian/changelog,
              Short  which  will only use the description (the first line) of the commit message when generating
              the changelog entry (useful when --full is given), and Full which will use the full commit message
              when generating the changelog entry (useful when --full is not given).

              In addition to Gbp-Dch, the deprecated Git-Dch is still supported.

       Thanks: msg
              Add a thanks message after the commit message.

       Closes: bugnumber
              Indicate  in the debian/changelog that the bug was closed by this commit. See the --meta-closes on
              how to extend this for other bugtrackers.

       The following git commit message:

             Document meta tags

             so one doesn't have to consult the manual

             Gbp-Dch: Short
             Closes: #636088
             Thanks: Raphaël Hertzog for the suggestion

       Results in this debian/changelog entry:

             * Document meta tags.
               Thanks to Raphaël Hertzog for the suggestion (Closes: #636088)

CONFIGURATION FILES

       Several gbp.conf files are parsed  to  set  defaults  for  the  above  command-line  arguments.  See  the
       gbp.conf(5)> manpage for details.

SEE ALSO

       gbp-buildpackage(1)>,   gbp-import-dsc(1)>,   gbp-import-dscs(1)>,   gbp-import-orig(1)>,   gbp.conf(5)>,
       debuild(1),  git(1),  pristine-tar(1),  The   Git-Buildpackage   Manual   <URL:file:///usr/share/doc/git-
       buildpackage/manual-html/index.html> Cl2vcs <URL:https://honk.sigxcpu.org/cl2vcs>,

AUTHOR

       Guido Guenther <agx@sigxcpu.org>

                                                 29 January 2016                                      GBP-DCH(1)