git-publish 1.0.2 → 2.1.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.
Files changed (3) hide show
  1. package/README.md +34 -11
  2. package/dist/index.js +71 -79
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,27 +1,34 @@
1
1
  # git-publish
2
2
 
3
- Publish your npm package to a Git branch.
3
+ Publish your npm package to a Git branch. Great for pre-publishing a package for testing.
4
4
 
5
- <sub>Support this project by ⭐️ starring and sharing it. [Follow me](https://github.com/privatenumber) to see what other cool projects I'm working on! ❤️</sub>
5
+ <br>
6
+
7
+ <p align="center">
8
+ <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>
9
+ <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>
10
+ </p>
6
11
 
7
12
  ## Why?
8
13
 
9
14
  To test a package without publishing to npm.
10
15
 
11
- When using `npm publish` to make a pre-release, you have the following drawbacks:
16
+ #### Why not use `npm publish` to make a pre-release?
17
+
18
+ Because of the following drawbacks:
12
19
 
13
20
  - **Versioning concerns:** even though you're just testing, you still need to version bump
14
21
  - **Undeleteable:** releases are hard to remove due to npm's [strict unpublish policy](https://docs.npmjs.com/policies/unpublish)
15
22
  - **Unverifyable:** npm does not offer a great way to browse the contents of a package
16
23
  - **Risky:** Publishing tests to a production environment can be dangerous (eg. accidentally publish as stable)
17
24
 
18
- When using `npm link`, you have the following drawbacks:
25
+ #### What about `npm link`?
19
26
  - No [npm life cycle scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts#life-cycle-scripts)
20
27
  - Includes non-publishable assets
21
28
  - Doesn't install dependencies
22
29
 
23
30
 
24
- In contrast, `git-publish` has the following benefits:
31
+ #### So why `git-publish`?
25
32
 
26
33
  - **No versions:** Instead of versions, branch names are used. Branches can be updated to reflect latest change.
27
34
 
@@ -41,7 +48,7 @@ Publish your npm package to a branch on the Git repository:
41
48
  npx git-publish
42
49
  ```
43
50
 
44
- > **⚠️ Warning:** This command will force-push to the remote branch `npm/<current branch>`. Make sure there are no unsaved changes there.
51
+ This command will publish to the remote branch `npm/<current branch>`.
45
52
 
46
53
 
47
54
  ### Global install
@@ -61,6 +68,7 @@ git-publish
61
68
  | - | - |
62
69
  | `-b, --branch <branch name>` | The branch to publish the package to. Defaults to prefixing "npm/" to the current branch or tag name. |
63
70
  | `-r, --remote <remote>` | The remote to push to. (default: `origin`) |
71
+ | `-o, --fresh` | Publish without a commit history. Warning: Force-pushes to remote |
64
72
  | `-d, --dry` | Dry run mode. Will not commit or push to the remote. |
65
73
  | `-h, --help` | Show help |
66
74
  | `--version` | Show version |
@@ -83,13 +91,20 @@ Like `npm publish`, you can call the build command it in the [`prepack` script](
83
91
 
84
92
  ### What does this script do?
85
93
 
86
- 1. Run [npm hooks](https://docs.npmjs.com/cli/v8/using-npm/scripts) `prepare` & `prepack`
87
- 2. Create a temporary branch by prefixing the current branch with the `npm/` namespace
88
- 3. Detect and commit the [npm publish files](https://github.com/npm/npm-packlist)
89
- 4. Force push the branch to remote
90
- 5. Delete local branch from Step 2
94
+ 1. If publish branch exists on remote, check it out to apply changes on top. Otherwise, create a new branch.
95
+ 2. Run [npm hooks](https://docs.npmjs.com/cli/v8/using-npm/scripts) `prepare` & `prepack`
96
+ 3. Detect and commit only the [npm publish files](https://github.com/npm/npm-packlist)
97
+ 4. Push the branch to remote
91
98
  6. Print the installation command for the branch
92
99
 
100
+ ### Why is the commit history preserved in the publish branch?
101
+
102
+ When pushing an npm installable commit to Git, it's important that it's an attached commit.
103
+
104
+ This is because npm lock references the commit hash, and not the branch name. So if the commit is detached, it will be removed upon reference loss and any subsequent npm installations referencing that commit hash will fail.
105
+
106
+ If you'd like a publish branch with a clean commit history despite these drawbacks, you can use the `--fresh` flag to force-push a single-commit branch to the remote.
107
+
93
108
  ### How is this different from simply committing the files to a branch?
94
109
 
95
110
  - There can be missing distribution files (eg. files outside of `dist`). _git-publish_ uses [npm-packlist](https://github.com/npm/npm-packlist) —the same library `npm publish` uses—to detect publish files declared via `package.json#files` and `.npmignore`.
@@ -115,3 +130,11 @@ $ npx git-publish --remote git@github.com:repo-b.git --branch test-pkg
115
130
  ✔ Successfully published branch! Install with command:
116
131
  → npm i 'repo-b#test-pkg'
117
132
  ```
133
+
134
+ ## Sponsors
135
+
136
+ <p align="center">
137
+ <a href="https://github.com/sponsors/privatenumber">
138
+ <img src="https://cdn.jsdelivr.net/gh/privatenumber/sponsors/sponsorkit/sponsors.svg">
139
+ </a>
140
+ </p>