diff options
Diffstat (limited to 'deps/npm/node_modules/tar/README.md')
| -rw-r--r-- | deps/npm/node_modules/tar/README.md | 57 |
1 files changed, 28 insertions, 29 deletions
diff --git a/deps/npm/node_modules/tar/README.md b/deps/npm/node_modules/tar/README.md index c6b0f829ee..5bcc82cd89 100644 --- a/deps/npm/node_modules/tar/README.md +++ b/deps/npm/node_modules/tar/README.md @@ -2,46 +2,45 @@ Tar for Node.js. -## Goals of this project +[](https://nodei.co/npm/tar/) -1. Be able to parse and reasonably extract the contents of any tar file - created by any program that creates tar files, period. +## API - At least, this includes every version of: +See `examples/` for usage examples. - * bsdtar - * gnutar - * solaris posix tar - * Joerg Schilling's star ("Schilly tar") +### var tar = require('tar') -2. Create tar files that can be extracted by any of the following tar programs: +Returns an object with `.Pack`, `.Extract` and `.Parse` methods. - * bsdtar/libarchive version 2.6.2 - * gnutar 1.15 and above - * SunOS Posix tar - * Joerg Schilling's star ("Schilly tar") +### tar.Pack([properties]) -3. 100% test coverage. Speed is important. Correctness is slightly more important. +Returns a through stream. Use +[fstream](https://npmjs.org/package/fstream) to write files into the +pack stream and you will receive tar archive data from the pack +stream. -4. Create the kind of tar interface that Node users would want to use. +The optional `properties` object are used to set properties in the tar +'Global Extended Header'. -5. Satisfy npm's needs for a portable tar implementation with a JavaScript interface. +### tar.Extract([options]) -6. No excuses. No complaining. No tolerance for failure. +Returns a through stream. Write tar data to the stream and the files +in the tarball will be extracted onto the filesystem. -## But isn't there already a tar.js? +`options` can be: -Yes, there are a few. This one is going to be better, and it will be -fanatically maintained, because npm will depend on it. +```js +{ + path: '/path/to/extract/tar/into', + strip: 0, // how many path segments to strip from the root when extracting +} +``` -That's why I need to write it from scratch. Creating and extracting -tarballs is such a large part of what npm does, I simply can't have it -be a black box any longer. +`options` also get passed to the `fstream.Writer` instance that `tar` +uses internally. -## Didn't you have something already? Where'd it go? +### tar.Parse() -It's in the "old" folder. It's not functional. Don't use it. - -It was a useful exploration to learn the issues involved, but like most -software of any reasonable complexity, node-tar won't be useful until -it's been written at least 3 times. +Returns a writable stream. Write tar data to it and it will emit +`entry` events for each entry parsed from the tarball. This is used by +`tar.Extract`. |