bestzip 3.0.3 → 3.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.
- package/bin/cli.js +14 -7
- package/lib/bestzip.js +227 -40
- package/package.json +1 -1
- package/readme.md +29 -16
package/bin/cli.js
CHANGED
|
@@ -5,7 +5,13 @@ import * as bestzip from "../lib/bestzip.js";
|
|
|
5
5
|
import yargs from "yargs";
|
|
6
6
|
import { hideBin } from "yargs/helpers";
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
// Rewrite -0 … -9 into --level 0 … --level 9 before yargs parses them
|
|
9
|
+
const preprocessed = hideBin(process.argv).flatMap((arg) => {
|
|
10
|
+
const match = /^-([0-9])$/.exec(arg);
|
|
11
|
+
return match ? ["--level", match[1]] : [arg];
|
|
12
|
+
});
|
|
13
|
+
|
|
14
|
+
const argv = yargs(preprocessed)
|
|
9
15
|
.usage("\nUsage: bestzip destination.zip sources/")
|
|
10
16
|
.option("force", {
|
|
11
17
|
describe: "Force use of node.js or native zip methods",
|
|
@@ -14,18 +20,17 @@ const argv = yargs(hideBin(process.argv))
|
|
|
14
20
|
.option("level", {
|
|
15
21
|
describe: "Level of compression",
|
|
16
22
|
type: "number",
|
|
17
|
-
|
|
23
|
+
})
|
|
24
|
+
.option("follow-sym-links", {
|
|
25
|
+
describe:
|
|
26
|
+
"Follow symbolic links and include their target contents in the archive",
|
|
27
|
+
type: "boolean",
|
|
18
28
|
})
|
|
19
29
|
.demand(2).argv;
|
|
20
30
|
|
|
21
31
|
const destination = argv._.shift();
|
|
22
32
|
const source = argv._;
|
|
23
33
|
|
|
24
|
-
if (argv.level < -1 || argv.level > 9) {
|
|
25
|
-
console.error("Invalid compression level, must be >= 0 and <= 9");
|
|
26
|
-
process.exit(1);
|
|
27
|
-
}
|
|
28
|
-
|
|
29
34
|
console.log("Writing %s to %s...", source.join(", "), destination);
|
|
30
35
|
|
|
31
36
|
let zip;
|
|
@@ -43,6 +48,8 @@ zip({
|
|
|
43
48
|
destination,
|
|
44
49
|
verbose: !!argv.verbose,
|
|
45
50
|
level: argv.level,
|
|
51
|
+
followSymLinks: argv.followSymLinks,
|
|
52
|
+
viaCli: true,
|
|
46
53
|
})
|
|
47
54
|
.then(function () {
|
|
48
55
|
console.log("zipped!");
|
package/lib/bestzip.js
CHANGED
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
// creates a zip file using either the native `zip` command if available,
|
|
2
2
|
// or a node.js zip implementation otherwise.
|
|
3
3
|
|
|
4
|
-
import cp from "node:child_process";
|
|
4
|
+
import cp, { spawnSync } from "node:child_process";
|
|
5
5
|
import fs from "node:fs";
|
|
6
|
+
import fsp from "node:fs/promises";
|
|
6
7
|
import path from "node:path";
|
|
8
|
+
import os from "node:os";
|
|
7
9
|
|
|
8
10
|
import { ZipArchive } from "archiver";
|
|
9
11
|
import { glob, hasMagic } from "glob";
|
|
@@ -13,6 +15,44 @@ function hasNativeZip() {
|
|
|
13
15
|
return Boolean(which.sync("zip", { nothrow: true }));
|
|
14
16
|
}
|
|
15
17
|
|
|
18
|
+
let nativeSymlinkCapability;
|
|
19
|
+
|
|
20
|
+
// The native zip command needs the --symlinks flag to store symlinks as links
|
|
21
|
+
// rather than following them. Not every build supports it (notably the
|
|
22
|
+
// Windows build of Info-ZIP). This probes the installed zip for support, since
|
|
23
|
+
// the version string isn't a reliable indicator.
|
|
24
|
+
function nativeZipSupportsSymlinks() {
|
|
25
|
+
if (nativeSymlinkCapability !== undefined) {
|
|
26
|
+
return nativeSymlinkCapability;
|
|
27
|
+
}
|
|
28
|
+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bestzip-symlink-check"));
|
|
29
|
+
try {
|
|
30
|
+
const file = path.join(dir, "file");
|
|
31
|
+
const link = path.join(dir, "link");
|
|
32
|
+
fs.writeFileSync(file, "bestzip symlink check");
|
|
33
|
+
try {
|
|
34
|
+
fs.symlinkSync("file", link);
|
|
35
|
+
} catch (e) {
|
|
36
|
+
nativeSymlinkCapability = false;
|
|
37
|
+
return nativeSymlinkCapability;
|
|
38
|
+
}
|
|
39
|
+
const res = spawnSync(
|
|
40
|
+
"zip",
|
|
41
|
+
["-q", "--symlinks", "check.zip", "file", "link"],
|
|
42
|
+
{
|
|
43
|
+
cwd: dir,
|
|
44
|
+
encoding: "utf8",
|
|
45
|
+
}
|
|
46
|
+
);
|
|
47
|
+
nativeSymlinkCapability = res.status === 0;
|
|
48
|
+
} catch (e) {
|
|
49
|
+
nativeSymlinkCapability = false;
|
|
50
|
+
} finally {
|
|
51
|
+
fs.rmSync(dir, { recursive: true, force: true });
|
|
52
|
+
}
|
|
53
|
+
return nativeSymlinkCapability;
|
|
54
|
+
}
|
|
55
|
+
|
|
16
56
|
async function expandSources(cwd, source) {
|
|
17
57
|
// options to behave more like the native zip's glob support
|
|
18
58
|
const globOpts = {
|
|
@@ -46,16 +86,79 @@ async function expandSources(cwd, source) {
|
|
|
46
86
|
}
|
|
47
87
|
}
|
|
48
88
|
|
|
49
|
-
function
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
89
|
+
async function walkTree(fullPath, followSymLinks) {
|
|
90
|
+
let stats;
|
|
91
|
+
if (followSymLinks) {
|
|
92
|
+
stats = await fsp.stat(fullPath);
|
|
93
|
+
} else {
|
|
94
|
+
stats = await fsp.lstat(fullPath);
|
|
95
|
+
}
|
|
96
|
+
if (stats.isSymbolicLink() || !stats.isDirectory()) {
|
|
97
|
+
return [{ path: fullPath, stats }];
|
|
98
|
+
}
|
|
99
|
+
const entries = await fsp.readdir(fullPath);
|
|
100
|
+
const children = await Promise.all(
|
|
101
|
+
entries.map((entry) => walkTree(path.join(fullPath, entry), followSymLinks))
|
|
102
|
+
);
|
|
103
|
+
return children.flat();
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
// Validates the compression level. A level of exactly 0-9 (an integer) is
|
|
107
|
+
// accepted; anything else that is set causes an error. An unset level is
|
|
108
|
+
// allowed and left to each implementation's default.
|
|
109
|
+
function validateLevel(level) {
|
|
110
|
+
if (typeof level === "undefined") {
|
|
111
|
+
return;
|
|
112
|
+
}
|
|
113
|
+
if (
|
|
114
|
+
typeof level !== "number" ||
|
|
115
|
+
!Number.isInteger(level) ||
|
|
116
|
+
level < 0 ||
|
|
117
|
+
level > 9
|
|
118
|
+
) {
|
|
119
|
+
const typehint = typeof level === "number" ? "" : ` (${typeof level})`;
|
|
120
|
+
throw new Error(
|
|
121
|
+
`bestzip: level should be an integer from 0 to 9, got ${level}${typehint}`
|
|
122
|
+
);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
async function detectSymlinks(cwd, sources) {
|
|
127
|
+
const results = await Promise.all(
|
|
128
|
+
sources.map(async (source) => {
|
|
129
|
+
const fullPath = path.resolve(cwd, source);
|
|
130
|
+
const entries = await walkTree(fullPath, false);
|
|
131
|
+
return entries
|
|
132
|
+
.filter((entry) => entry.stats.isSymbolicLink())
|
|
133
|
+
.map((entry) => entry.path);
|
|
134
|
+
})
|
|
135
|
+
);
|
|
136
|
+
return results.flat();
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function maybeWarnAboutSymlinks(options, symlinks, cwd) {
|
|
140
|
+
if (options.followSymLinks !== undefined || symlinks.length === 0) {
|
|
141
|
+
return;
|
|
142
|
+
}
|
|
143
|
+
const cli = options.viaCli;
|
|
144
|
+
const optIn = cli ? "pass --follow-sym-links" : "set followSymLinks: true";
|
|
145
|
+
const optOut = cli
|
|
146
|
+
? "pass --no-follow-sym-links"
|
|
147
|
+
: "set followSymLinks: false";
|
|
148
|
+
let lines = symlinks.map((p) => path.relative(cwd, p));
|
|
149
|
+
if (lines.length > 4) {
|
|
150
|
+
lines = lines.slice(0, 3);
|
|
151
|
+
lines.push(`...and ${symlinks.length - 3} more`);
|
|
152
|
+
}
|
|
153
|
+
console.warn(
|
|
154
|
+
"Warning: Symbolic links are followed by default — their target contents are included in the archive.\n" +
|
|
155
|
+
`To keep this behavior and prevent this warning, ${optIn}.\n` +
|
|
156
|
+
`To store symlinks as links instead, ${optOut}.\n` +
|
|
157
|
+
"This default will change in v4 to store symlinks as links. " +
|
|
158
|
+
"Set followSymLinks explicitly to opt in to following.\n" +
|
|
159
|
+
"Detected symlinks:\n" +
|
|
160
|
+
lines.join("\n")
|
|
161
|
+
);
|
|
59
162
|
}
|
|
60
163
|
|
|
61
164
|
const nativeZip = async (options) => {
|
|
@@ -63,20 +166,49 @@ const nativeZip = async (options) => {
|
|
|
63
166
|
const command = "zip";
|
|
64
167
|
const sources = await expandSources(cwd, options.source);
|
|
65
168
|
const destination = path.resolve(cwd, options.destination);
|
|
169
|
+
validateLevel(options.level);
|
|
170
|
+
// followSymLinks: false opts into storing symlinks as links; the default
|
|
171
|
+
// (unset or true) follows symlinks and is unchanged.
|
|
172
|
+
const followSymLinks = options.followSymLinks !== false;
|
|
66
173
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
174
|
+
if (!followSymLinks && !nativeZipSupportsSymlinks()) {
|
|
175
|
+
// The native zip command cannot store symlinks as links on this platform
|
|
176
|
+
// (e.g. the Windows build of Info-ZIP). nodeZip can, so the bestzip()
|
|
177
|
+
// entry point routes accordingly — but a direct nativeZip() call can't
|
|
178
|
+
// fulfill this request.
|
|
179
|
+
throw new Error(
|
|
180
|
+
"The native zip command on this platform cannot store symlinks as links. Use the bestzip() entry point, which will select the node implementation, or set followSymLinks to true to follow symlinks instead."
|
|
181
|
+
);
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
const args = ["--quiet", "--recurse-paths"];
|
|
185
|
+
if (typeof options.level === "number") {
|
|
186
|
+
args.push("-" + options.level.toString());
|
|
77
187
|
}
|
|
188
|
+
if (!followSymLinks) {
|
|
189
|
+
args.push("--symlinks");
|
|
190
|
+
}
|
|
191
|
+
args.push(destination, "--", ...sources);
|
|
192
|
+
|
|
193
|
+
// Scan for symlinks to warn about in parallel with the zip command. The
|
|
194
|
+
// scan is best-effort: if it fails (e.g. it races the zip command touching
|
|
195
|
+
// the same paths), log and fall back to no warning rather than aborting the
|
|
196
|
+
// zip, and never let it reject before the zip process has completed.
|
|
197
|
+
const warnScan = (async () => {
|
|
198
|
+
if (options.followSymLinks !== undefined) {
|
|
199
|
+
return [];
|
|
200
|
+
}
|
|
201
|
+
try {
|
|
202
|
+
return await detectSymlinks(cwd, sources);
|
|
203
|
+
} catch (err) {
|
|
204
|
+
console.warn(
|
|
205
|
+
`bestzip: failed to scan for symlinks to warn about: ${err.message}`
|
|
206
|
+
);
|
|
207
|
+
return [];
|
|
208
|
+
}
|
|
209
|
+
})();
|
|
78
210
|
|
|
79
|
-
|
|
211
|
+
const zipPromise = new Promise((resolve, reject) => {
|
|
80
212
|
const zipProcess = cp.spawn(command, args, {
|
|
81
213
|
stdio: "inherit",
|
|
82
214
|
cwd,
|
|
@@ -96,18 +228,34 @@ const nativeZip = async (options) => {
|
|
|
96
228
|
}
|
|
97
229
|
});
|
|
98
230
|
});
|
|
231
|
+
|
|
232
|
+
const [symlinks] = await Promise.all([warnScan, zipPromise]);
|
|
233
|
+
maybeWarnAboutSymlinks(options, symlinks, cwd);
|
|
99
234
|
};
|
|
100
235
|
|
|
101
236
|
// based on http://stackoverflow.com/questions/15641243/need-to-zip-an-entire-directory-using-node-js/18775083#18775083
|
|
102
237
|
const nodeZip = async (options) => {
|
|
103
238
|
const cwd = options.cwd || process.cwd();
|
|
104
|
-
|
|
239
|
+
validateLevel(options.level);
|
|
240
|
+
// followSymLinks: false stores symlinks as links; the default (unset or
|
|
241
|
+
// true) follows symlinks, matching the native zip implementation.
|
|
242
|
+
const followSymLinks = options.followSymLinks !== false;
|
|
243
|
+
const symlinks = [];
|
|
244
|
+
const outputFile = await fsp.open(
|
|
245
|
+
path.resolve(cwd, options.destination),
|
|
246
|
+
"w"
|
|
247
|
+
);
|
|
248
|
+
const output = outputFile.createWriteStream();
|
|
105
249
|
const archive = new ZipArchive({
|
|
106
250
|
zlib: { level: options.level },
|
|
107
251
|
});
|
|
108
252
|
|
|
109
|
-
output.on("close", () =>
|
|
253
|
+
output.on("close", async () => {
|
|
254
|
+
await outputFile.close();
|
|
255
|
+
resolvePromise();
|
|
256
|
+
});
|
|
110
257
|
archive.on("error", (err) => rejectPromise(err));
|
|
258
|
+
archive.on("warning", (err) => console.warn(err && err.message));
|
|
111
259
|
|
|
112
260
|
archive.pipe(output);
|
|
113
261
|
|
|
@@ -122,26 +270,57 @@ const nodeZip = async (options) => {
|
|
|
122
270
|
const fullPath = path.resolve(cwd, source);
|
|
123
271
|
const destPath = source;
|
|
124
272
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
const
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
273
|
+
if (!followSymLinks) {
|
|
274
|
+
// Store symlinks as link entries (their targets, not their contents).
|
|
275
|
+
const entries = await walkTree(fullPath, false);
|
|
276
|
+
for (const entry of entries) {
|
|
277
|
+
const subPath = entry.path.substring(fullPath.length);
|
|
278
|
+
if (entry.stats.isSymbolicLink()) {
|
|
279
|
+
symlinks.push(entry.path);
|
|
280
|
+
archive.symlink(
|
|
281
|
+
destPath + subPath,
|
|
282
|
+
await fsp.readlink(entry.path),
|
|
283
|
+
entry.stats.mode
|
|
284
|
+
);
|
|
285
|
+
} else {
|
|
286
|
+
archive.file(entry.path, {
|
|
287
|
+
name: destPath + subPath,
|
|
288
|
+
stats: entry.stats,
|
|
289
|
+
});
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
return;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
// Follow symlinks by default. Pass explicit (stat) stats so archiver
|
|
296
|
+
// dereferences symlinks and stores their target contents rather than the
|
|
297
|
+
// link itself, matching the native zip implementation.
|
|
298
|
+
const entries = await walkTree(fullPath, true);
|
|
299
|
+
for (const entry of entries) {
|
|
300
|
+
const archiveName = destPath + entry.path.substring(fullPath.length);
|
|
301
|
+
archive.file(entry.path, {
|
|
302
|
+
name: archiveName,
|
|
303
|
+
stats: entry.stats,
|
|
134
304
|
});
|
|
135
|
-
}
|
|
136
|
-
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
// Warn while following by default (followSymLinks unset): detect symlinks
|
|
308
|
+
// via an lstat walk so the deprecation warning still fires even though the
|
|
309
|
+
// archive stores their target contents.
|
|
310
|
+
if (options.followSymLinks === undefined) {
|
|
311
|
+
const detected = await walkTree(fullPath, false);
|
|
312
|
+
for (const entry of detected) {
|
|
313
|
+
if (entry.stats.isSymbolicLink()) {
|
|
314
|
+
symlinks.push(entry.path);
|
|
315
|
+
}
|
|
316
|
+
}
|
|
137
317
|
}
|
|
138
318
|
}
|
|
139
319
|
|
|
140
320
|
try {
|
|
141
321
|
const expandedSources = await expandSources(cwd, options.source);
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
}
|
|
322
|
+
await Promise.all(expandedSources.map(addSource));
|
|
323
|
+
maybeWarnAboutSymlinks(options, symlinks, cwd);
|
|
145
324
|
archive.finalize();
|
|
146
325
|
} catch (err) {
|
|
147
326
|
rejectPromise(err);
|
|
@@ -159,8 +338,16 @@ function zip(options) {
|
|
|
159
338
|
};
|
|
160
339
|
}
|
|
161
340
|
|
|
341
|
+
// The native zip command can store symlinks as links only when it supports
|
|
342
|
+
// --symlinks. If followSymLinks is not explicitly false, it just follows
|
|
343
|
+
// symlinks, which every native zip can do. When storing links is requested
|
|
344
|
+
// but the native zip can't do it, fall back to the node implementation.
|
|
345
|
+
const useNative =
|
|
346
|
+
hasNativeZip() &&
|
|
347
|
+
(options.followSymLinks !== false || nativeZipSupportsSymlinks());
|
|
348
|
+
|
|
162
349
|
let promise;
|
|
163
|
-
if (
|
|
350
|
+
if (useNative) {
|
|
164
351
|
promise = nativeZip(options);
|
|
165
352
|
} else {
|
|
166
353
|
promise = nodeZip(options);
|
|
@@ -175,4 +362,4 @@ function zip(options) {
|
|
|
175
362
|
|
|
176
363
|
export default zip;
|
|
177
364
|
|
|
178
|
-
export { zip, nodeZip, nativeZip, hasNativeZip };
|
|
365
|
+
export { zip, nodeZip, nativeZip, hasNativeZip, nativeZipSupportsSymlinks };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "bestzip",
|
|
3
|
-
"version": "3.0
|
|
3
|
+
"version": "3.1.0",
|
|
4
4
|
"description": "Uses OS zip command if available (for better performance and speed) or node.js version if there is no system command available. Can be called via node or command line.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": "./lib/bestzip.js",
|
package/readme.md
CHANGED
|
@@ -16,7 +16,7 @@ The native `zip` command on GNU/Linux and macOS is significantly faster and crea
|
|
|
16
16
|
## Global command line usage
|
|
17
17
|
|
|
18
18
|
npm install -g bestzip
|
|
19
|
-
bestzip destination.zip source/ [other sources...]
|
|
19
|
+
bestzip --no-follow-sym-links destination.zip source/ [other sources...]
|
|
20
20
|
|
|
21
21
|
## Command line usage within `package.json` scripts
|
|
22
22
|
|
|
@@ -28,42 +28,63 @@ package.json:
|
|
|
28
28
|
{
|
|
29
29
|
//...
|
|
30
30
|
"scripts": {
|
|
31
|
-
"build" "...",
|
|
32
|
-
"zip": "bestzip bundle.zip build/*",
|
|
31
|
+
"build": "...",
|
|
32
|
+
"zip": "bestzip --no-follow-sym-links bundle.zip build/*",
|
|
33
33
|
"upload": "....",
|
|
34
34
|
"deploy": "npm run build && npm run zip && npm run upload"
|
|
35
35
|
}
|
|
36
36
|
}
|
|
37
37
|
```
|
|
38
38
|
|
|
39
|
+
## Command line options
|
|
40
|
+
|
|
41
|
+
* `--follow-sym-links` / `--no-follow-sym-links`: Follow symbolic links and include their target contents in the archive (the default) or don't follow and instead include the link itself. Setting one flag or the other is recommended because the default will change in the next major version (v4.0.0). If symlinks are encountered when the flag is not set, a warning will be logged.
|
|
42
|
+
* `--level N` / `-N`: Level of compression, as with the native `zip` command. `N` must be an integer from 0 (store, no compression) to 9 (maximum compression). Defaults to each implementation's own default when unset.
|
|
43
|
+
* `--force node|native`: Force the Node.js implementation or the native `zip` command instead of letting bestzip pick automatically.
|
|
44
|
+
|
|
45
|
+
|
|
39
46
|
## Programmatic usage from within Node.js
|
|
40
47
|
|
|
41
48
|
```javascript
|
|
42
|
-
import zip from 'bestzip';
|
|
43
|
-
//
|
|
49
|
+
import { zip } from 'bestzip';
|
|
50
|
+
// const { zip } = require('bestzip'); // for CJS (requires node.js v22 or newer
|
|
44
51
|
|
|
45
52
|
// zip a single source
|
|
46
53
|
await zip({
|
|
47
54
|
source: 'build/*',
|
|
48
|
-
destination: './destination.zip'
|
|
55
|
+
destination: './destination.zip',
|
|
56
|
+
followSymLinks: false,
|
|
49
57
|
})
|
|
50
58
|
|
|
51
59
|
// zip multiple sources, starting in a different CWD (current working directory)
|
|
52
60
|
await zip({
|
|
53
61
|
source: ['img1.jpg', 'img2.jpg', 'imgn.jpg'],
|
|
54
62
|
destination: '../images.zip',
|
|
55
|
-
cwd: './images/' // optional, defaults to process.cwd()
|
|
63
|
+
cwd: './images/', // optional, defaults to process.cwd()
|
|
64
|
+
followSymLinks: false,
|
|
56
65
|
})
|
|
57
66
|
|
|
58
67
|
// Promises also work: zip({source, destination}).then(...).catch(...)
|
|
59
68
|
// Callbacks also work: zip(destination, sources, callback)
|
|
60
69
|
```
|
|
61
70
|
|
|
62
|
-
### Options
|
|
71
|
+
### API Options
|
|
63
72
|
|
|
64
73
|
* `source`: Path or paths to files and folders to include in the zip file. String or Array of Strings.
|
|
65
74
|
* `destination`: Path to generated .zip file.
|
|
66
75
|
* `cwd`: Set the Current Working Directory that source and destination paths are relative to. Defaults to `process.cwd()`
|
|
76
|
+
* `level`: Level of compression, as with the native `zip` command. An integer from 0 (store, no compression) to 9 (maximum compression). Defaults to each implementation's own default when unset.
|
|
77
|
+
* `followSymLinks`: Follow symbolic links and include the contents of their targets in the zip file. When set to `true` or `false` the preference is honored and no warning is printed. When left unset, symbolic links are followed (the current default) and a warning is printed whenever symlinks are detected, because this default will change in v4 to store symlinks as links instead (see [Symbolic links](#symbolic-links)).
|
|
78
|
+
|
|
79
|
+
## Symbolic links
|
|
80
|
+
|
|
81
|
+
By default, bestzip **follows** symbolic links — their target contents are included in the archive. When symlinks are present and the `followSymLinks` option has not been set explicitly, bestzip prints a warning to stderr listing the symlinked paths and how to opt in or out.
|
|
82
|
+
|
|
83
|
+
**This default will change in v4** to store symlinks as link entries (not following them), which is the more secure behavior. To prepare for this, set `followSymLinks` explicitly in your code.
|
|
84
|
+
|
|
85
|
+
To follow symlinks (the current default), set `followSymLinks: true` (programmatic API) or pass `--follow-sym-links` on the command line. To suppress the warning while keeping the current default, set `followSymLinks: true` explicitly. To store symlinks as links instead, set `followSymLinks: false` or pass `--no-follow-sym-links` on the command line.
|
|
86
|
+
|
|
87
|
+
When storing symlinks as links, bestzip uses the native `zip` command when available. Some native `zip` builds (notably the Windows build of Info-ZIP) cannot store symlinks as link entries at all, so bestzip falls back to its built-in Node.js implementation in that case. Note that calling `bestzip.nativeZip` directly with `followSymLinks` unset/false on such a platform throws an error; use the `bestzip()` entry point, which routes to the Node.js implementation automatically. Use `bestzip.nativeZipSupportsSymlinks()` to check whether the available native `zip` can store symlinks as links; it returns `true`/`false` and caches its result after the first call. `bestzip.hasNativeZip()` checks whether a native `zip` is installed at all.
|
|
67
88
|
|
|
68
89
|
## How to control the directory structure
|
|
69
90
|
|
|
@@ -90,11 +111,3 @@ Wildcards (`*`) ignore dotfiles.
|
|
|
90
111
|
* To include a dotfile, either include the directory it's in (`folder/`) or include it by name (`folder/.dotfile`)
|
|
91
112
|
* To omit dotfiles, either use a wildcard (`folder/*`) or explicitly list the desired files (`folder/file1.txt folder/file2.txt`)
|
|
92
113
|
|
|
93
|
-
## Breaking changes for v2
|
|
94
|
-
|
|
95
|
-
* `bestzip output.zip foo/bar/file.txt` now includes the foo/bar/ folders, previously it would place file.txt at the top-level
|
|
96
|
-
* This was done to more closely align with the native zip command
|
|
97
|
-
|
|
98
|
-
## Breaking changes for v3
|
|
99
|
-
|
|
100
|
-
* Switched from CJS to ESM
|