1 | # xyz
|
2 |
|
3 | xyz simplifies the publishing of npm packages by replacing several manual
|
4 | steps with a single command:
|
5 |
|
6 | $ xyz
|
7 | Current version is 0.6.0. Press [enter] to publish example@0.6.1.▌
|
8 |
|
9 | Several things will happen if one elects to continue:
|
10 |
|
11 | npm prune
|
12 | npm test
|
13 | env VERSION=0.6.1 node -e '
|
14 | var pkg = require("./package.json");
|
15 | pkg.version = process.env.VERSION;
|
16 | fs.writeFileSync("package.json", JSON.stringify(pkg, null, 2) + "\n");
|
17 | '
|
18 | git add package.json
|
19 | git commit --message 'Version 0.6.1'
|
20 | git tag --annotate v0.6.1 --message 'Version 0.6.1'
|
21 | git push --atomic origin refs/heads/main refs/tags/v0.6.1
|
22 | env VERSION=0.6.1 PREVIOUS_VERSION=0.6.0 bash -c 'npm publish'
|
23 |
|
24 | > [!IMPORTANT]
|
25 | >
|
26 | > **macOS Mojave**, released in 2018, provides a version of Bash from 2007.
|
27 | > xyz uses a feature added in Bash 4, released in 2009. macOS users should run
|
28 | > `brew install bash` to install a compatible Bash version.
|
29 |
|
30 | ## Usage
|
31 |
|
32 | Usage: xyz [options]
|
33 |
|
34 | Publish a new version of the npm package in the current working directory.
|
35 | This involves updating the version number in package.json, committing this
|
36 | change (along with any staged changes), tagging the commit, pushing to the
|
37 | remote git repository, and finally publishing to the public npm registry.
|
38 |
|
39 | Options:
|
40 |
|
41 | -b --branch <name>
|
42 | Specify the branch from which new versions must be published.
|
43 | xyz aborts if run from any other branch to prevent accidental
|
44 | publication of feature branches. 'main' is assumed if this
|
45 | option is omitted.
|
46 |
|
47 | -e --edit
|
48 | Allow the commit message to be edited before the commit is made.
|
49 |
|
50 | -i --increment <level>
|
51 | Specify the level of the current version number to increment.
|
52 | Valid levels: 'major', 'minor', 'patch', 'premajor', 'preminor',
|
53 | 'prepatch', and 'prerelease'. 'patch' is assumed if this option
|
54 | is omitted. Choosing one of the pre-releases causes the npm dist-tag
|
55 | to be set according to --prerelease-label.
|
56 |
|
57 | -m --message <template>
|
58 | Specify the format of the commit (and tag) message.
|
59 | 'X.Y.Z' acts as a placeholder for the version number.
|
60 | 'Version X.Y.Z' is assumed if this option is omitted.
|
61 |
|
62 | --prerelease-label <label>
|
63 | Specify the label to be used in the version number when publishing
|
64 | a pre-release version (e.g. 'beta' is the label in '2.0.0-beta.0').
|
65 | 'rc' is assumed if this option is omitted. If the release is a
|
66 | pre-release, as indicated by --increment, the --prerelease-label will
|
67 | be used to create an npm dist-tag for the release.
|
68 |
|
69 | --publish-command <command>
|
70 | Specify the command to be run to publish the package. It may refer
|
71 | to the VERSION and PREVIOUS_VERSION environment variables. A no-op
|
72 | command (':' or 'true') prevents the package from being published
|
73 | to a registry. 'npm publish' is assumed if this option is omitted.
|
74 | If this option is provided, the --prerelease-label will not be used
|
75 | to create an npm dist-tag for the release.
|
76 |
|
77 | -r --repo <repository>
|
78 | Specify the remote repository to which to 'git push'.
|
79 | The value must be either a URL or the name of a remote.
|
80 | The latter is not recommended: it relies on local state.
|
81 | 'origin' is assumed if this option is omitted.
|
82 |
|
83 | -s --script <path>
|
84 | Specify a script to be run after the confirmation prompt.
|
85 | It is passed VERSION and PREVIOUS_VERSION as environment
|
86 | variables. xyz aborts if the script's exit code is not 0.
|
87 |
|
88 | -t --tag <template>
|
89 | Specify the format of the tag name. As with --message,
|
90 | 'X.Y.Z' acts as a placeholder for the version number.
|
91 | 'vX.Y.Z' is assumed if this option is omitted.
|
92 |
|
93 | --dry-run
|
94 | Print the commands without evaluating them.
|
95 |
|
96 | -v --version
|
97 | Print xyz's version number and exit.
|
98 |
|
99 | ## Integration
|
100 |
|
101 | Installing xyz globally is okay, but it's good practice to add it as a dev
|
102 | dependency.
|
103 |
|
104 | ### npm
|
105 |
|
106 | ```json
|
107 | "scripts": {
|
108 | "release": "xyz --repo git@github.com:owner/repo.git --increment",
|
109 | }
|
110 | ```
|
111 |
|
112 | ```console
|
113 | $ npm run release minor
|
114 | ```
|
115 |
|
116 | ### Make
|
117 |
|
118 | ```make
|
119 | XYZ = node_modules/.bin/xyz --repo git@github.com:owner/repo.git
|
120 |
|
121 | .PHONY: release-major release-minor release-patch
|
122 | release-major release-minor release-patch:
|
123 | @$(XYZ) --increment $(@:release-%=%)
|
124 | ```
|
125 |
|
126 | ```console
|
127 | $ make release-minor
|
128 | ```
|