# dh_assistant

## NAME



           dh_assistant - tool for supporting debhelper tools and provide
           introspection
    


## SYNOPSIS



           **dh_assistant _command_ **[_additional options_]
    


## DESCRIPTION



           **dh_assistant** is a debhelper program that provides introspection
           into the debhelper stack to assist third-party tools (e.g.
           linters) or third-party debhelper implementations not using the
           debhelper script API (e.g., because they are not written in Perl).
    


## COMMANDS



           The **dh_assistant** supports the following commands:
    
       **active-compat-level (AJSON)**
           **Synopsis** : **dh_assistant active-compat-level**
    
           Outputs information about which compat level the package is using.
    
           For packages without valid debhelper compatibility information
           (whether missing, ambiguous, not supported or simply invalid),
           this command operates on a "best effort" basis and may abort when
           error instead of providing data.
    
           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**.
               This can be **null** when no compat level can be detected.
    
           declared-compat-level
               The compat level that the package declared as its default
               compat level.  This can be **null** if the package does not
               declare any compat level at all.
    
           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.
    
           This command accepts no options or arguments.
    
       **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.  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.
    
           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.  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).
    
           •   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.
    
       **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 it its
           dry-run mode, **make** may execute commands from _debian/rules_. Avoid
           using on packages from untrusted sources, where you have not
           reviewed the packaging for backdoors.
    
           The detection is based on scanning the rules file for any target
           that _might look_ like a hook target and can therefore list targets
           that are in fact not hook targets (or are but will never be
           triggered for other reasons).
    
           The detection uses a similar logic for scanning the rules file and
           is therefore subject to makefile conditionals (i.e., the truth
           value of makefile conditionals can change whether a hook target is
           visible in the output of this command).  In theory, you would have
           to setup up the environment to look like it would during a build
           for getting the most accurate output.  Though, a lot of packages
           will not have conditional hook targets, so the "out of the box"
           behaviour will work 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 details:
    
           commands-not-in-path
               This attribute lists all the commands related to hook targets,
               which **dh_assistant** could **not** 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 are using this command to verify an hook target is
               present, please double check that the command is spelled
               correctly.
    
           hook-targets
               List over hook targets found along with additional information
               about them.
    
               command
                   Attribute that lists which command this hook target is
                   related too.
    
               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 it.
                   In most cases, this will always be "debian/rules" though
                   in case of include files, the target could appear in an
                   include file.  Note this attribute is not super reliable
                   as 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
    
           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]
    
           Detects unknown and possibly misspelled override targets and hook
           targets in _debian/rules_ that will most likely not be used by
           dh(1).
    
           **UNSAFE**: This command relies on the output of make. Even it its
           dry-run mode, **make** may execute commands from _debian/rules_. Avoid
           using on packages from untrusted sources, where you have not
           reviewed the packaging for backdoors.
    
           This command differs from **detect-hook-targets** subtly in the scope.
           The **detect-hook-targets** will list all targets that looks like hook
           targets whether they are applicable or not. This command show all
           hook targets, for which a command cannot be found in any sequence.
           Accordingly, this command is better for linting purposes whereas
           **detect-hook-targets** is better if you 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 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:
    
           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 it.
                   In most cases, this will always be "debian/rules" though
                   in case of include files, the target could appear in an
                   include file.  Note this attribute is not super reliable
                   as 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.
    
           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 it.
                   In most cases, this will always be "debian/rules" though
                   in case of include files, the target could appear in an
                   include file.  Note this attribute is not super reliable
                   as 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, as 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.
    
           **--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]
    
           Load all **dh** sequence add-ons and extract a full list of all
           commands that will be invoked across all sequences. The command
           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).
    
           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 are 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.
    
           disabled-commands
               The top level key containing the list of all known commands
               that have been disabled. Each element in the list are 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, as 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]
    
           Load all **dh** sequence add-ons declaratively depended on, determine
           the full list of commands could be relevant for this source
           package and for each command used, then attempt to _guess_ which
           "config files" these commands are interested in.
    
           The command will include config files for commands that are not
           active with current add-ons, since the commands might be run
           manually from hook targets.
    
           Note this command only guesses "per command config files".
           Standard global config files such as _debian/control_ , _debian/rules_ ,
           and _debian/compat_ are not included in this output.
    
           As the command name implies, the resulting output is not a full
           list (and will never be).  The **dh_assistant** tool have to derive
           this from optional metadata that commands can choose to provide
           and **dh_assistant** has no means to validate that this metadata is up
           to date.
    
           As the command will attempt to load all plugins referenced by the
           package, 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:
    
               {
                  "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 containing the list of all config-files.
               Each element in the list are an object and can have the
               following keys:
    
               file-type
                   The type of config file detected. At the time of writing,
                   this will always be **pkgfile**. However, other values may
                   appear in the future.
    
                   The **pkgfile** key means that the config file is a **debhelper**
                   **pkgfile**(named after the **pkgfile** sub in
                   Debian::Debhelper::Dh_Lib that locates the file).
    
               pkgfile
                   When **file-type** is **pkgfile** , this key defines the name stem
                   of the **pkgfile**. An 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 names for these files are:
    
                        debian/PKGFILE
                        debian/PACKAGE.PKGFILE
    
                   However, there are more variants caused by **--name** plus
                   architecture specific suffixes.
    
               internal
                   This key may exist and any value for it is not
                   standardized. Use at own peril.
    
                   It used for document certain specific implementation
                   details such as bug compatibility and may change as the
                   situation changes.
    
               commands
                   This key will be a list with each element in it being an
                   object with the following keys:
    
                   command
                       Name of the command that is 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 reacts to (the now)
                       deprecated **tmpfile** pkgfile. In the 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 is not available in this
                       output either).
    
                   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 a command that would activate in a
                       different command level (than the one currently
                       active).
    
                       Note that commands that are not "active" can often
                       still be invoked manually from _debian/rules_ via hook
                       targets. Therefore, 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 even when
                       **is-active** is true. As an example, as 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** plus **is-active** being
                       false 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:
    
           **--with** _addon_ , **--without** _addon_
               These options behave the same as the dh(1) options with the
               same name.
    
       **log-installed-files (BLD)**
           **Synopsis** : [1mdh_assistant log-installed-files -p _pkg_
           _[--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 to
           have **dh_assistant** list 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 to use globs, have the shell
               perform the expansion first.
    
           •   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 is fine to provide the directory even if paths
               inside of it has been excluded as long as the directory is
               fully "covered".
    
           •   Do not worry about providing the same filename twice in
               different invocations to **dh_assistant** due to **-arch** / **-indep**
               overrides.  While it will be recorded multiple internally,
               dh_missing(1) will deduplicate when it parses the records.
    
           Note this command only _marks_ paths as installed. It does not
           actually install them - the caller should ensure that the paths
           are in fact handled (or installed).
    
       **restore-file-on-clean (BLD)**
           **Synopsis** : **dh_assistant restore-file-on-clean FILE ...**
    
           This command will take a backup of listed files and tell
           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 are
           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 this point, only a version control system or
           another backup can restore the files.
    
           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 does 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** is asking for corruption!).
    
           Files only, not directories nor symlinks to files
               This command will only restore files; not directories or
               symlinks to files. It will reject any non-files.
    
               Additionally, if the directory containing the file is removed,
               the restore will fail (as **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 are 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 ensure you do not accidentally trash
               important data that would help you undo mistakes.
    
           Heavy duty
               The command takes a **full copy** of all 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_]
    
           This command generates a compat upgrade checklist for the current
           package.
    
           The upgrade checklist is intended as an aid for contributors that
           upgrade a package to a newer compat level. Where possible,
           **dh_assistant** will attempt to detect whether some of the items are
           likely to be irrelevant and mark them as such. The logic will in
           many cases be a heuristic that can have false-positives and
           false-negatives.
    
           The output is a markdown based checklist template aimed at being
           human-readable (output stability is not a goal). Typically, the
           user will want to direct standard output and then edit the
           checklist as they process to a file 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
    
           The command will provide a checklist up to latest stable compat
           level or the compat level provided via the **--target-compat** option.
    
           This command accepts the following options:
    
           **--target-compat** _N_
               Request the upgrade checklist to stop at the provided compat
               level rather than the highest stable compat level. This option
               can be used to limit the checklist to a given compat level or
               request checklists for experimental compat levels.
    
               The option _cannot_ be used to generate a checklist for
               downgrading to a previous compat level. Trying to do so will
               result in an error message.
    
           Note: If you run this command from a git checkout of **debhelper** ,
           the behavior is slight different, since it will not correctly
           track which compat levels are stable (it is a build-time inserted
           property). As such, you will see experimental compat levels in the
           checklists by default, and they will **not** be marked as such.  If
           you use the git checkout, it falls on you to be extra careful with
           these limitations of the generated checklist.
    
       **supports (CFFA)**
           **Synopsis** : **dh_assistant supports COMMAND**
    
           This command is a scripting aid to programmatically determine
           whether **dh_assistant** knows about a given subcommand. Pass the name
           of a subcommand and this command will exit successfully if the
           subcommand was known and unsuccessfully otherwise.
    


## COMMAND TAGS



           Most commands have one or more of the following "tags" associated
           with them.  Their meaning is defined here.
    
           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 _out of the box_
               be unsafe. As an example, commands that parse the output of
               **make** is inherently unsafe, because it is trivial **make** to have
               **make** run code even in **--dry-run** mode. As a counter example,
               commands that only loads **dh** add-ons will be 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.
    
           OJSON
               The command *can* provide JSON output via
               **--output-format=json** , but does not do so 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 this 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 is
               considered 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 will need the package metadata to lookup the
               information.  Any command with this tag are exempt from this
               requirement and is expected to work regardless of where they
               are run.
    
           BLD The command is intended to be used as a part of a package
               build. It may leave artifacts behind that will need a
               dh_clean(1) invocation to remove.
    


## JSON OUTPUT



           Most commands uses JSON format as output.  Consumers 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.  As an
               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
    


* * *