📝 docs: document U flag and unset option

Author: gaborbernat

README.md

@@ -1,12 +1,12 @@
 # pytest-env
 
 [![PyPI](https://img.shields.io/pypi/v/pytest-env?style=flat-square)](https://pypi.org/project/pytest-env/)
-[![Supported Python
-versions](https://img.shields.io/pypi/pyversions/pytest-env.svg)](https://pypi.org/project/pytest-env/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/pytest-env.svg)](https://pypi.org/project/pytest-env/)
 [![check](https://github.com/pytest-dev/pytest-env/actions/workflows/check.yaml/badge.svg)](https://github.com/pytest-dev/pytest-env/actions/workflows/check.yaml)
 [![Downloads](https://static.pepy.tech/badge/pytest-env/month)](https://pepy.tech/project/pytest-env)
 
-This is a `pytest` plugin that enables you to set environment variables in `pytest.ini`, `pyproject.toml`, `pytest.toml` or `.pytest.toml` files.
+This is a `pytest` plugin that enables you to set environment variables in `pytest.ini`, `pyproject.toml`, `pytest.toml`
+or `.pytest.toml` files.
 
 ## Installation
 
@@ -20,19 +20,20 @@ pip install pytest-env
 
 ### Native form in `pyproject.toml`, `pytest.toml` and `.pytest.toml`
 
-> [!NOTE]
-> `pytest.toml` and `.pytest.toml` is only supported on Pytest 9.0+.
+> [!NOTE] `pytest.toml` and `.pytest.toml` is only supported on Pytest 9.0+.
 
-Native form takes precedence over the `pytest.ini` form. `pytest.toml` takes precedence over `.pytest.toml`, and that takes precedence over `pyproject.toml`.
+Native form takes precedence over the `pytest.ini` form. `pytest.toml` takes precedence over `.pytest.toml`, and that
+takes precedence over `pyproject.toml`.
 
 In `pyproject.toml`:
 
 ```toml
 [tool.pytest_env]
 HOME = "~/tmp"
 RUN_ENV = 1
-TRANSFORMED = {value = "{USER}/alpha", transform = true}
-SKIP_IF_SET = {value = "on", skip_if_set = true}
+TRANSFORMED = { value = "{USER}/alpha", transform = true }
+SKIP_IF_SET = { value = "on", skip_if_set = true }
+DATABASE_URL = { unset = true }
 ```
 
 In `pytest.toml` (or `.pytest.toml`):
@@ -41,14 +42,16 @@ In `pytest.toml` (or `.pytest.toml`):
 [pytest_env]
 HOME = "~/tmp"
 RUN_ENV = 1
-TRANSFORMED = {value = "{USER}/alpha", transform = true}
-SKIP_IF_SET = {value = "on", skip_if_set = true}
+TRANSFORMED = { value = "{USER}/alpha", transform = true }
+SKIP_IF_SET = { value = "on", skip_if_set = true }
+DATABASE_URL = { unset = true }
 ```
 
-The `tool.pytest_env` (`pytest_env` in `pytest.toml` and `.pytest.toml`) tables keys are the environment variables keys to set. The right hand side of the assignment:
+The `tool.pytest_env` (`pytest_env` in `pytest.toml` and `.pytest.toml`) tables keys are the environment variables keys
+to set. The right hand side of the assignment:
 
-- if an inline table you can set options via the `transform` or `skip_if_set` keys, while the `value` key holds the
-  value to set (or transform before setting). For transformation the variables you can use is other environment
+- if an inline table you can set options via the `transform`, `skip_if_set` or `unset` keys, while the `value` key holds
+  the value to set (or transform before setting). For transformation the variables you can use is other environment
   variable,
 - otherwise the value to set for the environment variable to set (casted to a string).
 
@@ -69,8 +72,8 @@ Or with `pyproject.toml`:
 ```toml
 [tool.pytest.ini_options]
 env = [
-    "HOME=~/tmp",
-    "RUN_ENV=test",
+  "HOME=~/tmp",
+  "RUN_ENV=test",
 ]
 ```
 
@@ -105,3 +108,14 @@ env =
     R:RUN_PATH=/run/path/{USER}
     R:D:RUN_PATH_IF_NOT_SET=/run/path/{USER}
 ```
+
+### Unsetting variables
+
+You can use `U:` (unset) as prefix to remove an environment variable. This differs from setting a variable to an empty
+string — the variable will be completely removed from `os.environ`:
+
+```ini
+[pytest]
+env =
+    U:DATABASE_URL
+```