Differentiate absence of value and value of absence for default and flag_value arguments

CHANGES.rst

@@ -1,10 +1,21 @@
 .. currentmodule:: click
 
-Version 8.2.x
+Version 8.3.x
 -------------
 
 Unreleased
-
+-   Rework relationship between ``flag_value`` and ``default``: the value given to
+    ``default`` is now left untouched, and keep the value it receive. So
+    ``default=<desired_value>`` is respected and ``<desired_value>`` is passed on as-is
+    to the CLI function. With the exception of flag options, where setting
+    ``default=True`` maintain the legacy behavior of defaulting to the ``flag_value``.
+    This allow ``default`` to be of any type, including ``bool`` or ``None``, fixing
+    inconsistencies reported in: :issue:`1992` :issue:`2012` :issue:`2514`
+    :issue:`2610` :issue:`3024` :pr:`3030`
+-   Allow ``default`` to be set on ``Argument`` for ``nargs = -1``. :issue:`2164`
+    :pr:`3030`
+-   Show correct auto complete value for ``nargs`` option in combination with flag
+    option :issue:`2813`
 -   Show correct auto complete value for nargs option in combination with flag option :issue:`2813`
 -   Fix handling of quoted and escaped parameters in Fish autocompletion. :issue:`2995` :pr:`3013`
 -   Lazily import ``shutil``. :pr:`3023`
@@ -14,12 +25,12 @@ Version 8.2.2
 
 Released 2025-07-31
 
--   Fix reconciliation of `default`, `flag_value` and `type` parameters for
+-   Fix reconciliation of ``default``, ``flag_value`` and ``type`` parameters for
     flag options, as well as parsing and normalization of environment variables.
     :issue:`2952` :pr:`2956`
 -   Fix typing issue in ``BadParameter`` and ``MissingParameter`` exceptions for the
     parameter ``param_hint`` that did not allow for a sequence of string where the
-    underlying functino ``_join_param_hints`` allows for it. :issue:`2777` :pr:`2990`
+    underlying function ``_join_param_hints`` allows for it. :issue:`2777` :pr:`2990`
 -   Use the value of ``Enum`` choices to render their default value in help
     screen. Refs :issue:`2911` :pr:`3004`
 -   Fix completion for the Z shell (``zsh``) for completion items containing

docs/options.md

@@ -314,7 +314,7 @@ If you want to define an alias for the second option only, then you will need to
 
 ## Flag Value
 
-To have an flag pass a value to the underlying function set `flag_value`. This automatically sets `is_flag=True`. To set a default flag, set `default=True`. Setting flag values can be used to create patterns like this:
+To have an flag pass a value to the underlying function set `flag_value`. This automatically sets `is_flag=True`. To mark the flag as default, set `default=True`. Setting flag values can be used to create patterns like this:
 
 ```{eval-rst}
 .. click:example::
@@ -335,6 +335,30 @@ To have an flag pass a value to the underlying function set `flag_value`. This a
     invoke(info)
 ```
 
+````{caution}
+The `default` argument of options always give to the underlying function its value *as-is*.
+
+But for flags, the interaction between `flag_value` and `default` is a bit special.
+
+If a flag has a `flag_value`, setting `default` to `True` means that the flag is activated by default. Not that the value passed to the underlying function is the `True` Python value. Instead, the default value will be aligned to the `flag_value` behind the scenes.
+
+Which means, the in example above, this option:
+
+```python
+@click.option('--upper', 'transformation', flag_value='upper', default=True)
+```
+
+is equivalent to:
+
+```python
+@click.option('--upper', 'transformation', flag_value='upper', default='upper')
+```
+
+This was implemented to support legacy behavior, that will be removed in Click 9.0 to allow for default to take any value, including `True`.
+
+In the mean time, to avoid confusion, it is recommended to always set `default` to the actual default value you want to pass to the underlying function, and not use `True`, `False` or `None`. Unless that's the precise value you want to explicitly force as default.
+````
+
 ## Values from Environment Variables
 
 To pass in a value in from a specific environment variable use `envvar`.
@@ -386,10 +410,11 @@ Here are the rules used to parse environment variable values for flag options:
    - If the flag option has a `flag_value` argument, passing that value in the environment variable will activate the flag, in addition to all the cases described above
    - Any other value is interpreted as deactivating the flag
 
-.. caution::
-    For boolean flags with a pair of values, the only recognized environment variable is the one provided to the `envvar` argument.
+```{caution}
+For boolean flags with a pair of values, the only recognized environment variable is the one provided to the `envvar` argument.
 
-    So an option defined as `--flag\--no-flag`, with a `envvar="FLAG"` parameter, there is no magical `NO_FLAG=<anything>` variable that is recognized. Only the `FLAG=<anything>` environment variable is recognized.
+So an option defined as `--flag\--no-flag`, with a `envvar="FLAG"` parameter, there is no magical `NO_FLAG=<anything>` variable that is recognized. Only the `FLAG=<anything>` environment variable is recognized.
+```
 
 Once the status of the flag has been determine to be activated or not, the `flag_value` is used as the value of the flag if it is activated. If the flag is not activated, the value of the flag is set to `None` by default.
 

src/click/_utils.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import enum
+import typing as t
+
+
+class Sentinel(enum.Enum):
+    """Enum used to define sentinel values.
+
+    .. seealso::
+
+        `PEP 661 - Sentinel Values <https://peps.python.org/pep-0661/>`_.
+    """
+
+    UNSET = object()
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}.{self.name}"
+
+
+UNSET = Sentinel.UNSET
+"""A sentinel object used to indicate that a value is not set."""
+
+T_UNSET = t.Literal[UNSET]  # type: ignore[valid-type]
+"""Type hint for the :data:`UNSET` sentinel value."""