DH_ASSISTANT(1)

📦
version 14.5ubuntu1 · 12 versions
, in ubuntu stonking

🫶 dh_assistant 🫶

okay bestie, this is dh_assistant(1) from the Debhelper manual, section 1 — and it's genuinely the moment debhelper let the other tools peek behind the curtain. no gatekeeping 💅

💖 NAME 💖

dh_assistant — a tool for supporting debhelper tools and providing introspection ✨ (fr fr, that's literally the whole job)

🌸 SYNOPSIS 🌸

dh_assistant command [additional options]

🦋 DESCRIPTION 🦋

dh_assistant is a debhelper program, and what it does is introspection into the debhelper stack 😌 It's here to help:

  • third-party tools (e.g. linters — yes, the ones that roast your debian/control 👀)
  • third-party debhelper implementations that aren't using the debhelper script API — like, because they're not written in Perl 🐪

👑 COMMANDS 👑

dh_assistant supports the following commands, and we are doing all of them, no skipping:

✨ active-compat-level (AJSON) ✨

Synopsis:

dh_assistant active-compat-level

This one spills the tea on which compat level the package is using 🍵

heads up: for packages without valid debhelper compatibility information — whether that's missing, ambiguous, not supported or simply invalid — this command operates on a "best effort" basis and may abort when error instead of providing data. it's giving chaos, so don't be shocked 😭

The returned JSON dictionary contains the following key-value pairs:

  • active-compat-level — the compat level that debhelper will be using. This is the same as DH_COMPAT when present, or else declared-compat-level. It can be null when no compat level can be detected at all 🙈
  • declared-compat-level — the compat level that the package declared as its default. This can be null if the package does not declare any compat level at all, periodt.
  • declared-compat-level-source — defines how the compat level was declared. This is null (for the same reason as declared-compat-level) or one of:
    • debian/compat — the compatibility level was declared in the single line debian/compat file 📄
    • X-DH-Compat: <C> — the compatibility was declared in the debian/control via a the X-DH-Compat field. In the output, the C is replaced by the actual compatibility level. A full example value would be:
X-DH-Compat: 15
  • Build-Depends: debhelper-compat (= <C>) — the compatibility was declared in the debian/control via a build dependency on the debhelper-compat (= <C>) package in the Build-Depends field. In the output, the C is replaced by the actual compatibility level. A full example value would be:
Build-Depends: debhelper-compat (= 15)

✨ supported-compat-levels (AJSON, CRFA) ✨

Synopsis:

dh_assistant supported-compat-levels

Outputs information about which compat levels, this build of debhelper knows about 👑 she's well-read.

This command accepts no options or arguments. None. Zero. Immaculate low-maintenance energy 💅

✨ which-build-system (AJSON) ✨

Synopsis:

dh_assistant which-build-system [build step]
[build system options]

Output information about which build system would be used for a particular build step 🔧

The build step must be one of configure, build, test, install or clean and must be the first argument after which-build-system when provided. If omitted, it defaults to configure as it is the most reliable step to use auto-detection on in a clean source directory. Also, note that build steps do not always agree when using auto-detection — particularly if the configure step has not been run 😭

Additionally, the clean step can also provide "surprising" results for builds that rely on a separate build directory. In such cases, debhelper will return the first build system that uses a separate build directory rather than the one build system that configure would detect. This is generally a cosmetic issue, as both build systems are all basically a glorified rm -fr builddir and more precise detection is functionally irrelevant as far as debhelper is concerned 🫠 slay, honestly.

The option accepts all debhelper build system arguments — i.e., options you can pass to all of the dh_auto_* commands plus (for the install step) the --destdir option. These options affect the output and auto-detection in various ways. Passing -S or --buildsystem overrides the auto-detection (as it does for dh_auto_*) but it still provides introspection into the chosen build system.

Things that are useful to know about the output:

  • The key build-system is the build system that would be used by debhelper for the given step (with the given options, debhelper compat level, environment variables and the given working directory). When -S and --buildsystem are omitted, this is the result of debhelper's auto-detection logic ✨
    • The value is valid as a parameter for the --buildsystem option.
    • The special value "none" is used to denote that no build system would be used (that is, a JSON string). This value is not present in --list parameter for the dh_auto_* commands, but since debhelper/12.9 the value is accepted for the --buildsystem option.
    • Note that auto-detection is subject to limitations in regards to third-party build systems. While debhelper does support auto-detecting some third-party build systems, they must be installed for the detection to work. If they are not installed, the detection logic silently skips that build system (often resulting in build-system being "none" in the output). ghosted 💀
  • The build-directory and buildpath values serve different but related purposes. The build-directory generally mirrors the --builddirectory option where as buildpath is the output directory that debhelper will use. Therefore the former will often be null when --builddirectory has not been passed while the latter will generally not be null (except when build-system is none).
  • The dest-directory (--destdir) is undefined for all build steps except the install build step (will be output as null or absent). For the same reason, --destdir should only be passed for install build step. Note that if not specified, this value is currently null by default.
  • The parallel value is subject to DEB_BUILD_OPTIONS. Notably, if that does not include the parallel keyword, then parallel field in the output will always be 1.
  • Most fields in the output can be null. Particular if there is no build system is detected (or when --buildsystem=none). Additionally, many of the fields can be null even if there is a build system if the build system does not use/set/define that variable 🤷

✨ parse-dh-cli-args (AJSON, BLD) ✨

Synopsis:

dh_assistant parse-dh-cli-args dh_assistant-options -- command-line-options

Parses command-line-options like a dh_* command would and output a JSON document with the result 📋

This subcommand is aimed at supporting third-party commands in implementing the debhelper command-line parsing logic. The rules look deceptively simple but turns out to be very complex, which means that tools not written using the Debian::Debhelper::Dh_Lib module will be at a massive disadvantage. As a consequence, consumers get a mixed result since some times behave differently to the same options than others 😵‍💫 it's giving inconsistent, bestie.

This command reacts to option parsing like any built debhelper command and therefore accounts for DH_OPTIONS and other such environment variables. However, since dh_assistant has to parse the options without knowing all arguments, it might get command specific options wrong if the value looks like option. As an example, if dh_assistant sees --foo -a, it assumes -a is the debhelper -a and leaves --foo as unparsed. If --foo always takes a parameter in the caller, then this is the wrong behavior. This ambiguity can be avoided if --foo=-a is passed instead. This problem can also occur due to "bundling" such as -fa (which debhelper reads as the two independent options -f -a. This is for the caller to avoid 🙃

If the command returns successfully, the output will be JSON describing the options (see description below for the details). Otherwise, there will be a human readable error on stderr for what went wrong. Note that stderr can also be used to emit warnings on a successful run.

The command-line-options should be the command line options the caller wish to have parsed on their behalf 💁

🎀 Options specific for dh_assistant 🎀

The command accepts the following arguments in the place of dh_assistant-options:

  • --on-behalf-of-cmd=COMMAND (mandatory) — the name of the command calling 📞
  • --masquerade, --no-masquerade (optional) — whether dh_assistant should pretend to be the caller if it outputs any warnings or errors. By default, it will use its own name but mention the calling command. When --masquerade is passed, only the calling commands name will be listed in the log file. The difference being whether the user sees:
dh_assistant (for dh_command): ...

vs.

dh_command: ...

Though, this option is only relevant if the stderr of the dh_assistant process is not redirected away.

  • --inhibit-log, --no-inhibit-log (optional) — whether dh_assistant should write to the debhelper log that the command has acted on the packages (when that is relevant). Any package name listed in active-packages of the output will be marked as acted on in the log when the log is used and --inhibit-log is used (which is the default). This is necessary for --remaining-packages to work correctly in hook targets. If --no-inhibit-log is passed, the caller must update the log themselves on successful completion of the command.
  • --noop-warnings, --no-noop-warnings (optional) — it is possible for a command to end up in a situation where the command line options plus the current build implies there are no packages to be acted on. This results in the active-packages key of the output being an empty list. Generally, the correct answer here is to output a warning and exit successfully despite having done nothing. By default (--noop-warnings), dh_assistant emits these warnings on behalf of the caller. The --no-noop-warnings can be used if the warning is undesirable for some reason.

🌈 JSON output format 🌈

The output of this command is a JSON document of

{
  "active-packages": ["debhelper"],
  "debhelper-settings": {
    "exclude": [],
    "no-act": false,
    "no-scripts": false,
    "quiet": false,
    "requested-staging-dir": null,
    "verbose": false
  },
  "options": {
    "--all": false,
    "--name": null,
    "-d": null,
    "-v": null,
    "args": [],
    "try-args": []
  },
  "packages": {
    "debhelper": {
       "binary-arch": "all",
       "declared-arch": "all",
       "package-type": "deb"
    }
  }
}

The keys have the following definition:

  • active-packages — list of packages to act on.

...and it's totally fine for this list to be empty, bestie! That happens when the user asked for packages that literally cannot be built — like with -a when every single package is Architecture: all, for example. 💫

The value is always included and never null. No cap.

debhelper-settings

This one's an object full of the common, well-defined debhelper options that might actually be interesting to you. Not all of them map 1:1 onto a command line option — quiet is basically the lovechild of not passing -v and having DEB_BUILD_OPTIONS=terse — but they still get served up here for simplicity's sake. 🫶

The object is always included and never null.

Here are the key-value pairs defined inside it:

verbose, quiet

These two define how chatty the command should be. They're never both true at the same time, because debhelper is a -v (verbose) girlie over terse (quiet) every single time. That said, they can both be false simultaneously — and that's the default state, lowkey iconic.

verbose gets triggered by stuff like -v, --verbose, or the DH_VERBOSE environment variable. quiet gets triggered by things like DEB_BUILD_OPTIONS containing terse.

The values are always set, boolean, and never null.

no-act

When true, the user passed --no-act. So the command is expected to write out what it would do without actually doing any of it. The accuracy here is best-effort only — actions can have side-effects that mess with later actions, and emulating all of that is genuinely difficult. 😭

The value is always set, boolean, and never null.

no-scripts

These options correspond to the --no-scripts option.

They typically control whether the command should generate maintscripts. When true, the command should skip generating those script snippets entirely. Some commands also use this to control whether triggers get generated, for historical reasons. 🕰️

The value is always set, boolean, and never null.

exclude

This is a list of every requested exclusion. Usually these come from --exclude options, but it also pulls in values from other sources like ENV variables. ✨

It's up to the command itself to define how exclusions affect it (if at all), or even how they match. Common examples are substring matching or regexes on filenames.

The value is always set, a list, and never null — but the list can be empty.

requested-staging-dir

This is a nullable string matching the -P option. If it's null (the default), then the default per-package staging directory should be used: debian/PACKAGE.

It only makes sense when there's at most one active package. Note it can show up with no active packages at all — like if the command is called unconditionally with -p PKG and the provided package shouldn't be built for some reason.

Note: the directory (when provided) can be either relative or absolute, depending on how the value for the option was defined. Also, the directory isn't required to exist, since tools are expected to create directories as needed. 💅

options

An object containing info about the command options that were used. The object is always present and never null.

Here are the key-value pairs defined inside it:

--all

Whether the --all option was passed. It's a boolean option (never null).

This is a niche option and honestly a lot of commands just ignore it. 🙈

--name

If it's not null, then the --name parameter was passed. For commands that support named configuration files, it defines the named segment of the files and typically also part of the basename the file gets installed under (if it's installed at all).

Many commands ignore this option too.

-d, -V

These options are defined as common arguments, but with no well-defined meaning. Commands are free to choose their own definition, so it's giving "you figure it out."

-d is a boolean option (never null). The value is true if -d was passed and false otherwise. -V is a parameter that optionally takes a string. It'll be null if -V wasn't passed; otherwise it'll be a string. The empty string means no value was passed to -V.

args

A list of arguments that dh_assistant didn't understand and assumes are arguments for the caller. Their relative order is preserved, but debhelper-specific options get removed. For example, if dh_assistant is passed --foo -a -v bar, then args will be the list ["--foo", "bar"]. 🌈

The value is always present, a list, and never null. It can be — and often is — empty.

try-args

A list of arguments that were prefixed with -O and that dh_assistant didn't understand.

The caller should try to parse each of them individually and accept the ones it understands. Unknown arguments should be ignored silently. 🤫

When parameters that accept values are passed via -O, they must always be passed with their value as a single argument (like -O--foo=bar). This is a deeply rooted assumption in debhelper, and the caller is expected to follow that assumption rather than conditionally parsing an extra argument.

The value is always present, a list, and never null. It can be — and often is — empty.

packages

An object containing info about packages. The object is always present and never null.

Each key is the name of a package defined in debian/control. The values are an object. There's always a key for every package defined in debian/control, even the ones that aren't listed in active-packages. 👑

Here are the key-value pairs defined in the per-package object:

declared-arch

This is the value of the Architecture field, and therefore a string. That string can be interpreted as a space-separated list of architectures or architecture wild cards.

If the value is equal to all, then the package is an arch:all package.

binary-arch

This is the architecture of this binary package if it is built. Unlike declared-arch, this is always a single architecture.

If the value is equal to all, then the package is an arch:all package.

You'd be forgiven for assuming this value is always either all or the value of DEB_HOST_ARCH. While that holds in 99.9% of cases, debhelper supports some extremely special cases where that is not true. Consumers are recommended to use this value rather than doing their own computation here. Trust the process. ✨

package-type

This is the type of package being built — the Package-Type field.

Most commonly the value will be deb. However, udeb is another known value. 🎀

detect-hook-targets (EXEC, AJSON)

Synopsis: dh_assistant detect-hook-targets

Detects possible override targets and hook targets that dh(1) might use — provided that the relevant command is in the sequence. 🔍

UNSAFE: This command relies on the output of make. Even in its dry-run mode, make may execute commands from debian/rules. Avoid using this on packages from untrusted sources, where you haven't reviewed the packaging for backdoors. Bestie, I am so serious about this one. 💀

The detection works by scanning the rules file for any target that might look like a hook target, which means it can absolutely list targets that are in fact not hook targets — or are hook targets but will never be triggered for other reasons.

The detection uses similar logic for scanning the rules file, so it's subject to makefile conditionals (i.e., the truth value of makefile conditionals can change whether a hook target shows up in the output of this command). In theory, you'd have to set up the environment to look like it would during a build to get the most accurate output. Though a lot of packages won't have conditional hook targets, so the "out of the box" behaviour works well in most cases. 🦋

The output looks something like this:

{
   "commands-not-in-path": [
      "dh_foo"
   ],
   "hook-targets": [
      {
         "command": "dh_strip_nondeterminism",
         "is-empty": true,
         "package-section-param": null,
         "filename": "debian/rules",
         "target-name": "override_dh_strip_nondeterminism"
      },
      {
         "command": "dh_foo",
         "is-empty": false,
         "package-section-param": "-a",
         "filename": "debian/rules",
         "target-name": "override_dh_foo-arch"
      }
   ]
}

In more detail:

commands-not-in-path

This attribute lists all the commands related to hook targets that dh_assistant couldn't find in PATH. These are usually caused by either the command not being installed on the system where dh_assistant is run, or by the command not existing at all. 😭

If you're using this command to verify that a hook target is present, please double check that the command is spelled correctly!

hook-targets

A list of the hook targets found, along with additional info about them.

command

Attribute that lists which command this hook target is related to.

target-name

The actual target name detected in the debian/rules file.

is-empty

A boolean that determines whether dh(1) will optimize the hook out at runtime (see "Completely empty targets" in dh(1)). Note that empty override targets will still cause dh(1) to skip the original command.

package-section-param

This attribute defines what package selection parameter should be passed to dh_* commands used in the hook target. It can either be -a, -i, or (if no parameter should be used) "null".

filename

This attribute reports which file the target was found in. In most cases this will always be "debian/rules", though in the case of include files, the target could appear in an include file. Note this attribute is not super reliable, since make(1) only reports it for targets with a "recipe" (targets with commands inside them). When make doesn't provide the filename, dh_assistant blindly assumes the filename is "debian/rules" (as overrides via includes isn't a commonly used feature). 💖

