Missing documentation for `lerna link convert` on link page

This was discussed in https://github.com/lerna/lerna/issues/1788 and many people made similar requests, but that issue was closed due to an unrelated quirk in the original asker’s particular scenario.

Expected Behavior

I expected the convert option for lerna link to be documented on the link page https://github.com/lerna/lerna/tree/master/commands/link#readme where other options for the lerna link command are documented, stating plainly exactly whatlerna link convert does and what its expected usage is.

Current Behavior

There is no documentation for lerna link convert on that page. I had thought that maybe it had been deprecated, but in various discussions it appears that it is still considered best practice for hoisting in certain situations.

There is a brief mention of one use case for the command on the main readme, which alludes to one usage, but isn’t clear on exactly what the command will do:

Most devDependencies can be pulled up to the root of a Lerna repo with lerna link convert

The above command will automatically hoist things and use relative file: specifiers.

It’s clear from reading the code that lerna link convert makes a number of changes across a project’s root and packages. It’d be good to be clear on exactly what these are and what the expected side effects or limitations are before running the command.

Possible Solution

Add a short section to https://github.com/lerna/lerna/tree/master/commands/link#readme stating:

• What precisely lerna link convert does: what it adds to the root package.json, what it removes from packages, what else changes
• What its intended usage is: e.g. when this is the preferred way to hoist, when it is not, what other use cases it has if any
• Any known caveats or warnings such as in what cases it shouldn’t be used, or, what known side effects it has (e.g. how it relates to the caveats added in https://github.com/lerna/lerna/pull/1751 )

[rafaeleyng]

Also, how to undo it? I’m in a world of pain right now and thinking it is probably because of some effect of lerna link convert

[alexjoyner]

On the list of things that should be added is to clarify this line from the README

Note that devDependencies providing “binary” executables that are used by npm scripts still need to be installed directly in each package where they’re used.

When I run lerna link convert it seems like lerna just pulls all devDependencies up to the root without any way to specify which of these dependencies need to be left in the package for binary executables. What’s the best practice to make sure these specific dependencies are always installed in their package while also not allowing lerna link convert to pull them up to the root?