Skip to content
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.

Sign up for GitHub

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

Jump to bottom

docs: Spell out "Install from Git repository" options properly #578

Closed
wants to merge 5 commits into from
Closed

docs: Spell out "Install from Git repository" options properly #578

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b703439
docs: Spell out "Install from Git repository" options properly
MichalBryxi Sep 16, 2024
13ea955
docs: Revert code fencing change
MichalBryxi Oct 4, 2024
7c1d336
docs: Git should be capitalized
MichalBryxi Oct 4, 2024
b65ca43
docs: Code sections inside bullet points
MichalBryxi Oct 4, 2024
eede7c1
docs: Code sections inside bullet points v2
MichalBryxi Oct 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 84 additions & 11 deletions docs/cli/add.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,26 +81,99 @@ pnpm add <git remote url>
```

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:
```
Copy link
Author

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you can have both. code sections inside bullet points. I don't think there's a reason to move the descriptions into the code blocks.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No hard feelings, I can revert it, but to show why I'm against copy&paste examples in inline form: Here you can see how precise I have to be to select exactly what I intended:

2024-10-04 11 08 36

Compare it to the code-fence version that has the full line for mousing around and thus it's way harder to select unwanted things:

2024-10-04 11 10 59

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I pushed the revert to adhere to the ways it was. Let me know if it works for you now.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But you could do it like this:

* Strict semver:
  
  `` `
  pnpm add zkochan/is-negative#semver:1.0.0
  `` `

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oooh, yeah why not. Pushed given change for both blocks. Also I used "Sentence case:" for the bullet points. Let me know if this works for you.

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

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:
Copy link
Author

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.


* 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
```
pnpm add myorg/repo#path:packages/foo
* 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
Copy link
Author

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.

```

If `[provider]:` is omited, it defaults to `github:`.
Copy link
Author

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.


#### 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
Expand Down