diff options
Diffstat (limited to 'docs/manpages/gbp-dch.sgml')
| -rw-r--r-- | docs/manpages/gbp-dch.sgml | 441 |
1 files changed, 441 insertions, 0 deletions
diff --git a/docs/manpages/gbp-dch.sgml b/docs/manpages/gbp-dch.sgml new file mode 100644 index 0000000..96e42f5 --- /dev/null +++ b/docs/manpages/gbp-dch.sgml @@ -0,0 +1,441 @@ +<refentry id="man.git.dch"> + <refentryinfo> + <address> + &dhemail; + </address> + <author> + &dhfirstname; + &dhsurname; + </author> + </refentryinfo> + <refmeta> + <refentrytitle>gbp-dch</refentrytitle> + &dhsection; + </refmeta> + <refnamediv> + <refname>git-dch;</refname> + <refname>gbp-dch;</refname> + <refpurpose>Generate the Debian changelog from git commit messages</refpurpose> + </refnamediv> + <refsynopsisdiv> + <cmdsynopsis> + &gbp-dch; + + <arg><option>--verbose</option></arg> + <arg><option>--debian-branch=</option><replaceable>branch_name</replaceable></arg> + <arg><option>--debian-tag=</option><replaceable>tag-format</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>--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>--customization=</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> + <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>--ignore-branch</option> + </term> + <listitem> + <para>Don't check if the current branch matches + <replaceable>debian-branch</replaceable>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--verbose</option></term> + <term><option>-v</option></term> + <listitem> + <para>verbose execution</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>Git-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 'Closes|LP' to support Debian and + Launchpad.</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> + </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>Git-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></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 + + Git-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> + <citerefentry> + <refentrytitle>gbp-buildpackage</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>gbp-import-dsc</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>gbp-import-dscs</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>gbp-import-orig</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>gbp.conf</refentrytitle> + &dhconfsection; + </citerefentry>, + &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> |