Also bestie, lowkey important: the accuracy of that filename attribute is limited by what data dh_assistant can actually read out of this command:

LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null

This command accepts no options or arguments.

🔍 detect-unknown-hook-targets (EXEC, AJSON, LINT)

Synopsis:

dh_assistant detect-unknown-hook-targets [--output-format=json] [command-options]

Okay so this one sniffs out unknown and possibly misspelled override targets and hook targets in debian/rules that will most likely not be used by dh(1). It's giving "spellcheck but for your rules file" ✨

UNSAFE: this command relies on the output of make. Even in its dry-run mode, make may execute commands from debian/rules. Avoid using it on packages from untrusted sources where you have not reviewed the packaging for backdoors. fr fr, don't run this on random code you found in a ditch 💀

Now, this command differs from detect-hook-targets subtly in the scope. detect-hook-targets will list all targets that look like hook targets whether they are applicable or not. This command shows all hook targets for which a command cannot be found in any sequence. So basically: this one is better for linting purposes, whereas detect-hook-targets is better if you just want to know which hook targets are present. All the limitations listed in detect-hook-targets about scanning the rules file apply equally to this command. 🫶

This command will attempt to load any sequence add-on listed via build-dependencies, and therefore these must be installed. Additional modules can be passed via --with like with dh(1) as needed.

