docs: add section on combining short options #3179
Open
+50
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 pallets#2779 --- Ahmed Adel Bakr Alderai
Rowlando13
reviewed
Jan 1, 2026
|
|
||
| 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 |
Collaborator
There was a problem hiding this comment.
change to single short option
Rowlando13
reviewed
Jan 1, 2026
|
|
||
| ```{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 |
Rowlando13
reviewed
Jan 1, 2026
| 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`). | ||
| ``` |
Collaborator
There was a problem hiding this comment.
should read: with the -- prefix
Collaborator
|
Great pr, with a few minor things to fix! Also please rebase onto stable. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds documentation for short option combining behavior, as requested in #2779.
Changes
New "Combining Short Options" section in
docs/options.md:-abc=-a -b -c)Changelog entry added to
CHANGES.rstPer maintainer request
Following @Rowlando13's guidance in the issue:
Closes #2779
Ahmed Adel Bakr Alderai