Redundant help and version options in man page

scriptingosx · July 30, 2025, 8:54am

When generating a man page with the generate-manual plug-in, the top-level --help and --version options get repeated for every subcommand.

This might make sense for the --help display and the completion output, but in the man page, it is very redundant and distracting.

Is there some way to avoid this?

Example, from my utiluti tool:

UTILUTI(1)                  General Commands Manual                 UTILUTI(1)

NAME
     utiluti – Read and set default URL scheme and file type handlers.

SYNOPSIS
     utiluti subcommand [--version] [--help]

DESCRIPTION
     --version
             Show the version.

     -h, --help
             Show help information.

     url     Manipulate default URL scheme handlers

             --version
                     Show the version.

             -h, --help
                     Show help information.

             get     Get the path to the default application.

                     scheme  the url scheme, e.g. 'http' or 'mailto'

                     --bundle-id
                             list bundle identifiers instead of paths

                     --version
                             Show the version.

                     -h, --help
                             Show help information.

             list    List all applications that can handle this URL scheme.

                     scheme  the url scheme, e.g. 'http' or 'mailto'

                     --bundle-id
                             list bundle identifiers instead of paths

                     --version
                             Show the version.

                     -h, --help
                             Show help information.

             set     Set the default app for this URL scheme.

                     scheme  the url scheme, e.g. 'http' or 'mailto'

                     bundleID
                             bundle identifier for the app

                     --version
                             Show the version.

rauhul · July 30, 2025, 7:56pm

Could you open a GitHub issue for this bug? Hopefully it's something simple to fix. Though I suspect we will need to update the ToolInfo structure with a notion of built-in flags

scriptingosx · August 1, 2025, 7:11am

github.com/apple/swift-argument-parser

Redundant help and version options in generated man page

opened 07:10AM - 01 Aug 25 UTC

scriptingosx

When generating a man page with the `generate-manual` plug-in, the top-level --h…elp and --version options get repeated for every subcommand. This might make sense for the --help display and the completion output, but in the man page, it is very redundant and distracting. Example, from [my utiluti tool](https://github.com/scriptingosx/utiluti): ``` UTILUTI(1) General Commands Manual UTILUTI(1) NAME utiluti – Read and set default URL scheme and file type handlers. SYNOPSIS utiluti subcommand [--version] [--help] DESCRIPTION --version Show the version. -h, --help Show help information. url Manipulate default URL scheme handlers --version Show the version. -h, --help Show help information. get Get the path to the default application. scheme the url scheme, e.g. 'http' or 'mailto' --bundle-id list bundle identifiers instead of paths --version Show the version. -h, --help Show help information. list List all applications that can handle this URL scheme. scheme the url scheme, e.g. 'http' or 'mailto' --bundle-id list bundle identifiers instead of paths --version Show the version. -h, --help Show help information. set Set the default app for this URL scheme. scheme the url scheme, e.g. 'http' or 'mailto' bundleID bundle identifier for the app --version Show the version. ``` **ArgumentParser version:** `1.6.1` **Swift version:** ``` swift-driver version: 1.120.5 Apple Swift version 6.1.2 (swiftlang-6.1.2.1.2 clang-1700.0.13.5) Target: arm64-apple-macosx15.0 ``` ### Checklist - [x] If possible, I've reproduced the issue using the `main` branch of this package - [x] I've searched for [existing GitHub issues](https://github.com/apple/swift-argument-parser/issues) ### Steps to Reproduce - Create a ParsableCommand with subcommands and a version. - use generate-manual plugin - view the generated man page with ``` man -M .build/plugins/GenerateManual/outputs/<commandName>/: <commandName> ``` ### Expected behavior The `--version` and `-h, --help` options should be shown once, at the top level and _not_ be repeated for every subcommand. At least there should be a way to mark them as global, so they are not repeated. ### Actual behavior The `--version` and `-h, --help` options are repeated for every sub level.