---
name: pkh
description: '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.