DEBCHANGE(1)

📦
version 2.26.11ubuntu1 · 7 versions
, in ubuntu stonking

💖 NAME 💖

okay so first things first, welcome to the DEBCHANGE(1) era bestie 🌸 — debchange is literally the tool for maintenance of the debian/changelog file in a source package. that's it, that's the vibe. 🎀

✨ SYNOPSIS ✨

debchange [options] [text ...]
dch [options] [text ...]

🦋 DESCRIPTION 🦋

so debchange, or its little alias dch (iconic, shorter, we stan), will add a new comment line to the Debian changelog in the current source tree. you must run this command from within that tree, no cap, it will not go hunting for you. 💅

if you give the text of the change on the command line, debchange runs in batch mode and just adds the text, with line breaks as necessary, at the appropriate place in debian/changelog (or the changelog specified by options, as described below, iykyk). if the text you give on the command line is a null string, debchange runs in batch mode without adding any text. if the text you give on the command line is a space string, it runs in batch mode and adds a blank changelog entry. wild, but okay.

if no text is specified, then debchange will run the editor as determined by sensible-editor so you can edit the file yourself. (the environment variables VISUAL and EDITOR are used in this order to figure out which editor to use. 📝) editors that understand the +n option for starting the editing on a specified line will use this to move to the correct line of the file for editing. if the editor is quit without modifying the temporary file, debchange will exit without touching the existing changelog — no harm done, we love a clean getaway. 🧚

heads up bestie: the changelog is assumed to be encoded with the UTF-8 encoding. if it is not, problems may occur. 😭 please see the iconv(1) manpage to find out how to convert changelogs from legacy encodings.

finally, a changelog or NEWS file can be created from scratch using the --create option described below. ✨

