yarn cli help "Usage" lines are wildly inconsistent

[dsifford]

Do you want to request a feature or report a bug? Little bit of both

What is the current behavior?

Hi there,

I'm the maintainer of a fairly popular bash completion repo for yarn.I'm in the process of writing some scripts to automate the process and test the output and, in my process of doing so, I noticed that there is a fairly widespread discrepancy in how the yarn commands are documented in the cli.

access              Usage: yarn [command] [flags]
add                 Usage: yarn add [packages ...] [flags]
autoclean           Usage: yarn autoclean [flags]
bin                 Usage: yarn [command] [flags]
*cache              Usage: yarn cache [ls|list|clean|dir] [flags]
check               Usage: yarn [command] [flags]
config              Usage: yarn [command] [flags]
create              Usage: yarn [command] [flags]
exec                Usage: yarn [command] [flags]
generate-lock-entry Usage: yarn [command] [flags]
*global             Usage: yarn global [add|bin|dir|ls|list|remove|upgrade|upgrade-interactive] [flags]
help                Usage: yarn [command] [flags]
import              Usage: yarn [command] [flags]
info                Usage: yarn [command] [flags]
init                Usage: yarn [command] [flags]
install             Usage: yarn install [flags]
licenses            Usage: yarn [command] [flags]
link                Usage: yarn [command] [flags]
list                Usage: yarn [command] [flags]
login               Usage: yarn [command] [flags]
logout              Usage: yarn [command] [flags]
node                Usage: yarn [command] [flags]
outdated            Usage: yarn outdated [packages ...]
owner               Usage: yarn [command] [flags]
pack                Usage: yarn [command] [flags]
**publish           Usage: yarn publish [<tarball>|<folder>] [--tag <tag>] [--access <public|restricted>]
remove              Usage: yarn remove [packages ...] [flags]
run                 Usage: yarn [command] [flags]
tag                 Usage: yarn [command] [flags]
team                Usage: yarn [command] [flags]
unlink              Usage: yarn [command] [flags]
upgrade             Usage: yarn upgrade [flags]
upgrade-interactive Usage: yarn upgrade-interactive [flags]
version             Usage: yarn [command] [flags]
versions            Usage: yarn [command] [flags]
why                 Usage: yarn [command] [flags]
workspace           Usage: yarn [command] [flags]
workspaces          Usage: yarn workspaces [info] [flags]
---------
 *: Correct usage.
**: Technically correct usage, though difficult to parse in scripts and could be simplified.

It appears as though yarn is sort of attempting to stick to docopt standards, but there are quite a few notable flaws.

1. [command] implies that there is an optional first-level command literally called command. This should instead be the literal name of the first-level command, without the brackets.
2. [flags] implies that there is an optional second-level command literally called flags. The actual shorthand for this should be precisely [options] (this actually agrees better with the cli anyway since you don't call flags "flags", you call them "options").
3. [packages ...] implies that you have an optional command literally called packages that can be repeated one or more times. It should instead be [<package>...].

What is the expected behavior?

I would recommend tailoring all of the usage statements to follow the docopt standard, similarly to how the commands marked * are above.

I would be happy to help contribute these changes when time allows with your blessing.

Please mention your node.js, yarn and operating system version.

Node: v10.10.0
Yarn: v1.9.4
OS: Linux archlinux 4.18.6-arch1-1-ARCH #1 SMP PREEMPT Wed Sep 5 11:54:09 UTC 2018 x86_64 GNU/Linux

---

Thanks for considering!

[dsifford]

Further, yarn help autoclean produces two options with the same name, but different descriptions....

  Usage: yarn autoclean [flags]

  Cleans and removes unnecessary files from package dependencies.

  Options:
  [ ..... ]
    --force                             install and build packages even if they were built before, overwrite lockfile
  [ ..... ]
    -F, --force                         Run autoclean using the existing ".yarnclean" file.

  Visit https://yarnpkg.com/en/docs/cli/autoclean for documentation about this command.

[dsifford]

Further still, it appears that the documentation is just plainly not complete for yarn help generate-lock-entry. Looks like maybe a placeholder slipped through the cracks....

  [ ..... ]
    --use-manifest <location>           description
    --resolved <resolved>               description
    --registry <registry>               description

Edit: Also, the option registry is listed twice.

  [ ..... ]
    --registry <url>                    override configuration registry
  [ ..... ]
    --registry <registry>               description

[dsifford]

Further, further still... yarn help global for whatever reason produces the --latest flag at the global level, not the upgrade level where I'd assume it would belong.

  [ ..... ]
    --prefix <prefix>                   bin prefix to use to install binaries
    --latest                            upgrade to the latest version of packages
  [ ..... ]

[dsifford]

Thoughts on this @arcanis? Obviously this would be low on the priority list for the team in general, but if it's something that you and the rest feel is something that should be addressed, I can work on a PR.

This specifically is holding back any progress on completion automation due to the issues described above causing test failures.

[arcanis]

Overall I'm not super satisfied with the state of the command line - we have an open issue to revamp it, but it's still waiting for someone to take the lead.

[dsifford]

@arcanis I like it. I'm definitely on board to help out.

[dsifford]

(I didn't forget about this.. Working on getting an update out over the next few days on the bash completions first then I'll jump in and get a PR going for this) -- I'll get the PR opened with minimal progress and tag you in it @arcanis just so I can be sure that the work I'm doing stays within the scope of your vision.

[paul-soporan]

Closing as all CLI help pages have been revamped in the v2 because we use a different CLI framework.

https://yarnpkg.com/getting-started/migration