man cp doesn’t document the -R option

[LucasLarson]

The manpage for cp/ucp shows the --recursive and -r options for recursive copying, but does not mention -R. All of the following work exactly as expected after running rm -rf directory elsewhere && mkdir directory:

$ "$(brew --prefix uutils-coreutils)"/libexec/uubin/cp -r          directory elsewhere
$                                                  ucp -r          directory elsewhere


$                                                  ucp --recursive directory elsewhere
$ "$(brew --prefix uutils-coreutils)"/libexec/uubin/cp --recursive directory elsewhere


$ "$(brew --prefix uutils-coreutils)"/libexec/uubin/cp -R          directory elsewhere
$                                                  ucp -R          directory elsewhere

but the last two lines use -R, which is undocumented in the manpage, and is the only POSIX-guaranteed option for recursive copying.

[BenWiederhake]

I'm not entirely sure what you mean?

$ cargo run cp --help
<SNIPPED some unrelated lines>
  -n, --no-clobber                           don't overwrite a file that already exists
  -r, --recursive                            copy directories recursively [short aliases: R]
      --strip-trailing-slashes               remove any trailing slashes from each SOURCE argument
<SNIPPED more unrelated lines>

So it is documented, it clearly says short aliases: R.

I agree that it could look nicer. That could be improved by switching to uutils-args, because I don't expect that clap will change their format.

[LucasLarson]

it is documented

I did not carefully read the longer description in the right column because I’ve never seen what I was looking for only in the description. I’ve only ever seen options listed as syntax in the lefthand column and perhaps mentioned again in their descriptions. But because this does not match GNU’s man cp, which since 2002, has said the following,

-R, -r, --recursive          copy directories recursively

this issue might be a bug, and might be related to #2138 and #2150.

it clearly says short aliases: R

Yes, but neither short aliases: R nor [short aliases: R] in the description column of a manpage makes it unambiguously clear what we’re discussing. Because it, too, does not mention -R with the hyphen, it was not clear to me yesterday that short aliases referred to this; I haven’t read uutils’s manpages, “[short aliases: R]” does not, on my first glance, look like it means cp -R. Moreover, it does look like it could mean the useless cp R.

That could be improved by switching to uutils-args

Is that what allows no more than two .short options listed?

[BenWiederhake]

The formatting as [short aliases: R] is done by clap, so there's not much that uutils can do.

If/when we switch to uutils-args, then we'll be able to fully control the output. I agree that [short aliases: R] looks weird, so please do implement it there, if it doesn't already exist.

[tertsdiepraam]

I'll add on some of my thoughts.

• I agree it's not super clear and I'd love for clap to improve this.
• Switching to uutils-args will indeed improve this issue.
• I don't consider this a bug because the help text is in my opinion not part of the compatibility. Again though, I agree this should still change.
• It's fine with me to reopen this while we discuss with the clap people.
• A tiny improvement in the meantime could be to switch -R and -r to -r being the alias because -R is the POSIX flag.

[tertsdiepraam]

I opened clap-rs/clap#5454

I've reopened this to keep track here as well. We can still close this anytime.