Permalink
Browse files

make doc

  • Loading branch information...
isaacs committed Jan 5, 2011
1 parent 7081f3e commit 39985c8f615441bea88db878cf99819d9619a1ad
Showing with 211 additions and 11 deletions.
  1. +41 −0 man1/config.1
  2. +41 −0 man1/get.1
  3. +41 −1 man1/json.1
  4. +47 −10 man1/scripts.1
  5. +41 −0 man1/set.1
View
@@ -107,6 +107,47 @@ npm config edit
.P
Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the global config\.
.
+.SH "Per\-Package Config Settings"
+When running scripts (see \fBnpm help scripts\fR)
+the package\.json "config" keys are overwritten in the environment if
+there is a config param of \fB<name>[@<version>]:<key>\fR\|\. For example, if
+the package\.json has this:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "config" : { "port" : "8080" }
+, "scripts" : { "start" : "node server\.js" } }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+and the server\.js is this:
+.
+.IP "" 4
+.
+.nf
+http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+then the user could change the behavior by doing:
+.
+.IP "" 4
+.
+.nf
+npm config set foo:port 80
+.
+.fi
+.
+.IP "" 0
+.
.SH "Config Settings"
npm supports a very basic argument parser\. For any of the settings
in npm\-config(1), you can set them explicitly for a single command by
View
@@ -107,6 +107,47 @@ npm config edit
.P
Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the global config\.
.
+.SH "Per\-Package Config Settings"
+When running scripts (see \fBnpm help scripts\fR)
+the package\.json "config" keys are overwritten in the environment if
+there is a config param of \fB<name>[@<version>]:<key>\fR\|\. For example, if
+the package\.json has this:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "config" : { "port" : "8080" }
+, "scripts" : { "start" : "node server\.js" } }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+and the server\.js is this:
+.
+.IP "" 4
+.
+.nf
+http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+then the user could change the behavior by doing:
+.
+.IP "" 4
+.
+.nf
+npm config set foo:port 80
+.
+.fi
+.
+.IP "" 0
+.
.SH "Config Settings"
npm supports a very basic argument parser\. For any of the settings
in npm\-config(1), you can set them explicitly for a single command by
View
@@ -1,7 +1,7 @@
.\" Generated with Ronnjs/v0.1
.\" http://github.com/kapouer/ronnjs/
.
-.TH "NPM\-JSON" "1" "December 2010" "" ""
+.TH "NPM\-JSON" "1" "January 2011" "" ""
.
.SH "NAME"
\fBnpm-json\fR \-\- Specifics of npm\'s package\.json handling
@@ -124,6 +124,23 @@ Both email and url are optional either way\.
.P
npm also sets a top\-level "maintainers" field with your npm user info\.
.
+.SH "files"
+The "files" field is an array of files to include in your project\. If
+you name a folder in the array, then it will also include the files
+inside that folder\. The default is just \fB[""]\fR which includes the
+entire package folder in the tarball, but you may want to only include
+specific things\.
+.
+.P
+If you specify modules, bins, or man pages, then those will be
+automatically added to the files array, even if they would not
+ordinarily be included\.
+.
+.P
+You can also provide a "\.npmignore" file in the root of your package,
+which will keep files from being included, even if they would be picked
+up by the files array\.
+.
.SH "main"
The main field is a module ID that is the primary entry point to your program\.
That is, if your package is named \fBfoo\fR, and a user installs it, and then does \fBrequire("foo")\fR, then your main module\'s exports object will be returned\.
@@ -384,6 +401,29 @@ event, and the value is the command to run at that point\.
.P
See \fBnpm help scripts\fR to find out more about writing package scripts\.
.
+.SH "config"
+A "config" hash can be used to set configuration
+parameters used in package scripts that persist across upgrades\. For
+instance, if a package had the following:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "config" : { "port" : "8080" } }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+and then had a "start" command that then referenced the \fBnpm_package_config_port\fR environment variable, then the user could
+override that by doing \fBnpm config set foo:port 8001\fR\|\.
+.
+.P
+See \fBnpm help config\fR and \fBnpm help scripts\fR for more on package
+configs\.
+.
.SH "dependencies"
Dependencies are specified with a simple hash of package name to version
range\. The version range is EITHER a string with has one or more
View
@@ -1,7 +1,7 @@
.\" Generated with Ronnjs/v0.1
.\" http://github.com/kapouer/ronnjs/
.
-.TH "NPM\-SCRIPTS" "1" "December 2010" "" ""
+.TH "NPM\-SCRIPTS" "1" "January 2011" "" ""
.
.SH "NAME"
\fBnpm-scripts\fR \-\- How npm handles the "scripts" field
@@ -81,29 +81,66 @@ stop and start scripts if no \fBrestart\fR script is provided\.
Additionally, arbitrary scrips can be run by doing \fBnpm run\-script <stage> <pkg>\fR\|\.
.
.SH "ENVIRONMENT"
-Package scripts run in an environment where many pieces of information are made available regarding the setup of npm and the current state of the process\.
+Package scripts run in an environment where many pieces of information are
+made available regarding the setup of npm and the current state of the
+process\.
.
-.IP "\(bu" 4
-package\.json vars:
+.SS "package\.json vars"
The package\.json fields are tacked onto the \fBnpm_package_\fR prefix\. So, for
instance, if you had \fB{"name":"foo", "version":"1\.2\.5"}\fR in your package\.json
file, then your package scripts would have the \fBnpm_package_name\fR environment
variable set to "foo", and the \fBnpm_package_version\fR set to "1\.2\.5"
.
-.IP "\(bu" 4
-configuration vars:
+.SS "configuration"
Configuration parameters are put in the environment with the \fBnpm_config_\fR
prefix\. For instance, you can view the effective \fBroot\fR config by checking the \fBnpm_config_root\fR environment variable\.
.
-.IP "\(bu" 4
-current lifecycle event:
+.SS "Special: package\.json "config" hash"
+The package\.json "config" keys are overwritten in the environment if
+there is a config param of \fB<name>[@<version>]:<key>\fR\|\. For example, if
+the package\.json has this:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "config" : { "port" : "8080" }
+, "scripts" : { "start" : "node server\.js" } }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+and the server\.js is this:
+.
+.IP "" 4
+.
+.nf
+http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+then the user could change the behavior by doing:
+.
+.IP "" 4
+.
+.nf
+npm config set foo:port 80
+.
+.fi
+.
+.IP "" 0
+.
+.SS "current lifecycle event"
Lastly, the \fBnpm_lifecycle_event\fR environment variable is set to whichever
stage of the cycle is being executed\. So, you could have a single script used
for different parts of the process which switches based on what\'s currently
happening\.
.
-.IP "" 0
-.
.P
Objects are flattened following this format, so if you had \fB{"scripts":{"install":"foo\.js"}}\fR in your package\.json, then you\'d see this
in the script:
View
@@ -107,6 +107,47 @@ npm config edit
.P
Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the global config\.
.
+.SH "Per\-Package Config Settings"
+When running scripts (see \fBnpm help scripts\fR)
+the package\.json "config" keys are overwritten in the environment if
+there is a config param of \fB<name>[@<version>]:<key>\fR\|\. For example, if
+the package\.json has this:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "config" : { "port" : "8080" }
+, "scripts" : { "start" : "node server\.js" } }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+and the server\.js is this:
+.
+.IP "" 4
+.
+.nf
+http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+then the user could change the behavior by doing:
+.
+.IP "" 4
+.
+.nf
+npm config set foo:port 80
+.
+.fi
+.
+.IP "" 0
+.
.SH "Config Settings"
npm supports a very basic argument parser\. For any of the settings
in npm\-config(1), you can set them explicitly for a single command by

0 comments on commit 39985c8

Please sign in to comment.