From 6851cd7cb45b6074e88c773ffa5fd0b99b110e3c Mon Sep 17 00:00:00 2001
From: Johannes Schauer Marin Rodrigues <josch@mister-muffin.de>
Date: Fri, 3 Sep 2021 12:04:40 +0200
Subject: [PATCH] move hooks/setup00-merged-usr.sh ->
 hooks/merged-usr/setup00.sh, expand docs

---
 .../setup00.sh}                               | 12 ++++++++++-
 mmdebstrap                                    | 21 ++++++++++++++++---
 2 files changed, 29 insertions(+), 4 deletions(-)
 rename hooks/{setup00-merged-usr.sh => merged-usr/setup00.sh} (85%)

diff --git a/hooks/setup00-merged-usr.sh b/hooks/merged-usr/setup00.sh
similarity index 85%
rename from hooks/setup00-merged-usr.sh
rename to hooks/merged-usr/setup00.sh
index 148023f..a776d87 100755
--- a/hooks/setup00-merged-usr.sh
+++ b/hooks/merged-usr/setup00.sh
@@ -5,7 +5,13 @@
 #
 # Using this hook script, you can emulate what debootstrap does to set up
 # merged /usr via directory symlinks, even using the exact same shell function
-# that debootstrap uses.
+# that debootstrap uses by running mmdebstrap with:
+#
+#     --setup-hook=/usr/share/mmdebstrap/hooks/merged-usr/setup00.sh
+#
+# Alternatively, you can setup merged-/usr by installing the usrmerge package:
+#
+#     --include=usrmerge
 #
 # mmdebstrap will not include this functionality via a --merged-usr option
 # because there are many reasons against implementing merged-/usr that way:
@@ -24,6 +30,10 @@
 # The information whether a distribution uses this approach to merged-/usr or
 # not is not anymore contained in its packages but in a tool from the outside.
 #
+# Example real world problem: I'm using debbisect to bisect Debian unstable
+# between 2015 and today. For which snapshot.d.o timestamp should a merged-/usr
+# chroot be created and for which ones not?
+#
 # The problem is not the idea of merged-/usr but the problem is the way how it
 # got implemented in debootstrap via directory symlinks. That way of rolling
 # out merged-/usr is bad from the dpkg point-of-view and completely opposite of
diff --git a/mmdebstrap b/mmdebstrap
index 77730bd..e60b0fc 100755
--- a/mmdebstrap
+++ b/mmdebstrap
@@ -6227,6 +6227,10 @@ package list is free of duplicates. So the following are equivalent:
     --include=pkg1/stable,pkg2=1.0,pkg3-
     --incl=pkg1/stable --incl="pkg2=1.0 pkg3-" --incl=pkg2=1.0,pkg3-
 
+Example: setting up merged-/usr via the usrmerge package
+
+    --include=usrmerge
+
 =item B<--components>=I<comp1>[,I<comp2>,...]
 
 Comma or whitespace separated list of components like main, contrib and
@@ -6273,13 +6277,19 @@ installed. At that point, the chroot directory does not contain any
 executables and thus cannot be chroot-ed into. See section B<HOOKS> for more
 information.
 
-Example: Setup merged-/usr via symlinks
+Example 1: Setup merged-/usr via symlinks, omitting the architecture specific
+symlinks
 
     --setup-hook='for d in bin sbin lib; do ln -s usr/$d "$1/$d";
         mkdir -p "$1/usr/$d"; done'
 
-Example: Setup chroot for installing a sub-essential busybox-based chroot with
---variant=custom
+Example 2: Setup merged-/usr using debootstrap-method which takes care of the
+architecture specific symlinks
+
+    --setup-hook=/usr/share/mmdebstrap/hooks/merged-usr/setup00.sh
+
+Example 3: Setup chroot for installing a sub-essential busybox-based chroot
+with --variant=custom
 --include=dpkg,busybox,libc-bin,base-files,base-passwd,debianutils
 
     --setup-hook='mkdir -p "$1/bin"'
@@ -6371,6 +6381,11 @@ Example 2: Setup chroot for installing a sub-essential busybox-based chroot
 
     --hook-dir=/usr/share/mmdebstrap/hooks/busybox
 
+Example 3: Setup merged-/usr using debootstrap-method which takes care of the
+architecture specific symlinks
+
+    --hook-dir=/usr/share/mmdebstrap/hooks/merged-usr
+
 =item B<--skip>=I<stage>[,I<stage>,...]
 
 B<mmdebstrap> tries hard to implement sensible defaults and will try to stop