debputy(1)

📦
version 0.1.96 · 5 versions
, in ubuntu stonking

🎀 debputy(1) — NAME 🎀

okay so welcome to the manual page for debputy, a.k.a. the manifest style Debian-based package builder 💖. Yes bestie, we're in the debputy(1) page of The debputy Debian packaging helper stack, and it is giving iconic. Also quick heads up: this is literally part 1 of like five, so hydrate, sit criss-cross, and stay with me. 🦋

✨ SYNOPSIS ✨

the vibe is: you got general options, you got a command, you got command options. simple as. 🫶

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]]

no cap, that's the whole map. 🌈

💅 DESCRIPTION 💅

so debputy is a manifest style Debian-based package builder, periodt. This man page is here to document some of the user facing commands — not all of them, some of them, bestie, read the words. 👑

🧚 screen reader besties, this one's for you: if you're using debputy with a screen reader, consider setting the environment variable OPTIMIZE_FOR_SCREEN_READER to 1. That makes a whole bunch of debputy commands drop a ton of irrelevant visual rendering. Especially the ASCII art style rendering, which is just gonna be straight up annoying to listen to 🫠. Also, some output gets described with text replacing the visual rendering, so you actually get useful words instead of vibes.

🌸 Commands 🌸

🔍 check-manifest

check-manifest makes debputy parse the manifest and go looking for obvious mistakes. It's giving "linter but make it nosy." 🔥

ngl though, this command will not catch every mistake, because some problems can only be detected during a build. Example so you get it: check-manifest can detect mistyped manifest variables, but it can't catch typos in path names for installation rules. so it's smart, not psychic 💀.

🚚 migrate-from-dh

migrate-from-dh attempts to migrate the current package over to debputy. glow up arc, basically. ✨

For this command to actually work, two things have to be true:

  • it must be run from the root of an unpacked Debian source package
  • the package should be using the dh sequencer

If you're looking to migrate to debputy from dh, you may want to peek at the GETTING-STARTED-WITH-dh-debputy.md file (it lives in the source root or in /usr/share/doc/). That doc is a how-to guide that has extended advice on migration from dh. iykyk 📖

The migration can be rerun with a newer version of debputy that might provide more features than the previous one, even inside the same level of adoption. For 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. 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. That default target will change over time as debputy and the migrator mature. The --migration-target option can be used to overrule this automatic detection. That's 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. Example: migrating from dh-sequence-zz-debputy-rrr towards dh-sequence-zz-debputy is supported, 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. cute lil draft pipeline 🎀

It supports the following options:

  • --migration-target TARGET-NAME — explicitly define how far the migration should go. This overrides 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 depends one whether the package is maintained in a supported version control system. If the package is in a supported version control system, then --apply-changes will be default and the changes will be registered with the version control system. Otherwise, --no-apply-changes is the default.

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. 🤝

  • --ignore-vcs — since 0.1.73, debputy will check if the package is maintained in a supported version control systems (git). If it is, then debputy will first ensure the repo is in a clean enough state to continue, and any changes performed will staged for a commit. 🧼

If debputy finds a supported version control system but version control system or repo is in an unsupported configuration, then debputy will ask you to explicitly provide this option to avoid surprises.

This option causes debputy to assume no version control system is used.

💖 reformat

Note: This subcommand needs optional dependencies to work from Recommends or Suggests 🫶

Apply the formatting style on the packaging files. it's the glow-up button bestie ✨

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. 🖤
  • --write-style — with --style, the chosen style will be written into the reformatted debian/control if it is not already present as-if this updated X-Style field was a formatting change (that is, it is subject to --auto-fix vs. --no-auto-fix).

This option requires --style and will cause an error if that option is missing. 🚨

This option requires debputy/0.1.70 or later.

  • --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. ⚠️

