DPATCH-EDIT-PATCH(1)

📦 version 2.0.41, in ubuntu jammy

🦋 DPATCH-EDIT-PATCH(1) — the dpatch users manual, bestie edition

okay so this is the manual page for dpatch-edit-patch, straight out of the dpatch users manual, section 1. buckle up, she's long but she's worth it 💖

✨ NAME ✨

dpatch-edit-patch — the girl who maintains dpatch patches for a Debian source package 🎀

✨ SYNOPSIS ✨

dpatch-edit-patch [options] command dpatchname [basepatch]

✨ DESCRIPTION ✨

This manual documents the dpatch-edit-patch command, which is the one holding down the dpatch patches for a dpatch-using Debian source package. 💅

And like, important vibe: dpatch-edit-patch copies the entire tree to a temporary directory to do its little work in. She does not mess with your actual tree, she makes her own. main character behaviour honestly. ✨

🚨 WARNING 🚨

dpatch is deprecated. bestie, please switch to the 3.0 (quilt) Debian source package format instead. there's a short guide on how to do it at http://wiki.debian.org/Projects/DebSrc3.0#FAQ 🫶

🌈 OPTIONS 🌈

So dpatch-edit-patch takes two forms of arguments: options and commands. And rn the only command that exists is "patch", which is the one that lets you create/edit dpatches. When no command is given, "patch" is just assumed. she reads the room. 😌

🎀 COMMANDS: 🎀

  • patch — This command needs one mandatory argument, and accepts one optional argument under certain circumstances. The mandatory one is dpatchname. It refers to a dpatch, exactly as it would be listed in debian/patches/00list. And no, it is not necessary for dpatchname to already exist before you run dpatch-edit-patch patch dpatchname — she'll handle it.

