gbp-dch(1)
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 ] [ [ -S | --snapshot ] [ -R | --release ] ] [ [ -a | --auto ] [ -s commitish | --since=commitish ] ] [ -N version | --new-version=version ] [ --bpo | --nmu | --qa | --security | --team ] [ --distribution=name ] [ --force-distribution ] [ -U level | --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|never|snapshot|release] ] [ --commit-msg=msg-format ] [ -c | --commit ] [ --customizations=customization-file ] [ --verbose ] [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 commit corresponding to 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". The above relies on the debian-branch option pointing to the current branch and upstream-branch pointing to the corresponding upstream branch in order to find the right merge points of these branches. Furthermore gbp dch must be able to identify git tags from upstream and Debian version numbers. If you're not using the defaults check the upstream-tag and debian-tag options.
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. This option can't
be set via gbp.conf.
--auto, -a
Guess the last commit documented in the changelog from the
snapshot banner (or from the last tag if no snapshot banner
exists). This option can't be set via gbp.conf.
--[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. This option can't be set via gbp.conf.
--new-version=version, -N version
Add a new changelog section with version newversion. Together
with --snapshot, the snapshot number will be appended to
newversion. This option can't be set via gbp.conf.
--team Create a Team upload changelog entry. This option can't be set
via gbp.conf.
--bpo Increment the Debian release number for an upload to backports,
and add a backport upload changelog comment. This option can't
be set via gbp.conf.
--nmu Increment the Debian release number for a non-maintainer
upload. This option can't be set via gbp.conf.
--qa Increment the Debian release number for a Debian QA Team upload,
and add a QA upload changelog comment. This option can't be set
via gbp.conf.
--security
Increment the Debian release number for a Debian Security Team
non-maintainer upload, and add a "Security Team upload"
changelog comment. This option can't be set via gbp.conf.
--distribution=name
Set the distribution field to name. This option can't be set
via gbp.conf.
--force-distribution
Force the distribution specified with --distribution to be used,
even if it doesn't match the list of known distributions. This
option can't be set via gbp.conf.
--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|never|snapshot|release]
Whether to spawn an editor: always, never, 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: Raphal Hertzog for the suggestion
Results in this debian/changelog entry:
* Document meta tags.
Thanks to Raphal 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>
31 December 2016 GBP-DCH(1)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
