1DEBCHANGE(1)                General Commands Manual               DEBCHANGE(1)
2
3
4

NAME

6       debchange  -  Tool  for  maintenance  of the debian/changelog file in a
7       source package
8

SYNOPSIS

10       debchange [options] [text ...]
11       dch [options] [text ...]
12

DESCRIPTION

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
36       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
47       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
54       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
69       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
86       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
99       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
104       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

Directory name checking

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
119       DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
120
121       0      Never check the directory name.
122
123       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
127       2      Always check the directory name.
128
129       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
141       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

OPTIONS

146       --append, -a
147              Add a new changelog entry at the end of  the  current  version's
148              entries.
149
150       --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
164       --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
174       --edit, -e
175              Edit the changelog in an editor.
176
177       --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
186       --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
192       --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
198       --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
210       --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
217       --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
222       --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
232       --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
238       --qa, -q
239              Increment the Debian release number for a Debian QA Team upload,
240              and add a QA upload changelog comment.
241
242       --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
247       --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
252       --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
256       --team Increment the Debian release number for a team upload, and add a
257              Team upload changelog comment.
258
259       --upstream, -U
260              Don't append distro-name1 to the version on a derived  distribu‐
261              tion. Increment the Debian version.
262
263       --bpo  Increment  the  Debian release number for an upload to bullseye-
264              backports, and add a backport upload changelog comment.
265
266       --stable
267              Increment the Debian release number for an upload to the current
268              stable release.
269
270       --local, -lsuffix
271               Add a suffix to the Debian version number for a local build.
272
273       --force-bad-version, -b
274              Force  a  version  number to be less than the current one (e.g.,
275              when backporting).
276
277       --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
281       --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
286       --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
291       --no-auto-nmu
292              Disable  automatic  NMU  detection.   Equivalent  to setting DE‐
293              BCHANGE_AUTO_NMU to no.
294
295       --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
305       --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
312       --[no]query
313              Should  we  attempt  to query the BTS when generating closes en‐
314              tries?
315
316       --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
321       --no-preserve, --nopreserve
322              Do not preserve the source tree directory name (default).
323
324       --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
329       --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
335       --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
340       --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
346       --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
352       --[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
358       --[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
364       --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
373       --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
381       --[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
391       --check-dirname-level N
392              See  the above section "Directory name checking" for an explana‐
393              tion of this option.
394
395       --check-dirname-regex regex
396              See the above section "Directory name checking" for an  explana‐
397              tion of this option.
398
399       --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
403       --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
408       --help, -h
409              Display a help message and exit successfully.
410
411       --version
412              Display version and copyright information and exit successfully.
413

CONFIGURATION VARIABLES

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
421       DEBCHANGE_PRESERVE
422              If this is set to yes, then it is the  same  as  the  --preserve
423              command line parameter being used.
424
425       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
429       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
436       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
442       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
447       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
453       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
457       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
462       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
466       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
472       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
476       DEBCHANGE_VENDOR
477              Use this vendor instead of  the  default  (dpkg-vendor  output).
478              See --vendor for details.
479

ENVIRONMENT

481       DEBEMAIL, EMAIL, DEBFULLNAME, NAME
482              See  the above description of the use of these environment vari‐
483              ables.
484
485       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
491       VISUAL, EDITOR
492              These environment variables (in this order) determine the editor
493              used by sensible-editor.
494

SEE ALSO

496       debc(1), debclean(1), dput(1), dupload(1), devscripts.conf(5)
497

AUTHOR

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>.
502
503
504
505DEBIAN                         Debian Utilities                   DEBCHANGE(1)
Impressum