A way to get your favourite libraries and scripts from the internet, and fast.
Supports Node 0.10.x and 0.8.x.
The following documentation is for using Pulldown as a CLI tool. If you'd like documentation on the use of Pulldown as a module, please see MODULE_USAGE.md.
Install pulldown globally using npm:
$ npm install -g pulldown
If you get any errors (particularly if you are on Node 0.8), try updating
$ npm install -g npm
This gives you a
pulldown command to use on your command line:
$ pulldownUsage: pulldown <identifier>[::<file>] [<identifier>[::<file>], ...] [options]An <identifier> can be a URL, a library name or a set.Options:-o, --output output directory-d, --dry-run don't actually download the files-v, --version get the current pulldown version-n, --noisy verbose mode, basicallyExample usage:pulldown jquery # Downloads jQuerypulldown jquery::jq.js # Downloads jQuery to jq.jspulldown jquery angular.js # Downloads jQuery and Angular.jspulldown backbone # Downloads jQuery, Underscore.js and Backbone.jspulldown backbone -o js # Downloads same as above, but into js/
$ pulldown jquery-> Success: was downloaded to jquery.min.js
$ pulldown jquery underscore-> Success: was downloaded to jquery.min.js-> Success: was downloaded to underscore.min.js
Pulldown works by searching on the cdnjs site for what you asked it for.
Of course, not everything you might want to download exists on cdnjs. You can add your own custom downloads to
~/.pulldown.json. This file might look something like this:
Then you can run:
$ pulldown mycustommodule-> Success: was downloaded to module.js
Pulldown will know where to look. Pulldown will always look in your local
~/.pulldown.json file before searching. This means if you want a particular version of a library you can put it into your local file, and Pulldown will always use that.
Pulldown comes with the notion of sets. Sets are a collection of libraries.
For example, a Backbone application typically requires 3 libraries:
Rather than download all three yourself, Pulldown has you covered:
$ pulldown backbone-> Success: was downloaded to underscore-min.js-> Success: was downloaded to backbone-min.js-> Success: was downloaded to jquery.min.js
You can define custom sets in your
~/.pulldown.json. They look like this:
Here I define a custom set,
backboneapp, that will download jQuery, Underscore and Backbone. This is an example we have on the server, so you don't need to, but it's useful for setting up common sets of libraries you use together. Downloading them all becomes as simple as:
$ pulldown backboneapp-> Success: was downloaded to underscore-min.js-> Success: was downloaded to backbone-min.js-> Success: was downloaded to jquery.min.js
You can tell Pulldown to save what it downloads into a directory, that will be created if it doesn't exist:
$ pulldown backbone -o foo/-> Success: was downloaded to foo/underscore-min.js-> Success: was downloaded to foo/backbone-min.js-> Success: was downloaded to foo/jquery.min.js
If you're downloading something that will resolve to a single file, you can choose the name of the file that will be downloaded using two colons:
$ pulldown jquery::foo.js-> Success: was downloaded to foo.js
Pulldown supports finding a specific version of a library, and will do its best to find it. Use
$ pulldown firstname.lastname@example.org-> Success: was downloaded to jquery.min.js
Pulldown searches cdnjs for it. If it can't find the right version, it'll give you the latest.
If you want to see what would happen when you run a particular command, append the
--dry-run flag. This will not download the files, but will tell you what would happen:
$ pulldown jquery -d-> Dry Run - no files will be downloaded-> would have been downloaded to jquery.min.js
$ npm update pulldown -g
See the CONTRIBUTING.md file.
We get a lot of questions about the similarities and differences of Pulldown compared to Bower.
Short Answer: Bower is a package manager; Pulldown downloads files. Bower configurations can be saved with a project and shared by people working on it; Pulldown cannot – it is almost configuration-less. Think of it as way to get a copy of your favourite library, fast.
Long Answer: Bower is a far more complex and fully-featured package and, more importantly, dependency manager. If you have a complex project with multiple 3rd party libraries in play, and you want to keep tight control over the versions you're using, Bower is best suited. Use Bower when you wouldn't want to commit all those libraries to Git, but would want to commit a component.json file.
We envisage (and personally use) Pulldown for those times when you just want one or two libraries, and have little care for versioning or dependencies. For example, if I want to prototype a quick Backbone app, I can quickly run $ pulldown jquery underscore backbone.js to get all three. Here it doesn't matter to me which versions I have (Pulldown will always pull in the latest stable version by default) and I'll probably commit those libraries to Git too. Pulldown also has the concept of sets, which is often where people get confused. These two commands are equal:
$ pulldown jquery underscore backbone.js$ pulldown backbone
The second command will download the Backbone set, which will give you Underscore, jQuery and Backbone. This looks like dependency management - and sort of is - but it's really dumb. All Pulldown is doing here is seeing you asked it for "backbone", and replacing that with "jquery underscore backbone.js", which it then goes and gets separately. Sets are hard coded in the Pulldown API:
"backbone": ["backbone.js", "underscore", "jquery"],
The sets are there purely to allow you to save time and type less. There is no versioning, dependency checks or anything done with sets. They are just a list of libraries to download, nothing more.
If you've any further questions, please do ask.
$ pulldown -v.
$ pulldown foo.com/bar.js::test.js), it will now save the file to the specified name and not just ignore it (bug #74).
found: trueflag to the results returned from the
pulldown.initcallback. This enables you to see if a searchTerm was successful by seeing if
result.found === true.
TypeErrorwhen you search for something that no longer exists ( Number #70 )
$ pulldown -d jquery(Number #40)
jquery:foo.js), which is incorrect, you'll see a nice error message instead of a JS exception. (Number #33)
$ pulldown lsto list the sets we support. (Number #38)
-oflag was ignored. (Number #41)
$ pulldown jquery::foo/bar/baz/jquery.js(Number #42)
var Pulldown = require("pulldown")(presuming it's in your package.json and installed as a dependency).
::for seperating search term with output name
zipextension to output path if it is already there
pulldown backbone -o foo/)
.pulldownrcto allow for specifying the file name
mkdirshowing error if no directory given
nodefetchmodule, with a better name.