From 76709daa4918da60f2dd7aac7bea74aa5dfe4624 Mon Sep 17 00:00:00 2001
From: Ahmed Adel <ahmed_adel_hr@cis.asu.edu.eg>
Date: Thu, 1 Jan 2026 01:49:01 +0000
Subject: [PATCH] docs: add section on combining short options

Add documentation explaining the standard POSIX behavior of combining
short options (e.g., -abc is equivalent to -a -b -c). This section
includes:

- Explanation of short option combining with examples
- Example showing value attachment to combined options
- Note clarifying that multi-character short options are not supported

Closes #2779

---
Ahmed Adel Bakr Alderai
---
 CHANGES.rst     |  2 ++
 docs/options.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/CHANGES.rst b/CHANGES.rst
index 774d59674..755d9eec8 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -2,6 +2,8 @@
 
 Unreleased
 
+-   Document short option combining behavior and clarify that multi-character
+    short options are not supported. :issue:`2779`
 -   Fix handling of ``flag_value`` when ``is_flag=False`` to allow such options to be
     used without an explicit value. :issue:`3084`
 
diff --git a/docs/options.md b/docs/options.md
index 46dccd47e..0df7fce83 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -212,6 +212,54 @@ The multiple options format allows options to take an arbitrary number of argume
     invoke(commit, args=['-m', 'foo', '-m', 'bar', '-m', 'here'])
 ```
 
+## Combining Short Options
+
+Short options that consist of a single character can be combined into a
+single argument. For example, `-a -b -c` can be written as `-abc`. This
+is standard POSIX behavior and applies to any short options, including
+flags and options that take values.
+
+```{eval-rst}
+.. click:example::
+
+    @click.command()
+    @click.option('-a', is_flag=True)
+    @click.option('-b', is_flag=True)
+    @click.option('-c', is_flag=True)
+    def flags(a, b, c):
+        click.echo(f"a={a} b={b} c={c}")
+
+.. click:run::
+
+    invoke(flags, args=['-a', '-b', '-c'])
+    invoke(flags, args=['-abc'])
+```
+
+When combining options, the last option in the combination can take a
+value. The value can be attached directly or passed as the next argument.
+
+```{eval-rst}
+.. click:example::
+
+    @click.command()
+    @click.option('-v', is_flag=True)
+    @click.option('-n', type=int)
+    def example(v, n):
+        click.echo(f"v={v} n={n}")
+
+.. click:run::
+
+    invoke(example, args=['-vn', '5'])
+    invoke(example, args=['-vn5'])
+```
+
+```{note}
+Multi-character short options are not supported. An argument like `-abc`
+is always interpreted as the combination of `-a`, `-b`, and `-c`, not as
+a single option named `-abc`. If you need longer option names, use long
+options with `--` prefix instead (e.g., `--abc`).
+```
+
 ## Counting
 
 To count the occurrence of an option pass in `count=True`. If the option is not passed in, then the count is 0. Counting is commonly used for verbosity.