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.
186 --force-save-on-release
188 When --release is used, an editor is opened to allow inspection
189 of the changelog. The user is required to save the file to
190 accept the modified changelog, otherwise the original will be
191 kept (default).
192 --no-force-save-on-release
194 Do not do so. Note that a dummy changelog entry may be supplied
195 in order to achieve the same effect - e.g. debchange --release
196 "". The entry will not be added to the changelog but its pres‐
197 ence will suppress the editor.
198 --create
200 This will create a new debian/changelog file (or NEWS if the
201 --news option is used). You must be in the top-level directory
202 to use this; no directory name checking will be performed. The
203 package name and version can either be specified using the
204 --package and --newversion options, determined from the direc‐
205 tory name using the --fromdirname option or entered manually
206 into the generated changelog file. The maintainer name is
207 determined from the environment if this is possible, and the
208 distribution is specified either using the --distribution option
209 or in the generated changelog file.
210 --empty
212 When used in combination with --create, suppress the automatic
213 addition of an "initial release" changelog entry (so that the
214 next invocation of debchange adds the first entry). Note that
215 this will cause a dpkg-parsechangelog warning on the next invo‐
216 cation due to the lack of changes.
217 --package package
219 This specifies the package name to be used in the new changelog;
220 this may only be used in conjunction with the --create, --incre‐
221 ment and --newversion options.
222 --nmu, -n
224 Increment the Debian release number for a non-maintainer upload
225 by either appending a ".1" to a non-NMU version number (unless
226 the package is Debian native, in which case "+nmu1" is appended)
227 or by incrementing an NMU version number, and add an NMU
228 changelog comment. This happens automatically if the packager
229 is neither in the Maintainer nor the Uploaders field in
230 debian/control, unless DEBCHANGE_AUTO_NMU is set to no or the
231 --no-auto-nmu option is used.
232 --bin-nmu
234 Increment the Debian release number for a binary non-maintainer
235 upload by either appending a "+b1" to a non-binNMU version num‐
236 ber or by incrementing a binNMU version number, and add a binNMU
237 changelog comment.
238 --qa, -q
240 Increment the Debian release number for a Debian QA Team upload,
241 and add a QA upload changelog comment.
242 --rebuild, -R
244 Increment the Debian release number for a no-change rebuild by
245 appending a "build1" or by incrementing a rebuild version num‐
246 ber.
247 --security, -s
249 Increment the Debian release number for a Debian Security Team
250 non-maintainer upload, and add a Security Team upload changelog
251 comment.
252 --lts Increment the Debian release number for a LTS Security Team non-
254 maintainer upload, and add a LTS Security Team upload changelog
255 comment.
256 --team Increment the Debian release number for a team upload, and add a
258 Team upload changelog comment.
259 --upstream, -U
261 Don't append distro-name1 to the version on a derived distribu‐
262 tion. Increment the Debian version.
263 --bpo Increment the Debian release number for an upload to buster-
265 backports, and add a backport upload changelog comment.
266 --stable
268 Increment the Debian release number for an upload to the current
269 stable release.
270 --local, -lsuffix
272 Add a suffix to the Debian version number for a local build.
273 --force-bad-version, -b
275 Force a version number to be less than the current one (e.g.,
276 when backporting).
277 --allow-lower-version pattern
279 Allow a version number to be less than the current one if the
280 new version matches the specified pattern.
281 --force-distribution
283 Force the provided distribution to be used, even if it doesn't
284 match the list of known distributions (e.g. for unofficial dis‐
285 tributions).
286 --auto-nmu
288 Attempt to automatically determine whether a change to the
289 changelog represents a Non Maintainer Upload. This is the
290 default.
291 --no-auto-nmu
293 Disable automatic NMU detection. Equivalent to setting
294 DEBCHANGE_AUTO_NMU to no.
295 --fromdirname, -d
297 This will take the upstream version number from the directory
298 name, which should be of the form package-version. If the
299 upstream version number has increased from the most recent
300 changelog entry, then a new entry will be made with version num‐
301 ber version-1 (or version if the package is Debian native), with
302 the same epoch as the previous package version. If the upstream
303 version number is the same, this option will behave in the same
304 way as -i.
305 --closes nnnnn[,nnnnn ...]
307 Add changelog entries to close the specified bug numbers. Also
308 invoke the editor after adding these entries. Will generate
309 warnings if the BTS cannot be contacted (and --noquery has not
310 been specified), or if there are problems with the bug report
311 located.
312 --[no]query
314 Should we attempt to query the BTS when generating closes
315 entries?
316 --preserve, -p
318 Preserve the source tree directory name if the upstream version
319 number (or the version number of a Debian native package)
320 changes. See also the configuration variables section below.
321 --no-preserve, --nopreserve
323 Do not preserve the source tree directory name (default).
324 --vendor vendor
326 Override the distributor ID over the default returned by dpkg-
327 vendor. This name is used for heuristics applied to new package
328 versions and for sanity checking of the target distribution.
329 --distribution dist, -D dist
331 Use the specified distribution in the changelog entry being
332 edited, instead of using the previous changelog entry's distri‐
333 bution for new entries or the existing value for existing
334 entries.
335 --urgency urgency, -u urgency
337 Use the specified urgency in the changelog entry being edited,
338 instead of using the default "medium" for new entries or the
339 existing value for existing entries.
340 --changelog file, -c file
342 This will edit the changelog file instead of the standard
343 debian/changelog. This option overrides any CHANGELOG environ‐
344 ment variable setting. Also, no directory traversing or check‐
345 ing will be performed when this option is used.
346 --news [newsfile]
348 This will edit newsfile (by default, debian/NEWS) instead of the
349 regular changelog. Directory searching will be performed. The
350 changelog will be examined in order to determine the current
351 package version.
352 --[no]multimaint
354 Should we indicate that parts of a changelog entry have been
355 made by different maintainers? Default is yes; see the discus‐
356 sion above and also the DEBCHANGE_MULTIMAINT configuration file
357 option below.
358 --[no]multimaint-merge
360 Should all changes made by the same author be merged into the
361 same changelog section? Default is no; see the discussion above
362 and also the DEBCHANGE_MULTIMAINT_MERGE configuration file
363 option below.
364 --maintmaint, -m
366 Do not modify the maintainer details previously listed in the
367 changelog. This is useful particularly for sponsors wanting to
368 automatically add a sponsorship message without disrupting the
369 other changelog details. Note that there may be some interest‐
370 ing interactions if multi-maintainer mode is in use; you will
371 probably wish to check the changelog manually before uploading
372 it in such cases.
373 --controlmaint, -M
375 Use maintainer details from the debian/control Maintainer field
376 rather than relevant environment variables (DEBFULLNAME, DEBE‐
377 MAIL, etc.). This option might be useful to restore details of
378 the main maintainer in the changelog trailer after a bogus edit
379 (e.g. when -m was intended but forgot) or when releasing a pack‐
380 age in the name of the main maintainer (e.g. the team).
381 --[no]mainttrailer, -t
383 If mainttrailer is set, it will avoid modifying the existing
384 changelog trailer line (i.e. the maintainer and date-stamp
385 details), unless used with options that require the trailer to
386 be modified (e.g. --create, --release, -i, --qa, etc.) This
387 option differs from --maintmaint in that it will use multi-main‐
388 tainer mode if appropriate, with the exception of editing the
389 trailer. See also the DEBCHANGE_MAINTTRAILER configuration file
390 option below.
391 --check-dirname-level N
393 See the above section "Directory name checking" for an explana‐
394 tion of this option.
395 --check-dirname-regex regex
397 See the above section "Directory name checking" for an explana‐
398 tion of this option.
399 --no-conf, --noconf
401 Do not read any configuration files. This can only be used as
402 the first option given on the command-line.
403 --release-heuristic log|changelog
405 Controls how debchange determines if a package has been
406 released, when deciding whether to create a new changelog entry
407 or append to an existing changelog entry.
408 --help, -h
410 Display a help message and exit successfully.
411 --version
413 Display version and copyright information and exit successfully.
414
416 The two configuration files /etc/devscripts.conf and ~/.devscripts are
417 sourced in that order to set configuration variables. Command line
418 options can be used to override configuration file settings. Environ‐
419 ment variable settings are ignored for this purpose. The currently
420 recognised variables are:
421 DEBCHANGE_PRESERVE
423 If this is set to yes, then it is the same as the --preserve
424 command line parameter being used.
425 DEBCHANGE_QUERY_BTS
427 If this is set to no, then it is the same as the --noquery com‐
428 mand line parameter being used.
429 DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX
431 See the above section "Directory name checking" for an explana‐
432 tion of these variables. Note that these are package-wide con‐
433 figuration variables, and will therefore affect all devscripts
434 scripts which check their value, as described in their respec‐
435 tive manpages and in devscripts.conf(5).
436 DEBCHANGE_RELEASE_HEURISTIC
438 Controls how debchange determines if a package has been
439 released, when deciding whether to create a new changelog entry
440 or append to an existing changelog entry. Can be either log or
441 changelog.
442 DEBCHANGE_MULTIMAINT
444 If set to no, debchange will not introduce multiple-maintainer
445 distinctions when a different maintainer appends an entry to an
446 existing changelog. See the discussion above. Default is yes.
447 DEBCHANGE_MULTIMAINT_MERGE
449 If set to yes, when adding changes in multiple-maintainer mode
450 debchange will check whether previous changes by the current
451 maintainer exist and add the new changes to the existing block
452 rather than creating a new block. Default is no.
453 DEBCHANGE_MAINTTRAILER
455 If this is set to no, then it is the same as the --nomaint‐
456 trailer command line parameter being used.
457 DEBCHANGE_TZ
459 Use this timezone for changelog entries. Default is the
460 user/system timezone as shown by `date -R` and affected by the
461 environment variable TZ.
462 DEBCHANGE_LOWER_VERSION_PATTERN
464 If this is set, then it is the same as the --allow-lower-version
465 command line parameter being used.
466 DEBCHANGE_AUTO_NMU
468 If this is set to no then debchange will not attempt to automat‐
469 ically determine whether the current changelog stanza represents
470 an NMU. The default is yes. See the discussion of the --nmu
471 option above.
472 DEBCHANGE_FORCE_SAVE_ON_RELEASE
474 If this is set to no, then it is the same as the
475 --no-force-save-on-release command line parameter being used.
476 DEBCHANGE_VENDOR
478 Use this vendor instead of the default (dpkg-vendor output).
479 See --vendor for details.
480
482 DEBEMAIL, EMAIL, DEBFULLNAME, NAME
483 See the above description of the use of these environment vari‐
484 ables.
485 CHANGELOG
487 This variable specifies the changelog to edit in place of
488 debian/changelog. No directory traversal or checking is per‐
489 formed when this variable is set. This variable is overridden
490 by the --changelog command-line setting.
491 VISUAL, EDITOR
493 These environment variables (in this order) determine the editor
494 used by sensible-editor.
495
497 debc(1), debclean(1), dput(1), dupload(1), devscripts.conf(5)
498
500 The original author was Christoph Lameter <clameter@debian.org>. Many
501 substantial changes and improvements were made by Julian Gilbey
502 <jdg@debian.org>.
503DEBIAN Debian Utilities DEBCHANGE(1)