From 654b76190cbc4ee4057ee4cc3aef5e56cd01daf1 Mon Sep 17 00:00:00 2001
From: Emil Hammarberg <emilhammarberg@mailbox.org>
Date: Fri, 27 Feb 2026 17:37:58 +0100
Subject: [PATCH] Clarify %if template behavior

Closes #4991
---
 docs/reference/pathformat.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/reference/pathformat.rst b/docs/reference/pathformat.rst
index 612d16d47..017a210b6 100644
--- a/docs/reference/pathformat.rst
+++ b/docs/reference/pathformat.rst
@@ -64,7 +64,9 @@ These functions are built in to beets:
 - ``%if{condition,text}`` or ``%if{condition,truetext,falsetext}``: If
   ``condition`` is nonempty (or nonzero, if it's a number), then returns the
   second argument. Otherwise, returns the third argument if specified (or
-  nothing if ``falsetext`` is left off).
+  nothing if ``falsetext`` is left off). Note that beets doesn't distinguish
+  between different data types, so ``%if{album,album/}`` evaluates as false for
+  albums named exactly "0".
 - ``%asciify{text}``: Convert non-ASCII characters to their ASCII equivalents.
   For example, "café" becomes "cafe". Uses the mapping provided by the
   `unidecode module`_. See the :ref:`asciify-paths` configuration option.