tar
Advanced tools
Comparing version 0.1.18 to 0.1.19
@@ -5,3 +5,3 @@ { | ||
"description": "tar for node", | ||
"version": "0.1.18", | ||
"version": "0.1.19", | ||
"repository": { | ||
@@ -8,0 +8,0 @@ "type": "git", |
@@ -5,44 +5,43 @@ # node-tar | ||
## Goals of this project | ||
[![NPM](https://nodei.co/npm/tar.png)](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`. |
143980
47