"rsyncit" notes                                        Revised: 120710
----------------------------------------------------------------------

1. Overview.

1.1. Purpose of project.

"rsync"  is a  widely-used CLI (Command Level Interface)  backup  tool
that supports backups both to directories mounted locally and across a
network using a protocol of the same name.

This  project  provides  a CLI wrapper  for  "rsync"  that  focuses on
local backups. The wrapper may be  convenient  in  some cases for  the
following reasons:  it  has  a simpler interface than "rsync", it adds
sanity checks, and  it  handles  target-directory  paths  consistently
(this is discussed below).

For more information on "rsync", visit:

      http:https://en.wikipedia.org/wiki/Rsync

1.2. Some details.

The wrapper consists  of a single  Perl5 script  named  "rsyncit"  (or
"rsyncit.pl").

"rsyncit" takes two arguments, not counting option switches:  a source
directory and a target directory.  The script uses "rsync" to  back-up
the directory and  its subdirectories to a subdirectory of the  target
directory.

The  target subdirectory  is transformed  into a  mirror of the source
directory.  As a consequence of this, files already stored in the sub-
directory will be  deleted  unless  corresponding  files exist in  the
source directory.

The  target subdirectory has the same  name as  the  source directory,
minus any higher-level directory components.  For example, the follow-
ing command transforms the directory tree  "/backup/bar" into a mirror
of "/foo/bar":

      rsyncit /foo/bar /backup

Note: This is a possibly significant difference between "rsyncit"  and
"rsync".  "rsync" seems to put files in  different places depending on
whether or not the source path is absolute or relative. "rsyncit" sets
the target subdirectory consistently.

1.3. "rsyncit" was created by OldCoder:

      Site:    http:https://oldcoder.org/
      Mail:    [email protected]
      GitHub:  https://github.com/OldCoder/
      Repo:    https://github.com/OldCoder/rsyncit.git

The license used for the current version is MIT/X.

----------------------------------------------------------------------

2. Development.

2.1. Source code.

Full source code  for the project is provided in the same directory as
this README file. The code  consists of a  single  Perl5 script  named
"rsyncit.pl".

2.2. Requirements.

Requirements are simply  Linux  (or a UNIX  system  that is reasonably
compatible  with Linux), Perl5 5.10.1 or above, and an  installed copy
of "rsync".  The standard  Linux program "less" is recommended but not
required.

2.3. Installation.

No "build" is needed.

To install the package, proceed as follows:

(a) Copy "rsyncit.pl" to wherever you'd like to store  the script.  If
possible, use one of the directories in PATH.

(b) Remove the  ".pl"  filename extension and set  file permissions to
octal 755. For example:

      mv rsyncit.pl rsyncit
      chmod 755     rsyncit

----------------------------------------------------------------------

3. Usage.

Usage: rsyncit         SourceDir TargetDir
or:    rsyncit OPTIONS SourceDir TargetDir

"rsyncit" uses "rsync" to  back-up the specified source directory  and
its subdirectories to a target subdirectory inside the  specified tar-
get directory.

The  target  subdirectory is  transformed into a mirror  of the source
directory.  As a consequence of this, files already stored in the tar-
get subdirectory will be  deleted unless  corresponding files exist in
the source directory.

The  target subdirectory has the same  name as  the  source directory,
minus any higher-level directory components.  For example, the follow-
ing command transforms the directory tree  "/backup/bar" into a mirror
of "/foo/bar":

      rsyncit /foo/bar /backup

----------------------------------------------------------------------

Backing up "/" (or to "/")  is prohibited. "rsyncit" also detects (and
prohibits) cases where the  source tree is inside the destination tree
or vice versa.

----------------------------------------------------------------------

By  default, the  target subdirectory must already exist. This rule is
intended  to reduce  the chances that files  will be  backed up to the
wrong place. To override the rule and create directories  automatical-
ly, use the option "-d":

      rsyncit -d /foo/bar /backup

The  word switch  "--mkdir" has the  same effect as  the letter switch
"-d":
      rsyncit --mkdir /foo/bar /backup

----------------------------------------------------------------------

By default,  "rsyncit" prints some messages but not a complete list of
files as they're copied.  For verbose operation, which includes a list
of this type, use the option "-v":

      rsyncit -v /foo/bar /backup

