Global

Methods

isThenable(o){boolean}

resolvable.js, line 60

Returns true when an object is a Promise-like one

Name	Type	Description
o	*	The thing to test

Returns:

when is promise-like, false otherwise

spawnGit(args, cb){Promise}

gitftw.js, line 149

Spawns a git process with the provider arguments This function is called when you call directly the require of gitftw

If you provide a second parameter

DISCLAIMER: I've not found any way to document this in jsdoc and this template in a proper way. Sorry for the possible missunderstanding

Name	Type	Description
args	Resolvable | Array.<(String|null)>	The arguments to pass to git command
cb	callback	optional The execution callback result

Fires:

• event:command the git command executed
• event:result the result from the command line

Returns:

Resolves with the git output Rejects with an invalid/not found git cmd Rejects with an error with the git cmd spawn Rejects with git exits with an error

Example

var git = require('gitftw');

//executes a `git version`
git(['version'], function(err, data) { console.log(data);});
//or
git(['version']).then(console.log);

Type Definitions

callback(err, result)

gitftw.js, line 317

A Typical node callback

Name	Type	Description
err	Error | null	The error (if any)
result	* | undefined	The result of executing the command

command(options){Promise}

gitftw.js, line 242

A gitftw command implementation.

It only receives as parameter an options object. The options object is resolved before reaching your implementation

The dual exported API (for Promises and node callbacks) is also managed for you. Therefore you only have to deal with one paradigm in the implementation: The promises one. It's safe to throw errors, and you have to return a promise or a value.

For most use cases, you dont have to known too much of promises. Probably you will have to call the git([arguments]) that creates a promise, and you only will have to deal with the output parsing and return it

One extra thing: It must be a named function. The implemented command available in the gitftw module, will be that name function.

Name	Type	Description
options	Object	The options to this command. All its properties are Resolvable

Returns:

The execution promise

Examples

Creating a command

var git = require('gitftw');

//implement a command as a named function
function doSomethingAwesome(options) {
 //All properties in the options object are resolved here.
 //read the docs about what an *optional* `resolvable` concept is
 var resolvable = git.getCurrentBranch;
 //issue a `git awesome master param`
 return git(['awesome', resolvable, options.name])
   .then(parseAwesomeCommandResult);
}

//implement an optional command parsing
function parseAwesomeCommandResult(res) {
 var lines = res.split('\n');
 if (lines[0] !== 'expected result') {
   //feel free to throw. It will be catched by the
   //promise engine and rejected or callbacked with err for you
   throw new Error('unable to parse the awesome');
 }
 //If everything goes well, return the command output
 return lines[1];
}

//register a command
git.command(doSomethingAwesome);

//Now it's available in the git module
git.doSomethingAwesome({
//available in the command implementation as options.name
name: 'param'
};

Creating commands in your module
//your custom commands in mycommands.js
module.exports = function(git) {
 //doSomethingAwesome is defined elsewhere
 git.command(doSomethingAwesome);

 //for chainable api: return git itself
 return git;
}

//////
The userland: using your commands
var git = require('gitftw');
require('./mycommands')(git)

git.doSomethingAwesome();

Resolvable

Resolvable is something that have invariant primitives, including all its properties, now or in the future.

Which things are resolvables?

1. A String, Number, Boolean primitives: string, 4, true

2. A array of resolvables: ['string', resolvable]

3. A literal object with resolvables properties: { foo: 'string', bar: resolvable }

4. An object with a toString method

5. An A+ promise (Q, bluebird, native...) that resolves to a resolvable: Promise.when('string')

6. A function that returns resolvables function() { return 'string'; }

resolvables are resolved in serie. Once something is resolved, goes to resolve the next one. Never in parallel. This avoids race conditions in your workflows while maintaining your code clean.

Example

//Using Q as promise library

var resolvableArray = [
  'string',
  Q.when('string'),
  function() {
   return 'string';
  },
  function() {
   return Q.when('string');
  }
];
var resolvableObject = {
 arr: resolvableArray,
 string: 'string'
}

//In the future, after resolving it, will become
var resolvableArray = ['string', 'string', 'string', 'string'];
var resolvableObject = {
 arr: ['string', 'string', 'string', 'string'],
 string: 'string'
}