treediff/README.md

Compare and find/sync differences in file trees

![TreeDiff Logo](http://s29.postimg.org/4kti791vb/tredifflogo.png)

File tree comparison and synchronization for Node.js!
## Installation
```bash
$ npm install treediff
```
Instantiate like so:
```javascript
var TreeDiff = require('treediff');
var treediff = new TreeDiff();
```

## Features
- **Map:** Turn a file tree into universal a JSON structure regardless of its origin
- **Compare:** Reveal modifications, addtions and deletions between two file trees
- **Synchronize:** Transfer modifications, additions and deletions between two file trees

## Methods
### .compare(mapA, mapB, callback)
Will compare one file location with another one.

#### Arguments
- ```mapA``` (Object) - The source to apply changes to
    - ```type``` (String) - The type of the map. Default is "local"
    - ```path``` (String) - The path to the root folder of the source
- ```mapB``` (Object) - The target to apply changes from
    - ```type``` (String) - The type of the map. Default is "local"
    - ```path``` (String) - The path to the root folder of the source
- ```callback(err, difference)``` (Function) - The callback that is called when comparison is complete
    - ```err``` (Error) - Any error that may occur during comparison
    - ```difference``` (Object) - Holds information about which files were added, modified and deleted
      - ```added``` (Array) - Files that are to be added to source
      - ```modified``` (Array) - Files that are to be modified on source
      - ```deleted``` (Array) - Files that are to be deleted on source
      - ```total``` (Number) - The total amount of differences

#### Example
```javascript
var folderA = {
  type: 'local',
  path: 'path/to/folder-a'
};

var folderB = {
  type: 'local',
  path: 'path/to/folder-b'
};

treediff.compare(folderA, folderB, function(err, differences){
  // ...
});
```

### .sync(mapA, mapB, callback)
Will apply the differences from mapB to mapA.

#### Arguments
- ```mapA``` (Object) - The source to apply changes to
    - ```type``` (String) - The type of the map. Default is "local"
    - ```path``` (String) - The path to the root folder of the source
- ```mapB``` (Object) - The target to apply changes from
    - ```type``` (String) - The type of the map. Default is "local"
    - ```path``` (String) - The path to the root folder of the source    
- ```callback(err)``` (Function) - The callback that is called when synchronization is complete
    - ```err``` (Error) - Any error that may occur during synchronization

#### Example
```javascript
var folderA = {
  type: 'local',
  path: 'path/to/folder-a'
};

var folderB = {
  type: 'local',
  path: 'path/to/folder-b'
};

treediff.sync(folderA, folderB, function(err){
  // ...
});  
```
### .registerFilter(filter)
Adds a filter to exlude entries from the comparison process. The filter will be evaluated for each entry as a glob expression. As an example, ```**/.DS_Store``` is applied by default.

#### Arguments
- ```filter``` (String) - The glob expression string to exclude entries by.

#### Example
```javascript
// Exclude entire folder
treediff.registerFilter('**/Folder-to-exclude/**');

// Exclude all MS Word documents
treediff.registerFilter('**/*.docx');
```