From b7034392c5915f71f82712f8938c94f95e67d463 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Bryxi=CC=81?= Date: Mon, 16 Sep 2024 12:40:57 +0200 Subject: [PATCH 1/5] docs: Spell out "Install from Git repository" options properly - 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: #577 --- docs/cli/add.md | 83 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 72 insertions(+), 11 deletions(-) diff --git a/docs/cli/add.md b/docs/cli/add.md index ea96d21cc275..f6399ec1a34d 100644 --- a/docs/cli/add.md +++ b/docs/cli/add.md @@ -81,26 +81,87 @@ pnpm add ``` Installs the package from the hosted Git provider, cloning it with Git. -You can use a protocol for certain Git providers. For example, -`pnpm add github:user/repo` -You may install from Git by: +You may install packages from Git by: -* latest commit from master: `pnpm add kevva/is-positive` -* 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` +``` +# latest commit from default branch +pnpm add kevva/is-positive + +# git commit hash +pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678 + +# git branch +pnpm add kevva/is-positive#master + +# git branch relative to refs +pnpm add zkochan/is-negative#heads/canary + +# git tag +pnpm add zkochan/is-negative#2.0.1 + +# v-prefixed git tag +pnpm add andreineculau/npm-publish-git#v0.0. +``` + +### Semver -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: ``` -pnpm add myorg/repo#path:packages/foo +# strict semver +pnpm add zkochan/is-negative#semver:1.0.0 + +# v-prefixed strict semver +pnpm add andreineculau/npm-publish-git#semver:v0.0.7 + +# semver version range +pnpm add kevva/is-positive#semver:^2.0.0 + +# v-prefixed semver version range +pnpm add andreineculau/npm-publish-git#semver:<=v0.0.7 +``` + +#### Subdirectory + +You may also install just a subdirectory from a Git-hosted monorepo using the `path:` parameter. For instance: + ``` +pnpm add RexSkz/test-git-subfolder-fetch#path:/packages/simple-react-app +``` + +#### Full URL + +If you want to be more explicit or are using alternative git hosting, you might want to spell out full git URL: + +``` +# git+ssh +pnpm add git+ssh://git@github.com:zkochan/is-negative.git#2.0.1 + +# https +pnpm add https://github.com/zkochan/is-negative.git#2.0.1 +``` + +#### Providers shorthand + +You can use a protocol shorthand `[provier]:` for certain Git providers: + +``` +pnpm add github:zkochan/is-negative +pnpm add bitbucket:pnpmjs/git-resolver +pnpm add gitlab:pnpm/git-resolver +``` + +If `[provider]:` is omited, it defaults to `github:`. + +#### Parameters combination -It is possible to combine multiple parameters by separating them with `&`. For instance, you can extend the above command by specifying which branch to fetch from: +It is possible to combine multiple parameters by separating them with `&`. This can be useful for forks of monorepos: ``` -pnpm add myorg/repo#path:packages/foo&next +# Install git branch `beta` +# Install only subfolder `/packages/simple-react-app` +pnpm add RexSkz/test-git-subfolder-fetch.git#beta&path:/packages/simple-react-app ``` ## Options From 13ea955665e4cb09d0139796c8cf91f2d62f5fa5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Bryxi=CC=81?= Date: Fri, 4 Oct 2024 11:20:13 +0200 Subject: [PATCH 2/5] docs: Revert code fencing change - Adhere to current way of bullet pointed examples --- docs/cli/add.md | 26 +++++++------------------- 1 file changed, 7 insertions(+), 19 deletions(-) diff --git a/docs/cli/add.md b/docs/cli/add.md index f6399ec1a34d..5aed90b87ed3 100644 --- a/docs/cli/add.md +++ b/docs/cli/add.md @@ -84,25 +84,13 @@ Installs the package from the hosted Git provider, cloning it with Git. You may install packages from Git by: -``` -# latest commit from default branch -pnpm add kevva/is-positive - -# git commit hash -pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678 - -# git branch -pnpm add kevva/is-positive#master - -# git branch relative to refs -pnpm add zkochan/is-negative#heads/canary - -# git tag -pnpm add zkochan/is-negative#2.0.1 - -# v-prefixed git tag -pnpm add andreineculau/npm-publish-git#v0.0. -``` +* latest commit from default branch: `pnpm add kevva/is-positive` +* git commit hash: `pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678` +* git branch: `pnpm add kevva/is-positive#master` +* git branch relative to refs: `pnpm add zkochan/is-negative#heads/canary` +* git tag: `pnpm add zkochan/is-negative#2.0.1` +* v-prefixed git tag: `pnpm add andreineculau/npm-publish-git#v0.0.7` +* version range: `pnpm add kevva/is-positive#semver:^2.0.0` ### Semver From 7c1d336bff2b8b938e062ecb4e2793dfe7d68ff0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Bryxi=CC=81?= Date: Fri, 4 Oct 2024 11:21:25 +0200 Subject: [PATCH 3/5] docs: Git should be capitalized --- docs/cli/add.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli/add.md b/docs/cli/add.md index 5aed90b87ed3..34bf2952a690 100644 --- a/docs/cli/add.md +++ b/docs/cli/add.md @@ -120,7 +120,7 @@ pnpm add RexSkz/test-git-subfolder-fetch#path:/packages/simple-react-app #### Full URL -If you want to be more explicit or are using alternative git hosting, you might want to spell out full git URL: +If you want to be more explicit or are using alternative Git hosting, you might want to spell out full Git URL: ``` # git+ssh From b65ca433d83f52b5dd64e99f1d1abe54c2b6fc25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Bryxi=CC=81?= Date: Fri, 4 Oct 2024 18:04:02 +0200 Subject: [PATCH 4/5] docs: Code sections inside bullet points - That and making the bullets sentence-case --- docs/cli/add.md | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/docs/cli/add.md b/docs/cli/add.md index 34bf2952a690..3132491972ee 100644 --- a/docs/cli/add.md +++ b/docs/cli/add.md @@ -84,13 +84,34 @@ Installs the package from the hosted Git provider, cloning it with Git. You may install packages from Git by: -* latest commit from default branch: `pnpm add kevva/is-positive` -* git commit hash: `pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678` -* git branch: `pnpm add kevva/is-positive#master` -* git branch relative to refs: `pnpm add zkochan/is-negative#heads/canary` -* git tag: `pnpm add zkochan/is-negative#2.0.1` -* v-prefixed git tag: `pnpm add andreineculau/npm-publish-git#v0.0.7` -* version range: `pnpm add kevva/is-positive#semver:^2.0.0` +* Latest commit from default branch: +``` +pnpm add kevva/is-positive +``` +* Git commit hash: +``` +pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678 +``` +* Git branch: +``` +pnpm add kevva/is-positive#master +``` +* Git branch relative to refs: +``` +pnpm add zkochan/is-negative#heads/canary +``` +* Git tag: +``` +pnpm add zkochan/is-negative#2.0.1 +``` +* V-prefixed Git tag: +``` +pnpm add andreineculau/npm-publish-git#v0.0.7 +``` +* Version range: +``` +pnpm add kevva/is-positive#semver:^2.0.0 +``` ### Semver From eede7c1ed8dc33f7d3ccb16d7cb119a36374be56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Bryxi=CC=81?= Date: Fri, 4 Oct 2024 18:06:32 +0200 Subject: [PATCH 5/5] docs: Code sections inside bullet points v2 - That and making the bullets sentence-case --- docs/cli/add.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/cli/add.md b/docs/cli/add.md index 3132491972ee..d283db98dd59 100644 --- a/docs/cli/add.md +++ b/docs/cli/add.md @@ -117,17 +117,20 @@ pnpm add kevva/is-positive#semver:^2.0.0 You can specify version (range) to install using the `semver:` parameter. For example: +* Strict semver: ``` -# strict semver pnpm add zkochan/is-negative#semver:1.0.0 - -# v-prefixed strict semver +``` +* V-prefixed strict semver: +``` pnpm add andreineculau/npm-publish-git#semver:v0.0.7 - -# semver version range +``` +* Semver version range: +``` pnpm add kevva/is-positive#semver:^2.0.0 - -# v-prefixed semver version range +``` +* V-prefixed semver version range: +``` pnpm add andreineculau/npm-publish-git#semver:<=v0.0.7 ```