This command will also need one of the following perl modules to be available: Text::Levenshtein, Text::LevenshteinXS, Text::Levenshtein::XS. The first one can be installed via apt install libtext-levenshtein-perl.

The text output is intended for human consumption and should be self-explanatory. Since it is not stable, it will not be documented. The JSON output looks something like this:

{
   "unknown-hook-targets": [
      {
         "target-name": "execute_before_dh_instlal",
         "filename": "debian/rules",
         "candidates": [
            "execute_before_dh_install"
         ]
      }
   ],
  "hook-targets-for-disabled-commands": [
      {
         "filename": "debian/rules",
         "target-name": "override_dh_builddeb",
         "removed-by": "zz-debputy"
      }
   ],

}

In more details, bestie 👇

  • unknown-hook-targets — list of all the unknown hook targets found, along with additional information about them.
    • target-name — the actual target name detected in the file (usually debian/rules).
    • filename — this attribute reports which file the target was found in. In most cases this will always be debian/rules, though in the case of include files, the target could appear in an include file. Note this attribute is not super reliable, because make(1) only reports it for targets with a "recipe" (targets with commands inside them). When make does not provide the filename, dh_assistant blindly assumes the filename is debian/rules (as overrides via includes is not a commonly used feature).
      • Note this accuracy of this attribute is limited about what data dh_assistant can read out from the following command:
LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null
  • candidates — when not null and not empty, each element in this list are names for likely candidates for the "correct" name of this target. it's literally autocorrect energy 💅
  • hook-targets-for-disabled-commands — list of known hook targets found related to disabled commands, along with additional information about them.
    • target-name — the actual target name detected in the file (usually debian/rules).
    • filename — this attribute reports which file the target was found in. In most cases this will always be debian/rules, though in the case of include files, the target could appear in an include file. Note this attribute is not super reliable, because make(1) only reports it for targets with a "recipe" (targets with commands inside them). When make does not provide the filename, dh_assistant blindly assumes the filename is debian/rules (as overrides via includes is not a commonly used feature).
      • Note this accuracy of this attribute is limited about what data dh_assistant can read out from the following command:
LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null
  • removed-by — if present, this denotes the dh add-on that removed the command from the sequence (thereby disabling this command for that package).
    • Note this field is not present in all cases. As an example, obsolete commands (such as dh_gconf) are not part of any sequence by the time they are marked as obsolete.
    • If you (as a consumer) need to know whether a command is obsolete or the particular reason why a command was disabled, please file a feature request to get that data. The absence of removed-by is not guaranteed to imply the command is obsolete. read that twice, bestie, it's a trap for parsers
  • issues — if present, then it is a list of one or more reasons why this output is definitely incomplete. Each element in the list is an object with the following keys:
    • issue — a key defining the issue. Currently it is always load-addon, which signals that dh_assistant could not load the add-on listed in the addon key.
      • Parsers should assume new issue types may appear in the future. future-proofing, periodt
    • addon — if present, it defines the name of a dh sequence add-on that is related to the failure.