okay bestie that's part 1 wrapped — more sections coming, don't go anywhere 💜

  • --supported-style-is-required — 💅 bail out with an error if literally no supported style can be found. This is the default behavior, bestie, but this option exists so you can override settings and turn it off. Real talk: the error does not tell you apart between "found no style at all" and "found an unsupported style" — both roads lead to an error. 😭 And if your whole thing depends on the exit code? Please, please just set this option explicitly. Do not make me beg. 🙏

lint

Note: this subcommand needs the optional dependencies from Recommends or Suggests to actually work 💖

Run the linting tooling for Debian packaging files 🧚 ✨. It fires up a linter that checks your Debian packaging files. This is that command for CI, or for when you literally cannot use the language server feature. It hands you the exact same diagnostics that debputy lsp server would give, except without needing an LSP capable editor sitting in the middle as a go-between. Heads up though — the output is only meant for human consumption. Machine readable output is not a goal at this time. Periodt.

The debputy lint command is a form of static analysis, and it will not load nor execute code from the code it is scanning. Ngl, it is a security bug for debputy lint to violate this principle, directly or indirectly. Which means debputy can only give you diagnostics from libraries and tools that take that principle seriously. And yeah, that also means debputy will likely have false-positives for self-hosting code, because it is not allowed to load the self-hosted code. That's the deal. 🤷‍♀️

Also note that, at the time of writing, the debputy.manifest file is only partially supported 🙈. If you've got debian/debputy.manifest, please also run debputy check-manifest to get more thorough checks on that file for now. The lint command will let you know about this whole situation in its output if it detects a debian/debputy.manifest file. She's honest, at least.

Some relevant options for this subcommand include:

  • --auto-fix — if debputy knows of one "obvious" solution to the issue, it just... applies it. ✨ This changes the file directly. Bestie, please use version control for your Debian packaging when you turn this on, in case you want to undo the result. 👑
  • --spellcheck — throw spellchecking into the linting results. These are omitted by default, because they're slower and there are often false-positives. 😩

When a word is correctly spelled but the spellchecker has never met it, you can often make debputy ignore the word by quoting it with either " or `. Like, for example:

    Some sentence with the word `tet` that looks like a typo but is not.

In that example, the word tet will not be checked for typos, since it's covered by ` quotes. slay.

The debputy engine also has some built-in exceptions where it tries to exclude things that look like a programming term. For example, $tet will not be checked for typos. But ngl there is often a fine line between something looking like a word vs. looking like a programming term. Take this one:

    Consider the well-known package debputy-lsp or the program dpkg-gensymbols.

At a pattern level, the "words" well-known, debputy-lsp, and dpkg-gensymbols all look the same: some lower-case letters, a dash/hyphen, and some lower-case letters. There are some heuristics to balance false-positives vs. false-negatives that may change over time. 💀

Note that spellchecking issues are not fixed automatically with --auto-fix.

  • --linter-exit-code, --no-linter-exit-code — there's a whole convention among linter tools to return a non-zero exit code for "severe issues". --linter-exit-code enforces that behavior, while --no-linter-exit-code disables 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 is actually useful if you want to run the tool programmatically to display results, and you only want the exit code to tell you whether there was a problem providing the results in the first place.

And if you rely on the exit code? You are recommended to explicitly pass the relevant variant of the flag, even if the current default happens to match your wishes. Trust. 🫶

  • --lint-report-format term|junit-xml — pick 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). Which is super handy for GitLab CI pipelines, so you can 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.

It's ignored with a warning for formats that don't 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 regarding validating the debian/debputy.manifest file. The warning will only show up if the manifest file actually exists. That is, the options have no effect either way when the file is not present. 🙈

