  Backup Copy - a mirroring utility for backing up your files
  Kevin Lindsay <klindsay@mkintraweb.com>
  Yuuki NINOMIYA <gm@debian.or.jp>
  $Date: 2001/03/30 14:53:06 $

  This document is the user's manual for Backup Copy.  Please read this
  before using the program.
  ______________________________________________________________________

  Table of Contents


  1. Introduction
  2. Description
  3. Usage
     3.1 Installation
     3.2 Command Line Options
     3.3 Examples
     3.4 Config File

  4. License
  5. Notice
  6. Tested Operating Systems
  7. Limitations
  8. Future Plans
  9. FAQ
  10. Request to Users
  11. Author
  12. The Latest Release
  13. The Latest Source Code
  14. Acknowledgement
     14.1 Borrowed Code / Library
     14.2 Contributions of Code or Document
     14.3 Translations
     14.4 Other

  15. History


  ______________________________________________________________________

  1.  Introduction

  This is my first attempt at somewhat proper documentation for Backup
  Copy. Hopefully this will provide an easy, quick guide to using this
  program. If there is anything that you feel should be changed, or if I
  should be knocked-up-side the head about, please let me know. (c;
  Contact info is at the bottom of this file.


  2.  Description

  Backup Copy is basically a smart copy program that allows a user to
  copy mass files from one place to another.  When coping over a
  previous copy, the key features will allow coping only of new or non
  existing files in the backup.  This results in saving time and less
  load on the drive.  Built into the same feature of copying new files
  only, is a file removal procedure.  If a file is removed from the
  source path, the same file will be removed when the next backup is
  performed.  This provides a backup that is exactly the same as the
  source without filling up the drive.  As an added option, all files
  that will be overwritten or deleted when doing a copy over a previous
  backup, have the opportunity to be stored in a trash bin.  You can
  leave this trash bin to grow and grow just in case you need a backup
  of your backup.  When you start running out of disk space you will
  need to remove or clean up the trash bin.
  3.  Usage



  3.1.  Installation

  The installation is very simple.  Run the following:



       $ ./configure
       $ make
       # make install



  3.2.  Command Line Options

  usage: cpbk [OPTIONS] SOURCE... DEST
  or: [OPTIONS] cpbk -c FILE


  Options:


     -c, --config=FILE
        Specify a configuration file.  See sub section "Config File"
        below on how to use the configurationfile.


     -e, --exclude="FILE,..."
        Exclude specified directories and/or files from the copy.  This
        option is handy for excluding NFS mounts that might result in
        multiple copies of the same files. Also if you are backup a
        directory which contains your destination directory for you
        backup, excluding your destination directory would be mandatory.


     -t, --trash-bin=DIR
        Move all overwritten or removed files from the last backup to
        the specified trashbin.


     -l, --list
        Display a listing of each name of new files, updated files,
        removed files, new directories and removed directories.


     -n, --nlist
        Display the number of new files, updated files, removed files,
        new directories and removed directories.


     -s, --simulate
        Perform ordering simulation. It doesn't actually change any
        files/directories.


     -f, --force
        Copy all files whether updated or not.



     -i, --inode-ctime
        Enable using ctime that is changed by writing or by setting
        inode information for file comparison check.  Cpbk assume a file
        has been updated with this option if the ctime is changed.


     -I, --ignore-minor-error
        Ignore minor error that process can proceed.  It may be danger.
        Please use this feature carefully.


     -q, --quiet
        Quite mode. Suppress all error messages and progress
        information.


     -p, --suppress-progress
        Suppress progress information.


     -v, --verbose
        Verbose mode. Display processed file names.


     -h, --help
        Display help and exit.


     -V, --version
        Display version information and exit.



  3.3.  Examples


     cpbk /source /dest
        Copy only updated files (or newly added files) from source
        directory to destination directory from the previous backup.
        And remove any files that have been removed from source
        directory from the previous backup.


     cpbk -t /trashbin /source /dest
        Perform the same action as 1st example, except copy all files
        that are being overwritten or removed from the previous backup
        to a trash bin.


     cpbk -t /trashbin -e "/excludedir1,/excludedir2" /source /dest
        Perform the exact same action as 2nd example except exclude two
        directories that are located in the source.



  3.4.  Config File

  If you so desire you may use a configuration file for some options.
  The file "sample.cpbkrc" should also have been included with your copy
  of Backup Copy. Below I will list how to to use each option for Backup
  Copy.

  (Notes: configuration in the file can be overrode by command line
  options)


  As a standard rule, ON and OFF will be represented as follows:


  o  ON = "True" or "Yes" or "1"

  o  OFF = "False" or "No" or "0"

  To toggle an option, simple place an equal mark then a True or False
  after the option. ie, this will turn an option on :


  ______________________________________________________________________
  OPTION = True
  ______________________________________________________________________



  Configuration Options:


     Source
        Specify a directory that you would like to copy your files from.
        For example:


        ________________________________________________________________
        Source = /home/foo
        ________________________________________________________________



     Dest
        Specify a directory that you would like to copy your file to.
        For example:


        ________________________________________________________________
        Dest = /home/backup
        ________________________________________________________________



     Exclude
        Specify directories and/or files that you would like to exclude.
        If you want to specify multiple directories or files, write
        multiple parameters. Same as --exclude option.  For example:


        ________________________________________________________________
        Exclude = /home/foo/garbage
        Exclude = /home/foo/temp
        ________________________________________________________________



     SaveExclude
        Set this parameter to False if you want to remove excluded
        directories and files from destination directory.


     TrashBin
        Move all overwritten or removed files from the last backup to
        the specified trash bin directory. Same as --trash-bin option.
        For example:


        ________________________________________________________________
        TrashBin = /home/foo/trashbin
        ________________________________________________________________



     Simulate
        Perform ordering simulation. It doesn't actually change any
        files/directories. Same as --simulate option.


     Force
        Copy all files whether updated or not. Same as --force option.


     InodeCtimeCheck
        Enable using ctime that is changed by writing or by setting
        inode information for file comparison check.  Cpbk assume a file
        has been updated with this option if the ctime is changed. Same
        as --inode-ctime option.


     FileSizeCheck
        Enable using file size for file comparison check.


     IgnoreMinorError
        Ignore minor error that process can proceed.  Same as --ignore-
        minor-error option.


     Quiet
        Quite mode. Suppress all error messages and progress
        information.  Same as --inode-ctime option.


     SuppressProgress
        Suppress progress information. Same as --suppress-progress
        option.


     Verbose
        Verbose mode. Display processed file names. Same as --verbose
        option.



  4.  License

  Copyright (C) 1998 Kevin Lindsay <klindsay@mkintraweb.com>
  Copyright (C) 2001 Yuuki NINOMIYA <gm@debian.or.jp>

  This program 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 2, or (at your option)
  any later version.

  This program 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 this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  USA.



  5.  Notice

  This software uses shhopt for parsing command line options.  Shhopt is
  released under the Artistic License. You can use it separately under
  the Artistic License if you want.



  6.  Tested Operating Systems


  o  Debian GNU/Linux sid



  7.  Limitations

  None.



  8.  Future Plans

  Support for --one-file-system option.  It is for skipping
  subdirectories that are on different filesystems from the one that the
  copy started on.


  9.  FAQ

  None.



  10.  Request to Users

  Comments, suggestions, bug reports and patches are always welcome.
  Please mail them to the following address.



  11.  Author

  Kevin Lindsay <klindsay@mkintraweb.com> (original author)
  Yuuki NINOMIYA <gm@debian.or.jp> (after Ver 3.0.0 author)



  12.  The Latest Release

  The latest official release of cpbk is available from:
  <http://www.enjoy.ne.jp/~gm/program/cpbk/index.html>



  13.  The Latest Source Code

  You can get the latest source code with Anonymous CVS.  Specify
  `:pserver:anonymous@linuxlovers.yi.org:/var/cvs' as repository, `cpbk'
  as project name, `anonymous' as password.


  ______________________________________________________________________
  % cvs -d :pserver:anonymous@linuxlovers.yi.org:/var/cvs login
  (Logging in to anonymous@linuxlovers.yi.org)
  CVS password: anonymous
  % cvs -d :pserver:anonymous@linuxlovers.yi.org:/var/cvs checkout cpbk
  ______________________________________________________________________



  See <http://www.cvshome.org/docs/manual/index.html> for details about
  CVS.



  14.  Acknowledgement



  14.1.  Borrowed Code / Library


     Sverre H. Huseby <sverrehu@online.no>

        o  shhopt.[ch] (parsing command line arguments)



  14.2.  Contributions of Code or Document


     Michael Oswell <oswell@xcert.com>

        o  For porting Backup Copy to HPUX, AIX, IRIX, and SUNOS.


     John Quinn <jquinn@soggey.ilo.dec.com>

        o  For porting Backup Copy to Digital UNIX V4.x gcc 2.8.0.


     Karl Iorio <iorio@i-cafe.net>

        o  For providing excellent beta testing and patch work.


     Jeff Trawick <trawick@ibm.net>

        o  For providing beta testing and partial patches.


     Robert Schouwenburg <rds@stack.nl>

        o  For providing helpful support and beta testing.


     Iain Patterson <me@iain.cx>

        o  For providing a patch fixing a bug that cpbk cannot copy a
           file properly in particular condition.



  14.3.  Translations


     Jacques JANVILLE <janville@worldnet.fr>

        o  French translations (fr.po) and man page



  14.4.  Other

  Thanks to many people who send me comments, bug reports and
  suggestions.

  And thank you for using cpbk!



  15.  History


     March 30, 2001 Ver 4.1.0

        o  The bug is fixed that exclude facility doesn't work when "/"
           is specified as source directory.
           Thanks to Torsten Wolf <t.wolf@tu-bs.de> and Hans Zoebelein
           <hzo@gmx.de>.

        o  IgnoreMinorError feature has been added.

        o  Checking return value of close() system call.

        o  Display detected excluded directories/files on verbose mode.

        o  The bug is fixed that directories/files that is not specified
           are excluded.

        o  The bug is fixed that file cannot be excluded.
           Thanks to Mario Vanoni <vanonim@dial.eunet.ch>.

        o  Parameter name `ExcludeDir' and `SaveExcludeDir' are changed.
           Please modify your configuration file. (sorry to bother you)

        o  The bug is fixed that latest file (not removed/overwritten)
           is copied to trash bin.
           Thanks to Michael Doerner <michael@baypc.co.nz>.

        o  Support for detection/modification of just permissions and
           ownership.
           Thanks to AAron nAAs <anaas@questra.com>.

        o  French translations (fr.po) and man page have been added.
           Thanks to Jacques JANVILLE <janville@worldnet.fr>.


     March 27, 2001 Ver 4.0.0

        o  Most codes have been rewritten from scratch.  Please use it
           with care because specification was changed largely.


     March 20, 2001 Ver 3.0.2

        o  Using file_copy() function instead of link() system call for
           copying a file to trash bin. Because hard links, as created
           by link(), cannot span filesystems.
           Thanks to Mario Vanoni <vanonim@dial.eunet.ch>.


     March 15, 2001 Ver 3.0.1

        o  The bug is fixed that cpbk cannot copy a file properly when
           it replaces an existing file with a smaller file without
           recursive mode.
           Thanks to Iain Patterson <me@iain.cx>.


     March 14, 2001 Ver 3.0.0a

        o  Installing not only English but also Japanese man page when
           run "make install".


     March 10, 2001 Ver 3.0.0

        o  Development of this program is taken over by Yuuki NINOMIYA
           <gm@debian.or.jp>.

        o  Autoconfiscate, automakize and gettextize.

        o  Using parsecfg for parsing a configuration file.

        o  Using shhopt for parsing command line arguments.

        o  Providing SGML documents.

        o  Japanese translations (ja.po) has been added.