This command accepts the following options:

  • --output-format=FORMAT — request a certain type of output format. Valid values are text or json.
    • The text format is intended for human consumption and may change between versions without any regard for machine consumption. If you want to use this command for machine consumption, please use the json format.
  • --no-linter-exit-code, --linter-exit-code — these options control whether the command should exit with the linter exit code (2) or not (0) when an unknown target is found. By default, it uses the linter exit code when an unknown target is found.
  • --with addon, --without addon — these options behave the same as the dh(1) options with the same name.

📋 list-commands (RJSON)

Synopsis:

dh_assistant list-commands [--output-format=json] [command-options]

Okay so this one is so satisfying tbh. It loads all dh sequence add-ons and extracts a full list of all commands that will be invoked across all sequences. It makes no attempt to filter out commands that will not be run due to override targets or due to certain sequences not being run (by dh or at all). it's giving "here's everyone, no filter, main character energy for every single command" 👑

As the command will attempt to load all plugins, they must be installed.

The text output is intended for human consumption and should be self-explanatory. Since it is not stable, it will not be documented. The JSON output looks something like this:

{
   "commands": [
      {
         "command": "dh_auto_build"
      },
      {
         "command": "dh_auto_clean"
      },
      [... more commands listed here... ]
   ],
   "removed-commands": [
       {
           "command": "dh_gconf"
       },
   ]
   "issues": [
        {
            "issue": "load-addon",
            "addon": "foo"
        }
   ]
}
  • commands — the top level key containing the list of all commands. Each element in the list is an object and can have the following keys:
    • command — the name of the command.
      • While most commands are resolved via PATH, a sequence add-on could register a command via a full path (by passing the path search). If so, the command provided in this output will also use the full path. no sneaky shortening, we show the whole path, slay
  • disabled-commands — the top level key containing the list of all known commands that have been disabled. Each element in the list is an object and can have the following keys:
    • command — the name of the command.
      • While most commands are resolved via PATH, a sequence add-on could register a command via a full path (by passing the path search). If so, the command provided in this output will also use the full path.
    • removed-by — if present, this denotes the dh add-on that removed the command from the sequence (thereby disabling this command for that package).
      • Note this field is not present in all cases. As an example, obsolete commands (such as dh_gconf) are not part of any sequence by the time they are marked as obsolete.
      • If you (as a consumer) need to know whether a command is obsolete or the particular reason why a command was disabled, please file a feature request to get that data. The absence of removed-by is not guaranteed to imply the command is obsolete.
  • issues — if present, then it is a list of one or more reasons why this output is definitely incomplete. Each element in the list is an object with the following keys:
    • issue — a key defining the issue. Currently it is always load-addon, which signals that dh_assistant could not load the add-on listed in the addon key.
      • Parsers should assume new issue types may appear in the future.
    • addon — if present, it defines the name of a dh sequence add-on that is related to the failure.

