Provided by: dh-debputy_0.1.67_all 
NAME
debputy - Manifest style Debian-based package builder
SYNOPSIS
debputy [general options ] command ... [ command options ]
debputy migrate-from-dh [--apply-changes] [--acceptable-migration-issues=issue[,issue,...]]
debputy lint [--auto-fix]
debputy reformat [--no-auto-fix]
debputy check-manifest [--debputy-manifest=path/to/debputy.manifest]
debputy lsp editor-config [NAME]
debputy lsp server [--tcp|--ws [--host BIND-ADDRESS] [--port PORT]]
DESCRIPTION
The debputy program is a manifest style Debian-based package builder. This man page documents some of the
user facing commands.
If you are using debputy with a screen reader, consider setting the environment variable
OPTIMIZE_FOR_SCREEN_READER to 1. This will make many debputy commands remove a lot of irrelevant visual
rendering. Especially ASCII art style rendering that will just be annoying to listen to. Additionally,
some output will be described with text to replace the visual rendering.
Commands
check-manifest
The check-manifest command will cause debputy to parse the manifest and examine it for obvious
mistakes.
Note that the command will not catch all mistakes as some problems can only be detected during a
build. As an example, check-manifest can detect mistyped manifest variables but not typos in path
names for installation rules.
migrate-from-dh
The migrate-from-dh command will attempt to migrate the current package to debputy.
For this command to be successful, it must be run from the root of an unpacked Debian source package
and the package should be using the dh sequencer.
If you are looking to migrate to debputy from dh, you may want to have a look at the
GETTING-STARTED-WITH-dh-debputy.md file (in the source root or in /usr/share/doc/). That document is
a how-to guide that as extended advice on migration from dh.
The migration can rerun with newer version of debputy that might provide more features since the
previous one even inside the same level of adoption. As an example, debputy/0.1.21 added support for
automatic relationship substvars. Re-running the migrator for an already migrated package can be used
to detect any unnecessary explicit relationship substvars as unnecessary.
The default migration target is based on existing features in the packaging where present. As an
example, a build-dependency on dh-sequence-zz-debputy-rrr will make the migration tool only run
migrators relevant for dh-sequence-zz-debputy-rrr (assuming no other markers are present). If the
migration cannot identify any target markers, it has a built-in default target. The default target
will change over time as debputy and the migrator mature. The --migration-target option can be used
to overrule this automatic detection. This can be useful both to expand on the migration level
without performing any changes or to choose a non default initial migration level.
Generally, the migration tool can take you from "less adoption" towards "more adoption" of debputy
but not the inverse. As an example, migrating from dh-sequence-zz-debputy-rrr towards dh-sequence-zz-
debputy is supposed, but the reverse is not. Use of version control is recommended for undoing
transition if necessary.
If any migrations involve creating a new or changing an existing debian/debputy.manifest, the
migration tool will first write a draft to debian/debputy.manifest.new. From there, it may be renamed
to debian/debputy.manifest automatically depending on --apply-changes or --no-apply-changes.
It supports the following options:
--migration-target TARGET-NAME
Explicitly define how far the migration should go. This will override the detected or built-in
default as the desired migration target.
See "INTEGRATION LEVELS" for details about the concrete levels of integration that can be used.
--acceptable-migration-issues NAME[,...,NAME], --acceptable-migration-issues=ALL
The migration may detect unsupported features in the package. Some, but not all, of these can be
reduced to a warning by passing --acceptable-migration-issues with the name of the issue as
provided in the error message. The special value ALL in all upper case will cause all issues that
can be reduced to a warning to be reduced to a warning.
This is only useful to reduce issues to warnings if you are reasonable sure that you can remove
the feature or convert it to something that debputy supports.
In some cases, it might be helpful to comment out the offending feature and re-run the migration
rather than using --acceptable.migration-issues. As an example, if a single line of
debian/install file is problematic, commenting it out will have debputy migrate the rest of the
file for you leaving you only to manually migrate a single line.
--apply-changes, --no-act, --no-apply-changes
These options decide whether the migration tool should perform destructive actions such as
overwriting the existing debian/debputy.manifest and deleting packaging files that have
successfully migrated.
The default is currently to not perform destructive actions as the migration tool does not detect
version control systems. If support for detecting version control systems is added, this default
may change.
Note that the migration may replace debian/debputy.manifest.new regardless of this option as that
is its output for the updated draft manifest.
The --no-act is an alias of --no-apply-changes to match the name that debhelper commands use.
reformat
Note: This subcommand needs optional dependencies to work from Recommends or Suggests
Apply the formatting style on the packaging files.
This is the same style that debputy lsp server would have applied if requested to reformat the files.
The debputy tool reacts to having a X-Style field in debian/control from where you can pick a named
style. The recommended style is black, which is named such to match the black code formatter for
Python (which imposes a style that evolves over time).
For packages that does not have the X-Style field, debputy will result to looking up the maintainer
(and possibly co-maintainers) for known style preferences in its built-in configuration. If debputy
can derive a style that all parties would agree too (or the team style for packaging teams), then
that style will be used.
The black style started as similar to that of wrap-and-sort -ast, since that was one of the most
common styles according to <https://bugs.debian.org/895570>, but the style is expected to evolve over
time and the two styles may diverge over time.
The command accepts the following options:
--style=black
Override the package style and use the black style. Any auto-detection or X-Style setting will be
ignored.
--auto-fix, --no-auto-fix
Decide whether any changes should be fixed automatically.
Either way, a difference (diff -u) is displayed to stdout if any changes were detected.
--linter-exit-code, --no-linter-exit-code
There is a convention among linter tools to return a non-zero exit code for "issues". The
--linter-exit-code will enforce this behavior while the --no-linter-exit-code will disable it.
The debputy program will use exit code 2 for "issues" as a "linter exit code" when linting based
exit codes are active.
Not having a linter based exit code can be useful if you want to run the tool programmatically to
perform the action and you only want the exit code to tell whether there was a problem providing
the results.
If you rely on the exit code, you are recommended to explicitly pass the relevant variant of the
flag even if the current default matches your wishes.
--unknown-or-unsupported-style-is-ok, --missing-style-is-ok
By default, debputy reformat will exit with an error when it cannot determine which style to use.
This is generally what you want for "per package" CI or other lint checks to inform you that the
reformatting will not work.
However, for "cross package" pipelines, like the default Debian Salsa CI pipeline, having debputy
reformat automatically work when a style is set and doing nothing otherwise is preferable, since
the pipeline can then provide a debputy reformat job for all consumers without worrying about
breaking their pipelines.
It can also be useful for scripts or automated mass-edits where you want debputy to fixup the
changes you did if there is a known style without being hampered by the packages that have no
known style.
The --missing-style-is-ok is a deprecated name since it does not correctly imply that unsupported
styles are also considered ok.
--supported-style-is-required
Exit with an error if no supported style can be found. This is the default behavior but this
option can be used to override settings to disable it. The error does not distinguish between no
style found or an unsupported style found (both lead to an error).
If you rely on the exit code, please set this option explicitly.
lint
Note: This subcommand needs optional dependencies to work from Recommends or Suggests
Run the linting tooling for Debian packaging files. This will run a linter to check the Debian
packaging files. This command is useful for CI or for when you cannot use the language server
feature. It provides the same diagnostics as debputy lsp server would but without requiring an LSP
capable editor as intermediate. The output is only intended for human consumption. Machine readable
is not a goal at this time.
The debputy lint command is a form of static analysis and will not load nor execute code from the
code it is scanning. It is a security bug for debputy lint to violate this principle directly or
indirectly. Therefore, debputy can only provide diagnostics from libraries and tools that takes this
principle seriously. It also means that debputy will likely have false-positives for self-hosting
code, since it is not allowed to load the self-hosted code.
Note that at the time of writing, the debputy.manifest file is only partially supported. If you have
debian/debputy.manifest, please also run debputy check-manifest to get more thorough checks for that
file for now. The lint command will inform you about this issue in the output if a
debian/debputy.manifest file is detected.
Some relevant options for this subcommand include:
--auto-fix
If debputy is aware of one "obvious" solution to the issue, just apply it. This will apply the
changes directly to the file. Use of version control for the Debian packaging is recommended when
using this option in case you want to undo the result.
--spellcheck
Include spellchecking in the linting results. These are by default omitted, since they are slower
and there are often false-positives.
Caveat: Before version 0.1.55 of debputy, --auto-fix with --spellcheck would auto-correct all
spelling mistakes with a single correction available. This can be suboptimal behavior in some
cases. As of 0.1.55, debputy no longer automatically applies typo fixes for free text fields when
--auto-fix --spellcheck. Instead, they will be reported as not being fixable automatically (but
instead have a "[LSP interactive quickfix]" tag associated with them).
--linter-exit-code, --no-linter-exit-code
There is a convention among linter tools to return a non-zero exit code for "severe issues". The
--linter-exit-code will enforce this behavior while the --no-linter-exit-code will disable it.
The debputy program will use exit code 2 for "severe issue" as a "linter exit code" when linting
based exit codes are active.
Not having a linter based exit code can be useful if you want to run the tool programmatically to
display the results and you only want the exit code to tell whether there was a problem providing
the results.
If you rely on the exit code, you are recommended to explicitly pass the relevant variant of the
flag even if the current default matches your wishes.
--lint-report-format term|junit-xml
Choose the output format of the resulting report. The term report is a terminal output report.
The junit-xml writes the output to an XML in a JUnit 4 format (should be compatible with the
xunit2 family of JUnit4 style input). This is useful for GitLab CI pipelines to get the results
imported via GitLab's junit CI pipeline feature.
--report-output DEST
For reports that generate file system artifacts, choose where the output should be placed.
Ignored with a warning for formats that do not generate file system outputs such as the term
report format.
--warn-about-check-manifest, --no-warn-about-check-manifest
Whether debputy lint should remind you that it has short comings in regards to validating the
debian/debputy.manifest file. The warning will only appear if the manifest file exists. That is,
the options have no effect either way when the file is not present.
The --no-warn-about-check-manifest is mostly used for generic pipelines that separately call
debputy check-manifest to ensure that the manifest is also validated or for cases where the
limitation is known and accepted.
A short comparison of debputy lint vs. other tools:
debputy lsp server
The language server feature from debputy lsp server provides an interactive and online version of
the linting from debputy lint directly in any LSP capable editor with the proper glue
configuration. The LSP feature gives you instant gratification, some additional editor-only
features and interactive choices of available quickfixes.
The "downside" of the debputy lsp server feature is that it requires a LSP capable editor and
each editor has their own glue configuration. Since the debputy language server is new, almost no
editor has built-in glue configuration meaning it has a steeper learning curve to get started.
Additionally, some times you want the checks for CI checks or the current state of the package
without having to open each file in an editor. Here debputy lint covers the same issues without
the need for anything else.
lintian
The primary difference between the debputy linter and lintian is that lintian works on "binary"
artifacts. Even the source checks of lintian checks the packaged version of the source rather
than the files you are directly working. This means that you have to do a package "build" for
lintian to spot any changes, which causes slow feedback loops. Additionally, debputy lint can
provide feedback regardless of whether your package can currently build. Accordingly, you can get
help and hints even for problems that would prevent a package build. By nature of how lintian
works, you can only get hints from lintian on matters that does not break the package build.
On the flip side, because lintian is checking the assembled artifacts, it can check for issues
that are only visible after a package build. Additionally, lintian also checks for issues in the
upstream sources to some extent. Checking upstream artifacts and the resulting Debian packages
are not in scope for debputy lint as the debputy lint is intended to be a mirror of the language
server diagnostics.
In summary: Use debputy lint (or debputy lsp server) for short feedback loops. Use lintian for
slower but more thorough checks on resulting packages.
lintian-brush
The lintian-brush has a broader scope than debputy lint. If you are a happy lintian-brush user,
odds are that debputy lint will not do a lot for you. Though, debputy lsp server might still be
relevant as the language server provides additional editor related features.
lsp server
Note: This subcommand needs optional dependencies to work from Recommends or Suggests
Start the debputy language server (per Language Server Protocol specification).
Many modern editors can delegate language support to a Language Server or indirectly via other
features like supporting youcompleteme (which in turn can delegate to a language server). The debputy
tool provides one for many common packaging formats via the lsp server subcommand for file formats
such as debian/control, debian/changelog and debian/copyright (DEP-5).
You will often need some editor specific glue configuration to link a given file format or name to
the language server. The debputy lsp editor-config might provide an example glue snippet for your
editor. In that glue configuration, you will need to provide a command. Often, debputy lsp server
will suffice (using the stdio transport). See debputy lsp server --help for other integration options
such as TCP (--tcp) or websocket (--ws) plus related supporting options.
The debputy lsp server command provides several features including a form of static analysis in the
form of "as-you-type" diagnostics. For the diagnostics, is debputy lsp server not allowed load nor
execute code from the code it is scanning. It is a security bug for debputy lsp server to violate
this principle directly or indirectly. Therefore, debputy can only provide diagnostics from libraries
and tools that takes this principle seriously. It also means that debputy will likely have false-
positives for self-hosting code, since it is not allowed to load the self-hosted code.
This security principle also applies to hover docs, completion suggestions and other trivial code
editing or viewing features. However, it is not universal, since certain LSP features are
deliberately designed to run the code you are viewing. As an example, debputy lsp server can provide
a "code lens" (LSP term) for building the current package. On activation of the code lens, debputy
will trigger code from the package to be run and that is expected. The critical points here are that
the user must explicitly trigger the feature and it must use terms commonly associated with running
code such as build, run or execute (non-exhaustive list).
If you need to debug an issue with the language server, the TCP integration (--tcp) can be quite
helpful. In this mode, you run debputy lsp server --tcp in a terminal before starting your editor.
This means you have direct and unfiltered access to the debputy command and its output. Remember to
update your editor to use TCP integration rather than stdio integration (and remember to swap back
when you are done). Check the debputy lsp server --help if you need a different bind address for the
language server.
If you can choose the language ID for a given file, you are recommended to use the file name relative
to the source root (such as debian/control). The service does account for some known variations such
as debian-control (as used by eglot from emacs) and debcontrol (as used by vim). See debputy lsp
features for a list of known language IDs along with their aliases.
When properly set up, the language server will offer a variety of features such as completion
suggestions, hover documentation, "as you type" diagnostics, quickfixes, etc. Please see debputy lsp
features for the full list of features per format. That command will also help identify mandatory and
optional dependencies for the debputy lsp server command.
Note many of the features are subject to the editor supporting them, correct language IDs being
passed to debputy, etc.
Options for this subcommand
--ignore-language-ids
When provided, debputy will ignore any language ID that the editor provides for any file.
Instead, debputy will only rely on the file name for determining how to interpret the file
content.
Since debputy supports multiple file formats, it is needs to know what kind of file it is working
with. The editor is supposed to provide this via a "Language ID" attribute. This enables you as a
user in the editor to override the file format and have proper editor support no matter the
filename. Unfortunately, most Debian packaging files do not have a language ID assigned in the
LSP specification, so editors either provide a custom language ID or no custom language ID at all
(that is, an empty string).
When the editor does not provide a language ID for file, debputy will since 0.1.25 automatically
attempt to derive the language from the filename. With this option (introduced in 0.1.29),
debputy will always derive the language from the filename even if the editor provided a language
ID. This can be helpful if your editor is providing language IDs that debputy does not recognize.
As an example, in emacs with eglot the language ID is derived from the name of the buffer's major
mode. If you tried to use debputy lsp server with a major mode that debputy does not recognize
then without this option, debputy would "silently" do nothing. With this option, it would have
worked provided the filename matched debputy's expectation no matter the major mode.
On the downside, debputy will not provide correct advice unless the paths matches
.../debian/filename. This can provide issues with some setups where the debian directory is
implicit such as some "packaging-only" repos or some editor scratch pads.
--force-locale=XX
When provided, debputy will always use the provided locale code for deciding the localization.
By default, the editor may provide a locale, which is then used. Alternatively, debputy will
attempt to guess the desired localization from defaults (like the LC_ALL variable). With this
option, you can override both of these and instead directly pick the locale you want.
Note that debputy will default to using US English for strings that are not translated into the
desired locale (no matter how that locale was chosen). If you still see untranslated strings with
this options, check you have the relevant translations installed and that the locale code is
correct.
--tcp or --ws
By default, the debputy language server will use stdio for communication with the editor. These
options provide either the TCP integration mode (--tcp) or the websocket integration mode (--ws).
In this mode, the --host and --port options can be used to choose the bind address.
These options are mutually exclusive.
The --ws option requires python3-websockets Debian package.
--host HOSTNAME, --port PORT
With --tcp or --ws, these option determines the bind address. The default is 127.0.0.1 for host
and 2087 for the port.
In integration modes that does not need a bind address (such as the stdio mode), this option is
ignored.
lsp editor-config [EDITOR]
Provide an example configuration glue for using the debputy lsp server with the given editor if
known. If EDITOR is not provided, then list the names of editors that debputy knows about.
The snippets are maintained on a best effort basis for editors without built-in config glue for the
debputy lsp server. Please file an issue (or a merge request) at
<https://salsa.debian.org/debian/debputy> if a snippet needs to be updated, added or removed.
lsp features
List in a human readable format details about what language IDs are handled by the debputy lsp server
along with what features are provided for each file format/language ID.
The command can also be used to determine if all the relevant dependencies have been installed for
the language server and linting features. It will also check for optional dependencies that can
enhance the feature set.
tool-support
These commands are intended for other tools to consume the output. Output is generally JSON by
default or supported via --output-format=json.
export-reference-data [DATASET]
The export-reference-data command export reference data. If provided, only the named dataset will
be exported. Otherwise, all datasets will be exported.
The reference data includes descriptions of the keywords used in the data set, which is helpful
to understand the data.
supports-tool-command <COMMAND>
Tests whether debputy knows about the named command. Returns successfully if known and
unsuccessfully if not known.
annotate-debian-directory
The annotate-debian-directory command will make debputy scan the debian/ directory for known
packaging files and annotate them with information.
Identifying known packaging files is done on a best effort basis and debputy has the following
sources of information:
Data from plugins
Any installed debputy plugin can provide data about known packaging files. Most of debputy's
"built-in" rules are stored in the debputy-documentation or the debhelper-documentation
plugin. These are installed in /usr/share/debputy/debputy/plugins/ by default. If any of the
data in there is wrong, please file a bug or a bug against the package providing the data
(often debputy or debhelper).
If the plugin provides the relevant data, debputy will expose install-pattern and install-
path, which are best-effort guesses for the file is installed (or where files listed in it
will be installed). Please check the config-features and file-categories for the file to see
when these field are applicable (and which case it is).
Note that some files can be matched multiple times. As an example debian/changelog and
debian/copyright will generally appear once per package, because they are installed in each
package.
Dynamic data from debhelper(7) (via dh_assistant(1)>)
Additionally, debputy will ask dh_assistant to resolve all relevant helper commands and their
relevant config snippets. This data will be cross referenced with the plugin provided data
where possible. This will detect files that debputy (and its plugins) does not know about,
but it cannot provide any additional information.
This part requires debhelper (>= 13.12~) to work fully. With older versions, the output will
include an issues attribute denoting that dh_assistant returned non-zero. Additionally, with
debhelper (>= 13.16~) the command will also provide data about files associated with some
dh_-commands not active with the current set of dh addons.
When dh_assistant list-guessed-dh-config-files is missing a file, it is typically because the
command that uses that config file is not introspectable. Typically, that can be fixed by
patching the command to include a command line a la:
# INTROSPECTABLE: CONFIG-FILES pkgfile(foo)
Assuming the command uses pkgfile($package, "foo") from Debian::Debhelper::Dh_Lib to look up
the config file.
Notable case that will likely not work is debian/foo.service where there is no foo package in
debian/control but debian/rules calls dh_installsystemd --name foo. This holds equally for
all debhelper config files and related commands. Here, the resulting file (if detected at
all) might be associated with the wrong package.
plugin list [TOPIC]
plugin show TOPIC identifier
These commands provides access to features that are provided by plugins (Note: many debputy features
are plugin provided, so these commands also covers a lot of "built-in" features).
These commands will access features of all plugins available even if the current package will not
activate all of these plugins. Unless otherwise stated, all output is intended to be human readable
rather than machine readable. Formatting may change between any version.
Many of the list subcommands also provide a csv format. Note this output is not intended for
scripting as the output is subject to change - both in form of format availability and content. The
csv output is intended as an aid to users of screen readers for which csv files are easier to deal
with than visually rendered tables. If you need a stable format of some particular output, please
file a feature request at <https://salsa.debian.org/debian/debputy/-/issues> or via reportbug
debputy.
You can use debputy plugin list --help and debputy plugin show --help to see which topics are
applicable for each subcommand.
Noteworthy topics include:
plugins
This topic provides a listing of all plugins that debputy is aware of.
This topic can only used with plugin list and not with plugin show.
pluggable-manifest-rules (aliases: pmr, p-m-r)
The debputy manifest provides a number of places where the packager can provide a number of
different rules such as install vs. install-doc vs. install-examples under installations:. These
are called pluggable manifest rules and this topic provides insights to which rules are available
where.
When used with list, debputy will list all pluggable manifest rules available. When used with
show, a rule name must be provided and debputy will then provide details about the rule. These
details include attributes available (where applicable) and any reference documentation provided
by the plugin.
As an example, here is how you get the details about the install rule:
debputy plugin show pluggable-manifest-rules install
When a rule name is ambiguous, debputy will ask that you use rule-type::rule-name instead of just
rule-name. As an example:
debputy plugin show pluggable-manifest-rules TransformationRule::remove
debputy plugin show pluggable-manifest-rules DpkgMaintscriptHelperCommand::remove
Note the type names (such as TransformationRule) are currently an implementation detail and may
change in the future.
packager-provided-files (aliases: ppf, p-p-f)
This topic provides details about all "packager provided files". Packager provided files can be
put into debian from where debputy will pick them up and install them somewhere in the package.
While this command shows all possible variants (by their stems), the used-packager-provided-files
topic will list real files matched.
When used with list, debputy will list all the packager provided files that debputy knows about.
When used with show, some additional details will be given.
In a few cases, the packager provided file will be processed first (as an example debian/symbols
will be passed to dpkg-gensymbols and the processed version will then be installed instead).
used-packager-provided-files (aliases: uppf, u-p-p-f)
This topic provides a list of all packager provided files used in this source package. This topic
differs from packager-provided-files in that it only shows files in actual use whereas the other
topic lists all known stems.
The listing will potentially include files that debputy could have picked up, but will not do so
during a package build because the relevant plugin is not explicitly requested (typically via a
Build-Depends). These cases are placed in a separate table and will be clearly marked.
This topic can only used with plugin list and not with plugin show.
This topic only works when the command is run from the root of an unpacked Debian source package
(as debputy needs to read debian/control and scan the debian/ directory).
metadata-detectors
This topic provides a listing of all "metadata detectors". These are plugin provided code
snippets that scan the final form of the package and add substvars (for dpkg-gencontrol),
generate maintscript snippets, or/and declare triggers.
This topic can only used with plugin list and not with plugin show.
manifest-variables
This topic covers plugin provided manifest variables. The listing will list the common manifest
variables by default along with their values in source context (if possible). Some of the special
case manifest variables are hidden by default (use debputy plugin list manifest-variables --help
to see the filter options).
When used with show VARIABLE, debputy will list the reference documentation (if provided by the
plugin) related to the value along with a few other details.
As implied above, this will only show plugin provided variables. Any manifest variables provided
directly in the manifest is not covered by these commands.
automatic-discard-rules
This topic covers automatic discard rules, which are rules that automatically filters out
(discards) sources from installation rules by default. The listing will list all the available
automatic discard rules. The show RULE command will show reference documentation and an example
of what the rule reacts to (if these have been provided by the plugin).
As an example:
debputy plugin show automatic-discard-rules la-files
type-mappings
This topic cover type mappings that explains how some non-trivial types are interpreted. These
covers types like FileSystemMatchRule and FileSystemMode, which are used by other features such
as pluggable manifest rules.
When used with show NAME, any plugin provided documentation and example inputs will be displayed
for that rule.
autopkgtest-test-runner
The autopkgtest-test-runner command is intended to be used by autodep8 or from autopkgtests to run
the tests of plugins in installed mode.
internal-command
This is for internal-only usage only. Any subcommand under internal-command may disappear or change
options between any release without any warning.
GENERAL OPTIONS
The following options general options or root level options are available.
-h, --help
Print usage information and exits.
The information printed depends on which subcommands appear prior to this option.
--version
Prints version information and exists.
Cannot be used with subcommands.
-d, --debug
Enable debug logging and raw stack traces on errors.
Some warnings become errors as a consequence.
It is also possible to set the environment variable DEBPUTY_DEBUG to 1, which also enable debug
logging. In general, the two methods are the same. However, there may be some subtle differences
involving early initialization, where the two might differ. Note that DEBPUTY_DEBUG must be set to
exactly 1 to enable debug logging that matches --debug.
--no-pager
Some subcommands will in their default output format pipe it to a pager to give you a more pleasant
experience if standard out is a terminal. Examples include many of the plugin list commands. This
option will disable the pager feature.
Most option formats via --output-format will imply --no-pager as well for subcommands that support
that option.
Note: Assuming the environment has no pager configuration at all, debputy will use less(1) with the
LESS environment variable set to -FRMQSX. Notable, the -F option will cause less to immediately
terminate if the output fits on the screen.
--plugin REQUIRED_PLUGIN
This option causes REQUIRED_PLUGIN to be loaded as a part of the commands execution if the command
needs to load plugin data. For commands that load all plugins by default, this option causes the
command to fail if REQUIRED_PLUGIN cannot be loaded. For commands that are restrictive about which
plugins are loaded, subcommand will load REQUIRED_PLUGIN in addition other plugins that would
normally be loaded.
The REQUIRED_PLUGIN can either be a plugin name or a filename. The debputy program considers
parameter with a forward slash as a filename. Otherwise, the parameter is interpreted as a plugin
name. When given a plugin name, debputy will search for the plugin in its plugin search path and load
it from there. When given a file name, debputy will read that file as a plugin and use the basename
minus any .json or .json.in extension as the plugin name.
For packages that need a plugin that they provide themselves during their build process, this option
can be useful to tell debputy about it. For the build itself, usually you want to use dh_debputy
--plugin path/to/plugin.json. But this option can still be useful for debputy check-manifest etc.
The other use-case is to load a plugin not installed into the plugin search directories. Notably, you
can use this to shadow an existing plugin, which can be useful for debugging and developing your
plugin changes.
This option cannot be used with bundled plugins. As an example, both --plugin debputy and --plugin
path/to/a/debputy.json will result in an error.
--debputy-manifest FILE
If the command needs to parse a manifest, have it read FILE instead of debian/debputy.manifest.
Note this is mostly for testing as other features might not work correctly if the manifest is not
aligned with the current working directory.
FILES
debian/debputy.manifest
Please see /usr/share/doc/dh-debputy/MANIFEST-FORMAT.md.gz for details on the format.
If you are converting your first package, you may want to read
/usr/share/doc/dh-debputy/GETTING-STARTED-WITH-dh-debputy.md.gz first.
Unlike most debhelper like tools, this file is per source package rather than per binary package.
Therefore, you cannot use debian/package.debputy.manifest to provide a specialized manifest for
package. Instead, all the needed parts should be written into the manifest itself.
The --debputy-manifest option can be used to have debputy process manifest other than
debian/debputy.manifest, which may be useful for testing or running debputy check-manifest but not
much else.
INTEGRATION LEVELS
The debputy has multiple levels of integrations, which defines how much of the packaging that debputy is
handling relative to the default dh sequence. The following integrations levels are available:
dh-sequence-zz-debputy-rrr
This integration level replaces the minimal number of commands necessary to provide Rules-Requires-
Root: no support for any package (even those needing static ownership). The sequence is often
compatible with other debhelper sequences. To use this debputy integration level, any custom file
ownership and mode should be migrated to the debian/debputy.manifest. Custom binary package version
(-v to dpkg-gencontrol) is supported via the manifest.
This migration level corresponds to a Build-Depends on dh-sequence-zz-debputy-rrr.
The following debhelper commands are removed:
- dh_fixperms
- dh_shlibdeps
- dh_gencontrol
- dh_md5sums
- dh_builddeb
Note the following debputy features are disabled in this integration mode:
- Installation rule (the installations keyword in the manifest). Any installation of content that
should go resulting .deb or .udeb should happen via debhelper's mechanisms such as dh_install.
- Metadata detectors from plugins. Instead, substvars, maintscripts and triggers are handled and
generated per debhelper conventions.
dh-sequence-zz-debputy
With this integration level, debputy will take over all installation of files into the packages.
This will replace basically all commands after the dh_auto_install command in the standard dh
sequence. This also makes the integration level incompatible with many debhelper add-ons, since they
expect to run after dh_auto_install and assume contents will be materialized into debian/package.
This migration level corresponds to a Build-Depends on dh-sequence-debputy or dh-sequence-zz-debputy.
REPORTING BUGS
If you found a bug, please report it at <https://salsa.debian.org/debian/debputy/-/issues>. For Debian
users, you can also use report debputy if you prefer using the Debian Bug Tracker.
SEE ALSO
dh_debputy(1)
AUTHOR
Niels Thykier <niels@thykier.net>
perl v5.40.1 2025-03-13 debputy(1)