From 3f843b8585a05500588c741b5bd58c5c87f0b7f7 Mon Sep 17 00:00:00 2001
From: Devyn Stott <SyntaxRules@users.noreply.github.com>
Date: Thu, 16 Apr 2015 11:56:25 -0700
Subject: [PATCH] Docs: Add gulp.registry API & examples

---
 docs/API.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/docs/API.md b/docs/API.md
index f0227f2b1..75b727ca1 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -682,6 +682,59 @@ gulp.tree({ deep: true })
 */
 ```
 
+### gulp.registry([registry])
+
+Get or set the underlying task registry. Inherited from [undertaker]; see the undertaker documention on [registries](https://github.com/phated/undertaker#registryregistryinstance). Using this, you can change registries that enhance gulp in different ways. Utilizing a custom registry has at least three use cases:
+
+- [Sharing tasks](https://github.com/phated/undertaker#sharing-tasks)
+- [Sharing functionality](https://github.com/phated/undertaker#sharing-functionalities). (e.g. you could override the task prototype to add some additional logging, bind task metadata or include some config settings.)
+- Handling other behavior that hooks into the registry lifecycle (see [gulp-hub](https://github.com/frankwallis/gulp-hub) for an example)
+
+To build your own custom registry see the [undertaker documentation on custom registries](https://github.com/phated/undertaker#custom-registries).
+
+#### registry
+
+A registry instance or constructor. When passed in, the tasks from the current registry will be transferred to the new registry and then current registry will be replaced with the new registry.
+
+#### Example
+
+This example shows how to create and use a simple custom registry to add tasks.
+
+```js
+//gulpfile.js
+var gulp = require('gulp');
+
+var companyTasks = require('./myCompanyTasksRegistry.js');
+
+gulp.registry(companyTasks);
+
+gulp.task('one', gulp.parallel('someCompanyTask', function(done) {
+  console.log('in task one');
+  done();
+}));
+```
+
+```js
+//myCompanyTasksRegistry.js
+var util = require('util');
+
+var DefaultRegistry = require('undertaker-registry');
+
+function MyCompanyTasksRegistry() {
+  DefaultRegistry.call(this);
+
+  this.set('clean', function(done) {
+    done();
+  });
+  this.set('someCompanyTask', function(done) {
+    console.log('performing some company task.');
+    done();
+  });
+}
+util.inherits(MyCompanyTasksRegistry, DefaultRegistry);
+
+module.exports = new MyCompanyTasksRegistry();
+```
 
 [Function.name]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name
 [gaze]: https://github.com/shama/gaze