--no-warn-about-check-manifest is mostly used for generic pipelines that separately call debputy check-manifest to make sure 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 gives you an interactive, online version of the linting from debputy lint, right inside 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 an LSP capable editor, and each editor has its 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. 😭 And also, sometimes you want the checks for CI checks, or the current state of the package, without having to open each file in an editor. That's where debputy lint covers the same issues without needing anything else. Iconic.

  • lintian — the primary difference between the debputy linter and lintian is that lintian works on "binary" artifacts. Even the source checks of lintian check the packaged version of the source, rather than the files you are directly working on. Which means you have to do a package "build" for lintian to spot any changes, and that causes slow feedback loops. 🐌 On top of that, debputy lint can give you feedback regardless of whether your package can currently build. So 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 don't break the package build.

On the flip side, because lintian checks the assembled artifacts, it can check for issues that are only visible after a package build. And lintian also checks for issues in the upstream sources, to some extent. Checking upstream artifacts and the resulting Debian packages is not in scope for debputy lint, since 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 — lintian-brush has a broader scope than debputy lint. If you're a happy lintian-brush user, odds are debputy lint won't do a lot for you. Though debputy lsp server might still be relevant, since the language server provides additional editor related features. 🦋

lsp server

Note: this subcommand needs the optional dependencies from Recommends or Suggests to actually work 💖

Start the debputy language server (per the Language Server Protocol specification). ✨

Lots of modern editors can delegate language support to a Language Server, or do it 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 give you an example glue snippet for your editor 🎀. In that glue configuration, you'll 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, debputy lsp server is not allowed to 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 take this principle seriously. It also means debputy will likely have false-positives for self-hosting code, since it is not allowed to load the self-hosted code. 🙈

Okay so this whole security vibe? It also applies to hover docs, completion suggestions and all the other lil trivial code-editing-or-just-viewing-stuff features 💅

But bestie, it's not universal — because certain LSP features are deliberately designed to run the code you're looking at. That's literally their whole job. Example: debputy lsp server can provide a "code lens" (that's the LSP term, iykyk) for building the current package. The second you activate the code lens, debputy triggers code from the package to be run — and that is expected 🫶 The critical points here: the user has to explicitly trigger the feature, and it has to use terms people already associate with running code, such as build, run or execute (non-exhaustive list, so yes there are more).

If you need to debug an issue with the language server, the TCP integration (--tcp) is genuinely so helpful. In this mode you run debputy lsp server --tcp in a terminal before starting your editor. Which means you get 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're done!). Check debputy lsp server --help if you need a different bind address for the language server.

If you get to choose the language ID for a given file, you're 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 whole 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. Iconic behaviour, truly.

Note many of the features are subject to the editor supporting them, correct language IDs being passed to debputy, etc. So like… vibe check your setup first 🙈

✨ Options for this subcommand ✨

  • --ignore-language-ids — When provided, debputy ignores any language ID the editor provides for any file. Instead, debputy only relies on the file name for determining how to interpret the file content.

Since debputy supports multiple file formats, it needs to know what kind of file it's working with. The editor is supposed to provide this via a "Language ID" attribute. This is what lets you, as a user in the editor, 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 a 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 option, 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. Pick one, bestie, you can't have both 🎀

The --ws option requires the python3-websockets Debian package.

  • --host HOSTNAME, --port PORT — With --tcp or --ws, these options determine 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 exports 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

Okay bestie these two are your backstage passes to everything the plugins bring to the party 💖 (and heads up: a lot of debputy features are plugin-provided, so these commands are lowkey covering a bunch of the "built-in" stuff too, no cap).

These commands will poke at features from all the plugins that are available — even if the package you're currently on won't activate all of them. And unless it says otherwise, every bit of output here is made for humans to read, not machines. The formatting? Yeah it can change between literally any version. 🙈

Lots of the list subcommands also have a csv format. But bestie, do not use that for scripting — the output is subject to change, both in whether the format even exists and in what's inside it. The csv output is there as a kindness to screen-reader users, since csv files are way easier to deal with than visually rendered tables. If you need a stable format for some specific output, please file a feature request at <https://salsa.debian.org/debian/debputy/-/issues> or via reportbug debputy. 🫶

You can run debputy plugin list --help and debputy plugin show --help to see which topics actually apply to each subcommand. Iconic.

