gulp-spsync-creds/README.md

Gulp plugin that syncs with a library in SharePoint Online and on-premises

# gulp-spsync-creds
> Gulp plugin for synchronizing local files with a SharePoint library

[![NPM](https://nodei.co/npm/gulp-spsync-creds.png?compact=true)](https://nodei.co/npm/gulp-spsync-creds/)

This Gulp plugin is based on [gulp-spsync](https://github.com/wictorwilen/gulp-spsync) which has been created by Wictor Wilen. The difference with gulp-spsync is that this plugin makes use for client credentials (username and password) in order to upload and/or download files. This makes the plugin usable for both SharePoint Online and on-premises environments.

## Installation
Run the following command to install the gulp-spsync-creds plugin:

```
$ npm install gulp-spsync-creds
```

## Usage
### Uploading files
For uploading files, you can add the following code to your `gulpfile.js`:

```javascript
var gulp = require('gulp');
var spsync = require('gulp-spsync-creds').sync;

gulp.src('./src/**/*')
.pipe(spsync({
    "username": "<username>",
    "password": "<password>",
    "site": "<site-url>",
}));
```

### Downloading files
For downloading files, you can add the following code to your `gulpfile.js`:

```javascript
var gulp = require('gulp');
var spdwn = require('gulp-spsync-creds').download;

spdwn({
    "site": "<site-url>",
    "username": "<username>",
    "password": "<password>",
    "startFolder": "<relative-folder-location>"
}).pipe(gulp.dest("src"));
```

*Information: it currently retrieves all files of the given path and the ones of three folders deep.*

## Options
The plugin has the following options that can be configured:

### username
Type: `String`
Default: `null`

Sets the username to be used for the sync action.

### password
Type: `String`
Default: `null`

Sets the password to be used for the sync action.

### site
Type: `String`
Default: `""`

Sets the site URL to where the files should be uploaded.

### startFolder
Type: `String`
Default: `""`

Choose the name of the folder location it has to starts from. This is useful when you have a nested folder structure. Example: 
if your folder structure is like this `src/template1/_sp/_catalogs`, and you set the *startFolder* option to `_sp`, it will strip out all the folder names before including `_sp`. You end up with `_catalogs`.

**Important**: this property can also be used to specify the location from where you want to download files.

### libraryPath **New property - v2.3.0**
Type: `string`
Default: `""`

The libraryPath property can be used if you want to define a default library path to where you want to upload your files.

By default the plugin uploads the files based on their file location (under your source folder).

```
src
|_ _catalogs
   |_ masterpage
      |_ your-folder
         |_ file1.html
```

So in the above case, `file1.html` will be uploaded to the master page gallery (`_catalogs/masterpage`) in a `your-folder` folder.

When you define the libaryPath to for example: `documents`. The plugin will upload the files to that specific document library with the folder structure. So in this case it will be `documents/_catalogs/masterpage/your-folder/file1.html`.

### update_metadata
Type: `Boolean`
Default: `false`

Specify if you want to update the metadata of files you are uploading. If this is set to `true`, you will have to pass the file metadata via the `files_metadata` option.

### files_metadata
Type: `Object`
Default: `[]`

With the files_metadata option you can specify the metadata of all the files you wish to upload. Example:

```json
"fileMetadata": [
    {
        "name": "Item_Minimal.js",
        "metadata": {
            "__metadata": {
                "type": "SP.Data.OData__x005f_catalogs_x002f_masterpageItem"
            },
            "Title": "Item Minimal Template (via GULP)",
            "MasterPageDescription": "This is a display template added via gulp.",
            "ManagedPropertyMapping": "'Path','Title':'Title'",
            "ContentTypeId": "0x0101002039C03B61C64EC4A04F5361F38510660500A0383064C59087438E649B7323C95AF6",
            "DisplayTemplateLevel": "Item",
            "TemplateHidden": false,
            "TargetControlType": {
                "__metadata": {
                "type": "Collection(Edm.String)"
                },
                "results": [
                "SearchResults",
                "Content Web Parts"
                ]
            }
        }
    },
    {
        "name": "Control_Minimal.js",
            "metadata": {
            "__metadata": {
                "type": "SP.Data.OData__x005f_catalogs_x002f_masterpageItem"
            },
            "Title": "Control Minimal Template (via GULP)",
            "MasterPageDescription": "This is a display template added via gulp.",
            "ContentTypeId": "0x0101002039C03B61C64EC4A04F5361F38510660500A0383064C59087438E649B7323C95AF6",
            "DisplayTemplateLevel": "Control",
            "TemplateHidden": false,
            "TargetControlType": {
                "__metadata": {
                "type": "Collection(Edm.String)"
                },
                "results": [
                "SearchResults",
                "Content Web Parts"
                ]
            }
        }
    }
]
```

### publish
Type: `Boolean`
Default: `false`

With this option you can specify if you want to publish files after they are uploaded.

### cache
Type: `Boolean`
Default: `false`

If set to true the plugin caches library locations that already have been processed. Makes the watch tasks quicker.

### associatedHtml *(only for download actions)*
Type: `Boolean`
Default: `true`

With this property you can specify if you want to download all files (by default set to `true`) from a folder. This will also download the files that are associated to an HTML template like a page layout, master page and display template. If you set this property to `false`, the plugin only downloads the HTML files and leaves the ".aspx", ".master" and ".js" files in the folder.

### verbose
Type: `Boolean`
Default: `false`

If you wish to see all the plugin logging you can set this to true.