desync
Justin Finnerty
Last Updated %%date(%c)

= NAME =
desync - the directory cleaner

= SYNOPSIS =

Perform directory clean up operations.

```
   desync [-no-filedup] [-no-compdup] [-no-dirdup] [-no-archdup]
          (-peer|-store) directory
	  [-backup-suffix <arg>] [-compress-suffix <arg>]
	  [-archive-suffix <arg>]
	  [-duplicate-cutoff <arg>]
```

Get help text.

```    desync  [-help] or [-h|-?] 

Get current configuration options.

```    desync  [-conf]

= DESCRIPTION =

**desync** is a program that cleans up directories and is particularly
useful where synchronisation is used.  Allowing a user working in
multiple locations to have a working directory in each location, that
are intermittently synchronised, is a major benefit of a program like
**rsync**(1).  However this comes at the price of excess storage
caused by file and directory duplication.  The **desync** program
attempts to reduce this excess storage by identifying and removing
duplication.

The program attempts to address the following causes of duplication.

- File back-ups exist that are actually identical to the original.

- Compressed and uncompressed versions of the same file exist.

- Remove multiple copies of identical archives.

- Where a directory is moved in the working directory, it can become
duplicated in its original and moved positions the next time the working
directory is synchronised.


The **desync** program divides the directories a program like
**rsync** works on into two broad types.  A //peer// type directory
holds files that are being worked on directly by a user and a //store//
type holds a static copy.  The **desync** program performs different
actions depending on the type of the directory.  For example you would
want to keep compressed and uncompressed versions of a file you are
currently working on in a //peer// directory but only want the
compressed version in a //store// directory.

= DESYNC EXECUTION =

The program performs its search for each type of duplication in
stages.  After performing the search for each stage it presents a
report of remedial actions.  The user can then accept, edit or ignore
the actions reported.  For those stages that allow the user to edit
the set of remedial actions an option to regenerate the stage exists.
If the user performs any of the actions of stage, in total or edited,
the program presents a report on the outcome of the actions.  At this
point the user can accept or undo the actions and then go on to the
next stage.

The duplicate directory stage presents a series of remedial actions
for only one pair of duplicated directories at a time.  For each
duplicated directory the user can perform the remedial actions or
search for the next duplicated directory.  This stage will be repeated
until no new duplicated directory is found.

The reports from each stage of the program are presented with a series
of numbered options.  To perform a particular option you type the
number of the option and then press the ``Enter/Return`` key.  The
main option is always the first option, so entering ``1`` each time
will perform the most cleaning up.

= SAFE GUARDS =

For duplicated directories the program attempts to determine the
correct location be determining which one is more recent.  It then
merges the two directories together.  The merging ensures that the
most recent copy of a file ends up in the kept directory.  Any files
that exist in only one of the directories are also kept.

The program does not actually delete any files.  Instead it moves them
into a separate //Trash// directory.  The name of this directory is the
same as the directory to be cleaned up with an additional suffix
derived from the date and time the program was run. This allows the
user to manually inspect the removed files before performing the
actual delete operation to recover disk storage.

All operations of the program are recorded into a log file.  This is
named ``LOG.<suffix>`` where, like the //Trash// directory, the suffix is
derived from the date and time the program was run.  This enables the
user to match the log file to its corresponding //Trash// directory. It
is intended that future versions of the program will be able to use
the log file and the //Trash// directory of files to undo all the
actions performed by a previous execution of **desync**.

= OPTIONS SUMMARY =

== CLEANING UP OPTIONS ==

: ``-archive-suffix <arg>``
A `:` separated list of suffixes used for archive files to be used
in finding duplicate archive files. 

: ``-backup-suffix <arg>``
A `:` separated list of backup filename suffixes to be used in finding
duplicated backup files. The -help option will print the default value
used if this option is not set.

: ``-compress-suffix <arg>``
A `:` separated list of suffixes used for compressed files to be used
in finding compressed duplicated files. 

: ``-duplicate_cutoff <arg>``
The maximum number of files with the same name to consider as
potential leads for finding duplicate branches. The -help option will
print the default value used if this option is not set.

: ``-no-archdup``
Do not attempt to find duplicate archive files.

: ``-no-compdup``
Do not attempt to find files with a compressed duplicate version.

: ``-no-dirdup``
Do not attempt to find duplicated directory trees.

: ``-no-filedup``
Do not attempt to find duplicated backup files.  


== HELP OPTIONS ==

: ``-help``
Print an extended help message to terminal

: ``-h|-?``
Print a short usage message to terminal


== CONFIGURATION ==

: ``-conf``
Print current configuration to terminal


== DIRECTORY OPTIONS ==

: ``-peer <required arg>``
Treat directory as a peer or working directory

: ``-store <required arg>``
Treat directory as a store or back-up directory


= FILES =

Further documentation may be found in /usr/local/share/desync/ or
/usr/share/desync/ directory.


= VERSION =

This man page is current for version 1.0 of **desync**

= CREDITS =

This version of **desync** is distributed under the Eiffel Forum License,
version 2.  See the file LICENSE for details.

I would be delighted to hear from you if you like this program.

This program uses the excellent zlib and bzip2 compression libraries.

= AUTHOR =

**desync** was written by Justin Finnerty.

