
PLEASE READ THE `RELEASE' FILE FOR INFORMATION ON THE CURRENT RELEASE

NOTE: This document is no longer being maintained. The definitive
documentation is the man page (distributed as 'sitecopy.1).

For information on the Windows and OS/2 ports, see the README.emx
file.

What it's supposed to do
------------------------

sitecopy is for copying locally stored websites to remote web servers.
The program will upload files to the server which have changed
locally, and delete files from the server which have been removed
locally, to keep the remote site synchronized with the local site,
with a single command.  The aim is to remove the hassle of uploading
and deleting individual files using an FTP client. sitecopy will also
optionally try to spot files you move locally, and move them remotely.

sitecopy is designed to not care about what is actually on the remote
server - it simply keeps a record of what it THINKS is in on the
remote server, and works from that.

What it's NOT Supposed To Do
----------------------------

sitecopy is NOT for copying ftp- or websites onto your hard disk - if
you want to do that, use mirror or one of it's friends.

If you have shell access to the remote server, then the `rsync'
program is a MUCH better alternative to sitecopy - see
http://samba.anu.edu.au/rsync/.  rsync uses a special protocol which
only transmits the differences between files, which should save you
bandwidth and time.

Also, look at CVS if you want version control too.

How Can I Compile It?
---------------------

Cross your fingers and type `make'. You might want to check the
Makefile first.

How To Upgrade From Old Versions
--------------------------------

If you have used version 0.1 before, but not 0.2 or 0.3.0, it is
highly advisable to perform a `sitecopy -u' using 0.1 on all the sites
you have defined, then upgrade to 0.4.0 and perform a `sitecopy -ca'. 
You have been warned.

Note - if you have only used 0.2.0 or 0.3.0 previously, then you
should have no problem upgrading.

How Do I Set it Up?
-------------------

You need two things: a `~/.sitecopyrc' file, and a `~/.sitecopy'
directory. You need to create them yourself. (Alternate locations can
be specified on the command line - see end of file)

