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
31 encoded 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
45 entry can be given on the command line in addition to the closes
46 entries.
47 At most one of --append, --increment, --edit, --release, and --newver‐
49 sion may be specified as listed below. If no options are specified,
50 debchange will use heuristics to guess whether or not the package has
51 been successfully released, and behave as if --increment had been spec‐
52 ified if the package has been released, or otherwise as if --append has
53 been specified.
54 Two different sets of heuristics can be used, as controlled by the
56 --release-heuristic option or the DEBCHANGE_RELEASE_HEURISTIC configu‐
57 ration variable. The default changelog heuristic assumes the package
58 has been released unless its changelog contains UNRELEASED in the dis‐
59 tribution field. If this heuristic is enabled then the distribution
60 will default to UNRELEASED in new changelog entries, and the --maint‐
61 trailer option described below will be automatically enabled. This can
62 be useful if a package can be released by different maintainers, or if
63 you do not keep the upload logs. The alternate log heuristic determines
64 if a package has been released by looking for an appropriate dupload(1)
65 or dput(1) log file in the parent directory. A warning will be issued
66 if the log file is found but a successful upload is not recorded. This
67 may be because the previous upload was performed with a version of
68 dupload prior to 2.1 or because the upload failed.
69 If either --increment or --newversion is used, the name and email for
71 the new version will be determined as follows. If the environment
72 variable DEBFULLNAME is set, this will be used for the maintainer full
73 name; if not, then NAME will be checked. If the environment variable
74 DEBEMAIL is set, this will be used for the email address. If this
75 variable has the form "name <email>", then the maintainer name will
76 also be taken from here if neither DEBFULLNAME nor NAME is set. If
77 this variable is not set, the same test is performed on the environment
78 variable EMAIL. Next, if the full name has still not been determined,
79 then use getpwuid(3) to determine the name from the password file. If
80 this fails, use the previous changelog entry. For the email address,
81 if it has not been set from DEBEMAIL or EMAIL, then look in /etc/mail‐
82 name, then attempt to build it from the username and FQDN, otherwise
83 use the email address in the previous changelog entry. In other words,
84 it's a good idea to set DEBEMAIL and DEBFULLNAME when using this
85 script.
86 Support is included for changelogs that record changes by multiple co-
88 maintainers of a package. If an entry is appended to the current ver‐
89 sion's entries, and the maintainer is different from the maintainer who
90 is listed as having done the previous entries, then lines will be added
91 to the changelog to tell which maintainers made which changes. Cur‐
92 rently only one of the several such styles of recording this informa‐
93 tion is supported, in which the name of the maintainer who made a set
94 of changes appears on a line before the changes, inside square brack‐
95 ets. This can be switched on and off using the --[no]multimaint option
96 or the DEBCHANGE_MULTIMAINT configuration file option; the default is
97 to enable it. Note that if an entry has already been marked in this
98 way, then this option will be silently ignored.
99 If the directory name of the source tree has the form package-version,
101 then debchange will also attempt to rename it if the (upstream) version
102 number changes. This can be prevented by using the --preserve command
103 line or configuration file option as described below.
104 If --force-bad-version or --allow-lower-version is used, debchange will
106 not stop if the new version is less than the current one. This is
107 especially useful while doing backports.
108
110 In common with several other scripts in the devscripts package,
111 debchange will climb the directory tree until it finds a
112 debian/changelog file. As a safeguard against stray files causing
113 potential problems, it will examine the name of the parent directory
114 once it finds the debian/changelog file, and check that the directory
115 name corresponds to the package name. Precisely how it does this is
116 controlled by two configuration file variables
117 DEVSCRIPTS_CHECK_DIRNAME_LEVEL and DEVSCRIPTS_CHECK_DIRNAME_REGEX, and
118 their corresponding command-line options --check-dirname-level and
119 --check-dirname-regex.
120 DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
122 0 Never check the directory name.
124 1 Only check the directory name if we have had to change directory
126 in our search for debian/changelog. This is the default behav‐
127 iour.
128 2 Always check the directory name.
130 The directory name is checked by testing whether the current directory
132 name (as determined by pwd(1)) matches the regex given by the configu‐
133 ration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the command
134 line option --check-dirname-regex regex. Here regex is a Perl regex
135 (see perlre(3perl)), which will be anchored at the beginning and the
136 end. If regex contains a '/', then it must match the full directory
137 path. If not, then it must match the full directory name. If regex
138 contains the string ´PACKAGE', this will be replaced by the source
139 package name, as determined from the changelog. The default value for
140 the regex is: ´PACKAGE(-.+)?', thus matching directory names such as
141 PACKAGE and PACKAGE-version.
142 The default changelog to be edited is debian/changelog; however, this
144 can be changed using the --changelog or --news options or the CHANGELOG
145 environment variable, as described below.
146
148 --append, -a
149 Add a new changelog entry at the end of the current version's
150 entries.
151 --increment, -i
153 Increment either the final component of the Debian release num‐
154 ber or, if this is a native Debian package, the version number.
155 On Ubuntu or Tanglu, this will also change the suffix from
156 buildX to ubuntu1/tanglu1. Use -R, --rebuild for a no change
157 rebuild increment. This creates a new section at the beginning
158 of the changelog with appropriate headers and footers. Also, if
159 this is a new version of a native Debian package, the directory
160 name is changed to reflect this. If DEBCHANGE_RELEASE_HEURISTIC
161 is changelog (default) and the current release is UNRELEASED,
162 this will only change the version of the current changelog
163 stanza. Otherwise, this will create a new changelog stanza with
164 the new version.
165 --newversion version, -v version
167 This specifies the version number (including the Debian release
168 part) explicitly and behaves as the --increment option in other
169 respects. It will also change the directory name if the
170 upstream version number has changed. If
171 DEBCHANGE_RELEASE_HEURISTIC is changelog (default) and the cur‐
172 rent release is UNRELEASED, this will only change the version of
173 the current changelog stanza. Otherwise, this will create a new
174 changelog stanza with the new version.
175 --edit, -e
177 Edit the changelog in an editor.
178 --release, -r
180 Finalize the changelog for a release. Update the changelog
181 timestamp. If the distribution is set to UNRELEASED, change it
182 to the distribution from the previous changelog entry (or
183 another distribution as specified by --distribution). If there
184 are no previous changelog entries and an explicit distribution
185 has not been specified, unstable will be used (or the name of
186 the current development release when run under Ubuntu).
187 --force-save-on-release
189 When --release is used, an editor is opened to allow inspection
190 of the changelog. The user is required to save the file to
191 accept the modified changelog, otherwise the original will be
192 kept (default).
193 --no-force-save-on-release
195 Do not do so. Note that a dummy changelog entry may be supplied
196 in order to achieve the same effect - e.g. debchange --release
197 "". The entry will not be added to the changelog but its pres‐
198 ence will suppress the editor.
199 --create
201 This will create a new debian/changelog file (or NEWS if the
202 --news option is used). You must be in the top-level directory
203 to use this; no directory name checking will be performed. The
204 package name and version can either be specified using the
205 --package and --newversion options, determined from the direc‐
206 tory name using the --fromdirname option or entered manually
207 into the generated changelog file. The maintainer name is
208 determined from the environment if this is possible, and the
209 distribution is specified either using the --distribution option
210 or in the generated changelog file.
211 --empty
213 When used in combination with --create, suppress the automatic
214 addition of an "initial release" changelog entry (so that the
215 next invocation of debchange adds the first entry). Note that
216 this will cause a dpkg-parsechangelog warning on the next invo‐
217 cation due to the lack of changes.
218 --package package
220 This specifies the package name to be used in the new changelog;
221 this may only be used in conjunction with the --create, --incre‐
222 ment and --newversion options.
223 --nmu, -n
225 Increment the Debian release number for a non-maintainer upload
226 by either appending a ".1" to a non-NMU version number (unless
227 the package is Debian native, in which case "+nmu1" is appended)
228 or by incrementing an NMU version number, and add an NMU
229 changelog comment. This happens automatically if the packager
230 is neither in the Maintainer nor the Uploaders field in
231 debian/control, unless DEBCHANGE_AUTO_NMU is set to no or the
232 --no-auto-nmu option is used.
233 --bin-nmu
235 Increment the Debian release number for a binary non-maintainer
236 upload by either appending a "+b1" to a non-binNMU version num‐
237 ber or by incrementing a binNMU version number, and add a binNMU
238 changelog comment.
239 --qa, -q
241 Increment the Debian release number for a Debian QA Team upload,
242 and add a QA upload changelog comment.
243 --rebuild, -R
245 Increment the Debian release number for a no-change rebuild by
246 appending a "build1" or by incrementing a rebuild version num‐
247 ber.
248 --security, -s
250 Increment the Debian release number for a Debian Security Team
251 non-maintainer upload, and add a Security Team upload changelog
252 comment.
253 --lts Increment the Debian release number for a LTS Security Team non-
255 maintainer upload, and add a LTS Security Team upload changelog
256 comment.
257 --team Increment the Debian release number for a team upload, and add a
259 Team upload changelog comment.
260 --upstream, -U
262 Don't append distro-name1 to the version on a derived distribu‐
263 tion. Increment the Debian version.
264 --bpo Increment the Debian release number for an upload to buster-
266 backports, and add a backport upload changelog comment.
267 --stable
269 Increment the Debian release number for an upload to the current
270 stable release.
271 --local, -lsuffix
273 Add a suffix to the Debian version number for a local build.
274 --force-bad-version, -b
276 Force a version number to be less than the current one (e.g.,
277 when backporting).
278 --allow-lower-version pattern
280 Allow a version number to be less than the current one if the
281 new version matches the specified pattern.
282 --force-distribution
284 Force the provided distribution to be used, even if it doesn't
285 match the list of known distributions (e.g. for unofficial dis‐
286 tributions).
287 --auto-nmu
289 Attempt to automatically determine whether a change to the
290 changelog represents a Non Maintainer Upload. This is the
291 default.
292 --no-auto-nmu
294 Disable automatic NMU detection. Equivalent to setting
295 DEBCHANGE_AUTO_NMU to no.
296 --fromdirname, -d
298 This will take the upstream version number from the directory
299 name, which should be of the form package-version. If the
300 upstream version number has increased from the most recent
301 changelog entry, then a new entry will be made with version num‐
302 ber version-1 (or version if the package is Debian native), with
303 the same epoch as the previous package version. If the upstream
304 version number is the same, this option will behave in the same
305 way as -i.
306 --closes nnnnn[,nnnnn ...]
308 Add changelog entries to close the specified bug numbers. Also
309 invoke the editor after adding these entries. Will generate
310 warnings if the BTS cannot be contacted (and --noquery has not
311 been specified), or if there are problems with the bug report
312 located.
313 --[no]query
315 Should we attempt to query the BTS when generating closes
316 entries?
317 --preserve, -p
319 Preserve the source tree directory name if the upstream version
320 number (or the version number of a Debian native package)
321 changes. See also the configuration variables section below.
322 --no-preserve, --nopreserve
324 Do not preserve the source tree directory name (default).
325 --vendor vendor
327 Override the distributor ID over the default returned by dpkg-
328 vendor. This name is used for heuristics applied to new package
329 versions and for sanity checking of the target distribution.
330 --distribution dist, -D dist
332 Use the specified distribution in the changelog entry being
333 edited, instead of using the previous changelog entry's distri‐
334 bution for new entries or the existing value for existing
335 entries.
336 --urgency urgency, -u urgency
338 Use the specified urgency in the changelog entry being edited,
339 instead of using the default "medium" for new entries or the
340 existing value for existing entries.
341 --changelog file, -c file
343 This will edit the changelog file instead of the standard
344 debian/changelog. This option overrides any CHANGELOG environ‐
345 ment variable setting. Also, no directory traversing or check‐
346 ing will be performed when this option is used.
347 --news [newsfile]
349 This will edit newsfile (by default, debian/NEWS) instead of the
350 regular changelog. Directory searching will be performed. The
351 changelog will be examined in order to determine the current
352 package version.
353 --[no]multimaint
355 Should we indicate that parts of a changelog entry have been
356 made by different maintainers? Default is yes; see the discus‐
357 sion above and also the DEBCHANGE_MULTIMAINT configuration file
358 option below.
359 --[no]multimaint-merge
361 Should all changes made by the same author be merged into the
362 same changelog section? Default is no; see the discussion above
363 and also the DEBCHANGE_MULTIMAINT_MERGE configuration file
364 option below.
365 --maintmaint, -m
367 Do not modify the maintainer details previously listed in the
368 changelog. This is useful particularly for sponsors wanting to
369 automatically add a sponsorship message without disrupting the
370 other changelog details. Note that there may be some interest‐
371 ing interactions if multi-maintainer mode is in use; you will
372 probably wish to check the changelog manually before uploading
373 it in such cases.
374 --controlmaint, -M
376 Use maintainer details from the debian/control Maintainer field
377 rather than relevant environment variables (DEBFULLNAME, DEBE‐
378 MAIL, etc.). This option might be useful to restore details of
379 the main maintainer in the changelog trailer after a bogus edit
380 (e.g. when -m was intended but forgot) or when releasing a pack‐
381 age in the name of the main maintainer (e.g. the team).
382 --[no]mainttrailer, -t
384 If mainttrailer is set, it will avoid modifying the existing
385 changelog trailer line (i.e. the maintainer and date-stamp
386 details), unless used with options that require the trailer to
387 be modified (e.g. --create, --release, -i, --qa, etc.) This
388 option differs from --maintmaint in that it will use multi-main‐
389 tainer mode if appropriate, with the exception of editing the
390 trailer. See also the DEBCHANGE_MAINTTRAILER configuration file
391 option below.
392 --check-dirname-level N
394 See the above section "Directory name checking" for an explana‐
395 tion of this option.
396 --check-dirname-regex regex
398 See the above section "Directory name checking" for an explana‐
399 tion of this option.
400 --no-conf, --noconf
402 Do not read any configuration files. This can only be used as
403 the first option given on the command-line.
404 --release-heuristic log|changelog
406 Controls how debchange determines if a package has been
407 released, when deciding whether to create a new changelog entry
408 or append to an existing changelog entry.
409 --help, -h
411 Display a help message and exit successfully.
412 --version
414 Display version and copyright information and exit successfully.
415
417 The two configuration files /etc/devscripts.conf and ~/.devscripts are
418 sourced in that order to set configuration variables. Command line
419 options can be used to override configuration file settings. Environ‐
420 ment variable settings are ignored for this purpose. The currently
421 recognised variables are:
422 DEBCHANGE_PRESERVE
424 If this is set to yes, then it is the same as the --preserve
425 command line parameter being used.
426 DEBCHANGE_QUERY_BTS
428 If this is set to no, then it is the same as the --noquery com‐
429 mand line parameter being used.
430 DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX
432 See the above section "Directory name checking" for an explana‐
433 tion of these variables. Note that these are package-wide con‐
434 figuration variables, and will therefore affect all devscripts
435 scripts which check their value, as described in their respec‐
436 tive manpages and in devscripts.conf(5).
437 DEBCHANGE_RELEASE_HEURISTIC
439 Controls how debchange determines if a package has been
440 released, when deciding whether to create a new changelog entry
441 or append to an existing changelog entry. Can be either log or
442 changelog.
443 DEBCHANGE_MULTIMAINT
445 If set to no, debchange will not introduce multiple-maintainer
446 distinctions when a different maintainer appends an entry to an
447 existing changelog. See the discussion above. Default is yes.
448 DEBCHANGE_MULTIMAINT_MERGE
450 If set to yes, when adding changes in multiple-maintainer mode
451 debchange will check whether previous changes by the current
452 maintainer exist and add the new changes to the existing block
453 rather than creating a new block. Default is no.
454 DEBCHANGE_MAINTTRAILER
456 If this is set to no, then it is the same as the --nomaint‐
457 trailer command line parameter being used.
458 DEBCHANGE_TZ
460 Use this timezone for changelog entries. Default is the
461 user/system timezone as shown by `date -R` and affected by the
462 environment variable TZ.
463 DEBCHANGE_LOWER_VERSION_PATTERN
465 If this is set, then it is the same as the --allow-lower-version
466 command line parameter being used.
467 DEBCHANGE_AUTO_NMU
469 If this is set to no then debchange will not attempt to automat‐
470 ically determine whether the current changelog stanza represents
471 an NMU. The default is yes. See the discussion of the --nmu
472 option above.
473 DEBCHANGE_FORCE_SAVE_ON_RELEASE
475 If this is set to no, then it is the same as the
476 --no-force-save-on-release command line parameter being used.
477 DEBCHANGE_VENDOR
479 Use this vendor instead of the default (dpkg-vendor output).
480 See --vendor for details.
481
483 DEBEMAIL, EMAIL, DEBFULLNAME, NAME
484 See the above description of the use of these environment vari‐
485 ables.
486 CHANGELOG
488 This variable specifies the changelog to edit in place of
489 debian/changelog. No directory traversal or checking is per‐
490 formed when this variable is set. This variable is overridden
491 by the --changelog command-line setting.
492 VISUAL, EDITOR
494 These environment variables (in this order) determine the editor
495 used by sensible-editor.
496
498 debc(1), debclean(1), dput(1), dupload(1), devscripts.conf(5)
499
501 The original author was Christoph Lameter <clameter@debian.org>. Many
502 substantial changes and improvements were made by Julian Gilbey
503 <jdg@debian.org>.
504DEBIAN Debian Utilities DEBCHANGE(1)