grunt-ncftp-push

Deploy your files to a FTP server

Getting Started

Requirements

Grunt ~0.4.5 Ncftp

Optional Requirements

Grunt watch

Install

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-ncftp-push --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-ncftp-push');

Usage

Grunt-ncftp-push adds two grunt taks you can use.

The "ncftp_push" task

Overview

The ncftp_push task pushes all the files given to it to the ftp server. Usually you would use this to upload your entire project or parts of your project to the ftp server at once.

Usage

In your project's Gruntfile, add a section named ncftp_push to the data object passed into grunt.initConfig().

grunt.initConfig({
  ncftp_push: {
    all: {
      options: {
        dest: 'destination/directory/on/ftp/server'
      },
      files: [{expand: true, src: ['trunk/*', '!trunk/composer*']}]
    }
  }
})

Options

All options are optional but you'll at least want to specify a destination directory otherwise it will go to the root directory of the ftp account.

dest

Type: String Default: / Required: false

Destination of where you want your files pushed to, relative to the host.

srcBase

Type: String Default: `` Required: false

Base of your source files relative to the project base that you want trimmed from the file names prior to uploading them to make the filename correct relative to the dest.

authFile

Type: String Default: .ftpauth Required: false

File to get the destination host and authorization credentials from. Default filename is .ftpauth. File should be in the following format:

host my.hostname.com
user myUsername
pass myPassword

Note that spacing is important and lines starting with # and blank lines will be ignored. For more information on this file see the ncftp docs.

redial

Type: Integer Default: 3 Required: false

Maximum number of retry attempts

ncftpPath

Type: String Default: `` Required: false

Path to the ncftpput command. `` means that the command can be executed without specifying a path. If a path is used it must contain the trailing slash.

join

Type: String Default: && Required: false

How to join the commands together when there are multiple files. Options are &&, &, and ;. The default is && which means only run the next command if the previous one succeeded. ; will run the commands sequentially and & will run the commands concurrently. Running the commands concurrently is usually not a good idea since most ftp servers have limits on concurrent connections. See the documentation for grunt-shell for more information on these options.

shellOptions

Type: Object Default: {} Required: false

Additional options to pass to the grunt-shell task. See the documents for grunt-shell for more information on the options that can be included.

debug

Type: Boolean Default: false Required: false

Enable debug mode for the ncftpput command to allow for verbose messages. This can be useful if the commands are failing and you can't see why. The entire conversation with the server will be output. See the ncftp documentation for more information.

debugFile

Type: String Default: stdout Required: false

File to send the debug info to if debug is true. The special string stdout means it will be sent to the terminal.

The "ncftp_watch" task

Overview

The ncftp_watch task is meant to be used with grunt watch. It starts up some a watcher to capture and queue up changed files when the watch event fires. When there are changed files in the queue it starts the ncfp_push:watch task to push those files to the server.

Usage

In your project's Gruntfile, add a section named ncftp_watch to the data object passed into grunt.initConfig(). Also add a sub-task to the watch task in your grunt config that runs the ncftp_watch task.

grunt.initConfig({
  watch: {
    ncftp_watch: {
      files: [ 'trunk/**/*', '!trunk/composer*'],
      tasks: ['ncftp_watch'],
      options: {
        atBegin: true,
        spawn: false,
        debounceDelay: 500
      }
    }
  },
  ncftp_watch: {
      options: {
        dest: 'wp-content/plugins/credit-helper-elite',
        srcBase: 'trunk/'
      },
      files: ['trunk/**', '!trunk/composer*']
    }
  }
})

ncftp_watch Options

The ncftp_watch task can have all the same options as the ncftp_push task. These options will be used in configuring an ncftp_push:watch task which will be started up as needed.

The files given to this task will be used to match against changed files so that only files that match these patterns are uploaded to the server.

watch ncftp_watch Options

The ncftp_watch sub-task of the watch task is a typical watch task.

You should include atBegin: true so that the ncftp_watch command runs when grunt watch first starts up. This sets up the watchers to catch the changed files and add them to the queue, and start it up if there are already changed files (there shouldn't be at this point, so the ncftp_push:watch task won't run at this point). If you don't set atBegin to true the watchers will start up the first time the ncftp_watch task is run, but any changed files that came before that run will not be uploaded.

spawn must be set to false. The ncftp_watch task must run in the same process as the watch task so that it can capture watch events and internal ncftp_start and ncftp_finish events emmitted by the ncftp_push task.

debounceDelay can be set to whatever works for you but the default 500 seems to work well (so it can technically be left off).

The ncftp_watch task should be your last watch task. This way it can capture all changed files from tasks that came before it and run the ncftp_push:watch task for any changed files.

If your watch tasks change additional files you may see the ncftp_push:watch task run twice. This is because grunt-watch doesn't seem to fire its event until after the next task is run so the ncftp_watch catches those files after ncftp_push:watch has already started running. When one ncftp_push:watch finishes it starts up another one for any remaining changed files that weren't in the list pushed to the server.

The ncftp_watch task can also be useful as a place to configure livereload to automatically reload your web page when files are changed. Just add livereload: true to the options. Check out the grunt watch documentation about configuring and using livereload.

Usage Examples

Sample .ftpauth file

This file's default name is .ftpauth and is in the same directory as your Gruntfile.js. You should add this file to your .gitignore so that it is not uploaded to your git repository or specify another file that is not in your project path.

The format of this file is specified by ncftp and more documentation on it can be found in the ncftp docs. It contains the hostname, username and password for the destination ftp server.

host my.hostname.com
user myUsername
pass myPassword

Extras

You can specify a destination inside your files objects like so:

{expand: true,cwd: 'test',src: ['**/*']},
{expand: true,cwd: 'tasks',src: ['**/*'], dest: 'test/' }

This will allow you to configure where you push your code in case you want to push to a diretory structure that is different from your local one. The dest here MUST be relative to the root destination.

Source files can be individual files or they can be directories. Directories will be pushed recursively so all files and other directories within that directory will be pushed to the destination. So if you want to include an entire directory to upload do it like so:

{expand: true, src: ['mydirectory']}

This works only for the ncftp_push task. The ncftp_watch task can only have one destination since files come from the watch events.

Notes

The output from ncftpput appears in the terminal twice. I don't believe the commands are being run twice it's just output twice. It has something to do with grunt-shell. I welcome any suggestions for how to solve it but for now it will just be there twice.

Dependencies

This plugin uses Sindre Sorhus grunt-shell module.

To do

Combine files with the same destination to a single ncftpput command.

Acknowledgements

This module was originally based on the grunt-ftp-push module by Robert Winterbottom and many of the utility functions are the same or very similar but the task code is now very different.

Contributing

Fork the repo. Make your changes then submit a pull request.

Please add unit tests in the root of the test folder for any new or changed functionality and please try to make sure that npm test will pass before submitting a pull request.

Thanks for contributing!

Release History

• 0.1.0 - 2016/09/11 Initial release
• 0.2.0 - 2016/09/26
• Combine all files with the same destination into one ncftpput command
• Rely on ncftp_watch command to start up ncftp_push at the end instead of checking if it's running for every changed file.