documentation + most short lived major so far (but this way is better)

CHANGELOG.md

@@ -1,5 +1,13 @@
+2.0.0 / 2015-03-28
+=================
+  * Dry run flag removed. Dry run is now the default.
+  * Execute flag added `-e` or `--execute`.
+  * Perform linking with either:
+   1. `symlink repoDirs | sh`
+   2. `symlink repoDirs --execute` (will log a little more)
+
 1.1.0 / 2015-03-28
-==================
+=================
   * Swap optimist for yargs and improve command line usage
   * Errors from child_process calls in CLI now result in non-zero return code
 

README.md

@@ -4,124 +4,92 @@
 [![dependency status](https://david-dm.org/clux/symlink.svg)](https://david-dm.org/clux/symlink)
 [![coverage status](http://img.shields.io/coveralls/clux/symlink.svg)](https://coveralls.io/r/clux/symlink)
 
-- Have lots of personal node modules?
-- Do you `npm link` them together to ensure they all work with latest while developing?
-- Find the process of linking together multiple modules tedious? (fresh os install / new build environment checkout)
+- Manage lots of node modules?
+- Do you `npm link` multiple modules together to ensure they all work with latest while developing?
+- Find the process of linking together multiple modules tedious?
 
 If you answered YES to all the above, then this module is for you.
 
 ## Usage
-Install, then give it a set of directories containing packages that you would like to link together (will take all subfolders that contain a package.json).
+Install, then give it a set of directories containing packages that you would like to link together (will parse all immediate subdirectories containing a package.json).
 
 ```bash
 npm install -g symlink
-symlink repoDir --dry-run
+symlink repoDir # prints a list of commands
 ```
 
 ## What it does
 
 - reads the `package.json` of each module founds in the given directory and collects their `dependencies` and `devDependencies`
-- figures out which deps are local (in one of the repoDirs)
+- figures out which deps are local (present on one of the repoDirs)
 - figures out which deps are external (complement)
 - orders the modules so that linking can be in a safe order without having to query npmjs.org more than necessary
 
-Once everything has been ordered, a bunch of child processes are executed in series for each module from the order of least inclusion;
+Once everything has been ordered, a bunch of commands are generated for each module from the order of least inclusion;
 
 - `npm link (localDeps) ∪ ((globals ∩ externalDeps))`
 - `npm install (externalDeps ∖ globals)`
 - `npm link`
 
 I.e. link in all locally available dependencies + extenal globals that were requested explicitly, install the rest, then link the module itself so the modules with more inclusions can safely link the module in.
 
+## Execute
+To execute these commands in series run symlink with the `--execute` flag (to get a log per command) or pipe to `sh` for hardcore mode.
+
+```sh
+symlink repoDir --execute
+```
+
 ## Example
-When I reinstall my linux, I git clone all my repos and let symlink figure out a safe order of commands and perform the following list of actions sequentially via `child_process`;
+Linking together the related tournament modules from [clux](https://github.com/clux)'s repositories, to ensure they all work together:
 
 ```
 # NB: for readability the full paths have been shortened
-kjttks@clux ~/repos $ symlink . --global tap --dry-run
-[
- "cd ./blog && npm install marked ecstatic promzard async browserify ejs",
- "cd ./blog && npm link",
- "cd ./confortable && npm link tap",
- "cd ./confortable && npm link",
- "cd ./decay && npm link tap",
- "cd ./decay && npm link",
- "cd ./fsx && npm link",
- "cd ./irc-stream && npm link tap",
- "cd ./irc-stream && npm install irc",
- "cd ./irc-stream && npm link",
- "cd ./operators && npm link tap",
- "cd ./operators && npm link",
- "cd ./autonomy && npm link tap operators",
- "cd ./autonomy && npm link",
- "cd ./combustion && npm link tap confortable fsx autonomy operators",
- "cd ./combustion && npm install optimist",
- "cd ./combustion && npm link",
- "cd ./sdp-transform && npm link tap",
- "cd ./sdp-transform && npm link",
- "cd ./splitter && npm link tap",
- "cd ./splitter && npm link",
- "cd ./statesoftheworld && npm link tap",
- "cd ./statesoftheworld && npm link",
- "cd ./subset && npm link tap",
- "cd ./subset && npm link",
- "cd ./curvefever-stats && npm link tap subset confortable",
- "cd ./curvefever-stats && npm install request cheerio async",
- "cd ./curvefever-stats && npm link",
- "cd ./interlude && npm link tap autonomy subset operators",
- "cd ./interlude && npm link",
- "cd ./symlink && npm link tap interlude",
- "cd ./symlink && npm install async optimist",
- "cd ./symlink && npm link",
- "cd ./testling-html-example && npm link",
- "cd ./testling-server-example && npm install tape",
- "cd ./testling-server-example && npm link",
- "cd ./topiary && npm link",
- "cd ./tournament && npm link tap interlude",
- "cd ./tournament && npm link",
- "cd ./tournament-components && npm link tournament",
- "cd ./tournament-components && npm install tape",
- "cd ./tournament-components && npm link",
- "cd ./trials && npm link tap",
- "cd ./trials && npm link",
- "cd ./dye && npm link tap trials subset",
- "cd ./dye && npm link",
- "cd ./tub && npm link tap splitter",
- "cd ./tub && npm install dev-null",
- "cd ./tub && npm link",
- "cd ./typr && npm link tap",
- "cd ./typr && npm link",
- "cd ./logule && npm link tap dye autonomy subset confortable typr",
- "cd ./logule && npm link",
- "cd ./gu && npm link tap logule",
- "cd ./gu && npm install hot-reload",
- "cd ./gu && npm link",
- "cd ./cleverbot-irc && npm link dye gu irc-stream confortable",
- "cd ./cleverbot-irc && npm install levenshtein cleverbot-node suncalc irc-colors",
- "cd ./cleverbot-irc && npm link",
- "cd ./curvefever-bot && npm link tap curvefever-stats gu confortable",
- "cd ./curvefever-bot && npm link",
- "cd ./meshrtc && npm link logule",
- "cd ./meshrtc && npm install shoe emit-stream bean bonzo qwery domready ecstatic mux-demux pause-stream dnode browserify",
- "cd ./meshrtc && npm link",
- "cd ./wolfram-alpha && npm link tap",
- "cd ./wolfram-alpha && npm install request libxmljs",
- "cd ./wolfram-alpha && npm link",
- "cd ./wolfram-irc && npm link gu irc-stream confortable wolfram-alpha",
- "cd ./wolfram-irc && npm link",
- "cd ./wrappers && npm link tap",
- "cd ./wrappers && npm link"
-]
+clux@kjttks ~/trn $ symlink . -g nodeunit -g jscoverage -g nodeunit
+cd tournament && npm link nodeunit jscoverage coveralls
+cd tournament && npm install interlude
+cd tournament && npm link
+cd duel && npm link nodeunit jscoverage coveralls tournament
+cd duel && npm install interlude
+cd duel && npm link
+cd ffa && npm link nodeunit jscoverage coveralls tournament
+cd ffa && npm install interlude group
+cd ffa && npm link
+cd groupstage && npm link nodeunit jscoverage coveralls tournament
+cd groupstage && npm install interlude roundrobin group
+cd groupstage && npm link
+cd masters && npm link nodeunit jscoverage coveralls tournament ffa
+cd masters && npm install interlude
+cd masters && npm link
+cd tiebreaker && npm link nodeunit jscoverage coveralls tournament groupstage ffa
+cd tiebreaker && npm install interlude
+cd tiebreaker && npm link
+cd tourney && npm link nodeunit jscoverage coveralls tournament
+cd tourney && npm install interlude
+cd tourney && npm link
+cd ffa-tb && npm link nodeunit jscoverage coveralls tourney tiebreaker ffa
+cd ffa-tb && npm install autonomy
+cd ffa-tb && npm link
+cd groupstage-tb && npm link nodeunit jscoverage coveralls tiebreaker groupstage tourney
+cd groupstage-tb && npm link
+cd groupstage-tb-duel && npm link nodeunit jscoverage duel groupstage-tb tourney groupstage
+cd groupstage-tb-duel && npm install autonomy
+cd groupstage-tb-duel && npm link
+
+# all looks sane - execute:
+$ kjttks@clux ~/repos $ !! | sh
 ```
 
-Without the dry-run flag, these commands would be executed sequentially in this order.
+The most independent modules (tournament) gets their missing dependencies installed first, then gets npm linked so the more requiring modules (specific implementations) can npm link in these.
 
-The most independent modules gets their missing dependencies installed first, then gets npm linked so the more requiring modules can npm link in these.
-
-If you have a local/chowned install of node (such that creating links to globally installed modules can be done sans-sudo) then `symlink` can run sudo free too.
+If you have a local/chowned install of node (such that creating links to globally installed modules can be done sans-sudo) then `symlink` can execute sudo free too.
 
 ## Globally linked modules
-If you want to use one globally available package everywhere, say [tap](https://npmjs.org/package/tap) for tests, then you can specify `-g tap` to `npm link tap` in all modules that has tap listed as a dependency.
+Test dependencies are often the same everywhere, and, to save querying npmjs, you could just give them the version you have installed (provided it is compatible):
+
+In the example above, every module that uses `jscoverage`, `nodeunit` or `coveralls` will get the relevant modules linked in.
+
+In the example above, `nodeunit`, `jscoverage`, and `coveralls` all use the same, globally installed version (less querying of npmjs).
 
 ## License
 MIT-Licensed. See LICENSE file for details.