There are numerous completion problems: some only for certain shells, some for specific CompletionKinds for certain shells, and some that are only for arguments but not for option values.

bash

• Offers candidates for all positional arguments regardless of current argument position
• Repeatedly offers singular options instead of just once
• Offers flags & options after --
• directory not implemented for arguments
• file not implemented for arguments
• directory & file(…) for option values moves to next parameter after selecting the first item, even if you've submitted a directory, instead of allowing you to request candidates from within the selected directories. If you move back to the parameter & append a /, tabbing will then offer properly filtered candidates.

There might not be a way in bash 3.2.57, or even in later bashes, to improve the following:

• outputs to stdout, then opens a new prompt rather than interactive output below command line

fish

• Offers candidates for all positional arguments regardless of current argument position
• Doesn't offer flags or options unless you type a leading -
• Repeatedly offers singular options instead of just once
• Repeats parameter help text for each candidate
• file() offers no candidates when no extensions were specified
• file(extensions:) doesn't offer directories

zsh

• shellCommand does not offer any candidates

There aren't necessarily bugs, they are just potentially suboptimal setups / aren't properly documented in the docs or code:

• If the user hasn't already typed a leading -, doesn't offer flags or options if there are unsupplied positional arguments
• file(extension:) if existing part of the completing parameter is a path to a leaf directory, and if no non-hidden files in that directory match any of the given extensions, then all non-hidden files in that directory are offered as candidates, regardless of their respective extensions. Is that intended? If so, it should be documented.

all

The following @Option doesn't offer true & false. Using a @Flag would probably be better, but if a developer wants to use a Bool @Option, the completion scripts should probably offer true & false without additional setup being required.

@Option(help: "Case Sensitive")
var caseSensitive: Bool

Documentation

The CompletionKind / CompletionKind.Kind documentation is also sometimes wrong or confusing, so I will update that along with the associated code.

PR

I will work on a PR to fix these problems. If I find additional problems, I'll add them to this issue.

Related Issues

• CompletionKind should support multiple options #566: My PR will fix the problems mentioned, but won't implement the proposed solution.
• Add completion for default subcommand to supercommand #488: My PR won't add support for this.
• Custom fish completions do not work #376: It looks like this has already been fixed, but if it somehow resurfaces, I'll fix it.

Versions

ArgumentParser version:
main branch

Swift version:

swift-driver version: 1.62.15 Apple Swift version 5.7.2 (swiftlang-5.7.2.135.5 clang-1400.0.29.51)
Target: x86_64-apple-macosx12.0

Checklist

• If possible, I've reproduced the issue using the main branch of this package
• I've searched for existing GitHub issues

Steps to Reproduce

Generate completion scripts using the aforementioned CompletionKinds.

Try to use them.

Expected behavior

Completion works.

Actual behavior

Some completion either does nothing, or outputs an error.

See per-shell sections above for details.