1DEBCHANGE(1) General Commands Manual DEBCHANGE(1)
2
6 debchange - Tool for maintenance of the debian/changelog file in a
7 source package
8
10 debchange [options] [text ...]
11 dch [options] [text ...]
12
14 debchange or its alias dch will add a new comment line to the Debian
15 changelog in the current source tree. This command must be run from
16 within that tree. If the text of the change is given on the command
17 line, debchange will run in batch mode and simply add the text, with
18 line breaks as necessary, at the appropriate place in debian/changelog
19 (or the changelog specified by options, as described below). If the
20 text given on the command line is a null string, debchange will run in
21 batch mode without adding any text. If the text given on the command
22 line is a space string, debchange will run in batch mode and add a
23 blank changelog entry. If no text is specified then debchange will run
24 the editor as determined by sensible-editor for you to edit the file.
25 (The environment variables VISUAL and EDITOR are used in this order to
26 determine which editor to use.) Editors which understand the +n option
27 for starting the editing on a specified line will use this to move to
28 the correct line of the file for editing. If the editor is quit with‐
29 out modifying the temporary file, debchange will exit without touching
30 the existing changelog. Note that the changelog is assumed to be en‐
31 coded with the UTF-8 encoding. If it is not, problems may occur.
32 Please see the iconv(1) manpage to find out how to convert changelogs
33 from legacy encodings. Finally, a changelog or NEWS file can be cre‐
34 ated from scratch using the --create option described below.
35 debchange also supports automatically producing bug-closing changelog
37 entries, using the --closes option. This will usually query the BTS,
38 the Debian Bug Tracking System (see https://bugs.debian.org/) to deter‐
39 mine the title of the bug and the package in which it occurs. This be‐
40 haviour can be stopped by giving a --noquery option or by setting the
41 configuration variable DEBCHANGE_QUERY_BTS to no, as described below.
42 In either case, the editor (as described above) will always be invoked
43 to give an opportunity to modify the entries, and the changelog will be
44 accepted whether or not modifications are made. An extra changelog en‐
45 try can be given on the command line in addition to the closes entries.
46 At most one of --append, --increment, --edit, --release, and --newver‐
48 sion may be specified as listed below. If no options are specified, de‐
49 bchange will use heuristics to guess whether or not the package has
50 been successfully released, and behave as if --increment had been spec‐
51 ified if the package has been released, or otherwise as if --append has
52 been specified.
53 Two different sets of heuristics can be used, as controlled by the
55 --release-heuristic option or the DEBCHANGE_RELEASE_HEURISTIC configu‐
56 ration variable. The default changelog heuristic assumes the package
57 has been released unless its changelog contains UNRELEASED in the dis‐
58 tribution field. If this heuristic is enabled then the distribution
59 will default to UNRELEASED in new changelog entries, and the --maint‐
60 trailer option described below will be automatically enabled. This can
61 be useful if a package can be released by different maintainers, or if
62 you do not keep the upload logs. The alternate log heuristic determines
63 if a package has been released by looking for an appropriate dupload(1)
64 or dput(1) log file in the parent directory. A warning will be issued
65 if the log file is found but a successful upload is not recorded. This
66 may be because the previous upload was performed with a version of du‐
67 pload prior to 2.1 or because the upload failed.
68 If either --increment or --newversion is used, the name and email for
70 the new version will be determined as follows. If the environment
71 variable DEBFULLNAME is set, this will be used for the maintainer full
72 name; if not, then NAME will be checked. If the environment variable
73 DEBEMAIL is set, this will be used for the email address. If this
74 variable has the form "name <email>", then the maintainer name will
75 also be taken from here if neither DEBFULLNAME nor NAME is set. If
76 this variable is not set, the same test is performed on the environment
77 variable EMAIL. Next, if the full name has still not been determined,
78 then use getpwuid(3) to determine the name from the password file. If
79 this fails, use the previous changelog entry. For the email address,
80 if it has not been set from DEBEMAIL or EMAIL, then look in /etc/mail‐
81 name, then attempt to build it from the username and FQDN, otherwise
82 use the email address in the previous changelog entry. In other words,
83 it's a good idea to set DEBEMAIL and DEBFULLNAME when using this
84 script.
85 Support is included for changelogs that record changes by multiple co-
87 maintainers of a package. If an entry is appended to the current ver‐
88 sion's entries, and the maintainer is different from the maintainer who
89 is listed as having done the previous entries, then lines will be added
90 to the changelog to tell which maintainers made which changes. Cur‐
91 rently only one of the several such styles of recording this informa‐
92 tion is supported, in which the name of the maintainer who made a set
93 of changes appears on a line before the changes, inside square brack‐
94 ets. This can be switched on and off using the --[no]multimaint option
95 or the DEBCHANGE_MULTIMAINT configuration file option; the default is
96 to enable it. Note that if an entry has already been marked in this
97 way, then this option will be silently ignored.
98 If the directory name of the source tree has the form package-version,
100 then debchange will also attempt to rename it if the (upstream) version
101 number changes. This can be prevented by using the --preserve command
102 line or configuration file option as described below.
103 If --force-bad-version or --allow-lower-version is used, debchange will
105 not stop if the new version is less than the current one. This is es‐
106 pecially useful while doing backports.
107
109 In common with several other scripts in the devscripts package, de‐
110 bchange will climb the directory tree until it finds a debian/changelog
111 file. As a safeguard against stray files causing potential problems,
112 it will examine the name of the parent directory once it finds the de‐
113 bian/changelog file, and check that the directory name corresponds to
114 the package name. Precisely how it does this is controlled by two con‐
115 figuration file variables DEVSCRIPTS_CHECK_DIRNAME_LEVEL and DE‐
116 VSCRIPTS_CHECK_DIRNAME_REGEX, and their corresponding command-line op‐
117 tions --check-dirname-level and --check-dirname-regex.
118 DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
120 0 Never check the directory name.
122 1 Only check the directory name if we have had to change directory
124 in our search for debian/changelog. This is the default behav‐
125 iour.
126 2 Always check the directory name.
128 The directory name is checked by testing whether the current directory
130 name (as determined by pwd(1)) matches the regex given by the configu‐
131 ration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the command
132 line option --check-dirname-regex regex. Here regex is a Perl regex
133 (see perlre(3perl)), which will be anchored at the beginning and the
134 end. If regex contains a '/', then it must match the full directory
135 path. If not, then it must match the full directory name. If regex
136 contains the string ´PACKAGE', this will be replaced by the source
137 package name, as determined from the changelog. The default value for
138 the regex is: ´PACKAGE(-.+)?', thus matching directory names such as
139 PACKAGE and PACKAGE-version.
140 The default changelog to be edited is debian/changelog; however, this
142 can be changed using the --changelog or --news options or the CHANGELOG
143 environment variable, as described below.
144
146 --append, -a
147 Add a new changelog entry at the end of the current version's
148 entries.
149 --increment, -i
151 Increment either the final component of the Debian release num‐
152 ber or, if this is a native Debian package, the version number.
153 On Ubuntu or Tanglu, this will also change the suffix from
154 buildX to ubuntu1/tanglu1. Use -R, --rebuild for a no change
155 rebuild increment. This creates a new section at the beginning
156 of the changelog with appropriate headers and footers. Also, if
157 this is a new version of a native Debian package, the directory
158 name is changed to reflect this. If DEBCHANGE_RELEASE_HEURISTIC
159 is changelog (default) and the current release is UNRELEASED,
160 this will only change the version of the current changelog
161 stanza. Otherwise, this will create a new changelog stanza with
162 the new version.
163 --newversion version, -v version
165 This specifies the version number (including the Debian release
166 part) explicitly and behaves as the --increment option in other
167 respects. It will also change the directory name if the up‐
168 stream version number has changed. If DEBCHANGE_RELEASE_HEURIS‐
169 TIC is changelog (default) and the current release is UNRE‐
170 LEASED, this will only change the version of the current
171 changelog stanza. Otherwise, this will create a new changelog
172 stanza with the new version.
173 --edit, -e
175 Edit the changelog in an editor.
176 --release, -r
178 Finalize the changelog for a release. Update the changelog
179 timestamp. If the distribution is set to UNRELEASED, change it
180 to the distribution from the previous changelog entry (or an‐
181 other distribution as specified by --distribution). If there
182 are no previous changelog entries and an explicit distribution
183 has not been specified, unstable will be used (or the name of
184 the current development release when run under Ubuntu).
185 --force-save-on-release
187 When --release is used, an editor is opened to allow inspection
188 of the changelog. The user is required to save the file to ac‐
189 cept the modified changelog, otherwise the original will be kept
190 (default).
191 --no-force-save-on-release
193 Do not do so. Note that a dummy changelog entry may be supplied
194 in order to achieve the same effect - e.g. debchange --release
195 "". The entry will not be added to the changelog but its pres‐
196 ence will suppress the editor.
197 --create
199 This will create a new debian/changelog file (or NEWS if the
200 --news option is used). You must be in the top-level directory
201 to use this; no directory name checking will be performed. The
202 package name and version can either be specified using the
203 --package and --newversion options, determined from the direc‐
204 tory name using the --fromdirname option or entered manually
205 into the generated changelog file. The maintainer name is de‐
206 termined from the environment if this is possible, and the dis‐
207 tribution is specified either using the --distribution option or
208 in the generated changelog file.
209 --empty
211 When used in combination with --create, suppress the automatic
212 addition of an "initial release" changelog entry (so that the
213 next invocation of debchange adds the first entry). Note that
214 this will cause a dpkg-parsechangelog warning on the next invo‐
215 cation due to the lack of changes.
216 --package package
218 This specifies the package name to be used in the new changelog;
219 this may only be used in conjunction with the --create, --incre‐
220 ment and --newversion options.
221 --nmu, -n
223 Increment the Debian release number for a non-maintainer upload
224 by either appending a ".1" to a non-NMU version number (unless
225 the package is Debian native, in which case "+nmu1" is appended)
226 or by incrementing an NMU version number, and add an NMU
227 changelog comment. This happens automatically if the packager
228 is neither in the Maintainer nor the Uploaders field in de‐
229 bian/control, unless DEBCHANGE_AUTO_NMU is set to no or the
230 --no-auto-nmu option is used.
231 --bin-nmu
233 Increment the Debian release number for a binary non-maintainer
234 upload by either appending a "+b1" to a non-binNMU version num‐
235 ber or by incrementing a binNMU version number, and add a binNMU
236 changelog comment.
237 --qa, -q
239 Increment the Debian release number for a Debian QA Team upload,
240 and add a QA upload changelog comment.
241 --rebuild, -R
243 Increment the Debian release number for a no-change rebuild by
244 appending a "build1" or by incrementing a rebuild version num‐
245 ber.
246 --security, -s
248 Increment the Debian release number for a Debian Security Team
249 non-maintainer upload, and add a Security Team upload changelog
250 comment.
251 --lts Increment the Debian release number for a LTS Security Team non-
253 maintainer upload, and add a LTS Security Team upload changelog
254 comment.
255 --team Increment the Debian release number for a team upload, and add a
257 Team upload changelog comment.
258 --upstream, -U
260 Don't append distro-name1 to the version on a derived distribu‐
261 tion. Increment the Debian version.
262 --bpo Increment the Debian release number for an upload to bullseye-
264 backports, and add a backport upload changelog comment.
265 --stable
267 Increment the Debian release number for an upload to the current
268 stable release.
269 --local, -lsuffix
271 Add a suffix to the Debian version number for a local build.
272 --force-bad-version, -b
274 Force a version number to be less than the current one (e.g.,
275 when backporting).
276 --allow-lower-version pattern
278 Allow a version number to be less than the current one if the
279 new version matches the specified pattern.
280 --force-distribution
282 Force the provided distribution to be used, even if it doesn't
283 match the list of known distributions (e.g. for unofficial dis‐
284 tributions).
285 --auto-nmu
287 Attempt to automatically determine whether a change to the
288 changelog represents a Non Maintainer Upload. This is the de‐
289 fault.
290 --no-auto-nmu
292 Disable automatic NMU detection. Equivalent to setting DE‐
293 BCHANGE_AUTO_NMU to no.
294 --fromdirname, -d
296 This will take the upstream version number from the directory
297 name, which should be of the form package-version. If the up‐
298 stream version number has increased from the most recent
299 changelog entry, then a new entry will be made with version num‐
300 ber version-1 (or version if the package is Debian native), with
301 the same epoch as the previous package version. If the upstream
302 version number is the same, this option will behave in the same
303 way as -i.
304 --closes nnnnn[,nnnnn ...]
306 Add changelog entries to close the specified bug numbers. Also
307 invoke the editor after adding these entries. Will generate
308 warnings if the BTS cannot be contacted (and --noquery has not
309 been specified), or if there are problems with the bug report
310 located.
311 --[no]query
313 Should we attempt to query the BTS when generating closes en‐
314 tries?
315 --preserve, -p
317 Preserve the source tree directory name if the upstream version
318 number (or the version number of a Debian native package)
319 changes. See also the configuration variables section below.
320 --no-preserve, --nopreserve
322 Do not preserve the source tree directory name (default).
323 --vendor vendor
325 Override the distributor ID over the default returned by dpkg-
326 vendor. This name is used for heuristics applied to new package
327 versions and for sanity checking of the target distribution.
328 --distribution dist, -D dist
330 Use the specified distribution in the changelog entry being
331 edited, instead of using the previous changelog entry's distri‐
332 bution for new entries or the existing value for existing en‐
333 tries.
334 --urgency urgency, -u urgency
336 Use the specified urgency in the changelog entry being edited,
337 instead of using the default "medium" for new entries or the ex‐
338 isting value for existing entries.
339 --changelog file, -c file
341 This will edit the changelog file instead of the standard de‐
342 bian/changelog. This option overrides any CHANGELOG environment
343 variable setting. Also, no directory traversing or checking
344 will be performed when this option is used.
345 --news [newsfile]
347 This will edit newsfile (by default, debian/NEWS) instead of the
348 regular changelog. Directory searching will be performed. The
349 changelog will be examined in order to determine the current
350 package version.
351 --[no]multimaint
353 Should we indicate that parts of a changelog entry have been
354 made by different maintainers? Default is yes; see the discus‐
355 sion above and also the DEBCHANGE_MULTIMAINT configuration file
356 option below.
357 --[no]multimaint-merge
359 Should all changes made by the same author be merged into the
360 same changelog section? Default is no; see the discussion above
361 and also the DEBCHANGE_MULTIMAINT_MERGE configuration file op‐
362 tion below.
363 --maintmaint, -m
365 Do not modify the maintainer details previously listed in the
366 changelog. This is useful particularly for sponsors wanting to
367 automatically add a sponsorship message without disrupting the
368 other changelog details. Note that there may be some interest‐
369 ing interactions if multi-maintainer mode is in use; you will
370 probably wish to check the changelog manually before uploading
371 it in such cases.
372 --controlmaint, -M
374 Use maintainer details from the debian/control Maintainer field
375 rather than relevant environment variables (DEBFULLNAME, DEBE‐
376 MAIL, etc.). This option might be useful to restore details of
377 the main maintainer in the changelog trailer after a bogus edit
378 (e.g. when -m was intended but forgot) or when releasing a pack‐
379 age in the name of the main maintainer (e.g. the team).
380 --[no]mainttrailer, -t
382 If mainttrailer is set, it will avoid modifying the existing
383 changelog trailer line (i.e. the maintainer and date-stamp de‐
384 tails), unless used with options that require the trailer to be
385 modified (e.g. --create, --release, -i, --qa, etc.) This option
386 differs from --maintmaint in that it will use multi-maintainer
387 mode if appropriate, with the exception of editing the trailer.
388 See also the DEBCHANGE_MAINTTRAILER configuration file option
389 below.
390 --check-dirname-level N
392 See the above section "Directory name checking" for an explana‐
393 tion of this option.
394 --check-dirname-regex regex
396 See the above section "Directory name checking" for an explana‐
397 tion of this option.
398 --no-conf, --noconf
400 Do not read any configuration files. This can only be used as
401 the first option given on the command-line.
402 --release-heuristic log|changelog
404 Controls how debchange determines if a package has been re‐
405 leased, when deciding whether to create a new changelog entry or
406 append to an existing changelog entry.
407 --help, -h
409 Display a help message and exit successfully.
410 --version
412 Display version and copyright information and exit successfully.
413
415 The two configuration files /etc/devscripts.conf and ~/.devscripts are
416 sourced in that order to set configuration variables. Command line op‐
417 tions can be used to override configuration file settings. Environment
418 variable settings are ignored for this purpose. The currently recog‐
419 nised variables are:
420 DEBCHANGE_PRESERVE
422 If this is set to yes, then it is the same as the --preserve
423 command line parameter being used.
424 DEBCHANGE_QUERY_BTS
426 If this is set to no, then it is the same as the --noquery com‐
427 mand line parameter being used.
428 DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX
430 See the above section "Directory name checking" for an explana‐
431 tion of these variables. Note that these are package-wide con‐
432 figuration variables, and will therefore affect all devscripts
433 scripts which check their value, as described in their respec‐
434 tive manpages and in devscripts.conf(5).
435 DEBCHANGE_RELEASE_HEURISTIC
437 Controls how debchange determines if a package has been re‐
438 leased, when deciding whether to create a new changelog entry or
439 append to an existing changelog entry. Can be either log or
440 changelog.
441 DEBCHANGE_MULTIMAINT
443 If set to no, debchange will not introduce multiple-maintainer
444 distinctions when a different maintainer appends an entry to an
445 existing changelog. See the discussion above. Default is yes.
446 DEBCHANGE_MULTIMAINT_MERGE
448 If set to yes, when adding changes in multiple-maintainer mode
449 debchange will check whether previous changes by the current
450 maintainer exist and add the new changes to the existing block
451 rather than creating a new block. Default is no.
452 DEBCHANGE_MAINTTRAILER
454 If this is set to no, then it is the same as the --nomaint‐
455 trailer command line parameter being used.
456 DEBCHANGE_TZ
458 Use this timezone for changelog entries. Default is the
459 user/system timezone as shown by `date -R` and affected by the
460 environment variable TZ.
461 DEBCHANGE_LOWER_VERSION_PATTERN
463 If this is set, then it is the same as the --allow-lower-version
464 command line parameter being used.
465 DEBCHANGE_AUTO_NMU
467 If this is set to no then debchange will not attempt to automat‐
468 ically determine whether the current changelog stanza represents
469 an NMU. The default is yes. See the discussion of the --nmu
470 option above.
471 DEBCHANGE_FORCE_SAVE_ON_RELEASE
473 If this is set to no, then it is the same as the
474 --no-force-save-on-release command line parameter being used.
475 DEBCHANGE_VENDOR
477 Use this vendor instead of the default (dpkg-vendor output).
478 See --vendor for details.
479
481 DEBEMAIL, EMAIL, DEBFULLNAME, NAME
482 See the above description of the use of these environment vari‐
483 ables.
484 CHANGELOG
486 This variable specifies the changelog to edit in place of de‐
487 bian/changelog. No directory traversal or checking is performed
488 when this variable is set. This variable is overridden by the
489 --changelog command-line setting.
490 VISUAL, EDITOR
492 These environment variables (in this order) determine the editor
493 used by sensible-editor.
494
496 debc(1), debclean(1), dput(1), dupload(1), devscripts.conf(5)
497
499 The original author was Christoph Lameter <clameter@debian.org>. Many
500 substantial changes and improvements were made by Julian Gilbey
501 <jdg@debian.org>.
502DEBIAN Debian Utilities DEBCHANGE(1)