docs: Spell out "Install from Git repository" options properly #578
Conversation
- Create sections to make visual/logical distinction of individual parts. - Spell out all major possible syntaxes. - Add more explanation to individual parts of the `URL` like `semver:` and `path:`. - Copy & paste examples directly from [tests](https://github.com/pnpm/pnpm/blob/main/resolving/git-resolver/test/index.ts) so that we're reasonably sure they are correct. - Explain defaults. - Explain common cases like monorepo & forks. Fixes: pnpm#577
|
|
|
@MichalBryxi is attempting to deploy a commit to the pnpm Team on Vercel. A member of the Team first needs to authorize it. |
|
Happy to talk about any and all choices and alter things if necessary, but I firmly believe that this amount of verboseness greatly reduces user confusion as they don't have to guess what is possible / why / how. |
| ``` | ||
| pnpm add github:zkochan/is-negative | ||
| pnpm add bitbucket:pnpmjs/git-resolver | ||
| pnpm add gitlab:pnpm/git-resolver |
There was a problem hiding this comment.
Is there more? I found only those in tests.
| * commit: `pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678` | ||
| * branch: `pnpm add kevva/is-positive#master` | ||
| * version range: `pnpm add kevva/is-positive#semver:^2.0.0` | ||
| ``` |
There was a problem hiding this comment.
Personally I prefer these triple-fenced examples, as they are way easier to target with a mouse for copy&pasting as you're constrained by the newlines. As opposed to the bullet point format above, which allows for copying the non-code prefix as well.
|
|
||
| You may also install just a subdirectory from a Git-hosted monorepo. For instance: | ||
| You can specify version (range) to install using the `semver:` parameter. For example: |
There was a problem hiding this comment.
I consider the semver: and path: (below) being explicitly spelled out very important. It makes sure that the user knows it's a keyword and not just a random thing in given repo.
| * branch: `pnpm add kevva/is-positive#master` | ||
| * version range: `pnpm add kevva/is-positive#semver:^2.0.0` | ||
| ``` | ||
| # latest commit from default branch |
There was a problem hiding this comment.
As far as I can tell pnpm does not look for master per-se, it looks for (in GitHub terminology) default branch, hence the naming change here.
| pnpm add gitlab:pnpm/git-resolver | ||
| ``` | ||
|
|
||
| If `[provider]:` is omited, it defaults to `github:`. |
There was a problem hiding this comment.
IMO important to know the default here.
URLlikesemver:andpath:.Fixes: #577