In `.sitecopyrc', a syntax not unlike .netrc (see ftp(1)) is used. As many 
sites can be defined as you like. Give each site a unique name.
A site definition is started by a line containing the `site' keyword.
After this line, you must include lines giving the server, username, password,
remote dir, and local dir:

 site <unique-name>
   server <remote.server.name>
 [ url <full site URL> ]
 [ protocol { ftp | http } ]
 [ port <port number> ]
 [ ftp nopasv ]
   username <username>
   password <password>
   remote <remote-root-directory>
   local <local-root-directory>
 [ permissions <permissions-mode> ]
 [ symlinks <symlinks-mode>
 [ nodelete ]
 [ checkmoved ]
 [ exclude <regex> ]...
 [ rename <localname> <remotename> ]...

Eg:

  site mysite
    server ftp.mysite.com   # My ISP
    username bloggsf
    password pecan
    remote /
    local /home/bloggsf/html/mysite/

Anything past a # in the line is ignored. Values can be quoted:
   local "/home/joe/html/dir name/another"
and escaped:
   local /home/joe/html/dir\ name/another
   password foo\#ba\"r
...if your password is `foo#ba"r'

NOTE: Don't forget to `chmod 600' your ~/.sitecopyrc file to be sure
nobody else can view your passwords. Similarly, `chmod 700' your
.sitecopy directory.

The protocol line is optional - the default protocol is FTP.
Specifying `protocol http' will force WebDAV (an HTTP extension) to
be used.  See the web page at http://www.lyra.org/sitecopy/dav.html
for more information about sitecopy and WebDAV.

The remote directory must give the path to your site on the remote
server. You can either give this as an absolute path (which must
including a leading '/'), or you can give it relative to the login
directory - in which case you MUST prefix the path with '~/'. For
instance, if the web site is held in a directory called 'html' below
the login directory, use:
	remote ~/html
If the site is held directly in the login directory, use:
	remote ~/
NOTE: The remote directory must already have been created on the server - 
sitecopy will not create it, if it has not.

The local directory must be the full path to the local site copy, and
cannot (currently) contain environment variables.

The site URL is only used by -ll mode, see below.

Moving and Deleting Remote Files
--------------------------------

If the 'nodelete' option is specified, remote files will NOT be
removed when local files are deleted.

sitecopy will not normally check to see whether a file has been moved
if it seems to have been deleted locally - add the 'checkmoved' option
to the site definition if you wish this to be done.

If this option is specified, then for every new file added locally,
sitecopy will check for a file with the same name, size and
last-modification time stamp in the rest of the site, and if one is
found, then the file will be moved remotely. This might be useful if
you hold large files in your site which might get moved around.

WARNING: Do NOT use the 'checkmoved' option if you tend to hold files
in different directories with identical sizes, modification times and
names and ever move them about. This seems unlikely, but don't say I
didn't warn you.

Handling File Permissions
-------------------------

The 'permissions' mode indicates whether you wish file permissions to
be set on the remote files. It can take one of three values: 'ignore',
'exec', or 'all':
  * ignore: File permissions are ignored. When you upload a new file,
it's permissions will take the default value.
  * exec: If, when a new file is uploaded, it is executable by the
user who performs the upload, then the permissions bits of the file
remotely will be set to be the same as the permission bits of the file
locally. In other words, if the file has permissions 755 locally, it
will be set to 755 remotely.
 * all: When a new file is uploaded, the permission bits of the file
remotely are set to be the same as the permission bits of the file
locally.

Handling Symbolic Links
-----------------------

The 'symlinks' mode indicates how you wish symlinks in the local site to be
handled:
  * ignore: Any symlinks in the local site are ignored
  * follow: The symlink is followed in the local site, and the corresponding
file/directory is uploaded.
The default mode is to follow symlinks.

Advanced Configuration
----------------------

You can exclude files from being upload by using the 'exclude'
keyword. This is useful, for instance, to prevent backup files from
being uploaded.

  site mysite
    server ftp.wherever.com
    ...
    exclude *~
    exclude "#*#"

This excludes all files ending with a ~, and all files which start and
end with #'s. DON'T FORGET to quote or escape the value if it includes
#'s:
    exclude "#*#"  
is equivalent to
    exclude \#*\#
but 
    exclude #*#
WILL NOT WORK.

You can also have files with different names remotely to locally, e.g.:

  site anothersite
    server ftp.blah.com
    ...
    rename index.html default.htm

This means that any files named `index.html' locally, will be uploaded
as `default.htm'. This might be useful if your remote server only
accepts `default.htm' as the default directory index page, but you
can only use `index.html' locally.

The syntax is:
   rename LOCALNAME REMOTENAME

How Do I Run the Thing?
-----------------------

If you are using an existing site (i.e., it has already been uploaded to
the remote server), then run:
	sitecopy -c sitename
which will make sitecopy think the remote site is an exact copy of the local
site (make sure it is, first!).

If you are using a new site (i.e., it has not been uploaded yet), then
run:
	sitecopy -i sitename
which will make sitecopy think that there are NO files on the server.

Subsequently, when you have changed files locally, run:
	sitecopy -u sitename
to update the remote site from the local files.

If you want to see what sitecopy thinks has changed before doing that,
try:
	sitecopy -l sitename
which is the default action, so the -l can be omitted.

If you wish to see a list of the sites you have defined in the rc file, then 
run:
	sitecopy -v

You can also use the -r and -p options in conjunction with the normal 
options to specify alternate locations for the .sitecopyrc file and .sitecopy 
directory, e.g.:
	sitecopy -r $HOME/etc/sitecopyrc -p $HOME/etc/sitecopy ...
will use the given rc file and directory. The defaults are `~/.sitecopyrc'
and `~/.sitecopy/' as indicated above.

Lastly, you can specify more than one site name on the command line if you 
so wish, e.g.:
	sitecopy -u foosite barsite 

will update both sites, one after the other.

If you wish to a given operation on ALL the sites in your rcfile, use:
	sitecopy -a ...
e.g.:
	sitecopy -a -u
will update all your sites.

Other Stuff
-----------

sitecopy will return the following exit codes when executed in -u (update)
mode:
 -1 ... update never even started - rcfile problem etc.
  0 ... update was entirely successful.
  1 ... update went wrong somewhere
  2 ... could not connect or login to server 

In -l (list) mode (the default), it will return:
 -1 ... could not form list - rcfile problem etc.
  0 ... the remote site does not need updating
  1 ... the remote site needs updating

If you specify multiple sites on the command line, the exit code is in
respect to the last site given.

Flat Listing Mode
-----------------

To produce an easily-parseable output of the changes to a site, use:
	sitecopy -ll sitename

A sample AWK script is provided, changes.awk, to parse this output and
produce an HTML page of changes is provided. If you wish for filenames
to be hyperlinked, you must include a URL for the site. The URL must
NOT include a trailing slash, e.g.:

   site mysite
     server my.server.com
     url http://www.server.com/homepage
   ... etc ...

Creation of such a page could be automated in a site update script,
e.g.:
	
	#!/bin/sh
	if sitecopy -l sitename > /dev/null; then
		echo No changes to the site.
		exit
	fi
	sitecopy -ll sitename | awk -f changes.awk > /local/site/changes.html
	sitecopy -u sitename

Debugging
---------

The -d argument takes an integer parameter which is the sum of any of
the following values:
	
	1	Socket handling
	2	File handling
	4	rcfile parser
	8	HTTP driver
	16	FTP driver
	32	Gtk interface

So, add any of the above together for the relevant debugging messages
to be produced. Debugging messages are sent to stderr.

e.g. for debugging socket handling and the HTTP driver, use 1 + 8 = 9:
	sitecopy -d 9 -u blah etc


The Frequently Asked Question
-----------------------------

- Why not use mirror, rsync, fmirror etc etc?

sitecopy is for maintaining web sites via FTP. This cannot be done
with rsync or fmirror, which require shell accounts on the web server.

You can use mirror instead of sitecopy - the basic functionality is
duplicated. But, sitecopy does NOT go to the FTP server and see what's
there every time - this is the fundamental difference between sitecopy
and mirror. This saves bandwidth, and startup time, especially so for
slow servers holding large sites. Also, sitecopy has some features
missing in mirror (though the reverse is also true), such as remote
file move and interactive confirmations.

Also, sitecopy can use WebDAV as well as FTP.
