DH_LINKTREE(1)

dh_linktree 💅✨

okay so bestie, welcome to the manual page for dh_linktree, and honestly? she's giving build-time icon energy. this is section 1 of the manual, which means she's a user command, and she comes to you from the dh_linktree 0.9build1 era. let's get into it 🫶

---

✨ NAME ✨

dh_linktree — create symlink trees to embed files from other packages 🦋

---

🌸 SYNOPSIS 🌸

dh_linktree [debhelper options] [-A] [-Xitem]
[action source destination ...]

---

💖 DESCRIPTION 💖

so dh_linktree is a debhelper program, and what she does is create symlink trees inside your package build directories. these symlinks point at files that other packages provide, and those files have to be present while you're building. which means — and this is the important bit, no cap — you have to put the packages that provide the destination files into your build dependencies. for every single symlink she creates, she'll add to ${misc:Depends} the dependency that's needed to make sure the target of that symlink is actually available. periodt. 👑

---

🧚 RATIONALE 🧚

the tea is that this tool got developed to handle embedded libraries written in interpreted languages (javascript, PHP, etc.). the vibe you usually want is: replace the embedded copy with the packaged one — except when they're not compatible. and since both versions evolve separately, you might have to switch back and forth between the embedded version and the packaged one a lot. 🙈

if the embedded library had just been replaced by a symlink to the top-level directory, you'd have to add code to the preinst/postinst every single time you switch from one to the other (to swap the real directory for a symlink and vice-versa). with a symlink tree, dpkg is doing everything by itself. iconic behaviour, honestly. 💅

but — and here's the caveat, bestie, listen up — since symlink trees are created statically at build-time, they are not very future-proof and they have a risk to miss some files introduced by a newer version of the package providing the file tree which is duplicated. that's why the generated dependencies generally ensure that the same upstream version is used at run-time as at build-time. it's giving locked-in, but for a reason. 🔥

---

🌈 USAGE 🌈

dh_linktree accepts arguments in sets of 3. one action, followed by source and destination file/directories. symlinking files works just like dh_link does, but symlinking directories will recreate the same directory hierarchy, and all the individual files get turned into symlinks. 🎀

the source files are the already existing files that will be symlinked from. the destination files are the symlinks that will be created.

okay so be sure you do specify the full filename to both the source and the destination files — unlike what you would do if you were using something like ln(1). don't be casual about it. 💀

dh_linktree will generate symlinks that comply with Debian policy: absolute when policy says they should be absolute, and relative links with as short a path as possible. it will also create any subdirectories it needs to, to put the symlinks in. so thoughtful of her. 🫶

note that dh_linktree will not be executed automatically by dh. you need to use dh $@ --with linktree to get it hooked into the list of dh_* commands that dh automatically executes. otherwise she's just sitting there, unbothered, moisturised, in her lane. ⭐

---

🍓 FILES 🍓

• debian/package.linktrees — lists source and destination trees to be symlinked. each line consists of 3 fields: the action, the source directory, the destination directory. should be put on its own line, with the source and destination separated by whitespace.

---

👑 OPTIONS 👑

• -Xitem, --exclude=item — do not create symlinks for files that contain item anywhere in their filename. 🙅
• action source destination ... — the main character trio. here's what each action is giving:
  • if the action is "embed", create a symlink tree named destination with all files within it pointing to the corresponding file in source. it generates a strong dependency ("exactly same upstream version"). 🔒
  • the "embed-weakdep" action is like "embed", except it generates a weak dependency ("at least the current upstream version").
  • the "deduplicate" action will not create new files, but it will replace existing files in the destination directory with symlinks to the corresponding source file — provided that both files have the same content. it generates a strong dependency. 💅
  • the "replace" action is like "deduplicate" except that it does replace existing files even if their content is different from the content of the source files. it generates a weak dependency ("at least the current upstream version") on the basis that you already assume that both versions are compatible — otherwise you would have used "deduplicate" or "embed". 😭

---

🔥 EXAMPLES 🔥

 dh_linktree embed usr/share/javascript/jquery usr/share/wordpress/plugin-jquery

make plugin-jquery be a symlink tree to jquery. slay. ✨

---

💀 ERRORS 💀

 dpkg-query: no path found matching pattern /some/file.
 [...]
 dh_linktree: error: dpkg --search -- /some/file [...] gave error exit status 1

you get this error when the source tree contains files (here /some/file) that are not managed by dpkg. dh_linktree can't generate a correct dependency for a file that is unknown to dpkg, and thus — bestie, she just fails. no workaround, no vibes, she simply cannot. 🫠

---

💜 SEE ALSO 💜

• debhelper(7)

this program is a part of debhelper. iykyk. 🧚

---

🎀 AUTHOR 🎀

Raphael Hertzog <hertzog@debian.org> and Joey Hess <joeyh@debian.org>. legends, honestly. 🌟

---

okay that's the whole page!! this was dh_linktree 0.9build1, dated 2025-12-08, and yes it lives in section 1 of the manual. go forth and build your symlink trees, bestie — you've got this 💖✨🎀🦋