When dpatchname does exist, dpatch-edit-patch sets up a working source tree, applies all the dpatches listed in debian/patches/00list up to and including dpatchname, and then spawns an interactive shell for the developer (that's you, bestie 🫶). You edit files in this working tree. When you're done, you exit the shell. Then dpatch-edit-patch updates dpatchname to reflect the changes you made. iconic.

And if you want to abort the whole thing from inside the interactive shell? You just need the shell to exit with an exit value of 230. Typically that's done by exiting the shell with the command exit 230. ngl that's a weird number but okay, we respect it. 💀

Now — if you wanna peek at the patch you're currently working on without leaving the subshell, there are two environment variables exported into the subshell to help you out:

  • DPEP_SHELL_REFDIR — set to the reference directory's full name
  • DPEP_SHELL_WORKDIR — set to the subshell's working directory

These two can be used to — for example — generate a diff between the reference version and the current tree:

diff -urNa $DPEP_SHELL_REFDIR $DPEP_SHELL_WORKDIR

When dpatchname does not exist, dpatch-edit-patch assumes a new dpatch should be created. Same deal as above: first she creates a working source tree. If the optional argument basepatch is supplied, all dpatches in debian/patches/00list up to and including basepatch get applied to the working tree. If basepatch is not supplied, no dpatches are applied to the working tree. Then when the developer exits the shell, dpatch-edit-patch creates dpatchname. If debian/patches/00template does not exist, a hardcoded dpatch header and shell snippet will be used. If it exists and is not executable, it will be copied verbatim as the header and shell snippet. periodt. 💅

Its first parameter is the base filename of the to-be-updated or to-be-created dpatch (useful for adding titles to the dpatch header). Its second parameter will be the description of the new patch. 🌸

💜 OPTIONS 💜

For the following options, bestie, the precedence goes like this: command-line arguments > environment variables > configuration variables. And the configuration variables are read from debian/patches/00dpatch.conf and ~/.dpatch.conf. 🌈

  • -s, --sourcedir=value — Directory containing the unpacked Debian source package. Configuration variable conf_sourcedir (settable only in ~/.dpatch.conf), environment variable DPEP_SOURCEDIR. Defaults to the current working directory. 📁
  • -o, --outdir=value — Directory where the updated or newly-created dpatch will be placed. Configuration variable conf_outdir (~/.dpatch.conf), environment variable DPEP_OUTDIR. Defaults to ./debian/patches/ ✨
  • -c, --clean — Tells dpatch-edit-patch that the current work directory can safely be cleaned. If this is not given, dpatch-edit-patch tries to preserve partial or complete builds by first copying the current work directory to a reference directory, and then invoking debian/rules clean on the reference directory. If it is given, the current directory is cleaned and then taken as the reference directory. Use this option if your source package is pretty large and no significant work gets destroyed by cleaning. Configuration variable conf_clean (~/.dpatch.conf), environment variable DPEP_CLEAN. 🧹
  • -b, --debianonly[=path] — Tells dpatch-edit-patch that the current work directory only contains a debian subdirectory, and that an upstream tarball is to be unpacked in the reference directory before copying the current work directory there. The optional argument is the path to the upstream tarball — including the tarball name. If no value is given, dpatch-edit-patch will use the hook script pointed to by conf_getorigtargz (~/.dpatch.conf) or DPEP_GETORIGTARGZ to obtain the upstream tarball. The hook script should take one argument: the destination directory where the fetched archive shall be put. Configuration variables: conf_debianonly (debian/patches/00dpatch.conf) and conf_origtargz (~/.dpatch.conf). Environment variables: DPEP_DEBIANONLY and DPEP_ORIGTARGZ. 📦
  • -P, --origtargzpath=path — When -b is in use, specify the path where upstream tarballs should be looked for. path is a colon-separated list of directories. Configuration variables: conf_origtargzpath (~/.dpatch.conf). Environment variables: DPEP_ORIGTARGZPATH. 🔍
  • -r, --rootcmd=value — The command used to gain root privileges, used to clean DPEP_SOURCEDIR. Configuration variable conf_rootcmd, environment variable DPEP_ROOTCMD. Defaults to fakeroot, if installed. If none of the above are specified, and fakeroot is not installed, dpatch-edit-patch will abort. And the dpatch authors strongly recommend the use of fakeroot for this purpose. 👑
  • -d, --description=value — The description used for a newly-created patch. Configuration variable conf_newdesc (~/.dpatch.conf), environment variable DPEP_NEWDESC, defaults to "No description." 😭
  • -k, --keeptemp=value — A boolean value, either 0 or 1. Configuration variable conf_keeptemp (~/.dpatch.conf), environment variable DPEP_KEEPTEMP. When set to 1, the temporary working tree is not deleted when dpatch-edit-patch is done. 🙈
  • -t, --tmpdir=value — The temporary directory within which dpatch-edit-patch will create the working source tree. Configuration variable conf_tmpdir (~/.dpatch.conf), environment variable DPEP_TMPDIR. Should none of the above be set, dpatch-edit-patch will first attempt to use the environment variable TMPDIR, and will fall back to /tmp. 🗂️
  • -p, --stampdir=value — The directory dpatch has used for creating patch stamps. Used for checking if the patch to be edited is already applied to the working tree. Configuration variable conf_stampdir (~/.dpatch.conf), environment variable DPEP_STAMPDIR. Should none of the above be set, dpatch-edit-patch will fall back to debian/patched. 🏷️
  • -e, --exclude=valuelist — A space-separated list of file- and directory names that dpatch-edit-patch will exclude from being copied and diffed. Configuration variable conf_exclude (~/.dpatch.conf), environment variable DPEP_EXCLUDE. Defaults to "CVS .svn .git .arch .hg _darcs .bzr" — which might cause you trouble if you use files named like that in your package. 😬
  • -O, --diffopts=valuelist — Extra options to directly pass to diff as-is. Configuration variable conf_diffopts (~/.dpatch.conf), environment variable DPEP_DIFF_OPTIONS. It is empty by default. 🫧
  • -l, --shell=shell — Tells dpatch-edit-patch which shell to invoke. Configuration variable conf_shell (~/.dpatch.conf), environment variable DPEP_SHELL, defaulting to $SHELL and the user's default shell. 🐚
  • -n, --notimestamp — Tells dpatch-edit-patch to remove timestamps from the diffs it generates. Can also be set in debian/patches/00options, with the DPEP_OMIT_TIMESTAMPS variable. ⏰
  • -0, --add2list — add the new patch to the 00list file. 📝
  • -a, --applyall — apply all available patches. 🔥

to be continued, bestie — more of this page is coming 💖

✨ EXAMPLES ✨ 🎀

Real talk, examples are where it all clicks, so here's the whole vibe in action 💅

🌸 Create a new patch to be applied after an existing patch 🌸

Okay so bestie, you wanna make a brand new patch that sits on top of an existing one, 90_ctrlkeyfix. Here's literally exactly how that goes:

$ dpatch-edit-patch patch 95_newupstreamfix 90_ctrlkeyfix
dpatch-edit-patch: * debian/patches/95_newupstreamfix.dpatch does not exist, it will be created as a new dpatch.
dpatch-edit-patch: * Cleaning /home/david/temp/sopwith-1.6.0
 ...
dpatch-edit-patch: * Applying patches
dpatch-edit-patch: ** Applying patch 90_ctrlkeyfix ... applied cleanly.
dpatch-edit-patch: * Copying /home/david/temp/sopwith-1.6.0 to work directory.
 ...
$ editor files
$ exit 0
dpatch-edit-patch: * Creating new patch debian/patches/95_newupstreamfix.dpatch
dpatch-edit-patch: Warning: debian/patches/00template does not exist, using hardcoded default.
dpatch-edit-patch: debian/patches/95_newupstreamfix.dpatch created.

See how it announces the new patch doesn't exist yet and is like "it will be created as a new dpatch"? Iconic. Then it cleans, applies your base patch, copies stuff to the work dir, and you get to go in with your editor, do your thing, and exit 0. Boom, new patch, created. 🦋

🦋 Create a new patch not depending on existing patches 🦋

Now if you want a patch that gets applied before any other patches (or, same energy, a patch that genuinely doesn't need anything else applied first), you just skip the base-patch argument entirely:

$ dpatch-edit-patch 10_debianstrings
dpatch-edit-patch: * debian/patches/10_debianstrings.dpatch does not exist, it will be created as a new dpatch.
dpatch-edit-patch: * Cleaning /home/david/temp/sopwith-1.6.0
 ...
dpatch-edit-patch: Warning: * No base-patch supplied, not applying any patches.
dpatch-edit-patch: * Copying /home/david/temp/sopwith-1.6.0 to work directory.
 ...
$ editor files
$ exit 0
 ...
dpatch-edit-patch: * Creating new patch debian/patches/10_debianstrings.dpatch
dpatch-edit-patch: Warning: debian/patches/00template does not exist, using hardcoded default.
dpatch-edit-patch: debian/patches/10_debianstrings.dpatch created.

Notice that little heads-up — Warning: * No base-patch supplied, not applying any patches. — that's just it being honest with you, no cap. Same deal otherwise: edit, exit 0, patch gets made. ✨

💜 Edit an existing patch 💜

And finally, the glow-up scenario: there's already a patch, and you just wanna tweak it.

$ dpatch-edit-patch 10_debianstrings
dpatch-edit-patch: * debian/patches/10_debianstrings.dpatch exists, this patch will be updated.
dpatch-edit-patch: * Cleaning /home/david/temp/sopwith-1.6.0
 ...
dpatch-edit-patch: * Applying patches
dpatch-edit-patch: * Copying /home/david/temp/sopwith-1.6.0 to work directory.
dpatch-edit-patch: * Applying current 10_debianstrings for editing.
 ...
$ editor files
$ exit 0
dpatch-edit-patch: Updating patch debian/patches/10_debianstrings.dpatch
dpatch-edit-patch: @DPATCH@ tag found, preserving dpatch header.
dpatch-edit-patch: debian/patches/10_debianstrings.dpatch updated.

It tells you the patch exists and "this patch will be updated", applies the current one so you're editing on top of what's already there, and when you're done it keeps your dpatch header intact because it found that @DPATCH@ tag. Chef's kiss. 💖

💅 NOTES 💅

Okay, the fine print, but make it cute:

dpatch-edit-patch uses the DEBFULLNAME environment variable as the author's name. If it's unset, the author name is just left blank. Ngl, set it. 🙈

For new patches, dpatch-edit-patch figures out the author's email address like this:

  1. If the DEBEMAIL environment variable exists, it is always used. Periodt.
  2. If the EMAIL environment variable exists, it gets used whenever DEBEMAIL doesn't exist.
  3. And if neither of those first two worked out? The email gets constructed from the login name of the user running dpatch-edit-patch, combined with the output of hostname -f.

Heads up, this part matters: when dpatch-edit-patch sets up a reference or a working directory, it dereferences all symlinks in the source. That means relative links keep working, and it means changes land on a single file rather than on both the linked file and the link target. But — and this is the dramatic part — if you run dpatch-edit-patch on source trees that have symbolic links, you might end up with a patch that is unapplyable to the original tree. 😭 So like, be aware.

Lowkey a trap. Highkey worth knowing before you ship.

🍓 FILES 🍓

  • debian/patches/00dpatch.conf
  • ~/.dpatch.conf

🌈 SEE ALSO 🌈

Go read these too, bestie, they're the whole friend group:

Also, files live in /usr/share/doc/dpatch/ 📁

👑 AUTHOR 👑

This manual page was written by David B. Harris <david@eelf.ddts.net> and modified in the course of development by Gergely Nagy <algernon@debian.org>, Marc Haber <mh+debian-packages@zugschlus.de>, Stefano Zacchiroli <zack@debian.org>, and Junichi Uekawa <dancer@debian.org>.

That's the whole page, bestie!! 💖 This one came from the DPATCH source, dated 23 Oct 2011, and it's DPATCH-EDIT-PATCH(1) — go forth and make beautiful patches. Slay. ✨💅🦋

📦 where this page comes from