Document reverse-resolving diversions when defaulting DEB_CHECK_FILES_SOURCE.

[config-package-dev.git] / config-package.mk

diff --git a/config-package.mk b/config-package.mk
index 2f6711266719ec88c1690aea66539e6333e4926b..9cd7802a8afb7d254c2ac068cb95ea5868eac986 100644 (file)
--- a/config-package.mk
+++ b/config-package.mk
@@ -60,7 +60,7 @@
 # These variables have the following defaults:
 #
 #   DEB_TRANSFORM_SCRIPT_path/file.divert = debian/transform_file.divert
-#   DEB_CHECK_FILES_SOURCE_/path/file.divert = path/file
+#   DEB_CHECK_FILES_SOURCE_/path/file.divert = /path/file
 #
 #   If DEB_CHECK_FILES_SOURCE_/path/file.divert does not match the
 # md5sums shipped with the package containing it, the package build
@@ -68,7 +68,11 @@
 # (potentially long) configuration file that will work on several
 # Debian versions.  We recommend using DEB_TRANSFORM_FILES in
 # conjunction with pbuilder, sbuild, or another tool for building
-# Debian packages in a clean environment.
+# Debian packages in a clean environment. (That said, if /path/file is
+# diverted on the running system, DEB_CHECK_FILES_SOURCE does
+# reverse-resolve the diversion and default to the original version of
+# the file, to allow you to rebuild a package using DEB_TRANSFORM_FILES
+# that is currently installed, in most cases.)
 #
 # DEB_REMOVE_FILES_package += /path/file
 #
@@ -85,24 +89,17 @@
 # DEB_DIVERT_FILES.
 #
 # DEB_UNDIVERT_FILES_package += /path/file.divert
-# DEB_UNDIVERT_VERSION_/path/file.divert = 1.0-1
 #
 #   List of absolute paths to files whose diversions caused by
-# DEB_DIVERT_FILES are to be removed upon installing this package.
-# This is primarily useful for removing a now-unecessary diversion
-# provided by a previous version of this package on an upgrade.
-#
-#   The DEB_UNDIVERT_VERSION_file variable should be set to the
-# version number of this package at which you added
-# DEB_UNDIVERT_FILES_path/file.divert; it is used to avoid attempting
-# to remove the diversions again on future upgrades.
+# DEB_DIVERT_FILES are to be removed upon installing this package, if
+# the diversions have been made on the target system.  This is
+# primarily useful for removing a now-unecessary diversion provided by
+# a previous version of this package on an upgrade.
 #
 # DEB_UNREMOVE_FILES_package += /path/file
-# DEB_UNREMOVE_VERSION_/path/file = 1.0-1
 #
 #   This works like DEB_UNDIVERT_FILES_package, except that it only
-# removes the diversion (not a symlink) and the version number is
-# specified with DEB_UNREMOVE_VERSION_/path/file.
+# removes the diversion (not a symlink).
 
 ifndef _cdbs_rules_config_package
 _cdbs_rules_config_package = 1