vovasync

Download from http://sourceforge.net/projects/vovasync
Updated: September 21, 2006

 

NAME

vovasync - a file synchronizer, works with multiple copies (>2), suitable for flash  

SYNOPSIS

vovasync
vovasync -h
vovasync [ -r rpath ] [ rname1 [ rname2 ... ]]
vovasync [ -r rpath ] -a new-rname lcpath
vovasync [ -r rpath ] -c [ -l ] rname lcpath
vovasync [ -r rpath ] -l [ rname1 [ rname2 ... ]]
vovasync [ -r rpath ] -z [ rname1 [ rname2 ... ]]
vovasync [ -r rpath ] -e [ rname1 [ rname2 ... ]]
vovasync [ -r rpath ] -E [ rname1 [ rname2 ... ]]
vovasync [ -r rpath ] -t [ rname1 [ rname2 ... ]]
 

DESCRIPTION

Imagine the situation when you have some files on one computer and transferring them to another. Then do some edits or add/delete some files on the second computer and then transferring them back to the first comp. Or you want to keep the same directory structure on Linux and Windows systems. Or you want to synchronize 3 or 4 copies. And you're using flash for transfers, but you want to preserve unix file attributes. And you have big and branchy directory structure and you're tired of manual transfers. If so, then VOVASYNC IS FOR YOU!


