Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
lib/ | 12-May-2024 | - | 4,000 | 3,126 | ||
node_modules/ | 12-May-2024 | - | 2,891 | 2,228 | ||
LICENSE | D | 12-May-2024 | 765 | 16 | 12 | |
README.md | D | 12-May-2024 | 38.5 KiB | 955 | 774 | |
index.js | D | 12-May-2024 | 683 | 19 | 14 | |
package.json | D | 12-May-2024 | 2.3 KiB | 92 | 91 |
README.md
1# node-tar 2 3[](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