This command accepts the following options:

  • --output-format=FORMAT — request a certain type of output format. Valid values are text or json.
    • The text format is intended for human consumption and may change between versions without any regard for machine consumption. If you want to use this command for machine consumption, please use the json format.
  • --with addon, --without addon — these options behave the same as the dh(1) options with the same name.

🕵️ list-guessed-dh-config-files (AJSON)

Synopsis:

dh_assistant list-guessed-dh-config-files [command-options]

It pulls in every dh sequence add-on that's declaratively depended on, figures out the full list of commands that could matter for this source package, and then — for every command that's used — has a lil guess at which "config files" those commands are interested in. 🔍✨

It will include config files for commands that are not active with the current add-ons, bestie, because those commands can still get run manually from hook targets. 💅

ok important: this only guesses "per command config files". The standard global config files — think debian/control, debian/rules, debian/compat — are NOT in this output. Not invited to the party. 🙈

And like, as the command name literally implies, the output is not a complete list and never will be. 😭 dh_assistant has to derive it from optional metadata that commands choose to provide, and it has no means to validate that this metadata is up to date. It's giving trust issues, fr.

Also — because it tries to load all the plugins that the package references, those plugins must be installed. No plugin, no service. 📦✨

The text output is for human consumption and should be self-explanatory. Since it is not stable, it is not documented. The JSON output looks something like this:

{
   "config-files": [
      {
         "commands": [
            {
               "command": "dh_autoreconf_clean"
               "is-active": true
            }
         ],
         "file-type": "pkgfile",
         "pkgfile": "autoreconf.before"
      },
      {
         "commands": [
            {
               "command": "dh_installgsettings"
               "is-active": true
            }
         ],
         "file-type": "pkgfile",
         "pkgfile": "gsettings-override"
      },
      # [ ... more entries here ...]
   ],
   "issues": [
       {
            "issue": "load-addon",
            "addon": "foo"
       }
   ]
}
  • config-files — the top level key holding the list of all the config-files. Each element of that list is an object, and it can have the following keys:
    • file-type — the type of config file that got detected. At the time of writing this is either pkgfile or path. That said, other values may show up in the future, so don't be shocked, ok? 👀

When it's pkgfile, then the config file is a debhelper pkgfile — named after the pkgfile sub in Debian::Debhelper::Dh_Lib that locates the file. The value denoted by the pkgfile key is the stem of the pkgfile (the install in debian/package.install).

  • pkgfile — when file-type is pkgfile, this key defines the name stem of the pkgfile. For example, this will be install for dh_install(1)'s config file and docs for dh_installdocs(1)'s config file.

When file-type is not pkgfile, then this key will be absent.

Typically the names for these files are:

debian/PKGFILE
debian/PACKAGE.PKGFILE

However, there are more variants, caused by --name plus architecture specific suffixes. The multiverse of pkgfiles. 🌈

  • path — when file-type is path, this key defines the static path of the configuration. For example, this will be debian/clean for dh_clean(1)'s config file and debian/not-installed for dh_missing(1).

When file-type is not path, then this key will be absent.

  • internal — this key may exist, and any value for it is not standardized. Use at own peril. 💀

