docs: Update core.md with clear explanation on reshim #1787
Conversation
|
Hey! This LGTM, but i'm not a maintainer and I'm no longer contributing to this project |
|
@hyperupcall Oh, I see. Thank you!! |
|
@Stratus3D Hi! Could you kindly review it when you have the chance? Thank you in advance for your time and feedback. |
| @@ -38,7 +38,21 @@ A helper command to print the OS, Shell and `asdf` debug information. Share this | |||
| asdf reshim <name> <version> | |||
| ``` | |||
|
|
|||
| This recreates the shims for the current version of a package. By default, shims are created by plugins during installation of a tool. Some tools like the [npm CLI](https://docs.npmjs.com/cli/) allow global installation of executables, for example, installing [Yarn](https://yarnpkg.com/) via `npm install -g yarn`. Since this executable was not installed via the plugin lifecycle, no shim exists for it yet. `asdf reshim nodejs <version>` will force recalculation of shims for any new executables, like `yarn`, for `<version>` of `nodejs` . | |||
| This recreates the shims for the current version of a package. By default, shims are created by `asdf` plugins during the installation of a tool. However, when using package managers like `yarn` or `pnpm` to globally install executables (for example, installing [serve](https://github.com/vercel/serve) via `yarn add global serve`), these packages are not installed during the asdf plugin lifecycle. As a result, shims for these executables are not automatically created. | |||
There was a problem hiding this comment.
The problem with this (and the existing text) is that asdf is a generic version manager. Not everyone using asdf will know what yarn and npm are, as they don't use Node.JS. I understand the behavior may be confusing to newcomers, but I'm think the references to Node.JS package managers may make this more confusing for most new users.
There was a problem hiding this comment.
Thank you for the review! Yes, I agree! But as you know, the original example explanation for reshim was about node and npm, and it was not accurate, so I edited this part to make it clearer.
Also, in order to explain reshim, there should be a case where the asdf plugin lifecycle and other package managers exist, but I can't think of any except this case. Do you have any other good examples?
Summary
Hi! For asdf beginners, reshim is a bit of a difficult concept at first, so it would be good to have a little more detailed explanation.
npmis usually installed by default when installing a node plugin, and according to the current example, when we donpm install -g yarn, npm itself is included in the asdf plugin lifecycle, so asdf will automatically create a shim foryarn.For a clear explanation, I changed the docs for reshim to use yarn and pnpm instead of node's package manager npm.
@hyperupcall @jthegedus Could you review it?
Other Information
I'm participating in Hacktoberfest 2024, if the PR makes sense right now, could you add "hacktoberfest-accepted" label? Thanks!
https://hacktoberfest.com/participation/#:~:text=%5Baccepted%5D%20Your%20PR/MRs%20must%20be%20merged%2C%20have%20the%20%E2%80%9Chacktoberfest%2Daccepted%E2%80%9D%20label%2C%20or%20have%20an%20overall%20approving%20review.