vovasync is a tool which maintains the repository (or several repositories), for example, on flash, and synchronizes file structure by simply typing 'vovasync' in command-line. vovasync is designed for unix file systems, but it also can be used in Windows (by means of CygWin <http://www.cygwin.com/>). For unix file systems permission info is preserved (inspite of vfat on flash, where the repository can reside). (For the file structure under Windows/CygWin preserving permissions can be switched off). (Info about user and groups is not preserved. Sorry.)


Ok. Let's have some terminology to make it clear.


Super-repository - main file structure, fully maintained by vovasync, which resides on a mobile drive like flash or mobile HDD, and is used for transferring files between different systems. Super-repository may contain several repositories. One user may have one and only one super-repository. And super-repository may belong to only one user.


Repository - a file structure, fully maintained by vovasync, containing neccessary files for transferring and syncing between local copies. A repository has a unique text name (user given). A repository is linked to one, two (normally), three and more local copies on different systems, which should be synced. Linking is made by numerical keys (each for each local copy ), maintained by vovasync. A repository is a part of one and only one super-repository and resides on a mobile drive. A repository can be in two main states: normal (compressed) state and full-image state. In normal state a repository contains only those files which are needed for syncing - new and edited files. If a file is synced among all local copies  - it's removed from repository in normal state. In full-image state a repository contains all files from a local copy. Full-image state is used for creating and linking new local copies of this repository.


Local copy - a directory structure on a particular computer (or system) which should be synced with the same dir structure on other computer. This is normal directory structure where we are working. It doesn't contain any special hidden files for vovasync and we can do anything we want there - create new files, edit them, rename, delete and so on. A local copy is linked to the repository by numeric key (maintained by vovasync ) and must reside at particular absolute path (registered when a repository or new local copy are created).


MainFileBook - a special file which resides in a repository and is maintaned by vovasync. It contains main info about files to be synced, about linking to local copies, file attributes, modification times, etc. If you lose this file - you'll lose a repository. That's why it's backed up in ~/.vovasync local directories.


~/.vovasync - special directory (one per one user and per one system), maintained by vovasync, which contains key and path information about local copy(ies) on the system which are linked to particular repository(ies).


First steps


First, a repository must be created. Typically you already have some dir structure which needs to be synced. In other words, you already have a local copy. So, you create a new repository by -a command:


vovasync [ -r rpath ] -a new-rname lcpath


where rpath is a path to your super-repository (to flash drive, for example, where your all repositories will be stored). For comfort you can define $VOVASYNC_REPOSITORY environment variable with absolute path to super-repository and not specify -r option. new-rname is the name of new repository to be created. Think of some suitable name for you. For example, "MyProjectXYZ". This name will uniquely define your repository among all local copies and against other repositories (if you have several ones). The name will be used for operations on particular repository. lcpath is a path to your local copy (you can specify relative path, though it will be extended to absolute). On executing vovasync will ask you if your local copy should support file permissions. Answer 'y' for unix file-systems, and 'n' for fat or ntfs. Then your files will be copied from the local copy to the repository :
LC -->Rep:file1
LC -->Rep:file2
LC -->Rep:dir1/file3

 ...
This will create the repository in full-image state (containing all files from the local copy ) from which a new local copy on a different system can be created. Also your local copy is linked to repository now. (Neccessary files in ~/.vovasync directories are created.)


The second step - creating a new local copy on a different system (or in a different place) from the existing repository. This is done by the command:


vovasync [ -r rpath ] -c [ -l ] rname lcpath


where rname is the name of existing repository in full-image state. lcpath is a new path to new local copy which will be created. Also you will be asked to choose if vovasync should take into consideration file permissions for this local copy. On execution you will see some kind of the following:
Rep-->LC :file1
Rep-->LC :file2
Rep-->LC :dir1/file3

 ...
So, files from the repository will be copied to new local copy and neccessary file attributes will be assigned (mod times and permissions). Then (if you haven't typed -l option) the repository will be "compressed". This means all unneccessary files will be removed from the repository. So, DON'T BE AFRAID when you see:
Deleting from Rep:file1
Deleting from Rep:file2
Deleting from Rep:dir1/file3

 ...
This means that the repository returns to its normal "compressed" state. And in normal state it contains only new and editted files neccessary for syncing. Note, that after "compressing" you can't create new local copy from the repository. If you want to create the 3rd and 4th (and so on) local copies you should type -l option while invoking -c command. This will "leave" full-image (all files) in repository.
Anyway, if your repository is in normal state - you can return it back to full-image state by invoking -l command:


vovasync [ -r rpath ] -l [ rname1 [ rname2 ... ]]


(By default, if no repository names specified - all repositories are transferred to full-image state).
You can "compress" a repository manually by invoking -z command:


vovasync [ -r rpath ] -z [ rname1 [ rname2 ... ]]


********************
* Normal operation *
********************


When you have created a repository and neccessary local copies you can do normal syncing between them. Typically you should just type:


vovasync


to sync all repositories on current system. Or:


vovasync [ -r rpath ] [ rname1 [ rname2 ... ]]


if you haven't specified $VOVASYNC_REPOSITORY variable and/or you want not all but particular local copies to be synchronized.


Normally, your working session on a computer must start with typing vovasync and must end with vovasync. First 'vovasync' will transfer new files from a repository(ies) to your computer. And the second 'vovasync' will transfer new and edited files back to repository(ies). When you come to other computer and type 'vovasync' there - these new and edited files will be copied to local copy of the second computer. You will get an output something like that:
Rep-->LC :file1
LC -->Rep:file2
Deleting :file3

 ...
Cleaning the repository...
Deleting from Rep:file1
Deleting from Rep:file3

 ...
In this example the local copy has old file1 or doesn't have it at all, and so it's copied from the repository to the local copy. file2 is new or edited in this local copy, so it's copied to the repository and then will be copied to other local copies on other computers. file3 was not found in this local copy, but found in MainFileBook, so it's considered to be deleted and it will be deleted in other local copies. file1 is synced among all local copies and it is cleaned out from the repository. file3 is cleaned out because it's deleted. And so on.

NOTE. Please, do 'vovasync' more often because it doesn't resolve conflicts automatically. For example, if you haven't synced for long time and have edited same files in different local copies - these editings will not be merged, but the newer file will overwrite the older one. Be careful.


 

COMMANDS AND OPTIONS

<no opts>
Perform normal syncing operation. If rnames are not specified - perform operation on all repositories.
-h
Print help message.
-r rpath
Specifies path to super-repository. Optional if $VOVASYNC_REPOSITORY variable is set.
-a
Create new repository.
-c
Create new local copy from existing repository which must be in full-image state.
-l
When used as option with -c command - tells not to "compress" a repository to normal state. When used as command - create full-image state of repository from current local copy.
-z
"Compress" repository to normal state. If rnames are not specified - compress all repositories.
-e
Unlink current local copy from repository. Files in local copy will remain. Only link to repository will be deleted. If rnames are not specified - perform operation on all repositories.
-E
Delete a repository. A repository must contain last link to the last local copy. Otherwise, equivalent to -e. If rnames are not specified - perform operation on all repositories.
-t
Touch a local copy. This means setting appropriate file permissions and modification times on files in local copy. This is done automatically after normal syncing operations. This option must be used only after crashing or when somehow mod times of synced files became newer but files theirselves were not altered. vovasync will tell you when and how to use this command after failure of vovasync. If rnames are not specified - perform operation on all repositories.
 

FILES

<super-rep-path>/<rname>.subrepository - a directory containing all data of particular repository on mobile drive.


<rname>.subrepository/MainFileBook - Main repository file. (See terminology above). Has text format, but shouldn't be hacked manually without a need.


<rname>.subrepository/root - a directory containing files for syncing or full-image.


~/.vovasync - a directory, locally created on systems in user home dir. Contains information about local copies on particular computer of particular user.


~/.vovasync/<rname>.path - a file containing absolute path of local copy. Can be corrected manually if local copy moved to other location. rname is the name of repository which the local copy is linked to.


~/.vovasync/<rname>.<key> - a file used to bind local copy to repository via numerical key. Also the file contain parameters of the local copy. For now "attr" or "noattr" specify if local copy supports file permissions.


~/.vovasync/<rname>.mfb_backup - a backup of MainFileBook after latest syncing.

ENVIRONMENT

VOVASYNC_REPOSITORY - absolute path to super-repository.

FEATURES AND LIMITATIONS

Comparing of files is based on modification times. Contents is not compared. So, if files are identical, but have different mod times - they are considered to be different.


Some problems may appear with non-ascii file names when transferring them from Unix to Windows and back. Try not to use non-ascii encodings across platforms.


Different users and groups in file attributes are not supported. All files will belong to one user.


In Unix don't create files in the same directory with the same names but in different cases, like:
File1
fILe1
These will be different files in Unix fs, but will lead to collision on flash (because FAT will treat them as one file).


When using 8.3 DOS names - don't make them in upper case. Make them in lower or mixed case. Otherwise, problems will with FAT on flash. (Linux vfat driver transfers 8.3 upper-case names to lower-case automatically, which causes vovasync database inconsistency). vovasync will inform you if you have such 8.3 upper-case files and won't proceed.


Try not to press Ctrl-C while long operations. Though the SIGINT signal is handled properly, the repository can remain in inconsistent state. It can be recovered by restoring MainFileBook from local backups and/or 'touching' local copy. vovasync will inform you what to do.  

BUGS

WARNING! Version 1.0 of vovasync is very very BETA version. Use with caution and at your own risk. Though I'm using it myself, and it's working so far so good - still there can be bugs in complicated situations. So, don't trust your important files to vovasync or backup your files.
Send bug reports to < vpodobaev (at) mail (point) ru>  

AUTHOR

Vladimir Podobaev <vpodobaev (at) mail (point) ru>

LICENSE

vovasync - a file synchronizer.
Copyright (C) 2006 by Vladimir Podobaev.

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 of the License, 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. See the file COPYING in vovasync distribution package.


This document was created by man2html, using the manual pages.
Time: 09:19:46 GMT, September 22, 2006