From 315814b52e6c2e27d062547dc02c0c3965816997 Mon Sep 17 00:00:00 2001
From: Mathias Buus <mathiasbuus@gmail.com>
Date: Fri, 20 Dec 2013 20:50:02 +0100
Subject: [PATCH] added modification example

---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 8c92da8..561a351 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # tar-stream
 
-tar-stream is a streaming tar parser and generator and nothing else. It is streams2 and operates purely using streams which means you can extract/parse tarballs without ever hitting the file system. 
+tar-stream is a streaming tar parser and generator and nothing else. It is streams2 and operates purely using streams which means easily you can extract/parse tarballs without ever hitting the file system. 
 
 	npm install tar-stream
 
@@ -14,21 +14,21 @@ To create a pack stream use `tar.pack()` and call `pack.entry(header, [callback]
 
 ``` js
 var tar = require('tar-stream');
-var p = tar.pack(); // p is a streams2 stream
+var pack = tar.pack(); // p is a streams2 stream
 
 // add a file called my-test.txt with the content "Hello World!"
-p.entry({ name: 'my-test.txt' }, 'Hello World!');
+pack.entry({ name: 'my-test.txt' }, 'Hello World!');
 
 // add a file called my-stream-test.txt from a stream
-myStream.pipe(p.entry({ name: 'my-stream-test.txt' }, function(err) {
+myStream.pipe(pack.entry({ name: 'my-stream-test.txt' }, function(err) {
 	// the stream was added
 }));
 
 // no more entries
-p.finalize();
+pack.finalize();
 
 // pipe the pack stream somewhere
-p.pipe(process.stdout);
+pack.pipe(process.stdout);
 ```
 
 ## Extracting
@@ -36,9 +36,9 @@ p.pipe(process.stdout);
 To extract a stream use `tar.extract()` and listen for `extract.on('entry', header, stream, callback)`
 
 ``` js
-var e = tar.extract();
+var extract = tar.extract();
 
-e.on('entry', function(header, stream, callback) {
+extract.on('entry', function(header, stream, callback) {
 	// header is the tar header
 	// stream is the content body (might be an empty stream)
 	// call callback when you are done with this entry
@@ -49,11 +49,39 @@ e.on('entry', function(header, stream, callback) {
 	});
 });
 
-e.on('finish', function() {
+extract.on('finish', function() {
 	// all entries read
 });
 
-packStream.pipe(e);
+pack.pipe(extract);
+```
+
+## Modifying existing tarballs
+
+Using tar-stream it is easy to rewrite paths / change modes etc in an existing tarball.
+
+``` js
+var extract = tar.extract();
+var pack = tar.pack();
+var path = require('path');
+
+extract.on('entry', function(header, stream, callback) {
+	// let's prefix all names with 'tmp'
+	header.name = path.join('tmp', header.name);
+	// write the new entry to the pack stream
+	stream.pipe(pack.entry(header, callback));
+});
+
+extract.on('finish', function() {
+	// all entries done - lets finalize it
+	pack.finalize();
+});
+
+// pipe the old tarball to the extractor
+oldTarball.pipe(extract);
+
+// pipe the new tarball the another stream
+pack.pipe(newTarball);
 ```
 
 ## Headers