debchange also supports automatically producing bug-closing changelog entries, using the --closes option. this will usually query the BTS, the Debian Bug Tracking System (see https://bugs.debian.org/) to determine the title of the bug and the package in which it occurs. 🐛 this behaviour can be stopped by giving a --noquery option or by setting the configuration variable DEBCHANGE_QUERY_BTS to no, as described below.

in either case, the editor (as described above) will always be invoked to give an opportunity to modify the entries, and the changelog will be accepted whether or not modifications are made. an extra changelog entry can be given on the command line in addition to the closes entries. slay. 💅

at most one of --append, --increment, --edit, --release, and --newversion may be specified as listed below. if no options are specified, debchange will use heuristics to guess whether or not the package has been successfully released, and behave as if --increment had been specified if the package has been released, or otherwise as if --append had been specified. the guessing game is real bestie. 🔮

two different sets of heuristics can be used, as controlled by the --release-heuristic option or the DEBCHANGE_RELEASE_HEURISTIC configuration variable. the default changelog heuristic assumes the package has been released unless its changelog contains UNRELEASED in the distribution field. if this heuristic is enabled then the distribution will default to UNRELEASED in new changelog entries, and the --mainttrailer option described below will be automatically enabled. this can be useful if a package can be released by different maintainers, or if you do not keep the upload logs. the alternate log heuristic determines if a package has been released by looking for an appropriate dupload(1) or dput(1) log file in the parent directory. a warning will be issued if the log file is found but a successful upload is not recorded. this may be because the previous upload was performed with a version of dupload prior to 2.1 or because the upload failed. 💀

if either --increment or --newversion is used, the name and email for the new version will be determined as follows. if the environment variable DEBFULLNAME is set, this will be used for the maintainer full name; if not, then NAME will be checked. if the environment variable DEBEMAIL is set, this will be used for the email address. if this variable has the form name <email>, then the maintainer name will also be taken from here if neither DEBFULLNAME nor NAME is set. if this variable is not set, the same test is performed on the environment variable EMAIL.

next, if the full name has still not been determined, then use getpwuid(3) to determine the name from the password file. if this fails, use the previous changelog entry. for the email address, if it has not been set from DEBEMAIL or EMAIL, then look in /etc/mailname, then attempt to build it from the username and FQDN, otherwise use the email address in the previous changelog entry.

in other words, it's a good idea to set DEBEMAIL and DEBFULLNAME when using this script. fr fr. 💖

support is included for changelogs that record changes by multiple co-maintainers of a package. if an entry is appended to the current version's entries, and the maintainer is different from the maintainer who is listed as having done the previous entries, then lines will be added to the changelog to tell which maintainers made which changes. 🫶

currently only one of the several such styles of recording this information is supported, in which the name of the maintainer who made a set of changes appears on a line before the changes, inside square brackets. this can be switched on and off using the --[no]multimaint option or the DEBCHANGE_MULTIMAINT configuration file option; the default is to enable it. note that if an entry has already been marked in this way, then this option will be silently ignored. 🙈

if the directory name of the source tree has the form package-version, then debchange will also attempt to rename it if the (upstream) version number changes. this can be prevented by using the --preserve command line or configuration file option as described below. 🎀

if --force-bad-version or --allow-lower-version is used, debchange will not stop if the new version is less than the current one. this is especially useful while doing backports. 🔥

📁 Directory name checking 📁

in common with several other scripts in the devscripts package, debchange will climb the directory tree until it finds a debian/changelog file. as a safeguard against stray files causing potential problems, it will examine the name of the parent directory once it finds the debian/changelog file, and check that the directory name corresponds to the package name. 🕵️‍♀️

precisely how it does this is controlled by two configuration file variables DEVSCRIPTS_CHECK_DIRNAME_LEVEL and DEVSCRIPTS_CHECK_DIRNAME_REGEX, and their corresponding command-line options --check-dirname-level and --check-dirname-regex.

DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:

  • 0 — Never check the directory name.
  • 1 — Only check the directory name if we have had to change directory in our search for debian/changelog. This is the default behaviour.
  • 2 — Always check the directory name.

the directory name is checked by testing whether the current directory name (as determined by pwd(1)) matches the regex given by the configuration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the command line option --check-dirname-regex regex. here regex is a Perl regex (see perlre(3perl)), which will be anchored at the beginning and the end. if regex contains a /, then it must match the full directory path. if not, then it must match the full directory name. if regex contains the string 'PACKAGE', this will be replaced by the source package name, as determined from the changelog. the default value for the regex is: 'PACKAGE(-.+)?', thus matching directory names such as PACKAGE and PACKAGE-version. ✨

the default changelog to be edited is debian/changelog; however, this can be changed using the --changelog or --news options or the CHANGELOG environment variable, as described below. 💅

👑 OPTIONS 👑

  • --append, -a — add a new changelog entry at the end of the current version's entries. 🍓
  • --increment, -i — increment either the final component of the Debian release number or, if this is a native Debian package, the version number. on Ubuntu or Tanglu, this will also change the suffix from buildX to ubuntu1/tanglu1. use -R, --rebuild for a no change rebuild increment. this creates a new section at the beginning of the changelog with appropriate headers and footers. also, if this is a new version of a native Debian package, the directory name is changed to reflect this. if DEBCHANGE_RELEASE_HEURISTIC is changelog (default) and the current release is UNRELEASED, this will only change the version of the current changelog stanza. otherwise, this will create a new changelog stanza with the new version. 🔥
  • --newversion version, -v version — this specifies the version number (including the Debian release part) explicitly and behaves as the --increment option in other respects. it will also change the directory name if the upstream version number has changed. if DEBCHANGE_RELEASE_HEURISTIC is changelog (default) and the current release is UNRELEASED, this will only change the version of the current changelog stanza. otherwise, this will create a new changelog stanza with the new version. 🌈
  • --edit, -e — edit the changelog in an editor. 📝
  • --release, -r — finalize the changelog for a release. update the changelog timestamp. if the distribution is set to UNRELEASED, change it to the distribution from the previous changelog entry (or another distribution as specified by --distribution). if there are no previous changelog entries and an explicit distribution has not been specified, unstable will be used (or the name of the current development release when run under Ubuntu). 🎀
  • --force-save-on-release — when --release is used, an editor is opened to allow inspection of the changelog. the user is required to save the file to accept the modified changelog, otherwise the original will be kept (default). 💖
  • --no-force-save-on-release — do not do so. note that a dummy changelog entry may be supplied in order to achieve the same effect — e.g. debchange --release "". the entry will not be added to the changelog but its presence will suppress the editor. 🧚
  • --create — bestie this one makes a whole new debian/changelog from nothing (or a NEWS file if you passed --news ✨). You must be sitting in the top-level directory for this — zero directory name checking happens, none, we're skipping that whole vibe. The package name and version come from one of three places: you hand them over with --package and --newversion, or they get sniffed out of the directory name via --fromdirname, or you just type them into the generated changelog yourself. The maintainer name gets pulled from the environment if that's even possible, and the distribution is set either with --distribution or straight in the generated changelog file. 💅
  • --empty — only works when you're tagging it along with --create, and what it does is suppress the automatic "initial release" changelog entry (so the next time you run debchange, that's when the first entry shows up). Heads up though 🫶: this makes dpkg-parsechangelog throw a warning on that next invocation, because there's literally no changes. Not a bug, just the consequence, iykyk.
  • --package package — this sets the package name for the new changelog. And it may only be used together with the --create, --increment and --newversion options. No solo runs, she needs her friends. 👑
  • --nmu, -n — bumps the Debian release number for a non-maintainer upload: it either appends a .1 to a non-NMU version number (unless the package is Debian native, in which case +nmu1 gets appended instead) or increments an existing NMU version number, and it drops in an NMU changelog comment. This whole thing happens automatically when the packager isn't in the Maintainer or Uploaders field of debian/control — unless DEBCHANGE_AUTO_NMU is set to no, or you used --no-auto-nmu. ✨
  • --bin-nmu — increments the Debian release number for a binary non-maintainer upload. Either appends +b1 to a non-binNMU version number or increments an existing binNMU version number, and adds a binNMU changelog comment. 🎀
  • --qa, -q — increments the Debian release number for a Debian QA Team upload and adds a QA upload changelog comment. Slay, team effort.
  • --rebuild, -R — increments the Debian release number for a no-change rebuild, by appending build1 or by incrementing an existing rebuild version number. Sometimes you just press the button again, fr fr. 🔁
  • --security, -s — increments the Debian release number for a Debian Security Team non-maintainer upload and adds a Security Team upload changelog comment. Very serious, very iconic. 🔥
  • --lts — increments the Debian release number for a LTS Team non-maintainer upload and adds a LTS Team upload changelog comment. Long term support girlies rise up 🌸
  • --team — increments the Debian release number for a team upload and adds a Team upload changelog comment. Group project but it actually works 💜
  • --upstream, -U — does not append distro-name1 to the version on a derived distribution. Increments the Debian version instead.
  • --bpo — increments the Debian release number for an upload to bullseye-backports and adds a backport upload changelog comment. 🦋
  • --stable — increments the Debian release number for an upload to the current stable release. Comfy. Cozy. Stable. 😌
  • *--local, -lsuffix* — adds a suffix to the Debian version number for a local build. Your own little garnish 🍓
  • --force-bad-version, -b — forces a version number to be less than the current one (e.g. when you're backporting). It's giving chaos but make it intentional 💀
  • *--allow-lower-version *pattern — allows a version number to be less than the current one if the new version matches the specified pattern. Rules with a loophole, love that for you.
  • --force-distribution — forces the distribution you provided to actually be used, even if it doesn't match the list of known distributions (perfect for unofficial distributions). Not on the list? Doesn't matter, she's going anyway. 💅
  • --auto-nmu — attempts to automatically figure out whether a change to the changelog represents a Non Maintainer Upload. And guess what, babe — this is the default. It's already doing this. 😭
  • --no-auto-nmu — disables automatic NMU detection. Equivalent to setting DEBCHANGE_AUTO_NMU to no. Same energy, different spelling.
  • --fromdirname, -d — takes the upstream version number from the directory name, which should be shaped like package-version. If the upstream version number went up from the most recent changelog entry, a new entry gets made with version number version-1 (or version if the package is Debian native), keeping the same epoch as the previous package version. If the upstream version number is the same, this option behaves exactly like -i. 👑
  • --closes nnnnn[,nnnnn ...] — adds changelog entries that close the bug numbers you list. It also invokes the editor after adding these entries. And it will generate warnings if the BTS can't be contacted (and --noquery hasn't been specified), or if there are problems with the bug report it located. ⚠️
  • --[no]query — should we or should we not attempt to query the BTS when generating closes entries? That's the whole question, bestie. ❓
  • --preserve, -p — preserves the source tree directory name if the upstream version number (or the version number of a Debian native package) changes. See also the configuration variables section below. 🫶
  • --no-preserve, --nopreserve — does not preserve the source tree directory name. This is the default, fyi.
  • *--vendor *vendor — overrides the distributor ID that dpkg-vendor returns by default. This name gets used for the heuristics applied to new package versions and for sanity checking the target distribution. 🔍
  • *--distribution *dist, -D dist — uses the specified dist in the changelog entry being edited, instead of using the previous changelog entry's distribution for new entries, or the existing value for existing entries. Say it with your chest and it gets written down. ✨
  • *--urgency *urgency, -u urgency — uses the specified urgency in the changelog entry being edited, instead of using the default "medium" for new entries or the existing value for existing entries. No cap, medium was just the placeholder.
  • *--changelog *file, -c file — this edits file instead of the standard debian/changelog. This option overrides any CHANGELOG environment variable setting. Also, no directory traversing or checking is performed when this option is used — we're going straight to the file, no detours. 🎯
  • *--news [newsfile*] — this edits newsfile (by default, debian/NEWS) instead of the regular changelog. Directory searching will be performed. The changelog gets examined in order to determine the current package version. 📰
  • --[no]multimaint — should we indicate that parts of a changelog entry were made by different maintainers? Default is yes; see the discussion above and also the DEBCHANGE_MULTIMAINT configuration file option below. 🫂
  • --[no]multimaint-merge — should all changes made by the same author be merged into the same changelog section? Default is yes; see the discussion above and also the DEBCHANGE_MULTIMAINT_MERGE configuration file option below. 🧚
  • --maintmaint, -m — do not modify the maintainer details already listed in the changelog. This is especially useful for sponsors who want to automatically add a sponsorship message without disrupting the other changelog details. Note though: there may be some interesting interactions if multi-maintainer mode is in use, and in those cases you'll probably want to check the changelog manually before uploading it. 👀
  • --controlmaint, -M — use the maintainer details from the debian/control Maintainer field rather than the relevant environment variables (DEBFULLNAME, DEBEMAIL, etc.). This might be handy to restore the main maintainer's details in the changelog trailer after a bogus edit (e.g. when -m was intended but you forgot it), or when releasing a package in the name of the main maintainer (e.g. the team). Reparative queen 💖
  • --[no]mainttrailer, -t — if mainttrailer is set, it avoids modifying the existing changelog trailer line (i.e. the maintainer and date-stamp details), unless it's used with options that require the trailer to be modified (e.g. --create, --release, -i, --qa, etc.). This option differs from --maintmaint because it will use multi-maintainer mode if appropriate — with the single exception of editing the trailer. See also the DEBCHANGE_MAINTTRAILER configuration file option below. 🎀
  • *--check-dirname-level *N — see the above section "Directory name checking" for an explanation of this option. (Yes, we covered that already, go peek 👀)
  • *--check-dirname-regex *regex — see the above section "Directory name checking" for an explanation of this option. Same deal, bestie, it's all up there.
  • --no-conf, --noconf — do not read any configuration files. And plot twist: this can only be used as the first option given on the command-line. First in line or it doesn't count. 🚫
  • *--release-heuristic *log|changelog — controls how debchange determines if a package has been released, when it's deciding whether to create a new changelog entry or append to an existing changelog entry. Detective work 🔍✨
  • --date date — uses the specified date in the changelog entry being edited. The date **must be in RFC 5322 format, i.e. as produced by date -R. Format matters, don't freestyle it. 📅
  • --help, -h — displays a help message and exits successfully. Your lil safety net 🫶
  • --version — displays version and copyright information and exits successfully. Iconic of her. 👑

