Document the bundle command

4 files changed, 197 insertions, 0 deletions

diff --git a/doc/bundle.md b/doc/bundle.md
new file mode 100644
index 000000000..b630c1d65
--- /dev/null
+++ b/doc/bundle.md
@@ -0,0 +1,70 @@
+npm-bundle(1) -- Bundle package dependencies
+============================================
+
+## EXPERIMENTAL
+
+This is experimental functionality.  If you have thoughts about how it
+should work, please post a comment at:
+http://github.com/isaacs/npm/issues/issue/74
+
+## SYNOPSIS
+
+    npm bundle <folder> [<pkg>]
+
+* `<folder>`:
+  The place where bundled dependencies go.
+* `<pkg>`:
+  The package whose dependencies are to be bundled. Defaults to $PWD.
+  See `npm help install` for more on the ways to identify a package.
+
+## DESCRIPTION
+
+Bundles all the dependencies of a package into a specific folder.
+
+Furthermore, sets up an index.js in the folder that will shift it onto the
+require.paths, and export the bundled modules.
+
+For example, to install of your requirements into a "deps" folder,
+you could do this:
+
+    npm bundle deps
+
+Assuming your code is in the "lib" folder, and it depended on a package
+"foo", you could then do this:
+
+    require("../deps") // this sets the require.paths properly.
+    var foo = require("foo")
+
+The bundle index will also return the modules that your package
+depends on.  So, this would work as well:
+
+    require("../deps").foo.createFoo(...)
+
+The dependencies of those packages installed will also be installed and
+linked, just like an `npm install` command.  In fact, internally `buffer`
+just sets the `root` config and then does a normal `npm install` to put
+the modules in place.
+
+To update to new versions (or if the dependencies change) then run the
+bundle command again.
+
+## CAVEATS
+
+There is no pretty to "remove" a package from a bundle at the moment.
+However, you can do this:
+
+    npm --root ./deps rm foo
+
+Bins and man pages are not installed by bundle.
+
+Packages are *built*, which often means they're compiled in that
+architecture and against that version of node.  To update them, you can
+do:
+
+    npm --root ./deps rebuild
+
+or run `npm bundle deps` on the target machine.
+
+The `npm update` command will do *horrible* things to a bundle folder.
+Don't ever point update at that root, or your bundles may no longer
+satisfy your dependencies.
diff --git a/doc/help.md b/doc/help.md
index 0db8c1c62..69b20d6f2 100644
--- a/doc/help.md
+++ b/doc/help.md
@@ -11,6 +11,7 @@ npm-help(1) -- Get help about npm commands
 activate
 adduser
 build
+bundle
 cache
 coding-style
 config
diff --git a/man/bundle.1 b/man/bundle.1
new file mode 100644
index 000000000..23c3e25d3
--- /dev/null
+++ b/man/bundle.1
@@ -0,0 +1,125 @@
+.\" Generated with Ronnjs/v0.1
+.\" http://github.com/kapouer/ronnjs/
+.
+.TH "NPM\-BUNDLE" "1" "August 2010" "" ""
+.
+.SH "NAME"
+\fBnpm-bundle\fR \-\- Bundle package dependencies
+.
+.SH "EXPERIMENTAL"
+This is experimental functionality\.  If you have thoughts about how it
+should work, please post a comment at:
+http://github\.com/isaacs/npm/issues/issue/74
+.
+.SH "SYNOPSIS"
+.
+.nf
+npm bundle <folder> [<pkg>]
+.
+.fi
+.
+.IP "\(bu" 4
+\fB<folder>\fR:
+The place where bundled dependencies go\.
+.
+.IP "\(bu" 4
+\fB<pkg>\fR:
+The package whose dependencies are to be bundled\. Defaults to $PWD\.
+See \fBnpm help install\fR for more on the ways to identify a package\.
+.
+.IP "" 0
+.
+.SH "DESCRIPTION"
+Bundles all the dependencies of a package into a specific folder\.
+.
+.P
+Furthermore, sets up an index\.js in the folder that will shift it onto the
+require\.paths, and export the bundled modules\.
+.
+.P
+For example, to install of your requirements into a "deps" folder,
+you could do this:
+.
+.IP "" 4
+.
+.nf
+npm bundle deps
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Assuming your code is in the "lib" folder, and it depended on a package
+"foo", you could then do this:
+.
+.IP "" 4
+.
+.nf
+require("\.\./deps") // this sets the require\.paths properly\.
+var foo = require("foo")
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The bundle index will also return the modules that your package
+depends on\.  So, this would work as well:
+.
+.IP "" 4
+.
+.nf
+require("\.\./deps")\.foo\.createFoo(\.\.\.)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The dependencies of those packages installed will also be installed and
+linked, just like an \fBnpm install\fR command\.  In fact, internally \fBbuffer\fR
+just sets the \fBroot\fR config and then does a normal \fBnpm install\fR to put
+the modules in place\.
+.
+.P
+To update to new versions (or if the dependencies change) then run the
+bundle command again\.
+.
+.SH "CAVEATS"
+There is no pretty to "remove" a package from a bundle at the moment\.
+However, you can do this:
+.
+.IP "" 4
+.
+.nf
+npm \-\-root \./deps rm foo
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Bins and man pages are not installed by bundle\.
+.
+.P
+Packages are \fIbuilt\fR, which often means they\'re compiled in that
+architecture and against that version of node\.  To update them, you can
+do:
+.
+.IP "" 4
+.
+.nf
+npm \-\-root \./deps rebuild
+.
+.fi
+.
+.IP "" 0
+.
+.P
+or run \fBnpm bundle deps\fR on the target machine\.
+.
+.P
+The \fBnpm update\fR command will do \fIhorrible\fR things to a bundle folder\.
+Don\'t ever point update at that root, or your bundles may no longer
+satisfy your dependencies\.
diff --git a/man/help.1 b/man/help.1
index f17a638cf..b19817ccb 100644
--- a/man/help.1
+++ b/man/help.1
@@ -18,6 +18,7 @@ npm help <section>
 activate
 adduser
 build
+bundle
 cache
 coding\-style
 config