The word switch  "--verbose" has the same effect as the  letter switch
"-v":
      rsyncit --verbose /foo/bar /backup

----------------------------------------------------------------------

Single-letter  "rsyncit" option switches may be combined. For example,
"-dv" is equivalent to: -d -v.  Additionally,  option switches  may be
placed at any position in the command line. For example, the following
two commands are equivalent:

      rsyncit -v /foo/bar /backup
      rsyncit    /foo/bar /backup -v

----------------------------------------------------------------------

To perform a dry run (i.e., to show what will be done but not actually
do it), use "-n":

      rsyncit -n /foo/bar /backup

The  "word"  switch "--dry-run" (or "--dryrun") has the same effect as
the "letter" switch "-n":

      rsyncit --dry-run /foo/bar /backup

Note: "-n" and its aliases don't imply "-v".  To produce a verbose ex-
planation of what will be done, add the second switch:

      rsyncit -n -v /foo/bar /backup
or:   rsyncit -nv   /foo/bar /backup

----------------------------------------------------------------------

"rsyncit" supports "rsync"-compatible "--exclude" switches.  For exam-
ple, the following command does a backup that excludes the contents of
# directories named "tmp":

      rsyncit --exclude="*/tmp/*" -v /foo/bar /backup

If excluded objects are present in the backup tree  (for example, from
previous  backup  operation),  "rsyncit"  deletes them.  "rsyncit" and
"rsync" differ in this respect;  "rsync"  only does this if the switch
"--delete-excluded" is specified  ("rsyncit" sets the switch in quest-
ion automatically).

----------------------------------------------------------------------

To  pass  "rsync"-level  option switches to "rsync",  use one  or more
"rsyncit"-level option switches of the form:

      --rs:"--foo --bar=xyzzy"
or:   --rsync:"--foo --bar=xyzzy"

where  "--foo --bar=xyzzy"  are  "rsync"-level switches  separated  by
spaces. The  switches  themselves shouldn't  include  spaces or double
quotes.

Each  "--rs" (or "--rsync")  switch may  specify one or more  "rsync"-
level switches. If two or more "--rsync" switches are used, all of the
specified "rsync"-level switches will be passed.

----------------------------------------------------------------------

If multiple backups are done over time using the same source and  tar-
get directories, "rsyncit" reuses existing backup files when possible.
The algorithm used for this purpose is  good enough for most purposes,
but if files are modified and neither timestamps  nor sizes are chang-
ed, modifications of this type may not be detected and backed up.  The
option "-c" may be used to fix this,  but this option will slow things
down.

The word switch "--checksum" has the  same effect as the letter switch
"-c":
      rsyncit --checksum /foo/bar /backup

----------------------------------------------------------------------

The  letter switch "-f" (or the word switch "--flag") tells  "rsyncit"
to manage a "flag" file related to the current backup:

      rsyncit -f /foo/bar /backup

The "flag" file has the same pathname as the target subdirectory,  but
the string  ".rsynced" is added.  "rsyncit" deletes the file initially
and creates it at the end if the backup appears to be successful.

Note: If an object  with the indicated  flag-file name exists and it's
a symbolic link or  anything but a regular file,  flag-file operations
are skipped.  The "-n" (or "--dry-run") option  also suppresses  flag-
file operations.

----------------------------------------------------------------------

If you'd like to save existing files from the target subdirectory that
are going to be modified or deleted, use  the "letter" switch "-b" (or
the "word" switch "--backup"):

      rsyncit -b /foo/bar /backup

This option moves  the current  versions of files that are going to be
modified or  deleted  to a  second  backup-directory tree.  The second
tree is stored in a  directory named "rsyncbak" that's  located in the
same directory as the target subdirectory.

For example,  "rsyncit -b /foo/bar /backup"  will transform  "/backup/
bar"  into  a mirror of  "/foo/bar" while  saving modified  or deleted
files from "/backup/bar" in "/backup/rsyncbak/bar".

----------------------------------------------------------------------

The  "word"  switch "--go" or "--normal"  (there  is no  corresponding
"letter" switch) is equivalent to:

      -bfv
or:   -b -f -v
or:   --backup --flag --verbose