The noteworthy topics include:

  • plugins

This topic gives you a full listing of every plugin debputy is aware of. ⭐

It can only be used with plugin list — not with plugin show.

  • pluggable-manifest-rules (aliases: pmr, p-m-r)

So the debputy manifest has a bunch of spots where the packager can drop in different rules — think install vs. install-doc vs. install-examples under installations:. Those are what we call pluggable manifest rules, and this topic gives you the tea on which rules are available where. 🍓

With list, debputy lists every pluggable manifest rule available. With show, you have to hand over a rule name, and then debputy spills the details about that rule — including the attributes available (where applicable) and any reference documentation the plugin provides.

For example, here's 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 you to use rule-type::rule-name instead of just rule-name. Like so:

debputy plugin show pluggable-manifest-rules TransformationRule::remove
debputy plugin show pluggable-manifest-rules DpkgMaintscriptHelperCommand::remove

Just so you know: those type names (like TransformationRule) are currently an implementation detail and may change in the future. 💅

  • packager-provided-files (aliases: ppf, p-p-f)

This topic gives you the details on all "packager provided files". These are files you can pop into debian and debputy will pick them up and install them somewhere in the package. And yes, while this command shows all the possible variants (by their stems), the used-packager-provided-files topic is the one that lists the real files that got matched. 🎀

With list, debputy lists all the packager provided files it knows about. With show, you get some extra details.

In a few cases, the packager provided file gets processed first — for example debian/symbols gets handed off to dpkg-gensymbols, and the processed version is what actually gets installed instead. ✨

  • used-packager-provided-files (aliases: uppf, u-p-p-f)

This topic lists all packager provided files used in this source package. It's different from packager-provided-files because it only shows files actually in use, while the other topic lists every known stem.

The listing may also include files that debputy could have picked up but won't during a package build, because the relevant plugin isn't explicitly requested (usually via a Build-Depends). Those cases get stashed in a separate table and are clearly marked. 👑

This topic can only be used with plugin list — not with plugin show.

Also, it only works when you run the command from the root of an unpacked Debian source package, because debputy needs to read debian/control and scan the debian/ directory.

  • metadata-detectors

Listing time for all the "metadata detectors" — 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 be used with plugin list — not with plugin show.

  • manifest-variables