🎀 CONFIGURATION VARIABLES 🎀

okay bestie so there are two config files and they get sourced in this exact order:

  1. /etc/devscripts.conf
  2. ~/.devscripts

sourced one after the other, slay, and they set your configuration variables. 💅

Command line options can override whatever the config files said. Environment variable settings are ignored for this purpose — like, they don't get a vote here, sorry not sorry.

Here's the currently recognised lineup, and yes we're going through all of them:

  • DEBCHANGE_PRESERVE — set it to yes and it's literally the same as passing --preserve on the command line. same energy, different address. ✨
  • DEBCHANGE_QUERY_BTS — set it to no and it's the same as using --noquery on the command line. bye BTS queries, you're on your own. 💀
  • DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX — go peek at the Directory name checking section up above for the whole explanation of these two. ⚠️ heads up though: these are package-wide configuration variables, so they affect all the devscripts scripts that check their value, exactly as described in their own manpages and in devscripts.conf(5). so like, they're not just yours, they're everyone's. 🫶
  • DEBCHANGE_RELEASE_HEURISTIC — this one controls how debchange figures out whether a package has been released, which matters when it's deciding between creating a whole new changelog entry versus appending to one that already exists. it can be either log or changelog. pick your fighter. 🔥
  • DEBCHANGE_MULTIMAINT — if you set this to no, debchange will not introduce those multiple-maintainer distinctions when a different maintainer appends an entry to an existing changelog. the discussion of that is above, go read it. the default is yes. 👑
  • DEBCHANGE_MULTIMAINT_MERGE — set this to yes and, when it's adding changes in multiple-maintainer mode, debchange checks whether previous changes by the current maintainer already exist, and if they do it adds the new changes to that existing block instead of making a brand new block. tidy. the default is yes. 🧚
  • DEBCHANGE_MAINTTRAILER — set it to no and it's the same as the --nomainttrailer command line parameter. iconic.
  • DEBCHANGE_TZ — use this timezone for your changelog entries. the default is the user/system timezone, as shown by date -R and affected by the environment variable TZ. ✨
  • DEBCHANGE_LOWER_VERSION_PATTERN — if this is set, then it's the same as the --allow-lower-version command line parameter being used. yes queen, let the lower versions in. 🦋
  • DEBCHANGE_AUTO_NMU — if this is set to no then debchange won't attempt to automatically determine whether the current changelog stanza represents an NMU. the default is yes. there's a whole discussion of the --nmu option up above if you need the lore. 🔍
  • DEBCHANGE_FORCE_SAVE_ON_RELEASE — if this is set to no, then it's the same as the --no-force-save-on-release command line parameter being used. periodt.
  • DEBCHANGE_VENDOR — use this vendor instead of the default (which is the dpkg-vendor output). check --vendor for the details. 💜

🌈 ENVIRONMENT 🌈

the environment gets a say too, and here's who's talking:

  • DEBEMAIL, EMAIL, DEBFULLNAME, NAME — see the description above for how these get used. they've already had their moment. ✨
  • CHANGELOG — this variable names the changelog to edit in place of debian/changelog. ⚠️ important: when this variable is set, no directory traversal or checking is performed. none. zero. it just goes. and heads up, this variable gets overridden by the --changelog command-line setting, so the flag wins the argument. 💅
  • VISUAL, EDITOR — these two environment variables, in this order, determine which editor sensible-editor uses. so VISUAL gets first dibs, and EDITOR is the backup bestie. 🫶

🔥 SEE ALSO 🔥

go read these next, they're all part of the family:

👑 AUTHOR 👑

the original author was Christoph Lameter <clameter@debian.org>. 💖

many substantial changes and improvements were made by Julian Gilbey <jdg@debian.org>. 🌟

and that's the whole page bestie, we made it to the end 🎉 this one is from the Debian Utilities set and its manual page is DEBCHANGE(1) — shoutout to the legends who wrote it, and shoutout to you for reading all three parts, that's main character energy fr fr. now go update a changelog and slay 💅✨🦋

📦 where this page comes from