git: 7778c983ab - main - porters-handbook: clarify semantics of CONFLICTS* definitions

The branch main has been updated by se (ports, src committer):

URL: https://cgit.FreeBSD.org/doc/commit/?id=7778c983ab0d812ae30ea95d617bc7316797be80

commit 7778c983ab0d812ae30ea95d617bc7316797be80
Author:     Stefan Eßer <se@FreeBSD.org>
AuthorDate: 2022-04-23 06:18:23 +0000
Commit:     Stefan Eßer <se@FreeBSD.org>
CommitDate: 2022-04-23 06:18:23 +0000

    porters-handbook: clarify semantics of CONFLICTS* definitions
    
    There has been some confusion about the correct specification of
    CONFLICTS definitions in port Makefiles.
    
    The examples hint at the correct use of the package base name when
    possible (i.e. no version check required), but there were quite a
    few definitions that included unneccessary wild-card patterns to
    match all versions.
    
    Since I had to explain the semantics by mail to several maintainers
    after fixing up stale or incorrect definitions and since I received
    a request to clarify the semantics of CONFLICTS definitions, I have
    created a new section that explains the correct use.
    
    After having the change available for review for 2 months without
    any reaction of the assigned reviewers and since the next round of
    CONFLICTS fixes is likely to result in many requests to explain
    the correctness of the changes performed, I'm committing this text
    now.
    
    Differential Revision:  https://reviews.freebsd.org/D34352
---
 .../en/books/porters-handbook/makefiles/_index.adoc       | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
index 8c423ed961..2b4759731a 100644
--- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
@@ -4999,6 +4999,21 @@ Build conflicts are not recorded in the resulting package.
 If the port cannot be built if a certain port is already installed and the resulting package cannot coexist with the other package.
 `CONFLICTS` check is done prior to the build stage and prior to the install stage.
 
+The values assigned to the `CONFLICTS*` variables are matched against the package base names and the full package names of all installed packages using file globbing rules.
+If the base name of the currently built package is matched by a `CONFLICTS*` pattern, this match is ignored.
+This allows to list all flavors of a port in a conflicts list, without being considered if the installed port matching this pattern is upgraded.
+For example, if git-lite is installed, `CONFLICTS_INSTALL=git git-lite` would allow to perform:
+[source,shell]
+....
+% make -C devel/git FLAVOR=lite all deinstall install
+....
+
+But the following command would report a conflict, since the package base name installed is `git-lite`, while `git` would be built, but cannot be installed in addition to `git-lite`:
+[source,shell]
+....
+% make -C devel/git FLAVOR=default all deinstall install
+....
+
 The most common content of one of these variable is the package base of another port.
 The package base is the package name without the appended version, it can be obtained by running `make -V PKGBASE`.