Yarn: Improve `yarn -h`

Created on 13 Oct 2016 · 9Comments · Source: yarnpkg/yarn

Do you want to request a _feature_ or report a _bug_?

Feature

What is the current behavior?

# yarn -h
  Usage: yarn install [flags]

  Options:

    -h, --help                  output usage information
    -V, --version               output the version number
    --offline                   
    --prefer-offline            
    --strict-semver             
    --json                      
    --global-folder [path]      
    --modules-folder [path]     rather than installing modules into the node_modules folder relative to the cwd, output them here
    --packages-root [path]      rather than storing modules into a global packages root, store them here
    --mutex [type][:specifier]  use a mutex to ensure only one yarn instance is executing
    --har                       save HAR output of network traffic
    --ignore-engines            ignore engines check
    --ignore-scripts            
    --ignore-optional           
    --force                     
    --flat                      only allow one version of a package
    --prod, --production        
    --no-lockfile               don't read or generate a lockfile
    --pure-lockfile             don't generate a lockfile
    -g, --global                DEPRECATED
    -S, --save                  DEPRECATED - save package to your `dependencies`
    -D, --save-dev              DEPRECATED - save package to your `devDependencies`
    -P, --save-peer             DEPRECATED - save package to your `peerDependencies`
    -O, --save-optional         DEPRECATED - save package to your `optionalDependencies`
    -E, --save-exact            DEPRECATED
    -T, --save-tilde            DEPRECATED

What is the expected behavior?

I would like it to print enough to teach me how to use yarn. With the above output, I don't know what the top-level commands are besides install. When I do yarn install -h, the output is the same. I expect #407 would help with some of this if/when it happens.

Also, I assume Usage: yarn install [flags] is incomplete – it doesn't cover eg yarn install a-single-packagename (eg Usage: yarn install <packagename>. I think flags are always implied.)

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

node v5.4.1
yarn install v0.15.1
Sierra 10.12

cat-feature

Source

lorensr

👍11

Most helpful comment

The feature already exists, but is a bit hidden. To get the information you require, you have to use yarn help - i.e. call yarn with the help command.

I would argue that this is a bug in the way commands are parsed. yarn by itself is translated to yarn install. yarn -h and yarn --help are translated to yarn install --help, and give help only for installing.

In my opinion, any command followed by --help or -h should print the basic information. It is not safe to call a random command with just help as the argument, as this could mean something like open a file called "help". It would be fine if yarn --help just told you something like "Usage: yarn [command]; for a list of commands run yarn help", but yarn --help should be the root point of discovery.

rjmunro on 14 Oct 2016

👍5

All 9 comments

Also it shows Usage: yarn install [flags] which throws an installCommandRenamed error because correct usage is yarn add.

petetnt on 13 Oct 2016

The feature already exists, but is a bit hidden. To get the information you require, you have to use yarn help - i.e. call yarn with the help command.

rjmunro on 14 Oct 2016

👍5

Yep, definitely confusing. Developers instinctively first try app --help or man app.

app --help is supposed to be synonymous with app -h and app help, so this is definitely a user-experience bug.

sheharyarn on 17 Oct 2016

+1. yarn help is very confusing. It's common to try yarn & yarn -h & yarn --help. For commands - yarn <command> -h & yarn <command> --help.

Also, IMHO, it's seems better to show full commands list on the first help screen. Please, do yarn CLI behaviour more common. Good example - git.

PS. yarn is cool, thanks for your work!

puzrin on 17 Oct 2016

This is a near dupe of #740, fixed in #765.

rjmunro on 17 Oct 2016

@rjmunro may be it still worth to make commands help work via yarn <command> -h but that's less critical. Probably it worth to create one common issue "make help work right". Current pending things i see are:

notation for command help.
missed descriptions for some options.

After #765 things are not so horrible - at least it's possible to understand cli output and what to type next.

puzrin on 17 Oct 2016

None of commands even have descriptions of what they do in their help pages, just a usage format and a link directing you to the website.

Twipped on 17 Oct 2016

As @rjmunro mentioned, this is no longer an issue in the latest yarn. Running yarn -h and yarn help give the same output, including a list of available commands in the CLI. Adding more detail to each yarn help <Command> seems like a different issue and should probably be it's own ticket.