aboutsummaryrefslogtreecommitdiff
path: root/docs/manpages/gbp-dch.sgml
blob: 5303c628474f90d2b551333d8cbffe79168a7a15 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
<refentry id="man.gbp.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;
      &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-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>--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>--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 '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>
      <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>~&lt;snaspshotnumber&gt;.gbp&lt;commitid&gt;</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>
	    Insteaad of <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>