It's used for documenting certain specific implementation details, like bug compatibility, and it may change as the situation changes.

  • commands — this key is a list, and each element in it is an object with the following keys:
    • command — the name of the command that's interested in this config file. Multiple commands can be interested in the same config file. An example of this would be dh_installinit, dh_installsystemd and dh_installtmpfiles, which all react to (the now) deprecated tmpfile pkgfile. In that particular case, only one command reacts to the file for a given compat level — but that information is not available to dh_assistant, and therefore it's not available in this output either. Sorry bestie, it's a whole thing. 😭
    • is-active — a boolean that determines whether the command is active with the loaded sequences. When false, the command is known to debhelper but it is not run automatically via dh. The command might be explicitly removed by a sequence, marked as obsolete, or possibly known to debhelper as a command that would activate at a different command level (than the one that's currently active).

Note that commands which are not "active" can often still be invoked manually from debian/rules via hook targets. So this reflects whether dh would call the command directly or provide its standard hook targets for the command.

  • removed-by — if present, this denotes the dh add-on that removed the command from the sequence (thereby disabling this command for that package).

Note this field is not present in all cases, regardless of the value of is-active. As an example: obsolete commands (such as dh_gconf) are not part of any sequence by the time they're marked as obsolete.

If you (as a consumer) need to know whether a command is obsolete, or the particular reason why a command was disabled, please file a feature request to get that data. 🙏 The absence of removed-by plus is-active being false is not guaranteed to imply the command is obsolete.

  • issues — if present, then it's a list of one or more reasons why this output is definitely incomplete. Each element in the list is an object with the following keys:
    • issue — a key defining the issue. Currently it is always load-addon, which signals that dh_assistant could not load the add-on listed in the addon key.

Parsers should assume new issue types may appear in the future. 👑

  • addon — if present, it defines the name of a dh sequence add-on that's related to the failure.

This command accepts the following options:

  • --with addon, --without addon — these options behave the same as the dh(1) options with the same name. Periodt.

🎀 log-installed-files (BLD) 🎀

Synopsis:

dh_assistant log-installed-files -ppkg
[--on-behalf-of-cmd=dh_foo] path ...

Mark one or more paths as installed for a given package. This is useful for telling dh_missing(1) that the paths have been installed manually. 🫶

The --on-behalf-of-cmd option can be used by third-party tools so that dh_assistant lists them as the installer of the provided paths. The convention is to use the basename of the tool itself as its name (e.g. dh_install).

Please keep in mind that:

  • No glob or substitution expansion is done by dh_assistant on the provided paths. If you want globs, have the shell do the expansion first. Bestie, do it yourself. 💅
  • Paths must be given as relative to the source root directory (e.g., debian/tmp/...).
  • You can provide a directory. If you do, the directory and anything recursively below it will be considered as installed. Note that it's fine to provide the directory even if paths inside of it have been excluded — as long as the directory is fully "covered". 🧺
  • Do not worry about providing the same filename twice in different invocations of dh_assistant because of -arch / -indep overrides. While it will be recorded multiple times internally, dh_missing(1) will deduplicate when it parses the records. Slay, dedup. ✨

Note this command only marks paths as installed. It does not actually install them — the caller should make sure the paths are in fact handled (or installed). Don't @ me. 😭

🌸 restore-file-on-clean (BLD) 🌸

Synopsis:

dh_assistant restore-file-on-clean FILE ...

This command takes a backup of the listed files and tells dh_clean(1) to restore them when it runs. 🧚

Note that generally you do not need to restore modified files on clean. Often you can get away with just removing them if they're regenerated anyway (which is the most common case for files being modified during builds). Use this command when something taints a file and the build does not cope with the file being removed.

The file is stored in debian/.debhelper. If you remove this directory manually without calling dh_clean(1), then your dh_assistant-provided backup is gone permanently and the restore will never occur. At that point, only a version control system or another backup can restore the files. 💀 No cap, that's it, that's the end of the road.

The command has the following limitations:

💀 No thread-safety - concurrency will corrupt the restore

The command relies on updating an internal index, and concurrent writes will cause it to be corrupt.

While most dh_* commands do not use the underlying function, any of them could do so. Avoid running another dh_* command while dh_assistant processes this command — especially running multiple concurrent instances of dh_assistant restore-file-on-clean, which is literally asking for corruption! 🙈

This command will only restore files — not directories, and not symlinks to files. It will reject any non-files.

Additionally, if the directory containing the file is removed, the restore will fail (since debhelper does not track the directory, it cannot restore it reliably). If this happens, you can do a mkdir to restore the directory and run dh_clean(1) again to get the files back. After that, consider what went wrong and whether you're using the correct tool(s). 🫠

💀 Strict file names

All filenames must be relative to the package root (without using the ./ prefix). No hidden files (that is, any file starting with a period .) and no version control directories (such as CVS). The checks are best effort.

These checks are here to make sure you don't accidentally trash important data that would help you undo mistakes. 🥺

💀 Heavy duty

The command takes a full copy of all the files you pass it. This is fine for a handful of small files, which is the intended use-case. If you find yourself passing 10+ files or very large files, you might be applying a sledgehammer where you needed a different tool. 🔨👑

💅 compat-upgrade-checklist (EXEC) 💅

Synopsis:

dh_assistant compat-upgrade-checklist [--target-compat N]

Bestie, this one literally makes you a compat upgrade checklist for whatever package you're standing in. That's the whole job. ✨

It's meant to be a lil ✨helper✨ for contributors who are bumping a package up to a newer compat level. And where it can, dh_assistant will try to clock which items are probably irrelevant and mark them as such — but heads up, the logic is a heuristic in a whole bunch of cases, so it can give you false-positives and false-negatives. It's giving vibes, not gospel. 🙈

The output? A markdown-based checklist template, designed to be human-readable — and output stability is not a goal, so don't you dare script against it, iykyk. Typically you're gonna pipe stdout somewhere and then edit the checklist as you work through it, a la:

dh_assistant compat-upgrade-checklist > debian/compat-upgrade-checklist.md
editor debian/compat-upgrade-checklist.md
# Iterate through the checklist, tweak the packaging, cross off items from the checklist (rinse and repeat)
# Finally, remove the checklist.
rm -f debian/compat-upgrade-checklist.md  # when the migration is complete

It'll hand you a checklist up to the latest stable compat level, or up to whatever compat level you gave it via the --target-compat option. Your choice, queen. 👑

This command accepts the following options:

  • --target-compat N — ask for the upgrade checklist to stop at the compat level you name instead of going all the way to the highest stable compat level. You can use it to cap the checklist at a given compat level, or to request checklists for experimental compat levels. 🧪
But no cap: you cannot use this option to generate a checklist for downgrading to a previous compat level. Try it and you get an error message. Periodt. 💀

Note: if you run this command from a git checkout of debhelper, the behavior is slightly different — it won't correctly track which compat levels are stable (because that's a build-time inserted property). So by default you'll see experimental compat levels in the checklists, and they won't be marked as such. If you're using the git checkout, staying extra careful with those limitations of the generated checklist falls on you. No pressure bestie. 🫶

