Deploy your files to a FTP server
Grunt ~0.4.5
Ncftp
Grunt watch
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');
Grunt-ncftp-push adds two grunt taks you can use.
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.
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*']}]
}
}
})
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.
Type: String
Default: /
Required: false
Destination of where you want your files pushed to, relative to the host.
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.
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.
Type: Integer
Default: 3
Required: false
Maximum number of retry attempts
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.
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.
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.
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.
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 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.
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*']
}
}
})
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.
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.
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
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.
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.
This plugin uses Sindre Sorhus grunt-shell
module.
Combine files with the same destination to a single ncftpput
command.
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.
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!
- 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.