source: trip-planner-front/node_modules/tar/README.md@ b738035

Last change on this file since b738035 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 43.8 KB
Line 
1# node-tar
2
3[Fast](./benchmarks) and full-featured Tar for Node.js
4
5The API is designed to mimic the behavior of `tar(1)` on unix systems.
6If you are familiar with how tar works, most of this will hopefully be
7straightforward for you. If not, then hopefully this module can teach
8you useful unix skills that may come in handy someday :)
9
10## Background
11
12A "tar file" or "tarball" is an archive of file system entries
13(directories, files, links, etc.) The name comes from "tape archive".
14If you run `man tar` on almost any Unix command line, you'll learn
15quite a bit about what it can do, and its history.
16
17Tar has 5 main top-level commands:
18
19* `c` Create an archive
20* `r` Replace entries within an archive
21* `u` Update entries within an archive (ie, replace if they're newer)
22* `t` List out the contents of an archive
23* `x` Extract an archive to disk
24
25The other flags and options modify how this top level function works.
26
27## High-Level API
28
29These 5 functions are the high-level API. All of them have a
30single-character name (for unix nerds familiar with `tar(1)`) as well
31as a long name (for everyone else).
32
33All the high-level functions take the following arguments, all three
34of which are optional and may be omitted.
35
361. `options` - An optional object specifying various options
372. `paths` - An array of paths to add or extract
383. `callback` - Called when the command is completed, if async. (If
39 sync or no file specified, providing a callback throws a
40 `TypeError`.)
41
42If the command is sync (ie, if `options.sync=true`), then the
43callback is not allowed, since the action will be completed immediately.
44
45If a `file` argument is specified, and the command is async, then a
46`Promise` is returned. In this case, if async, a callback may be
47provided which is called when the command is completed.
48
49If a `file` option is not specified, then a stream is returned. For
50`create`, this is a readable stream of the generated archive. For
51`list` and `extract` this is a writable stream that an archive should
52be written into. If a file is not specified, then a callback is not
53allowed, because you're already getting a stream to work with.
54
55`replace` and `update` only work on existing archives, and so require
56a `file` argument.
57
58Sync commands without a file argument return a stream that acts on its
59input immediately in the same tick. For readable streams, this means
60that all of the data is immediately available by calling
61`stream.read()`. For writable streams, it will be acted upon as soon
62as it is provided, but this can be at any time.
63
64### Warnings and Errors
65
66Tar emits warnings and errors for recoverable and unrecoverable situations,
67respectively. In many cases, a warning only affects a single entry in an
68archive, or is simply informing you that it's modifying an entry to comply
69with the settings provided.
70
71Unrecoverable warnings will always raise an error (ie, emit `'error'` on
72streaming actions, throw for non-streaming sync actions, reject the
73returned Promise for non-streaming async operations, or call a provided
74callback with an `Error` as the first argument). Recoverable errors will
75raise an error only if `strict: true` is set in the options.
76
77Respond to (recoverable) warnings by listening to the `warn` event.
78Handlers receive 3 arguments:
79
80- `code` String. One of the error codes below. This may not match
81 `data.code`, which preserves the original error code from fs and zlib.
82- `message` String. More details about the error.
83- `data` Metadata about the error. An `Error` object for errors raised by
84 fs and zlib. All fields are attached to errors raisd by tar. Typically
85 contains the following fields, as relevant:
86 - `tarCode` The tar error code.
87 - `code` Either the tar error code, or the error code set by the
88 underlying system.
89 - `file` The archive file being read or written.
90 - `cwd` Working directory for creation and extraction operations.
91 - `entry` The entry object (if it could be created) for `TAR_ENTRY_INFO`,
92 `TAR_ENTRY_INVALID`, and `TAR_ENTRY_ERROR` warnings.
93 - `header` The header object (if it could be created, and the entry could
94 not be created) for `TAR_ENTRY_INFO` and `TAR_ENTRY_INVALID` warnings.
95 - `recoverable` Boolean. If `false`, then the warning will emit an
96 `error`, even in non-strict mode.
97
98#### Error Codes
99
100* `TAR_ENTRY_INFO` An informative error indicating that an entry is being
101 modified, but otherwise processed normally. For example, removing `/` or
102 `C:\` from absolute paths if `preservePaths` is not set.
103
104* `TAR_ENTRY_INVALID` An indication that a given entry is not a valid tar
105 archive entry, and will be skipped. This occurs when:
106 - a checksum fails,
107 - a `linkpath` is missing for a link type, or
108 - a `linkpath` is provided for a non-link type.
109
110 If every entry in a parsed archive raises an `TAR_ENTRY_INVALID` error,
111 then the archive is presumed to be unrecoverably broken, and
112 `TAR_BAD_ARCHIVE` will be raised.
113
114* `TAR_ENTRY_ERROR` The entry appears to be a valid tar archive entry, but
115 encountered an error which prevented it from being unpacked. This occurs
116 when:
117 - an unrecoverable fs error happens during unpacking,
118 - an entry has `..` in the path and `preservePaths` is not set, or
119 - an entry is extracting through a symbolic link, when `preservePaths` is
120 not set.
121
122* `TAR_ENTRY_UNSUPPORTED` An indication that a given entry is
123 a valid archive entry, but of a type that is unsupported, and so will be
124 skipped in archive creation or extracting.
125
126* `TAR_ABORT` When parsing gzipped-encoded archives, the parser will
127 abort the parse process raise a warning for any zlib errors encountered.
128 Aborts are considered unrecoverable for both parsing and unpacking.
129
130* `TAR_BAD_ARCHIVE` The archive file is totally hosed. This can happen for
131 a number of reasons, and always occurs at the end of a parse or extract:
132
133 - An entry body was truncated before seeing the full number of bytes.
134 - The archive contained only invalid entries, indicating that it is
135 likely not an archive, or at least, not an archive this library can
136 parse.
137
138 `TAR_BAD_ARCHIVE` is considered informative for parse operations, but
139 unrecoverable for extraction. Note that, if encountered at the end of an
140 extraction, tar WILL still have extracted as much it could from the
141 archive, so there may be some garbage files to clean up.
142
143Errors that occur deeper in the system (ie, either the filesystem or zlib)
144will have their error codes left intact, and a `tarCode` matching one of
145the above will be added to the warning metadata or the raised error object.
146
147Errors generated by tar will have one of the above codes set as the
148`error.code` field as well, but since errors originating in zlib or fs will
149have their original codes, it's better to read `error.tarCode` if you wish
150to see how tar is handling the issue.
151
152### Examples
153
154The API mimics the `tar(1)` command line functionality, with aliases
155for more human-readable option and function names. The goal is that
156if you know how to use `tar(1)` in Unix, then you know how to use
157`require('tar')` in JavaScript.
158
159To replicate `tar czf my-tarball.tgz files and folders`, you'd do:
160
161```js
162tar.c(
163 {
164 gzip: <true|gzip options>,
165 file: 'my-tarball.tgz'
166 },
167 ['some', 'files', 'and', 'folders']
168).then(_ => { .. tarball has been created .. })
169```
170
171To replicate `tar cz files and folders > my-tarball.tgz`, you'd do:
172
173```js
174tar.c( // or tar.create
175 {
176 gzip: <true|gzip options>
177 },
178 ['some', 'files', 'and', 'folders']
179).pipe(fs.createWriteStream('my-tarball.tgz'))
180```
181
182To replicate `tar xf my-tarball.tgz` you'd do:
183
184```js
185tar.x( // or tar.extract(
186 {
187 file: 'my-tarball.tgz'
188 }
189).then(_=> { .. tarball has been dumped in cwd .. })
190```
191
192To replicate `cat my-tarball.tgz | tar x -C some-dir --strip=1`:
193
194```js
195fs.createReadStream('my-tarball.tgz').pipe(
196 tar.x({
197 strip: 1,
198 C: 'some-dir' // alias for cwd:'some-dir', also ok
199 })
200)
201```
202
203To replicate `tar tf my-tarball.tgz`, do this:
204
205```js
206tar.t({
207 file: 'my-tarball.tgz',
208 onentry: entry => { .. do whatever with it .. }
209})
210```
211
212To replicate `cat my-tarball.tgz | tar t` do:
213
214```js
215fs.createReadStream('my-tarball.tgz')
216 .pipe(tar.t())
217 .on('entry', entry => { .. do whatever with it .. })
218```
219
220To do anything synchronous, add `sync: true` to the options. Note
221that sync functions don't take a callback and don't return a promise.
222When the function returns, it's already done. Sync methods without a
223file argument return a sync stream, which flushes immediately. But,
224of course, it still won't be done until you `.end()` it.
225
226To filter entries, add `filter: <function>` to the options.
227Tar-creating methods call the filter with `filter(path, stat)`.
228Tar-reading methods (including extraction) call the filter with
229`filter(path, entry)`. The filter is called in the `this`-context of
230the `Pack` or `Unpack` stream object.
231
232The arguments list to `tar t` and `tar x` specify a list of filenames
233to extract or list, so they're equivalent to a filter that tests if
234the file is in the list.
235
236For those who _aren't_ fans of tar's single-character command names:
237
238```
239tar.c === tar.create
240tar.r === tar.replace (appends to archive, file is required)
241tar.u === tar.update (appends if newer, file is required)
242tar.x === tar.extract
243tar.t === tar.list
244```
245
246Keep reading for all the command descriptions and options, as well as
247the low-level API that they are built on.
248
249### tar.c(options, fileList, callback) [alias: tar.create]
250
251Create a tarball archive.
252
253The `fileList` is an array of paths to add to the tarball. Adding a
254directory also adds its children recursively.
255
256An entry in `fileList` that starts with an `@` symbol is a tar archive
257whose entries will be added. To add a file that starts with `@`,
258prepend it with `./`.
259
260The following options are supported:
261
262- `file` Write the tarball archive to the specified filename. If this
263 is specified, then the callback will be fired when the file has been
264 written, and a promise will be returned that resolves when the file
265 is written. If a filename is not specified, then a Readable Stream
266 will be returned which will emit the file data. [Alias: `f`]
267- `sync` Act synchronously. If this is set, then any provided file
268 will be fully written after the call to `tar.c`. If this is set,
269 and a file is not provided, then the resulting stream will already
270 have the data ready to `read` or `emit('data')` as soon as you
271 request it.
272- `onwarn` A function that will get called with `(code, message, data)` for
273 any warnings encountered. (See "Warnings and Errors")
274- `strict` Treat warnings as crash-worthy errors. Default false.
275- `cwd` The current working directory for creating the archive.
276 Defaults to `process.cwd()`. [Alias: `C`]
277- `prefix` A path portion to prefix onto the entries in the archive.
278- `gzip` Set to any truthy value to create a gzipped archive, or an
279 object with settings for `zlib.Gzip()` [Alias: `z`]
280- `filter` A function that gets called with `(path, stat)` for each
281 entry being added. Return `true` to add the entry to the archive,
282 or `false` to omit it.
283- `portable` Omit metadata that is system-specific: `ctime`, `atime`,
284 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note
285 that `mtime` is still included, because this is necessary for other
286 time-based operations. Additionally, `mode` is set to a "reasonable
287 default" for most unix systems, based on a `umask` value of `0o22`.
288- `preservePaths` Allow absolute paths. By default, `/` is stripped
289 from absolute paths. [Alias: `P`]
290- `mode` The mode to set on the created file archive
291- `noDirRecurse` Do not recursively archive the contents of
292 directories. [Alias: `n`]
293- `follow` Set to true to pack the targets of symbolic links. Without
294 this option, symbolic links are archived as such. [Alias: `L`, `h`]
295- `noPax` Suppress pax extended headers. Note that this means that
296 long paths and linkpaths will be truncated, and large or negative
297 numeric values may be interpreted incorrectly.
298- `noMtime` Set to true to omit writing `mtime` values for entries.
299 Note that this prevents using other mtime-based features like
300 `tar.update` or the `keepNewer` option with the resulting tar archive.
301 [Alias: `m`, `no-mtime`]
302- `mtime` Set to a `Date` object to force a specific `mtime` for
303 everything added to the archive. Overridden by `noMtime`.
304
305The following options are mostly internal, but can be modified in some
306advanced use cases, such as re-using caches between runs.
307
308- `linkCache` A Map object containing the device and inode value for
309 any file whose nlink is > 1, to identify hard links.
310- `statCache` A Map object that caches calls `lstat`.
311- `readdirCache` A Map object that caches calls to `readdir`.
312- `jobs` A number specifying how many concurrent jobs to run.
313 Defaults to 4.
314- `maxReadSize` The maximum buffer size for `fs.read()` operations.
315 Defaults to 16 MB.
316
317### tar.x(options, fileList, callback) [alias: tar.extract]
318
319Extract a tarball archive.
320
321The `fileList` is an array of paths to extract from the tarball. If
322no paths are provided, then all the entries are extracted.
323
324If the archive is gzipped, then tar will detect this and unzip it.
325
326Note that all directories that are created will be forced to be
327writable, readable, and listable by their owner, to avoid cases where
328a directory prevents extraction of child entries by virtue of its
329mode.
330
331Most extraction errors will cause a `warn` event to be emitted. If
332the `cwd` is missing, or not a directory, then the extraction will
333fail completely.
334
335The following options are supported:
336
337- `cwd` Extract files relative to the specified directory. Defaults
338 to `process.cwd()`. If provided, this must exist and must be a
339 directory. [Alias: `C`]
340- `file` The archive file to extract. If not specified, then a
341 Writable stream is returned where the archive data should be
342 written. [Alias: `f`]
343- `sync` Create files and directories synchronously.
344- `strict` Treat warnings as crash-worthy errors. Default false.
345- `filter` A function that gets called with `(path, entry)` for each
346 entry being unpacked. Return `true` to unpack the entry from the
347 archive, or `false` to skip it.
348- `newer` Set to true to keep the existing file on disk if it's newer
349 than the file in the archive. [Alias: `keep-newer`,
350 `keep-newer-files`]
351- `keep` Do not overwrite existing files. In particular, if a file
352 appears more than once in an archive, later copies will not
353 overwrite earlier copies. [Alias: `k`, `keep-existing`]
354- `preservePaths` Allow absolute paths, paths containing `..`, and
355 extracting through symbolic links. By default, `/` is stripped from
356 absolute paths, `..` paths are not extracted, and any file whose
357 location would be modified by a symbolic link is not extracted.
358 [Alias: `P`]
359- `unlink` Unlink files before creating them. Without this option,
360 tar overwrites existing files, which preserves existing hardlinks.
361 With this option, existing hardlinks will be broken, as will any
362 symlink that would affect the location of an extracted file. [Alias:
363 `U`]
364- `strip` Remove the specified number of leading path elements.
365 Pathnames with fewer elements will be silently skipped. Note that
366 the pathname is edited after applying the filter, but before
367 security checks. [Alias: `strip-components`, `stripComponents`]
368- `onwarn` A function that will get called with `(code, message, data)` for
369 any warnings encountered. (See "Warnings and Errors")
370- `preserveOwner` If true, tar will set the `uid` and `gid` of
371 extracted entries to the `uid` and `gid` fields in the archive.
372 This defaults to true when run as root, and false otherwise. If
373 false, then files and directories will be set with the owner and
374 group of the user running the process. This is similar to `-p` in
375 `tar(1)`, but ACLs and other system-specific data is never unpacked
376 in this implementation, and modes are set by default already.
377 [Alias: `p`]
378- `uid` Set to a number to force ownership of all extracted files and
379 folders, and all implicitly created directories, to be owned by the
380 specified user id, regardless of the `uid` field in the archive.
381 Cannot be used along with `preserveOwner`. Requires also setting a
382 `gid` option.
383- `gid` Set to a number to force ownership of all extracted files and
384 folders, and all implicitly created directories, to be owned by the
385 specified group id, regardless of the `gid` field in the archive.
386 Cannot be used along with `preserveOwner`. Requires also setting a
387 `uid` option.
388- `noMtime` Set to true to omit writing `mtime` value for extracted
389 entries. [Alias: `m`, `no-mtime`]
390- `transform` Provide a function that takes an `entry` object, and
391 returns a stream, or any falsey value. If a stream is provided,
392 then that stream's data will be written instead of the contents of
393 the archive entry. If a falsey value is provided, then the entry is
394 written to disk as normal. (To exclude items from extraction, use
395 the `filter` option described above.)
396- `onentry` A function that gets called with `(entry)` for each entry
397 that passes the filter.
398- `onwarn` A function that will get called with `(code, message, data)` for
399 any warnings encountered. (See "Warnings and Errors")
400- `noChmod` Set to true to omit calling `fs.chmod()` to ensure that the
401 extracted file matches the entry mode. This also suppresses the call to
402 `process.umask()` to determine the default umask value, since tar will
403 extract with whatever mode is provided, and let the process `umask` apply
404 normally.
405
406The following options are mostly internal, but can be modified in some
407advanced use cases, such as re-using caches between runs.
408
409- `maxReadSize` The maximum buffer size for `fs.read()` operations.
410 Defaults to 16 MB.
411- `umask` Filter the modes of entries like `process.umask()`.
412- `dmode` Default mode for directories
413- `fmode` Default mode for files
414- `dirCache` A Map object of which directories exist.
415- `maxMetaEntrySize` The maximum size of meta entries that is
416 supported. Defaults to 1 MB.
417
418Note that using an asynchronous stream type with the `transform`
419option will cause undefined behavior in sync extractions.
420[MiniPass](http://npm.im/minipass)-based streams are designed for this
421use case.
422
423### tar.t(options, fileList, callback) [alias: tar.list]
424
425List the contents of a tarball archive.
426
427The `fileList` is an array of paths to list from the tarball. If
428no paths are provided, then all the entries are listed.
429
430If the archive is gzipped, then tar will detect this and unzip it.
431
432Returns an event emitter that emits `entry` events with
433`tar.ReadEntry` objects. However, they don't emit `'data'` or `'end'`
434events. (If you want to get actual readable entries, use the
435`tar.Parse` class instead.)
436
437The following options are supported:
438
439- `cwd` Extract files relative to the specified directory. Defaults
440 to `process.cwd()`. [Alias: `C`]
441- `file` The archive file to list. If not specified, then a
442 Writable stream is returned where the archive data should be
443 written. [Alias: `f`]
444- `sync` Read the specified file synchronously. (This has no effect
445 when a file option isn't specified, because entries are emitted as
446 fast as they are parsed from the stream anyway.)
447- `strict` Treat warnings as crash-worthy errors. Default false.
448- `filter` A function that gets called with `(path, entry)` for each
449 entry being listed. Return `true` to emit the entry from the
450 archive, or `false` to skip it.
451- `onentry` A function that gets called with `(entry)` for each entry
452 that passes the filter. This is important for when both `file` and
453 `sync` are set, because it will be called synchronously.
454- `maxReadSize` The maximum buffer size for `fs.read()` operations.
455 Defaults to 16 MB.
456- `noResume` By default, `entry` streams are resumed immediately after
457 the call to `onentry`. Set `noResume: true` to suppress this
458 behavior. Note that by opting into this, the stream will never
459 complete until the entry data is consumed.
460- `onwarn` A function that will get called with `(code, message, data)` for
461 any warnings encountered. (See "Warnings and Errors")
462
463### tar.u(options, fileList, callback) [alias: tar.update]
464
465Add files to an archive if they are newer than the entry already in
466the tarball archive.
467
468The `fileList` is an array of paths to add to the tarball. Adding a
469directory also adds its children recursively.
470
471An entry in `fileList` that starts with an `@` symbol is a tar archive
472whose entries will be added. To add a file that starts with `@`,
473prepend it with `./`.
474
475The following options are supported:
476
477- `file` Required. Write the tarball archive to the specified
478 filename. [Alias: `f`]
479- `sync` Act synchronously. If this is set, then any provided file
480 will be fully written after the call to `tar.c`.
481- `onwarn` A function that will get called with `(code, message, data)` for
482 any warnings encountered. (See "Warnings and Errors")
483- `strict` Treat warnings as crash-worthy errors. Default false.
484- `cwd` The current working directory for adding entries to the
485 archive. Defaults to `process.cwd()`. [Alias: `C`]
486- `prefix` A path portion to prefix onto the entries in the archive.
487- `gzip` Set to any truthy value to create a gzipped archive, or an
488 object with settings for `zlib.Gzip()` [Alias: `z`]
489- `filter` A function that gets called with `(path, stat)` for each
490 entry being added. Return `true` to add the entry to the archive,
491 or `false` to omit it.
492- `portable` Omit metadata that is system-specific: `ctime`, `atime`,
493 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note
494 that `mtime` is still included, because this is necessary for other
495 time-based operations. Additionally, `mode` is set to a "reasonable
496 default" for most unix systems, based on a `umask` value of `0o22`.
497- `preservePaths` Allow absolute paths. By default, `/` is stripped
498 from absolute paths. [Alias: `P`]
499- `maxReadSize` The maximum buffer size for `fs.read()` operations.
500 Defaults to 16 MB.
501- `noDirRecurse` Do not recursively archive the contents of
502 directories. [Alias: `n`]
503- `follow` Set to true to pack the targets of symbolic links. Without
504 this option, symbolic links are archived as such. [Alias: `L`, `h`]
505- `noPax` Suppress pax extended headers. Note that this means that
506 long paths and linkpaths will be truncated, and large or negative
507 numeric values may be interpreted incorrectly.
508- `noMtime` Set to true to omit writing `mtime` values for entries.
509 Note that this prevents using other mtime-based features like
510 `tar.update` or the `keepNewer` option with the resulting tar archive.
511 [Alias: `m`, `no-mtime`]
512- `mtime` Set to a `Date` object to force a specific `mtime` for
513 everything added to the archive. Overridden by `noMtime`.
514
515### tar.r(options, fileList, callback) [alias: tar.replace]
516
517Add files to an existing archive. Because later entries override
518earlier entries, this effectively replaces any existing entries.
519
520The `fileList` is an array of paths to add to the tarball. Adding a
521directory also adds its children recursively.
522
523An entry in `fileList` that starts with an `@` symbol is a tar archive
524whose entries will be added. To add a file that starts with `@`,
525prepend it with `./`.
526
527The following options are supported:
528
529- `file` Required. Write the tarball archive to the specified
530 filename. [Alias: `f`]
531- `sync` Act synchronously. If this is set, then any provided file
532 will be fully written after the call to `tar.c`.
533- `onwarn` A function that will get called with `(code, message, data)` for
534 any warnings encountered. (See "Warnings and Errors")
535- `strict` Treat warnings as crash-worthy errors. Default false.
536- `cwd` The current working directory for adding entries to the
537 archive. Defaults to `process.cwd()`. [Alias: `C`]
538- `prefix` A path portion to prefix onto the entries in the archive.
539- `gzip` Set to any truthy value to create a gzipped archive, or an
540 object with settings for `zlib.Gzip()` [Alias: `z`]
541- `filter` A function that gets called with `(path, stat)` for each
542 entry being added. Return `true` to add the entry to the archive,
543 or `false` to omit it.
544- `portable` Omit metadata that is system-specific: `ctime`, `atime`,
545 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note
546 that `mtime` is still included, because this is necessary for other
547 time-based operations. Additionally, `mode` is set to a "reasonable
548 default" for most unix systems, based on a `umask` value of `0o22`.
549- `preservePaths` Allow absolute paths. By default, `/` is stripped
550 from absolute paths. [Alias: `P`]
551- `maxReadSize` The maximum buffer size for `fs.read()` operations.
552 Defaults to 16 MB.
553- `noDirRecurse` Do not recursively archive the contents of
554 directories. [Alias: `n`]
555- `follow` Set to true to pack the targets of symbolic links. Without
556 this option, symbolic links are archived as such. [Alias: `L`, `h`]
557- `noPax` Suppress pax extended headers. Note that this means that
558 long paths and linkpaths will be truncated, and large or negative
559 numeric values may be interpreted incorrectly.
560- `noMtime` Set to true to omit writing `mtime` values for entries.
561 Note that this prevents using other mtime-based features like
562 `tar.update` or the `keepNewer` option with the resulting tar archive.
563 [Alias: `m`, `no-mtime`]
564- `mtime` Set to a `Date` object to force a specific `mtime` for
565 everything added to the archive. Overridden by `noMtime`.
566
567
568## Low-Level API
569
570### class tar.Pack
571
572A readable tar stream.
573
574Has all the standard readable stream interface stuff. `'data'` and
575`'end'` events, `read()` method, `pause()` and `resume()`, etc.
576
577#### constructor(options)
578
579The following options are supported:
580
581- `onwarn` A function that will get called with `(code, message, data)` for
582 any warnings encountered. (See "Warnings and Errors")
583- `strict` Treat warnings as crash-worthy errors. Default false.
584- `cwd` The current working directory for creating the archive.
585 Defaults to `process.cwd()`.
586- `prefix` A path portion to prefix onto the entries in the archive.
587- `gzip` Set to any truthy value to create a gzipped archive, or an
588 object with settings for `zlib.Gzip()`
589- `filter` A function that gets called with `(path, stat)` for each
590 entry being added. Return `true` to add the entry to the archive,
591 or `false` to omit it.
592- `portable` Omit metadata that is system-specific: `ctime`, `atime`,
593 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note
594 that `mtime` is still included, because this is necessary for other
595 time-based operations. Additionally, `mode` is set to a "reasonable
596 default" for most unix systems, based on a `umask` value of `0o22`.
597- `preservePaths` Allow absolute paths. By default, `/` is stripped
598 from absolute paths.
599- `linkCache` A Map object containing the device and inode value for
600 any file whose nlink is > 1, to identify hard links.
601- `statCache` A Map object that caches calls `lstat`.
602- `readdirCache` A Map object that caches calls to `readdir`.
603- `jobs` A number specifying how many concurrent jobs to run.
604 Defaults to 4.
605- `maxReadSize` The maximum buffer size for `fs.read()` operations.
606 Defaults to 16 MB.
607- `noDirRecurse` Do not recursively archive the contents of
608 directories.
609- `follow` Set to true to pack the targets of symbolic links. Without
610 this option, symbolic links are archived as such.
611- `noPax` Suppress pax extended headers. Note that this means that
612 long paths and linkpaths will be truncated, and large or negative
613 numeric values may be interpreted incorrectly.
614- `noMtime` Set to true to omit writing `mtime` values for entries.
615 Note that this prevents using other mtime-based features like
616 `tar.update` or the `keepNewer` option with the resulting tar archive.
617- `mtime` Set to a `Date` object to force a specific `mtime` for
618 everything added to the archive. Overridden by `noMtime`.
619
620#### add(path)
621
622Adds an entry to the archive. Returns the Pack stream.
623
624#### write(path)
625
626Adds an entry to the archive. Returns true if flushed.
627
628#### end()
629
630Finishes the archive.
631
632### class tar.Pack.Sync
633
634Synchronous version of `tar.Pack`.
635
636### class tar.Unpack
637
638A writable stream that unpacks a tar archive onto the file system.
639
640All the normal writable stream stuff is supported. `write()` and
641`end()` methods, `'drain'` events, etc.
642
643Note that all directories that are created will be forced to be
644writable, readable, and listable by their owner, to avoid cases where
645a directory prevents extraction of child entries by virtue of its
646mode.
647
648`'close'` is emitted when it's done writing stuff to the file system.
649
650Most unpack errors will cause a `warn` event to be emitted. If the
651`cwd` is missing, or not a directory, then an error will be emitted.
652
653#### constructor(options)
654
655- `cwd` Extract files relative to the specified directory. Defaults
656 to `process.cwd()`. If provided, this must exist and must be a
657 directory.
658- `filter` A function that gets called with `(path, entry)` for each
659 entry being unpacked. Return `true` to unpack the entry from the
660 archive, or `false` to skip it.
661- `newer` Set to true to keep the existing file on disk if it's newer
662 than the file in the archive.
663- `keep` Do not overwrite existing files. In particular, if a file
664 appears more than once in an archive, later copies will not
665 overwrite earlier copies.
666- `preservePaths` Allow absolute paths, paths containing `..`, and
667 extracting through symbolic links. By default, `/` is stripped from
668 absolute paths, `..` paths are not extracted, and any file whose
669 location would be modified by a symbolic link is not extracted.
670- `unlink` Unlink files before creating them. Without this option,
671 tar overwrites existing files, which preserves existing hardlinks.
672 With this option, existing hardlinks will be broken, as will any
673 symlink that would affect the location of an extracted file.
674- `strip` Remove the specified number of leading path elements.
675 Pathnames with fewer elements will be silently skipped. Note that
676 the pathname is edited after applying the filter, but before
677 security checks.
678- `onwarn` A function that will get called with `(code, message, data)` for
679 any warnings encountered. (See "Warnings and Errors")
680- `umask` Filter the modes of entries like `process.umask()`.
681- `dmode` Default mode for directories
682- `fmode` Default mode for files
683- `dirCache` A Map object of which directories exist.
684- `maxMetaEntrySize` The maximum size of meta entries that is
685 supported. Defaults to 1 MB.
686- `preserveOwner` If true, tar will set the `uid` and `gid` of
687 extracted entries to the `uid` and `gid` fields in the archive.
688 This defaults to true when run as root, and false otherwise. If
689 false, then files and directories will be set with the owner and
690 group of the user running the process. This is similar to `-p` in
691 `tar(1)`, but ACLs and other system-specific data is never unpacked
692 in this implementation, and modes are set by default already.
693- `win32` True if on a windows platform. Causes behavior where
694 filenames containing `<|>?` chars are converted to
695 windows-compatible values while being unpacked.
696- `uid` Set to a number to force ownership of all extracted files and
697 folders, and all implicitly created directories, to be owned by the
698 specified user id, regardless of the `uid` field in the archive.
699 Cannot be used along with `preserveOwner`. Requires also setting a
700 `gid` option.
701- `gid` Set to a number to force ownership of all extracted files and
702 folders, and all implicitly created directories, to be owned by the
703 specified group id, regardless of the `gid` field in the archive.
704 Cannot be used along with `preserveOwner`. Requires also setting a
705 `uid` option.
706- `noMtime` Set to true to omit writing `mtime` value for extracted
707 entries.
708- `transform` Provide a function that takes an `entry` object, and
709 returns a stream, or any falsey value. If a stream is provided,
710 then that stream's data will be written instead of the contents of
711 the archive entry. If a falsey value is provided, then the entry is
712 written to disk as normal. (To exclude items from extraction, use
713 the `filter` option described above.)
714- `strict` Treat warnings as crash-worthy errors. Default false.
715- `onentry` A function that gets called with `(entry)` for each entry
716 that passes the filter.
717- `onwarn` A function that will get called with `(code, message, data)` for
718 any warnings encountered. (See "Warnings and Errors")
719- `noChmod` Set to true to omit calling `fs.chmod()` to ensure that the
720 extracted file matches the entry mode. This also suppresses the call to
721 `process.umask()` to determine the default umask value, since tar will
722 extract with whatever mode is provided, and let the process `umask` apply
723 normally.
724
725### class tar.Unpack.Sync
726
727Synchronous version of `tar.Unpack`.
728
729Note that using an asynchronous stream type with the `transform`
730option will cause undefined behavior in sync unpack streams.
731[MiniPass](http://npm.im/minipass)-based streams are designed for this
732use case.
733
734### class tar.Parse
735
736A writable stream that parses a tar archive stream. All the standard
737writable stream stuff is supported.
738
739If the archive is gzipped, then tar will detect this and unzip it.
740
741Emits `'entry'` events with `tar.ReadEntry` objects, which are
742themselves readable streams that you can pipe wherever.
743
744Each `entry` will not emit until the one before it is flushed through,
745so make sure to either consume the data (with `on('data', ...)` or
746`.pipe(...)`) or throw it away with `.resume()` to keep the stream
747flowing.
748
749#### constructor(options)
750
751Returns an event emitter that emits `entry` events with
752`tar.ReadEntry` objects.
753
754The following options are supported:
755
756- `strict` Treat warnings as crash-worthy errors. Default false.
757- `filter` A function that gets called with `(path, entry)` for each
758 entry being listed. Return `true` to emit the entry from the
759 archive, or `false` to skip it.
760- `onentry` A function that gets called with `(entry)` for each entry
761 that passes the filter.
762- `onwarn` A function that will get called with `(code, message, data)` for
763 any warnings encountered. (See "Warnings and Errors")
764
765#### abort(error)
766
767Stop all parsing activities. This is called when there are zlib
768errors. It also emits an unrecoverable warning with the error provided.
769
770### class tar.ReadEntry extends [MiniPass](http://npm.im/minipass)
771
772A representation of an entry that is being read out of a tar archive.
773
774It has the following fields:
775
776- `extended` The extended metadata object provided to the constructor.
777- `globalExtended` The global extended metadata object provided to the
778 constructor.
779- `remain` The number of bytes remaining to be written into the
780 stream.
781- `blockRemain` The number of 512-byte blocks remaining to be written
782 into the stream.
783- `ignore` Whether this entry should be ignored.
784- `meta` True if this represents metadata about the next entry, false
785 if it represents a filesystem object.
786- All the fields from the header, extended header, and global extended
787 header are added to the ReadEntry object. So it has `path`, `type`,
788 `size`, `mode`, and so on.
789
790#### constructor(header, extended, globalExtended)
791
792Create a new ReadEntry object with the specified header, extended
793header, and global extended header values.
794
795### class tar.WriteEntry extends [MiniPass](http://npm.im/minipass)
796
797A representation of an entry that is being written from the file
798system into a tar archive.
799
800Emits data for the Header, and for the Pax Extended Header if one is
801required, as well as any body data.
802
803Creating a WriteEntry for a directory does not also create
804WriteEntry objects for all of the directory contents.
805
806It has the following fields:
807
808- `path` The path field that will be written to the archive. By
809 default, this is also the path from the cwd to the file system
810 object.
811- `portable` Omit metadata that is system-specific: `ctime`, `atime`,
812 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note
813 that `mtime` is still included, because this is necessary for other
814 time-based operations. Additionally, `mode` is set to a "reasonable
815 default" for most unix systems, based on a `umask` value of `0o22`.
816- `myuid` If supported, the uid of the user running the current
817 process.
818- `myuser` The `env.USER` string if set, or `''`. Set as the entry
819 `uname` field if the file's `uid` matches `this.myuid`.
820- `maxReadSize` The maximum buffer size for `fs.read()` operations.
821 Defaults to 1 MB.
822- `linkCache` A Map object containing the device and inode value for
823 any file whose nlink is > 1, to identify hard links.
824- `statCache` A Map object that caches calls `lstat`.
825- `preservePaths` Allow absolute paths. By default, `/` is stripped
826 from absolute paths.
827- `cwd` The current working directory for creating the archive.
828 Defaults to `process.cwd()`.
829- `absolute` The absolute path to the entry on the filesystem. By
830 default, this is `path.resolve(this.cwd, this.path)`, but it can be
831 overridden explicitly.
832- `strict` Treat warnings as crash-worthy errors. Default false.
833- `win32` True if on a windows platform. Causes behavior where paths
834 replace `\` with `/` and filenames containing the windows-compatible
835 forms of `<|>?:` characters are converted to actual `<|>?:` characters
836 in the archive.
837- `noPax` Suppress pax extended headers. Note that this means that
838 long paths and linkpaths will be truncated, and large or negative
839 numeric values may be interpreted incorrectly.
840- `noMtime` Set to true to omit writing `mtime` values for entries.
841 Note that this prevents using other mtime-based features like
842 `tar.update` or the `keepNewer` option with the resulting tar archive.
843
844
845#### constructor(path, options)
846
847`path` is the path of the entry as it is written in the archive.
848
849The following options are supported:
850
851- `portable` Omit metadata that is system-specific: `ctime`, `atime`,
852 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note
853 that `mtime` is still included, because this is necessary for other
854 time-based operations. Additionally, `mode` is set to a "reasonable
855 default" for most unix systems, based on a `umask` value of `0o22`.
856- `maxReadSize` The maximum buffer size for `fs.read()` operations.
857 Defaults to 1 MB.
858- `linkCache` A Map object containing the device and inode value for
859 any file whose nlink is > 1, to identify hard links.
860- `statCache` A Map object that caches calls `lstat`.
861- `preservePaths` Allow absolute paths. By default, `/` is stripped
862 from absolute paths.
863- `cwd` The current working directory for creating the archive.
864 Defaults to `process.cwd()`.
865- `absolute` The absolute path to the entry on the filesystem. By
866 default, this is `path.resolve(this.cwd, this.path)`, but it can be
867 overridden explicitly.
868- `strict` Treat warnings as crash-worthy errors. Default false.
869- `win32` True if on a windows platform. Causes behavior where paths
870 replace `\` with `/`.
871- `onwarn` A function that will get called with `(code, message, data)` for
872 any warnings encountered. (See "Warnings and Errors")
873- `noMtime` Set to true to omit writing `mtime` values for entries.
874 Note that this prevents using other mtime-based features like
875 `tar.update` or the `keepNewer` option with the resulting tar archive.
876- `umask` Set to restrict the modes on the entries in the archive,
877 somewhat like how umask works on file creation. Defaults to
878 `process.umask()` on unix systems, or `0o22` on Windows.
879
880#### warn(message, data)
881
882If strict, emit an error with the provided message.
883
884Othewise, emit a `'warn'` event with the provided message and data.
885
886### class tar.WriteEntry.Sync
887
888Synchronous version of tar.WriteEntry
889
890### class tar.WriteEntry.Tar
891
892A version of tar.WriteEntry that gets its data from a tar.ReadEntry
893instead of from the filesystem.
894
895#### constructor(readEntry, options)
896
897`readEntry` is the entry being read out of another archive.
898
899The following options are supported:
900
901- `portable` Omit metadata that is system-specific: `ctime`, `atime`,
902 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note
903 that `mtime` is still included, because this is necessary for other
904 time-based operations. Additionally, `mode` is set to a "reasonable
905 default" for most unix systems, based on a `umask` value of `0o22`.
906- `preservePaths` Allow absolute paths. By default, `/` is stripped
907 from absolute paths.
908- `strict` Treat warnings as crash-worthy errors. Default false.
909- `onwarn` A function that will get called with `(code, message, data)` for
910 any warnings encountered. (See "Warnings and Errors")
911- `noMtime` Set to true to omit writing `mtime` values for entries.
912 Note that this prevents using other mtime-based features like
913 `tar.update` or the `keepNewer` option with the resulting tar archive.
914
915### class tar.Header
916
917A class for reading and writing header blocks.
918
919It has the following fields:
920
921- `nullBlock` True if decoding a block which is entirely composed of
922 `0x00` null bytes. (Useful because tar files are terminated by
923 at least 2 null blocks.)
924- `cksumValid` True if the checksum in the header is valid, false
925 otherwise.
926- `needPax` True if the values, as encoded, will require a Pax
927 extended header.
928- `path` The path of the entry.
929- `mode` The 4 lowest-order octal digits of the file mode. That is,
930 read/write/execute permissions for world, group, and owner, and the
931 setuid, setgid, and sticky bits.
932- `uid` Numeric user id of the file owner
933- `gid` Numeric group id of the file owner
934- `size` Size of the file in bytes
935- `mtime` Modified time of the file
936- `cksum` The checksum of the header. This is generated by adding all
937 the bytes of the header block, treating the checksum field itself as
938 all ascii space characters (that is, `0x20`).
939- `type` The human-readable name of the type of entry this represents,
940 or the alphanumeric key if unknown.
941- `typeKey` The alphanumeric key for the type of entry this header
942 represents.
943- `linkpath` The target of Link and SymbolicLink entries.
944- `uname` Human-readable user name of the file owner
945- `gname` Human-readable group name of the file owner
946- `devmaj` The major portion of the device number. Always `0` for
947 files, directories, and links.
948- `devmin` The minor portion of the device number. Always `0` for
949 files, directories, and links.
950- `atime` File access time.
951- `ctime` File change time.
952
953#### constructor(data, [offset=0])
954
955`data` is optional. It is either a Buffer that should be interpreted
956as a tar Header starting at the specified offset and continuing for
957512 bytes, or a data object of keys and values to set on the header
958object, and eventually encode as a tar Header.
959
960#### decode(block, offset)
961
962Decode the provided buffer starting at the specified offset.
963
964Buffer length must be greater than 512 bytes.
965
966#### set(data)
967
968Set the fields in the data object.
969
970#### encode(buffer, offset)
971
972Encode the header fields into the buffer at the specified offset.
973
974Returns `this.needPax` to indicate whether a Pax Extended Header is
975required to properly encode the specified data.
976
977### class tar.Pax
978
979An object representing a set of key-value pairs in an Pax extended
980header entry.
981
982It has the following fields. Where the same name is used, they have
983the same semantics as the tar.Header field of the same name.
984
985- `global` True if this represents a global extended header, or false
986 if it is for a single entry.
987- `atime`
988- `charset`
989- `comment`
990- `ctime`
991- `gid`
992- `gname`
993- `linkpath`
994- `mtime`
995- `path`
996- `size`
997- `uid`
998- `uname`
999- `dev`
1000- `ino`
1001- `nlink`
1002
1003#### constructor(object, global)
1004
1005Set the fields set in the object. `global` is a boolean that defaults
1006to false.
1007
1008#### encode()
1009
1010Return a Buffer containing the header and body for the Pax extended
1011header entry, or `null` if there is nothing to encode.
1012
1013#### encodeBody()
1014
1015Return a string representing the body of the pax extended header
1016entry.
1017
1018#### encodeField(fieldName)
1019
1020Return a string representing the key/value encoding for the specified
1021fieldName, or `''` if the field is unset.
1022
1023### tar.Pax.parse(string, extended, global)
1024
1025Return a new Pax object created by parsing the contents of the string
1026provided.
1027
1028If the `extended` object is set, then also add the fields from that
1029object. (This is necessary because multiple metadata entries can
1030occur in sequence.)
1031
1032### tar.types
1033
1034A translation table for the `type` field in tar headers.
1035
1036#### tar.types.name.get(code)
1037
1038Get the human-readable name for a given alphanumeric code.
1039
1040#### tar.types.code.get(name)
1041
1042Get the alphanumeric code for a given human-readable name.
Note: See TracBrowser for help on using the repository browser.