This one covers plugin-provided manifest variables. The listing shows the common manifest variables by default, along with their values in source context (if that's possible). Some of the special-case manifest variables are hidden by default — use debputy plugin list manifest-variables --help to see the filter options. 🦋

With show VARIABLE, debputy will list the reference documentation (if the plugin provided it) related to the value, plus a few other details.

And as hinted above: this only shows plugin-provided variables. Any manifest variables you provided directly in the manifest are not covered by these commands.

  • automatic-discard-rules

Automatic discard rules, bestie! These are rules that automatically filter out (discard) sources from installation rules by default. The listing shows all available automatic discard rules. And show RULE will show you the reference documentation plus an example of what the rule reacts to — assuming the plugin provided those. 💜

Like, for example:

debputy plugin show automatic-discard-rules la-files
  • type-mappings

This topic covers type mappings, which explain how some non-trivial types get interpreted. These cover types like FileSystemMatchRule and FileSystemMode, which are used by other features such as pluggable manifest rules. 🌈

With show NAME, any plugin-provided documentation and example inputs get displayed for that rule.

  • autopkgtest-test-runner

The autopkgtest-test-runner command is meant to be used by autodep8 or from autopkgtests to run the tests of plugins in installed mode. 🧚

  • internal-command

Internal-only usage, periodt. Any subcommand under internal-command may disappear or change options between any release without any warning. 💀

✨ GENERAL OPTIONS ✨

These general options / root-level options are the ones available to you:

  • -h, --help — Prints usage information and exits. 👑

The info printed depends on which subcommands appear prior to this option.

  • --version — Prints version information and exits. ✨

Cannot be used with subcommands.

  • -d, --debug — Enables debug logging and raw stack traces on errors. 🐛

Heads up: some warnings become errors as a consequence.

You can also set the environment variable DEBPUTY_DEBUG to 1, which enables debug logging too. 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 partial credit, bestie.

  • --no-pager — Some subcommands pipe their default output format to a pager, so you get a nicer experience when standard out is a terminal. Examples include many of the plugin list commands. This option disables 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. Notably, 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 command's 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, the subcommand will load REQUIRED_PLUGIN in addition to the other plugins that would normally be loaded. 💅

REQUIRED_PLUGIN can either be a plugin name or a filename. The debputy program considers a parameter containing a forward slash as a filename. Otherwise, the parameter is interpreted as a plugin name. When given a plugin name, debputy searches for the plugin in its plugin search path and loads it from there. When given a file name, debputy reads that file as a plugin and uses the basename minus any .json or .json.in extension as the plugin name.

For packages that need a plugin they provide themselves during their build process, this option is useful for telling debputy about it. For the build itself, usually you want dh_debputy --plugin path/to/plugin.json. But this option can still be useful for debputy check-manifest etc.

The other use-case is loading a plugin that isn't installed into the plugin search directories. Notably, you can use this to shadow an existing plugin, which is handy 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 — bestie, this is the file. For all the deets on the format, go read /usr/share/doc/dh-debputy/MANIFEST-FORMAT.md.gz. 💖

If this is your very first package conversion, honestly? Read /usr/share/doc/dh-debputy/GETTING-STARTED-WITH-dh-debputy.md.gz first. Trust me on this one, it's giving tutorial energy and you'll want it. ✨

Okay so here's the thing that trips people up: unlike most debhelper-ish tools, this file is per source package, not per binary package. Which means you literally cannot use debian/package.debputy.manifest to give package a specialized manifest. Nope. Not a thing. Instead, every part you need goes straight into the manifest itself. All of it. In one place. Periodt. 💅

And the --debputy-manifest option? It lets debputy process a manifest other than debian/debputy.manifest. Super handy for testing, or for running debputy check-manifest — and ngl, that's kinda it. Not much else it's good for. 🙈

👑 INTEGRATION LEVELS 👑

debputy has multiple levels of integration, and what that means is: it decides how much of the packaging debputy is handling relative to the default dh sequence. Basically, how much of the main character energy debputy has in your build. 🌈

Here are the levels on offer:

dh-sequence-zz-debputy-rrr

This one replaces the minimal number of commands necessary to give you Rules-Requires-Root: no support for any package — even the ones needing static ownership. Slay. This sequence is often compatible with other debhelper sequences too, which is lowkey the best part. 🫶

To use this 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
Heads up bestie — 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 into the 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. Yes, all of it. 💅 This replaces basically every command after the dh_auto_install command in the standard dh sequence.

This also makes the integration level incompatible with many debhelper add-ons, because they expect to run after dh_auto_install and just assume the contents will be materialized into debian/package. It's giving chaos, honestly. 💀

This migration level corresponds to a Build-Depends on dh-sequence-debputy or dh-sequence-zz-debputy.

🐛 REPORTING BUGS 🐛

Found a bug? Not me finding bugs 😭 — okay but for real, please report it at <https://salsa.debian.org/debian/debputy/-/issues>.

And for Debian users, you can also use report debputy if you prefer kicking it over to the Debian Bug Tracker. Your call, bestie. 🎀

🦋 SEE ALSO 🦋

💜 AUTHOR 💜

Niels Thykier <niels@thykier.net>

Okay that's the whole page, we made it 🫶💖 Give Niels some love for building this thing, shout at the issue tracker when something's cursed, and go manifest your little heart out. This page was generated with perl v5.42.3 and it's got a 2026-10-04 date stamp on it, so that's the vintage of the debputy(1) era you're living in, and honestly? Iconic. ✨👑

📦 where this page comes from