/ 
upfiles-7
River stage zero No dependents
/ upfiles

NAME

upfiles -- upload files to an FTP server, for push mirroring

SYNOPSIS

upfiles [--options] [filename...]

DESCRIPTION

Upfiles uploads changed files from your local disk to an FTP server, for a simple kind of "push" mirroring.

Create files locally with the same directory structure as the target, and in a ~/.upfiles.conf file give the locations,

upfiles (local  => '/my/directory',
         remote => 'ftp://fred@some-server.org/pub/fred');

This is actually Perl code, so you can put comment lines with #, write some conditionals, use $ENV{HOME}, etc. Then to upload run

upfiles

Or to upload just some selected files,

upfiles /my/directory/foo.txt /my/directory/src/xyzzy.pl

Your username on the remote system is in the ftp:// remote URL. A password is taken from ~/.netrc the same as for the ftp program and other programs. See netrc(5) or Net::Netrc for the format of that file.

upfiles records what has been sent in an SQLite database file .upfiles.sqdb in each local toplevel directory, for example /my/directory/.upfiles.sqdb. Local changes are identified by comparing file mtimes and sizes against the database. This is much faster than asking the remote server what it's got.

For convenience some local files are always excluded from the upload. Currently this is

.upfiles.sqdb    from upfiles itself
foo~             Emacs backups
#foo#            Emacs autosaves
.#foo            Emacs lockfiles

Files are uploaded one by one. The upload goes first to a temporary file and is then renamed. This means an incomplete file isn't left if the connection is lost or upfiles is killed during transfer. Temporary files are noted in the database and any leftovers deleted on the next upfiles run.

Plain RFC959 ftp doesn't have a notion of symlinks or hard links so upfiles follows any local links to actual content to upload.

CONFIGURATION

Each upfiles call in ~/.upfiles.conf takes the following parameters,

local (string)

The local directory to upload from.

remote (string)

The remote FTP server to upload to, as a URL. The path in the URL is the target directory, and if your username on the remote machine is not the same as your local username then include it with "@" syntax, like

remote => 'ftp://fred@some-server.org/pub/fred',
exclude_regexps (arrayref of regexps)

Additional filenames to exclude. For example to exclude a local Makefile

upfiles (local => '/my/directory',
         remote => 'ftp://some-server.org/pub/fred',
         exclude_regexps => [ qr{/(^|/)[Mm]akefile$} ]);

COMMAND-LINE OPTIONS

The command line options are

-n, --dry-run

Show what would be uploaded or deleted on the server, but don't actually do anything.

upfiles -n
--help

Print some brief help information.

-V, --verbose, --verbose=N

Print some diagnostics about what's being done. With --verbose=2 or --verbose=3 print some technical details too.

upfiles --verbose
--version

Print the upfiles program version number. With --verbose=2 also print the version numbers of some modules used.

FILES

~/.upfiles.conf

Configuration file.

~/.netrc

FTP password file.

$localdir/.upfiles.sqdb

SQLite database of information about what has been sent.

BUGS

Changing a local file from a file to a directory or vice versa probably doesn't work very well. Remove it and upload, then create the new and upload that.

FTP requires a couple of round trip command/responses to the server for every file. When uploading many small files something streaming or parallel might be faster. The temp file and rename adds a round trip too, but is desirable so anyone looking at the server doesn't see a half file. Perhaps an option could turn this off if that doesn't matter (upfiles for a remote backup or some such).

The temporary files are named using the local $$ PID added to the target filename. This is enough to protect against simultaneous uploads from the same source machine, but potentially unsafe if you're networked and are foolish enough to upfiles simultaneously from two different source machines. STOU would guarantee uniqueness, but is there a window if interrupted while the name comes back that could leave it created but unknown? Net::FTP put_unique() doesn't return the name until after transfer too.

SEE ALSO

Net::FTP, netrc(5), Net::Netrc, DBD::SQLite

sitecopy(1), ftpmirror(1), ftp-upload(1), rsync(1)

HOME PAGE

http://user42.tuxfamily.org/upfiles/index.html

(Upfiles is good for uploading to tuxfamily.)

LICENSE

Copyright 2009, 2010, 2011, 2012 Kevin Ryde

Upfiles is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Upfiles is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Upfiles. If not, see http://www.gnu.org/licenses/.