GNU usbsync 0.1 - README ======================== Copyright (C) 2008, 2009 Free Software Foundation, Inc. Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. About ----- usbsync is a small but powerful utility that assists you in keeping files as well as entire directory trees synchronized between a portable storage volume (such as a usb flash drive) and arbitrarily many hosts. This is accomplished by employing a special text file used by the usbsync program. The file, usually named `.usbsync', is placed in a storage volume's top-level directory and contains user-written synchronization entries. These entries define certain file and directory correspondences and thereby allow a user to specify which data objects one the storage volume are to be kept synchronized with their counterparts on any number of local hosts. The basic concept of having correspondences specified in a file is greatly enhanced by a large number of options; a user is able to directly set some of those in the `.usbsync' file, whereas others are to be given as arguments on the command line. In order to get an understanding of how to use usbsync appropriately please refer to the manual pages `usbsync(1)' and `usbsync(5)' or to the info pages `usbsync' and `usbsyncfile' which will be present on your system after the installation process has successfully been completed. If you are looking for a short introductory example please see the section titled "Getting started" further down in this README. Installation ------------ For a basic installation, executing the following sequence of commands in your system shell should suffice in most cases: `./configure' `make' `sudo make install' Please note that in order to install usbsync properly you have to be logged in as root or use the `sudo' program as shown in the last of the above steps. To obtain a list of all possible options to the configuration script, you may exectute `./configure --help'. If you intend to set up usbsync in debugging mode you may do so by entering `./configure --enable-debug' For more advanced installation options, please see the ./INSTALL file for additional instructions. Getting started --------------- For the purpose of providing a quick and pratical example of how to use usbsync, the top-level source directory (the same directory in which this ./README can be found) contains a directory named `sample'. Therein, a hypothetical "storage volume/hard disc" set-up is presented to illustrate the use of usbsync with it: The `sample' directory contains two sub-directories named `hdd' and `usb'. Suppose `hdd' to be the root of your local host and `usb' to be the top-level directory of your portable usb flash drive. In order to successfully try out usbsync with this set-up a few changes in the `.usbsync' file residing in the `usb' directory are necessary. Edit this file by replacing all brackets <...>, once with the path on your local machine, that is, where you have unpacked the usbsync-0.1 distribuation directory to, and once with the user@host combination specific to your user and machine. Now, you may run the usbsync program with the following command, assuming that your current working directory is the usbsync distribution's top-level directory: `usbsync sample/usb' As you can see, files and directories are being synchronized, meaning that, in this case, they are simply copied or created respectively. The directory tree of the `sample' directory before running usbsync should have looked like the following schematic: sample/ |-- hdd | `-- dir_on_hdd | |-- file_1 | `-- file_2 `-- usb |-- dir_on_usb | `-- subdir | |-- file_in_subdir | |-- file_in_subdir2 | |-- file_in_subdir3 | `-- subsubdir |-- just_a_file_usb `-- .usbsync After running usbsync both, the `hdd' directory being an arbitrary folder on your host, and the `usb' directory, being a hypothetical mass storage volume, should look similar. Since the `.usbsync' file associates the directory `dir_on_usb' with the directory `dir_on_hdd' both get synchronized recursively, meaning that their contents will exactly match after the synchronization process has successfully finished. The single file `just_a_file_usb' is defined to correspond to the file `just_a_file_hdd' in the directory `hdd'. Since the latter one does not exist it will subsequently be copied from `usb' to `hdd' during synchronization. Please refer to the manual page usbsync(5) for a more detailed description of the expected format of a `.usbsync' file. Additional notes ---------------- Although usbsync as a whole has been designed to be as portable as possible you might very unlikely encountered a situation in which compilation fails. Moreover, there might be certain scenarious in which usbsync as a program yields an unexpected result or behaves strangely. According to the paradigm of constantly improving this piece of software you may hereby be highly encouraged to report any bugs you encounter to the package maintainer. Also, if you have in mind to contribute or offer your assistance to the usbsync project, you are very much welcome to do so. Please contact the package maintainer named below. GNU usbsync is currently maintained by: Soeren Wellhoefer You may also directly contact one of the authors listed in the ./AUTHORS file for further requests or comments. Feel also free to visit the projects webpage at http://usbsync.sourceforge.net License ------- usbsync has been released under the terms of the GNU General Public License Version 2. For more specific information on the terms and conditions please see the ./COPYING file.