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