pkh/data/skill/SKILL.md

name, description

name

description

pkh

Drive pkh, a Debian/Ubuntu packaging helper: pull source packages, generate changelog entries, build .dsc/.deb, lint, and upload to a PPA. Use it whenever the task touches Debian or Ubuntu packaging: patching an existing package, preparing an SRU, backport or NMU, scaffolding a new .deb, rebuilding for a PPA, or uploading a source package. Trigger on "update the changelog", "package this", or a bare package name, even when the user never mentions Debian.

pkh

pkh wraps the Debian packaging toolchain (dch, dpkg-buildpackage, sbuild, dpkg-source, quilt, lintian, PPA uploads) in one CLI. The subcommands share one set of option names, so -s always targets the series and --ppa always names the PPA. Each step also does more than the raw tool it replaces: pull fetches the orig tarball with the source, chlog commits the entry it writes, deb sets up a chroot and installs the build dependencies.

Check the install with pkh --version. Each command lists its flags with pkh <command> --help, so check there instead of guessing. pkh shells out to host tools (git, dpkg-dev, quilt, mmdebstrap, lintian, pristine-tar, schroot, ...). Install the ones your workflow uses, or use the classic snap, which carries them.

Shared options

Option	Meaning
-d, --dist <dist>	Target distribution, debian or ubuntu
-s, --series <series>	Target series, for example resolute or noble
-v, --version <version>	Target package version
-a, --arch <arch>	Target architecture, for example amd64 or riscv64
-p, --pocket <pocket>	Distribution pocket: updates, security, proposed
--ppa <user/ppa>	Act on the named PPA

Defaults come from the host vendor, its development series, and its architecture. When the target differs, pass the flags: packaging for Ubuntu on a Debian host needs -d ubuntu, and a series or architecture that differs from the host needs -s or -a.

Patch an Ubuntu package

pkh pull hello                     # source and orig tarball; add -d ubuntu off an Ubuntu host
# edit the package, committing each patch to git
pkh chlog                          # generates the entry, opens it for editing, commits it
git add debian/changelog && git commit -m "d/changelog"
pkh build                          # source package, written next to the tree
pkh deb                            # binary build in a chroot with build deps installed
pkh lint                           # lintian plus pkh-native checks
pkh put --ppa user/hello_xxx       # uploads the .changes file from the build
git push xxx user-fork             # push the branch to your fork

Run pkh chlog and pkh build from the root of the source tree; they act on the package in the current directory.

Command reference

• pkh new [name] scaffolds a buildable source package. --lang picks the build system (rust, python, meson, cmake, autotools, go, shell, makefile); --source <PATH> packages existing sources instead. --upstream-version and --revision set the version. --description, --homepage, --license <SPDX>, --command, --maintainer "Name <email>", and --depends fill in the package metadata, with the maintainer defaulting to DEBFULLNAME/DEBEMAIL and then git config. --quilt and --native choose the source format; --orig-from release|git|path|snapshot and --orig-path control the orig tarball. The changelog starts as UNRELEASED; --release targets --series instead. --defaults answers every remaining question with its default, which keeps the run non-interactive.

• pkh pull <package> fetches a source package from the archive or git. --archive skips git. --ppa user/ppa and --repository <suite-url> pull from a PPA or an external flat repository instead. -d, -s, -v, and -p target an exact source.

• pkh chlog generates the changelog entry from the commits since the last version tag, opens it for editing, and commits it. --backport, --nmu, and --rebuild apply the matching numbering scheme (3.1-1ubuntu2~24.04.1, 1.0-1.1, 1.0-1build1); -v sets an explicit version instead.

• pkh build produces the .dsc. --orig auto|always|never controls whether the upload includes the orig tarball; the default, auto, includes it only when the upstream version changed.

• pkh deb builds the binary packages in an isolated context with the build dependencies installed. --ppa (repeatable) adds dependency sources, --inject <package|.deb> preinstalls a package, and -j caps parallel jobs. --cross cross-compiles instead of using qemu-binfmt, but most packages cannot cross-compile, so prefer qemu. Leave --mode unset unless you need a specific build context.

• pkh lint [path] runs lintian plus the pkh-native checks. --json emits a machine-readable report and --list-tags prints the native tag catalog. --fail-on sets the severities that fail the run (errors by default), --suppress-tags ignores tags, --check runs a single native check, and --info, --pedantic, and --experimental add detail. --repack packs the tree fresh instead of reusing the existing build output.

• pkh put [changes] uploads a .changes file to --ppa user/ppa. With no argument it uploads the .changes from this package's last build, found next to the source tree. --force re-uploads a file that was already uploaded.

• pkh prune removes build artifacts and caches. Run it with --dry-run first to list them. --all also deletes the cached chroot tarballs, which take long to download again, so use it when you need the disk space.

Notes for agent runs

• Pass -d, -s, and -a whenever the target differs from the host, so runs are reproducible.
• Keep runs non-interactive. Pass explicit flags, use pkh new --defaults, and set EDITOR before pkh chlog (EDITOR=true keeps the generated text). Commands may ask short questions on the terminal; flags avoid most prompts.
• Pass RUST_LOG=debug for pkh's own logs. --verbose on pkh build and pkh deb prints raw tool output instead of the live view.
• pkh writes the build artifacts (.dsc, .changes, logs) next to the source tree. pkh put finds them without arguments, and pkh prune removes them again.
• Run pkh lint before pkh put. It exits nonzero when findings reach the --fail-on level, which defaults to errors.
• pkh intercepts Ctrl+C, runs its cleanup hooks, and exits with status 130. pkh prune removes anything left over.

The upstream repository is https://git.vhaudiquet.fr/vhaudiquet/pkh. Its README has longer workflow examples.