123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543 |
- <refentry id="man.gbp.dch">
- <refentryinfo>
- <address>
- &dhemail;
- </address>
- <author>
- &dhfirstname;
- &dhsurname;
- </author>
- </refentryinfo>
- <refmeta>
- <refentrytitle>gbp-dch</refentrytitle>
- &dhsection;
- </refmeta>
- <refnamediv>
- <refname>gbp-dch</refname>
- <refpurpose>Generate the &debian; changelog from git commit messages</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <cmdsynopsis>
- &gbp-dch;
- &man.common.options.synopsis;
- <arg><option>--debian-branch=</option><replaceable>branch_name</replaceable></arg>
- <arg><option>--debian-tag=</option><replaceable>tag-format</replaceable></arg>
- <arg><option>--upstream-branch=</option><replaceable>branch_name</replaceable></arg>
- <arg><option>--upstream-tag=</option><replaceable>tag-format</replaceable></arg>
- <arg><option>--ignore-branch</option></arg>
- <group>
- <arg><option>--snapshot</option></arg>
- <arg><option>--release</option></arg>
- </group>
- <group>
- <arg><option>--auto</option></arg>
- <arg><option>--since=</option><replaceable>commitish</replaceable></arg>
- </group>
- <arg><option>--new-version=</option><replaceable>version</replaceable></arg>
- <group>
- <arg><option>--bpo</option></arg>
- <arg><option>--nmu</option></arg>
- <arg><option>--qa</option></arg>
- <arg><option>--team</option></arg>
- </group>
- <arg><option>--distribution=</option><replaceable>name</replaceable></arg>
- <arg><option>--force-distribution</option></arg>
- <arg><option>--urgency=</option><replaceable>level</replaceable></arg>
- <arg><option>--[no-]full</option></arg>
- <arg><option>--[no-]meta</option></arg>
- <arg><option>--meta-closes=bug-close-tags</option></arg>
- <arg><option>--meta-closes-bugnum=bug-number-format</option></arg>
- <arg><option>--snapshot-number=</option><replaceable>expression</replaceable></arg>
- <arg><option>--id-length=</option><replaceable>number</replaceable></arg>
- <arg><option>--git-log=</option><replaceable>git-log-options</replaceable></arg>
- <arg><option>--[no-]git-author</option></arg>
- <arg><option>--[no-]multimaint</option></arg>
- <arg><option>--[no-]multimaint-merge</option></arg>
- <arg><option>--spawn-editor=[always|snapshot|release]</option></arg>
- <arg><option>--commit-msg=</option><replaceable>msg-format</replaceable></arg>
- <arg><option>--commit</option></arg>
- <arg><option>--customizations=</option><replaceable>customization-file</replaceable></arg>
- <arg choice="plain"><replaceable>[path1 path2]</replaceable></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
- <refsect1>
- <title>DESCRIPTION</title>
- <para>
- &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
- <filename>debian/changelog</filename> is <emphasis>UNRELEASED</emphasis>,
- the changelog entries will be inserted into this section. Otherwise, a new
- section will be created.
- </para>
- <para>
- If <option>--auto</option> is given &gbp-dch;, tries to guess the
- last &git; commit documented in the changelog - this only works in snapshot
- mode. Otherwise, <option>--since</option> can be used to tell &gbp-dch;
- at which point it should start in the &git; history.
- </para>
- <para>
- The additional path arguments can be used to restrict the repository paths
- &gbp-dch; looks at. Setting <replaceable>path</replaceable> to
- <emphasis>debian/</emphasis> is a good choice if upstream uses &git; and
- all Debian packaging changes are restricted to the
- <replaceable>debian/</replaceable> subdir. In more sophisticated cases
- (like backports), you can use <option>--git-log</option> to restrict the
- generated changelog entries further, e.g. by using
- <option>--git-log=</option><replaceable>"--author=Foo Bar"</replaceable>.
- </para>
- </refsect1>
- <refsect1>
- <title>OPTIONS</title>
- <variablelist>
- &man.common.options.description;
- <varlistentry>
- <term><option>--debian-branch</option>=<replaceable>branch_name</replaceable>
- </term>
- <listitem>
- <para>
- The branch in the Git repository the Debian package is being
- developed on, default is <replaceable>master</replaceable>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--upstream-branch</option>=<replaceable>branch_name</replaceable>
- </term>
- <listitem>
- <para>
- Branch to determine the upstream version from.
- Default is <replaceable>upstream</replaceable>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--git-upstream-tag=</option><replaceable>TAG-FORMAT</replaceable>
- </term>
- <listitem>
- <para>
- use this tag format when looking for tags of upstream versions,
- default is <replaceable>upstream/%(version)s</replaceable>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--ignore-branch</option>
- </term>
- <listitem>
- <para>
- Don't check if the current branch matches
- <replaceable>debian-branch</replaceable>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--debian-tag=</option><replaceable>tag-format</replaceable>
- </term>
- <listitem>
- <para>
- tag format used, when tagging debian versions,
- default is <replaceable>debian/%(version)s</replaceable>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--since=</option><replaceable>committish</replaceable>
- </term>
- <listitem>
- <para>
- Start reading commit messages at
- <replaceable>committish</replaceable>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--auto</option>,
- <option>-a</option></term>
- <listitem>
- <para>
- Guess the last commit documented in the changelog from the
- snapshot banner (or from the last tag if no snapshot banner exists).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--[no-]meta</option></term>
- <listitem>
- <para>
- Parse meta tags like <option>Closes:</option>,
- <option>Thanks:</option> and <option>Gbp-Dch:</option>. See META TAGS
- below.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--meta-closes=</option><replaceable>bug-close-tags</replaceable>
- </term>
- <listitem>
- <para>
- What meta tags to look for to generate bug-closing changelog entries.
- The default is <literal>'Closes|LP'</literal> to support Debian and Launchpad.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--meta-closes-bugnum=</option><replaceable>bug-number-format</replaceable>
- </term>
- <listitem>
- <para>
- What regular expression should be used to parse out the bug number.
- The default is <literal>'(?:bug|issue)?\#?\s?\d+'</literal>. Note: the regex should
- suppress all portions of the bug number that are not wanted using
- <literal>"(?:)"</literal>, see Python regex manual for details.
- </para>
- <para>
- Example:
- <option>--meta-closes-bugnum=</option><literal>"(?:bug)?\s*ex-\d+"</literal>
- would match all of the following:
- <screen>
- Possible Txt Match? Result
- ------------ ------ ------
- bug EX-12345 Y EX-12345
- ex-01273 Y ex-01273
- bug ex-1ab Y ex-1
- EX--12345 N</screen>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--[no-]full</option>
- </term>
- <listitem>
- <para>
- Include the full commit message in the changelog output.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--snapshot</option>,
- <option>-S</option></term>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--snapshot-number=</option><replaceable>expression</replaceable>
- </term>
- <listitem>
- <para>
- Python expression that gets eval()ed to the new snapshot number.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--release</option>,
- <option>-R</option></term>
- <listitem>
- <para>
- Remove any snapshot release banners and version suffixes, set
- the current distribution to <replaceable>unstable</replaceable>, and
- open the changelog for final tweaking.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--new-version=</option><replaceable>version</replaceable>,
- <option>-N</option> <replaceable>version</replaceable>
- </term>
- <listitem>
- <para>
- Add a new changelog section with version
- <replaceable>newversion</replaceable>. Together with
- <option>--snapshot</option>, the snapshot number will be appended to
- <replaceable>newversion</replaceable>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--team</option>
- </term>
- <listitem>
- <para>
- Create a Team upload changelog entry.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--bpo</option>
- </term>
- <listitem>
- <para>
- Increment the Debian release number for an upload to backports, and
- add a backport upload changelog comment.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--nmu</option>
- </term>
- <listitem>
- <para>
- Increment the Debian release number for a non-maintainer upload.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--qa</option>
- </term>
- <listitem>
- <para>
- Increment the Debian release number for a Debian QA Team upload, and
- add a QA upload changelog comment.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--distribution=</option><replaceable>name</replaceable>
- </term>
- <listitem>
- <para>
- Set the distribution field to <replaceable>name</replaceable>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--force-distribution</option>
- </term>
- <listitem>
- <para>
- Force the distribution specified with <option>--distribution</option>
- to be used, even if it doesn't match the list of known distributions.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--urgency=</option><replaceable>level</replaceable>
- </term>
- <listitem>
- <para>
- Set the urgency field to <replaceable>level</replaceable>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--git-log=</option><replaceable>git-log-options</replaceable>
- </term>
- <listitem>
- <para>
- Options passed on verbatim to git-log(1).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--id-length=</option><replaceable>N</replaceable>
- </term>
- <listitem>
- <para>
- Include <replaceable>N</replaceable> digits of the commit id in the
- changelog entry. Default is to not include any commit ids at all.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--ignore-regex=</option><replaceable>regex</replaceable>
- </term>
- <listitem>
- <para>
- Ignore commit lines matching <replaceable>regex</replaceable>
- when generating the changelog.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--git-author</option>
- </term>
- <listitem>
- <para>
- Use user.name and user.email from
- <application>git-config</application>(1) for changelog trailer.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--[no-]multimaint-merge</option>
- </term>
- <listitem>
- <para>
- Merge commits by maintainer.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--spawn-editor=<replaceable>[always|snapshot|release]</replaceable></option>
- </term>
- <listitem>
- <para>
- Whether to spawn an editor: always, when doing snapshots or when
- doing a release.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--commit-msg=</option><replaceable>msg-format</replaceable>
- </term>
- <listitem>
- <para>
- use this format string for the commit message when committing the
- generated changelog file (when <option>--commit</option> is given).
- Default is
- <replaceable>Update changelog for %(version)s release</replaceable>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--commit</option>
- </term>
- <listitem>
- <para>
- Commit the generated changelog.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--customizations=</option><replaceable>customization-file</replaceable>
- </term>
- <listitem>
- <para>
- Load Python code from <replaceable>customization-file</replaceable>.
- At the moment, the only useful thing the code can do is define a
- custom format_changelog_entry() function.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Snapshot mode</title>
- <para>
- Snapshot mode can be used for quick test and install cycles without
- having to worry about version numbers or changelog entries.
- </para>
- <para>
- When using <option>--snapshot</option> or <option>-S</option>, &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
- <replaceable>~<snaspshotnumber>.gbp<commitid></replaceable>.
- It automatically increments the snapshot number on subsequent invocations
- of &gbp-dch; <option>-S</option> so that later snapshots automatically
- have a higher version number. To leave snapshot mode, invoke &gbp-dch;
- with the <option>--release</option> option. This removes the pseudo
- header and unmangles the version number so the released version has a
- higher version number than the snapshots.
- </para>
- </refsect1>
- <refsect1>
- <title>META TAGS</title>
- <para>
- Additional to the above options, the formatting of the commit message
- in <filename>debian/changelog</filename> can be modified by special tags
- (called Meta Tags)
- given in the git commit message. Meta Tag processing can be activated via
- the <option>--meta</option> option. The tags must start at the first column of
- a commit message but can appear on any line.
- They are of the form <option>Tagname</option>:
- <replaceable>value</replaceable>. Valid Meta Tags are:
- </para>
- <variablelist>
- <varlistentry>
- <term>
- <option>Gbp-Dch</option>: <replaceable>action</replaceable>
- </term>
- <listitem>
- <para>
- Supported actions are: <replaceable>Ignore</replaceable>
- which will ignore this commit when
- generating <filename>debian/changelog</filename>,
- <replaceable>Short</replaceable> which will only use the
- description (the first line) of the commit message when
- generating the changelog entry (useful
- when <option>--full</option> is given), and
- <replaceable>Full</replaceable> which will use the full
- commit message when generating the changelog entry (useful
- when <option>--full</option> is not given).
- </para>
- <para>
- In addition to <option>Gbp-Dch</option>, the
- deprecated <option>Git-Dch</option> is still supported.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>Thanks</option>: <replaceable>msg</replaceable>
- </term>
- <listitem>
- <para>
- Add a thanks message after the commit message.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>Closes</option>: <replaceable>bugnumber</replaceable>
- </term>
- <listitem>
- <para>
- Indicate in the <filename>debian/changelog</filename> that the bug
- was closed by this commit. See the <option>--meta-closes</option> on
- how to extend this for other bugtrackers.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- The following git commit message:
- </para>
- <screen>
- Document meta tags
- so one doesn't have to consult the manual
- Gbp-Dch: Short
- Closes: #636088
- Thanks: Raphaël Hertzog for the suggestion
- </screen>
- <para>
- Results in this <filename>debian/changelog</filename> entry:
- </para>
- <screen>
- * Document meta tags.
- Thanks to Raphaël Hertzog for the suggestion (Closes: #636088)
- </screen>
- </refsect1>
- <refsect1>
- &man.gbp.config-files;
- </refsect1>
- <refsect1>
- <title>SEE ALSO</title>
- <para>
- <xref linkend="man.gbp.buildpackage"/>,
- <xref linkend="man.gbp.import.dsc"/>,
- <xref linkend="man.gbp.import.dscs"/>,
- <xref linkend="man.gbp.import.orig"/>,
- <xref linkend="man.gbp.conf"/>,
- &man.seealso.common;
- <ulink url="https://honk.sigxcpu.org/cl2vcs">
- <citetitle>Cl2vcs</citetitle></ulink>,
- </para>
- </refsect1>
- <refsect1>
- <title>AUTHOR</title>
- <para>
- &dhusername; &dhemail;
- </para>
- </refsect1>
- </refentry>
|