Skip to content

Commit

Permalink
Updated README
Browse files Browse the repository at this point in the history
  • Loading branch information
@lazd
lazd committed Dec 12, 2013
1 parent dfbc4f0 commit 56ab547
Showing 1 changed file with 118 additions and 150 deletions.
268 changes: 118 additions & 150 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,172 +1,168 @@
[![Build Status](https://travis-ci.org/wearefractal/gulp.png?branch=master)](https://travis-ci.org/wearefractal/gulp)
[![Dependency Status](https://david-dm.org/wearefractal/gulp.png)](https://david-dm.org/wearefractal/gulp)
# gulp [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][depstat-image]][depstat-url]
> The streaming build system
## Information

<table>
<tr>
<td>Package</td><td>gulp</td>
</tr>
<tr>
<td>Description</td>
<td>Simple stream-y build helper</td>
</tr>
<tr>
<td>Node Version</td>
<td>>= 0.8</td>
</tr>
</table>
## Usage

This project is in its early stages. If something is not working or you would like a new feature please use the issues page.
### 1. Install gulp globally:

## Links
```
npm install -g gulp
```

[Slideshow](http://slid.es/contra/gulp)
### 2. Install gulp in your project devDependencies:

[Twitter for updates](http://twitter.com/eschoff)
```
npm install --save-dev gulp
```

[Company twitter](http://twitter.com/wearefractal)
### 3. Create a `gulpfile.js` at the root of your project:

## Plugin List
```javascript
/*
This is an EXAMPLE gulpfile.js
You'll want to change it to match your project.
Find plugins at https://npmjs.org/browse/keyword/gulpplugin
*/
var gulp = require('gulp');
var uglify = require('gulp-uglify');

You can view a list of plugins by going to [this npm search](https://npmjs.org/search?q=gulpplugin).
gulp.task('scripts', function() {
// Minify and copy all JavaScript (except vendor scripts)
gulp.src(['client/js/**/*.js'])
.pipe(uglify())
.pipe(gulp.dest('build/js'));

## Usage
// Copy vendor files
gulp.src('client/js/vendor/**')
.pipe(gulp.dest('build/js/vendor'));
});

This code would go in your `Gulpfile.js` (case insensitive) at the root of your project. For more information on how to use other languages check the [compilers](#compilers) section.
// Copy all static assets
gulp.task('copy', function() {
gulp.src('client/img/**')
.pipe(gulp.dest('build/img'));

```javascript
var gulp = require('gulp');
var jade = require('gulp-jade');
var coffee = require('gulp-coffee');
var minify = require('gulp-minify');
gulp.src('client/css/**')
.pipe(gulp.dest('build/css'));

// compile, minify, and copy templates
gulp.task('templates', function(){
gulp.src("./client/templates/*.jade")
.pipe(jade())
.pipe(minify())
.pipe(gulp.dest("./public/templates"));
gulp.src('client/*.html')
.pipe(gulp.dest('build'));
});

gulp.task('scripts', function(){

// compile, minify, and copy coffeescript
gulp.src(["./client/js/*.coffee". "!./client/js/vendor/**"])
.pipe(coffee())
.pipe(minify())
.pipe(gulp.dest("./public/js"));
// The default task (called when you run `gulp`)
gulp.task('default', function() {
gulp.run('scripts', 'copy');

// copy vendor files
gulp.src("./client/js/vendor/**")
.pipe(minify())
.pipe(gulp.dest("./public/js/vendor"));
// Watch files and run tasks if they change
gulp.watch('client/js/**', function(event) {
gulp.run('scripts');
});

gulp.watch([
'client/img/**',
'client/css/**',
'client/*.html'
], function(event) {
gulp.run('copy');
});
});
```

// copy all static assets
gulp.task('copy', function(){
gulp.src("./client/img/**")
.pipe(gulp.dest("./public/img"));
### 4. Run gulp

gulp.src("./client/css/**")
.pipe(gulp.dest("./public/css"));
```
gulp
```

gulp.src("./client/*.html")
.pipe(gulp.dest("./public"));
The default tasks will run and gulp will watch for changes.

gulp.src("./client/*.ico")
.pipe(gulp.dest("./public"));
To run individual tasks, use `gulp <task> <othertask>`

});

// default task gets called when you run the `gulp` command
gulp.task('default', function(){
gulp.run('templates', 'scripts', 'copy');
## Available Plugins

// watch files and run scripts if they change
gulp.watch("./client/js/**", function(event){
gulp.run('scripts');
});
The gulp community is growing, with new plugins being added daily. See the [npm search results][plugin search] for a complete list.

gulp.watch("./client/templates/**", function(event){
gulp.run('templates');
});

});
```
## gulp API

### gulp.src(globs[, opt])
### gulp.src(globs[, options])

Takes a glob and represents a file structure. Can be piped to plugins. You can specify a single glob or an array of globs (see docs). All options are passed directly through to [glob-stream](https://github.com/wearefractal/glob-stream). See the [glob-stream documentation](https://github.com/wearefractal/glob-stream) for more information.
Takes a glob and represents a file structure. Can be piped to plugins. You can specify a single glob or an array of globs (see docs). All options are passed directly through to [glob-stream]. See the [glob-stream documentation] for more information.

```javascript
gulp.src("./client/templates/*.jade")
gulp.src('./client/templates/*.jade')
.pipe(jade())
.pipe(minify())
.pipe(gulp.dest("./public/minified_templates"));
.pipe(gulp.dest('./build/minified_templates'));
```

##### Options
#### options.buffer
Type: `Boolean`
Default: `true`

Setting this to `false` will return `file.contents` as a stream and not buffer files. This may not be supported by many plugins.

`buffer: false` will return file.content as a stream and not buffer files. This may not be supported by many plugins.
#### options.read
Type: `Boolean`
Default: `true`

`read: false` will return file.content as null and not read the file at all.
Setting this to `false` will return `file.contents` as null and not read the file at all.

### gulp.dest(path[, opt])
### gulp.dest(path[, options])

Can be piped to and it will write files. Re-emits all data passed to it so you can pipe to multiple folders.

```javascript
gulp.src("./client/templates/*.jade")
.pipe(jade())
.pipe(gulp.dest("./public/templates"))
.pipe(minify())
.pipe(gulp.dest("./public/minified_templates"));
gulp.src('./client/templates/*.jade')
.pipe(jade())
.pipe(gulp.dest('./build/templates'))
.pipe(minify())
.pipe(gulp.dest('./build/minified_templates'));
```

### gulp.task(name[, deps], fn)

Tasks that you want to run from the command line should not have spaces in them.

The task system is [Orchestrator](https://github.com/robrich/orchestrator) so check there for more detailed information.
The task system is [Orchestrator] so check there for more detailed information.

```javascript
gulp.task('somename', function(){
// do stuff
gulp.task('somename', function() {
// Do stuff
});
```

##### Task dependencies
#### Task dependencies

This lets you specify tasks to be executed and completed before your task will run.

```javascript
gulp.task('somename', ['array','of','task','names'], function(){
// do stuff
gulp.task('somename', ['array', 'of', 'task', 'names'], function() {
// Do stuff
});
```

If the dependencies are asynchronous it is not guaranteed that they will finish before `'somename'` is executed. To ensure they are completely finished, you need to make sure the dependency tasks have asynchronous support through one of the methods outlined below. The most simple method is to return the stream. By returning the stream, Orchestrator is able to listen for the end event and only run `'somename'` once each dependencies' stream end event has been emitted. You can also use callbacks or promises to do your own cool stuff.

##### Async tasks
#### Async tasks

With callbacks:

```javascript
gulp.task('somename', function(cb){
// do stuff
gulp.task('somename', function(cb) {
// Do stuff
cb(err);
});
```

Wait for stream to end:

```javascript
gulp.task('somename', function () {
gulp.task('somename', function() {
var stream = gulp.src('./client/**/*.js')
.pipe(minify())
.pipe(gulp.dest('/public');
.pipe(gulp.dest('/build');
return stream;
});
```
Expand All @@ -176,11 +172,11 @@ With promises:
```javascript
var Q = require('q');

gulp.task('somename', function(){
gulp.task('somename', function() {
var deferred = Q.defer();

// do async stuff
setTimeout(function () {
// Do async stuff
setTimeout(function() {
deferred.resolve();
}, 1);

Expand All @@ -197,7 +193,7 @@ gulp.run('scripts', 'copyfiles', 'builddocs');
```
```javascript
gulp.run('scripts', 'copyfiles', 'builddocs', function (err) {
gulp.run('scripts', 'copyfiles', 'builddocs', function(err) {
// All done or aborted due to err
});
```
Expand All @@ -209,7 +205,7 @@ Use gulp.run to run tasks from other tasks. You will probably use this in your d
glob can be a standard glob or an array of globs. cb is called on each fs change with an object describing the change.
```javascript
gulp.watch("js/**/*.js", function(event){
gulp.watch('js/**/*.js', function(event) {
gulp.run('scripts', 'copyfiles');
});
```
Expand All @@ -218,11 +214,12 @@ gulp.watch("js/**/*.js", function(event){
gulp.env is an optimist arguments object. Running `gulp test dostuff --production` will yield `{_:["test","dostuff"],production:true}`. Plugins don't use this.
## gulp cli
## gulp CLI
### Tasks
Tasks can be executed by running `gulp <taskname> <othertask> <somethingelse>`. Just running `gulp` will execute the task you registered called `default`. If there is no `default` task gulp will error.
Tasks can be executed by running `gulp <task> <othertask>`. Just running `gulp` will execute the task you registered called `default`. If there is no `default` task gulp will error.
### Compilers
Expand All @@ -235,59 +232,15 @@ gulp dosomething --require coffee-script
```
## Writing a plugin
This is a simple plugin that adds a header to the beginning of each file. It takes one argument (a string). Let's call it `gulp-header`. I recommend event-stream as a utility for creating these plugins.
## Write your own gulp plugins
#### Code
See the [Writing a gulp plugin] wiki page for guidelines and an example to get you started.
```javascript
var es = require('event-stream');

module.exports = function(header){
// check our options
if (!header) throw new Error("header option missing");
// our map function
function modifyContents(file, cb){
// remember that contents is ALWAYS a buffer
file.contents = new Buffer(header + String(file.contents));
## More information
// first argument is an error if one exists
// second argument is the modified file object
cb(null, file);
}
See [the wiki][wiki] for more information and [the FAQ][FAQ] for more answers to common questions.
// return a stream
return es.map(modifyContents);
}
```
#### Usage
```javascript
var gulp = require('gulp');
var header = require('gulp-header');

// Add a copyright header to each file
gulp.src('./client/scripts/*.js')
.pipe(header('// This file is copyrighted'))
.pipe(gulp.dest("./public/scripts/"))
```
## Plugin Guidelines
A gulp plugin is exclusively something that deals with file streams. If your library is not for streaming files but is still made for use with gulp, just tag it as `gulpfriendly` instead of `gulpplugin`.
1. file.contents should always go out the same way it came in
- Respect buffered, streaming, and non-read files as well as folders!
1. Do not pass the file object downstream until you are done with it
1. Make use of the gulp-util library. Templating, CLI colors, logging. Do you need to change a file's extension or do some tedious fs crap? Try looking there first and add it if it doesn't exist
1. Remember: Your plugin should only do one thing! It should not have a complex config object that makes it do multiple things. It should not concat and add headers/footers. This is not grunt. Keep it simple.
1. Do not throw errors. Emit them from the stream (or pass them to the callback if using event-stream's .map).
1. Add "gulpplugin" as a keyword in your package.json so you show up on our search
If you don't follow these guidelines and somebody notices your plugin will be shitlisted from the ecosystem.
## LICENSE
Expand Down Expand Up @@ -317,3 +270,18 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/wearefractal/gulp/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
[glob-stream documentation]: https://github.com/wearefractal/glob-stream
[glob-stream]: https://github.com/wearefractal/glob-stream
[Orchestrator]: https://github.com/robrich/orchestrator
[plugin search]: https://npmjs.org/browse/keyword/gulpplugin
[wiki]: /wearefractal/gulp/wiki
[FAQ]: /wearefractal/gulp/wiki/FAQ
[Writing a gulp plugin]: /wearefractal/gulp/wiki/Writing-a-gulp-plugin
[npm-url]: https://npmjs.org/package/gulp
[npm-image]: https://badge.fury.io/js/gulp.png
[travis-url]: https://travis-ci.org/wearefractal/gulp
[travis-image]: https://travis-ci.org/wearefractal/gulp.png?branch=master
[depstat-url]: https://david-dm.org/wearefractal/gulp
[depstat-image]: https://david-dm.org/wearefractal/gulp.png

0 comments on commit 56ab547

Please sign in to comment.