-
Notifications
You must be signed in to change notification settings - Fork 484
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Spell out "Install from Git repository" options properly #578
base: main
Are you sure you want to change the base?
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
Run & review this pull request in StackBlitz Codeflow. |
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO important to know the default here.
URL
likesemver:
andpath:
.Fixes: #577