🌸 supports (CFFA) 🌸

Synopsis:

dh_assistant supports COMMAND

This one is a scripting aid, so you can programmatically find out whether dh_assistant knows about a given subcommand. Hand it the name of a subcommand, and it'll exit successfully if the subcommand was known — and unsuccessfully if it wasn't. Clean, simple, iconic. ✨

🏷️ COMMAND TAGS 🏷️

Most commands have one or more of these "tags" attached to them, and their meanings live right here. Let's get into it. 💖

  • EXEC — this command will or may execute content from the package. Do not run on untrusted packages. 🚨

Note: this tag only applies if the command will be unsafe out of the box. For example, commands that parse the output of make are inherently unsafe, because it's trivial for make to have make run code even in --dry-run mode. Counter example: commands that only load dh add-ons are considered safe, because PERL5LIB is assumed to be curated to only include trusted plugins. 🧚

  • AJSON — the command always provides JSON output. See "JSON OUTPUT" for details. 📋
  • RJSON — the command can provide JSON output via --output-format=json, but doesn't do it by default. See "JSON OUTPUT" for details when using --output-format=json. 📋
  • LINT — the command is, or can be, used for linting purposes. This command will exit with code 2 when an important issue is found. Be careful if the command is also tagged with EXEC — when that happens, the command should only be used on trusted content (see the EXEC tag for details). 👀

Note that commands may have options that redefine what counts as an "important" issue.

  • CRFA — mnemonic: "Can be Run From Anywhere". 🗺️

Most commands must be run inside a source package root directory (a directory containing debian/control), because debhelper needs the package metadata to look up the information. Any command with this tag is exempt from that requirement and is expected to work no matter where you run it from. Slay.

  • BLD — the command is intended to be used as part of a package build. It may leave artifacts behind that will need a dh_clean(1) invocation to remove. 🧹

🌈 JSON OUTPUT 🌈

Most commands use JSON format as output. Consumers, listen up, you need to be aware that:

  • Additional keys may be added at any time. For backwards compatibility, the absence of a key should in general be interpreted as null — unless another default is documented or would be "obvious" for that case.
  • Many keys can be null/undefined in special cases. For example, some information may be unavailable when this command is run directly from the debhelper source (git repository).

The output will be prettified when stdout is detected as a terminal. If you need to pipe the output to a pager/file (etc.) and still want it prettified, please use an external JSON formatter. An example of this:

dh_assistant supported-compat-levels | json_pp | less

🦋 SEE ALSO 🦋

This program is a part of debhelper.

And that's a wrap, bestie!! 💜 This page was living its truth as version 14.5ubuntu1, dated 2026-09-21 — go forth and upgrade those compat levels responsibly, mwah 🎀✨

📦 where this page comes from