git-publish 2.0.0 → 2.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +104 -60
- package/dist/index.js +71 -79
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,120 +1,164 @@
|
|
|
1
1
|
# git-publish
|
|
2
2
|
|
|
3
3
|
Publish your npm package to a Git branch.
|
|
4
|
+
Useful for testing packages in production-like environments before publishing to npm.
|
|
4
5
|
|
|
5
|
-
<
|
|
6
|
+
<br>
|
|
6
7
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
#### Why not use `npm publish` to make a pre-release?
|
|
8
|
+
<p align="center">
|
|
9
|
+
<a href="https://github.com/sponsors/privatenumber/sponsorships?tier_id=398771"><img width="412" src="https://raw.githubusercontent.com/privatenumber/sponsors/master/banners/assets/donate.webp"></a>
|
|
10
|
+
<a href="https://github.com/sponsors/privatenumber/sponsorships?tier_id=416984"><img width="412" src="https://raw.githubusercontent.com/privatenumber/sponsors/master/banners/assets/sponsor.webp"></a>
|
|
11
|
+
</p>
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
- **Versioning concerns:** even though you're just testing, you still need to version bump
|
|
16
|
-
- **Undeleteable:** releases are hard to remove due to npm's [strict unpublish policy](https://docs.npmjs.com/policies/unpublish)
|
|
17
|
-
- **Unverifyable:** npm does not offer a great way to browse the contents of a package
|
|
18
|
-
- **Risky:** Publishing tests to a production environment can be dangerous (eg. accidentally publish as stable)
|
|
13
|
+
## Why?
|
|
19
14
|
|
|
20
|
-
|
|
21
|
-
- No [npm life cycle scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts#life-cycle-scripts)
|
|
22
|
-
- Includes non-publishable assets
|
|
23
|
-
- Doesn't install dependencies
|
|
15
|
+
To test a package without publishing to the npm registry.
|
|
24
16
|
|
|
17
|
+
### Why not use `npm publish`?
|
|
25
18
|
|
|
26
|
-
|
|
19
|
+
Publishing to npm just for testing has major downsides:
|
|
27
20
|
|
|
28
|
-
- **
|
|
21
|
+
- **Versioning overhead:** You must bump the version, even for throwaway builds.
|
|
22
|
+
- **Permanent:** npm's [strict unpublish policy](https://docs.npmjs.com/policies/unpublish) makes removing test releases difficult.
|
|
23
|
+
- **Hard to inspect:** npm doesn't make it easy to view the contents of a published package.
|
|
24
|
+
- **Risky:** You could accidentally publish test code as a stable release.
|
|
29
25
|
|
|
30
|
-
|
|
26
|
+
### Why not use `npm link`?
|
|
31
27
|
|
|
32
|
-
-
|
|
28
|
+
- Skips [npm lifecycle scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts#life-cycle-scripts)
|
|
29
|
+
- Links the entire project (including source, tests, configs)
|
|
30
|
+
- Doesn't install dependencies automatically
|
|
33
31
|
|
|
34
|
-
|
|
32
|
+
### So why `git-publish`?
|
|
35
33
|
|
|
36
|
-
- **
|
|
34
|
+
- **No versioning required:** Uses Git branches instead of package versions.
|
|
35
|
+
- **Easy cleanup:** Delete the branch when you're done.
|
|
36
|
+
- **Browsable:** View and verify the published package on GitHub.
|
|
37
|
+
- **Safe:** Keeps test builds out of npm.
|
|
38
|
+
- **Realistic simulation:** Runs `prepare` and `prepack`, and includes only publishable files.
|
|
37
39
|
|
|
38
40
|
## Usage
|
|
39
41
|
|
|
40
|
-
Publish your npm package to a
|
|
42
|
+
Publish your npm package to a Git branch:
|
|
41
43
|
|
|
42
44
|
```sh
|
|
43
45
|
npx git-publish
|
|
44
46
|
```
|
|
45
47
|
|
|
46
|
-
This
|
|
47
|
-
|
|
48
|
+
This publishes the current package to the branch `npm/<current branch>` on the remote `origin`.
|
|
48
49
|
|
|
49
50
|
### Global install
|
|
50
|
-
Keep the command handy by installing it globally:
|
|
51
51
|
|
|
52
52
|
```sh
|
|
53
53
|
npm install -g git-publish
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
-
|
|
56
|
+
Then run with:
|
|
57
|
+
|
|
57
58
|
```sh
|
|
58
59
|
git-publish
|
|
59
60
|
```
|
|
60
61
|
|
|
61
|
-
### Flags
|
|
62
|
-
|
|
63
|
-
|
|
|
64
|
-
|
|
|
65
|
-
| `-
|
|
66
|
-
| `-
|
|
67
|
-
| `-
|
|
68
|
-
| `-
|
|
69
|
-
|
|
|
62
|
+
### CLI Flags
|
|
63
|
+
|
|
64
|
+
| Flag | Description |
|
|
65
|
+
| ----------------------- | ------------------------------------------------------------- |
|
|
66
|
+
| `-b, --branch <name>` | Target branch name. Defaults to `npm/<current branch or tag>` |
|
|
67
|
+
| `-r, --remote <remote>` | Git remote to push to (default: `origin`) |
|
|
68
|
+
| `-o, --fresh` | Create a fresh single-commit branch. Force-pushes to remote |
|
|
69
|
+
| `-d, --dry` | Simulate the process. Does not commit or push |
|
|
70
|
+
| `-h, --help` | Show CLI help |
|
|
71
|
+
| `--version` | Show CLI version |
|
|
70
72
|
|
|
71
73
|
## FAQ
|
|
72
74
|
|
|
73
|
-
### What are some use
|
|
74
|
-
|
|
75
|
+
### What are some use cases?
|
|
76
|
+
|
|
77
|
+
- Testing a package before it's ready for npm
|
|
78
|
+
- Contributing to a repo where you don't have publish access
|
|
79
|
+
- Testing in a CI/CD or remote environment where `npm link` doesn't work
|
|
80
|
+
- Avoiding symlink issues from `npm link`
|
|
75
81
|
|
|
76
|
-
|
|
82
|
+
### How do I include a build step?
|
|
77
83
|
|
|
78
|
-
|
|
84
|
+
Add your build command to the [`prepack`](https://docs.npmjs.com/cli/v8/using-npm/scripts#prepack) script in `package.json`:
|
|
85
|
+
|
|
86
|
+
```json5
|
|
87
|
+
{
|
|
88
|
+
// ...
|
|
89
|
+
|
|
90
|
+
"scripts": {
|
|
91
|
+
"prepack": "npm run build",
|
|
92
|
+
},
|
|
93
|
+
}
|
|
94
|
+
```
|
|
79
95
|
|
|
80
|
-
|
|
96
|
+
This mirrors the same behavior as `npm publish`.
|
|
81
97
|
|
|
98
|
+
### What does `git-publish` do?
|
|
82
99
|
|
|
83
|
-
|
|
100
|
+
1. Checks out or creates the publish branch
|
|
101
|
+
2. Runs the `prepare` and `prepack` npm scripts
|
|
102
|
+
3. Uses [npm-packlist](https://github.com/npm/npm-packlist) to determine publishable files
|
|
103
|
+
4. Commits only those files
|
|
104
|
+
5. Pushes the branch to the Git remote
|
|
105
|
+
6. Prints the command to install the package via Git
|
|
84
106
|
|
|
85
|
-
|
|
107
|
+
### Why preserve commit history on the publish branch?
|
|
86
108
|
|
|
87
|
-
|
|
109
|
+
When installing from Git, npm uses commit hashes—not branch names. If the commit is "detached" (i.e., unreachable from history), it may be garbage-collected, breaking installs.
|
|
88
110
|
|
|
89
|
-
|
|
90
|
-
2. Create a temporary branch by prefixing the current branch with the `npm/` namespace
|
|
91
|
-
3. Detect and commit only the [npm publish files](https://github.com/npm/npm-packlist)
|
|
92
|
-
4. Push the branch to remote
|
|
93
|
-
5. Delete local branch from Step 2
|
|
94
|
-
6. Print the installation command for the branch
|
|
111
|
+
To avoid this, `git-publish` preserves history by default.
|
|
95
112
|
|
|
96
|
-
|
|
113
|
+
If you prefer a single clean commit and understand the risks, use the `--fresh` flag to force-push a one-commit branch.
|
|
97
114
|
|
|
98
|
-
|
|
99
|
-
- Irrelevant files are committed (eg. source files). This can slow down installation or even interfere with the library behavior. For example, if your project has development configuration files, they can accidentally be read by the dependent tooling.
|
|
115
|
+
### Why not just commit the files manually?
|
|
100
116
|
|
|
101
|
-
|
|
117
|
+
Manual commits often:
|
|
118
|
+
|
|
119
|
+
- Miss important files (e.g., those not in `dist/`)
|
|
120
|
+
- Include irrelevant files (e.g., tests, source, configs)
|
|
121
|
+
- Skip npm lifecycle scripts
|
|
122
|
+
|
|
123
|
+
`git-publish` avoids these pitfalls by using `npm-packlist` (same as `npm publish`) and running `prepare` and `prepack`.
|
|
124
|
+
|
|
125
|
+
### Can I use this in a monorepo?
|
|
126
|
+
|
|
127
|
+
Yes. Run `git-publish` from inside the specific package directory (e.g., `packages/my-lib`).
|
|
128
|
+
|
|
129
|
+
It will detect and publish only that package's contents to the root of the Git branch.
|
|
130
|
+
|
|
131
|
+
> [!IMPORTANT]
|
|
132
|
+
> Currently does not support resolving `workspace:` protocol dependencies. Avoid using those or pre-bundle them before publishing.
|
|
102
133
|
|
|
103
134
|
### Can I publish to and install from a private repository?
|
|
104
135
|
|
|
105
|
-
Yes
|
|
136
|
+
Yes—if your Git client (e.g., local dev, CI, etc.) is authorized to access the repo.
|
|
106
137
|
|
|
107
|
-
If
|
|
138
|
+
If that's not possible, you can push the branch to a public repo using the `--remote` flag.
|
|
108
139
|
|
|
140
|
+
> [!WARNING]
|
|
141
|
+
> Minify or obfuscate private code before publishing to a public repo.
|
|
109
142
|
|
|
110
|
-
####
|
|
111
|
-
You want to test a branch on a private repository _Repo A_, but GitHub Actions on the consuming project _Repo B_ doesn't have access to the private repository so `npm install` fails.
|
|
143
|
+
#### Example: publishing from private repo A to public repo B
|
|
112
144
|
|
|
113
|
-
|
|
145
|
+
Say you're testing changes in **Repo A**, but your GitHub Actions workflow in **Repo B** can't access private repos. You can push the publish branch to **Repo B** instead:
|
|
114
146
|
|
|
115
147
|
```sh
|
|
116
|
-
|
|
148
|
+
npx git-publish --remote git@github.com:repo-b.git --branch test-pkg
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Result:
|
|
117
152
|
|
|
153
|
+
```sh
|
|
118
154
|
✔ Successfully published branch! Install with command:
|
|
119
155
|
→ npm i 'repo-b#test-pkg'
|
|
120
156
|
```
|
|
157
|
+
|
|
158
|
+
## Sponsors
|
|
159
|
+
|
|
160
|
+
<p align="center">
|
|
161
|
+
<a href="https://github.com/sponsors/privatenumber">
|
|
162
|
+
<img src="https://cdn.jsdelivr.net/gh/privatenumber/sponsors/sponsorkit/sponsors.svg">
|
|
163
|
+
</a>
|
|
164
|
+
</p>
|