\input texinfo
@c %**start of header
@setfilename sharutils.info
@settitle GNU @code{shar} utilities
@finalout
@c %**end of header

@include version.texi

@ifinfo
@set Francois Franc,ois
@end ifinfo
@tex
@set Francois Fran\noexpand\ptexc cois
@end tex

@ifinfo
@format
START-INFO-DIR-ENTRY
* Shar utilities: (sharutils).          GNU shar utilities.
* mail-files: (sharutils)mail-files invocation. Send files to remote site.
* mailshar: (sharutils)mailshar invocation.     Make and send a shell archive.
* remsync: (sharutils)remsync invocation.       Synchronize remote files.
* shar: (sharutils)shar invocation.             Make a shell archive.
* unshar: (sharutils)unshar invocation.         Explode a shell archive.
* uudecode: (sharutils)uudecode invocation.     Restore file from 7-bits.
* uuencode: (sharutils)uuencode invocation.     Force binary file to 7-bits.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
This file documents the GNU set of shar utilities.

Copyright (C) 1994 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifinfo

@titlepage
@title GNU sharutils, version @value{VERSION}
@subtitle A set of shell archiver utilities
@subtitle Edition @value{EDITION}, @value{UPDATED}
@author Jan Dj@"arv
@author @value{Francois} Pinard

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1994 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end titlepage

@ifinfo
@node Top, Introduction, (dir), (dir)
@top GNU @code{shar} utilities

@c @item @b{@code{sharutils}} @value{hfillkludge} (UtilD, SrcCD (??))
@c
GNU @code{shar} makes so-called shell archives out of many files,
preparing them for transmission by electronic mail services,
while @code{unshar} helps unpacking shell archives after reception.
Other tools help using @code{shar} with the electronic mail system,
and even allow synchronization of remote directory trees.
This is release @value{VERSION}.

@menu
* Introduction::                Introduction to this toolset
* Basic::                       The basic @code{shar} utilities
* Wrappers::                    Simple wrappers around @code{shar}
* Remsync::                     Remote synchronisation of directories

 --- The Detailed Node Listing ---

The basic @code{shar} utilities

* shar invocation::             Invoking the @code{shar} program
* unshar invocation::           Invoking the @code{unshar} program
* Miscellaneous::               Miscellaneous considerations

Invoking the @code{shar} program

* Selecting::                   Selecting files
* Splitting::                   Splitting output
* Headers::                     Controlling the shar headers
* Stocking::                    Selecting how files are stocked
* Transmission::                Protecting against transmission
* Kinds::                       Producing different kinds of shar

Simple wrappers around @code{shar}

* Invoking mailshar::           The @code{mailshar} command and arguments
* Invoking mail-files::         The @code{mail-files} command and arguments
* Invoking find-mailer::        The @code{find-mailer} command and arguments

Remote synchronisation of directories

* Quick start::                 Quick start at using @code{remsync}
* Invoking remsync::            The @code{remsync} command and arguments
* Conveniences::                Automatic mechanisms in the @code{remsync} program
* Commands::                    Commands for @code{remsync}
* Internals::                   How @code{remsync} works
* Formats::                     Related file formats
* Xremsync::                    Format of the @file{.remsync} file
* Package::                     Format of transiting packages
* Alternatives::                Other means to synchronization
* Previous::                    Documentation for obsolete scripts

The @code{remsync} command and arguments

* Conveniences::                Automatic mechanisms in the @code{remsync} program
* Commands::                    Commands for @code{remsync}

Related file formats

* Xremsync::                    Format of the @file{.remsync} file
* Package::                     Format of transiting packages

Documentation for obsolete scripts

* mailsync::                    mailsync
* resync::                      resync
@end menu

@end ifinfo

@node Introduction, Basic, Top, Top
@chapter Introduction to this toolset

GNU @code{uuencode} and @code{uudecode} have an history which roots
are lost in ages, and we will not even try to trace it.  The current
versions were brought into GNU by Ian Lance Taylor, and later
modernized by Ulrich Drepper.  GNU @code{shar} surely has a long
history, too.  All along this long road, numerous users contributed
various improvements.  The file @file{THANKS} in the distribution,
as far as we know, contain the names of all contributors we could
identify, and for which email addresses are seemingly valid.

Please help us getting the history straight, for the following
information is somewhat approximative.  James Gosling wrote the
public domain @code{shar 1.x}.  William Davidsen rewrote it as
@code{shar 2.x}.  Warren Tucker implemented modifications and called
it @code{shar 3.x}.  Richard Gumpertz maintained it until 1990.
@value{Francois} Pinard, from the public domain @code{shar 3.49}, made
@code{GNU shar 4.x}, in 1994.  Some modules and other code sections
were freely borrowed from other GNU distributions, bringing this
@code{shar} under the terms of the GNU General Public License.

The few wrapper scripts and the @code{remsync} program have been
contributed more recently by @value{Francois} Pinard, just as an
attempt for making this GNU @code{sharutils} toolset more useful.

Your feedback helps us to make a better and more portable product.
Mail suggestions and bug reports (including documentation errors)
for these programs to @file{bug-gnu-utils@@prep.ai.mit.edu}.

@node Basic, Wrappers, Introduction, Top
@chapter The basic @code{shar} utilities

GNU @code{shar} makes so-called shell archives out of many files,
preparing them for transmission by electronic mail services.
A @dfn{shell archive} is a collection of files that can be unpacked by
@code{/bin/sh}.  A wide range of features provide extensive flexibility
in manufacturing shars and in specifying shar @emph{smartness}.  For
example, @code{shar} may compress files, uuencode binary files, split
long files and construct multi-part mailings, ensure correct unsharing
order, and provide simplistic checksums.  @xref{shar invocation}.

GNU @code{unshar} scans a set of mail messages looking for the start
of shell archives.  It will automatically strip off the mail headers
and other introductory text.  The archive bodies are then unpacked by
a copy of the shell.  @code{unshar} may also process files containing
concatenated shell archives.  @xref{unshar invocation}.

@menu
* shar invocation::             Invoking the @code{shar} program
* unshar invocation::           Invoking the @code{unshar} program
* Miscellaneous::               Miscellaneous considerations
@end menu

@node shar invocation, unshar invocation, Basic, Basic
@section Invoking the @code{shar} program
@pindex shar

The format of the @code{shar} command is one of:

@example
shar [ @var{option} ] @dots{} @var{file} @dots{}
shar -S [ @var{option} ] @dots{}
@end example

In the first form, the file list is given as command arguments.  In the
second form, the file list is read from standard input.  The resulting
archive is sent to standard output unless the @code{-o} option is given.

Options can be given in any order.  Some options depend on each other:
the @code{-o} option is required if the @code{-l} or @code{-L} option
is used.  The @code{-n} option is required if the @code{-a} option
is used.  Also see @code{-V} below.

Some options are special purpose:

@table @code

@item --help
Print a help summary on standard output, then immediately exits.

@item --version
Print the version number of the program on standard output, then
immediately exits.

@item -q
@itemx --quiet
Verbose @emph{off} at @code{shar} time.  Messages are usually issued
on standard error to let the user follow the progress, while making
the archives.  This option inhibits these messages.

@end table

@menu
* Selecting::                   Selecting files
* Splitting::                   Splitting output
* Headers::                     Controlling the shar headers
* Stocking::                    Selecting how files are stocked
* Transmission::                Protecting against transmission
* Kinds::                       Producing different kinds of shar
@end menu

@node Selecting, Splitting, shar invocation, shar invocation
@subsection Selecting files

@table @code

@item -p
@itemx --intermix-type
Allow positional parameter options.  The options @code{-M}, @code{-B},
@code{-T}, @code{-z} and @code{-Z} may be embedded, and files to
the right of the option will be processed in the specified mode.
Without the @code{-p} option, embedded options would be interpreted
as file names.  @xref{Stocking}, for more information on these options.

@item -S
@itemx --stdin-file-list
Read list of files to be packed from the standard input rather
than from the command line.  Input must be one file name per line.
This switch is especially useful when the command line will not hold
the list of files to be packed.  For example:

@example
find . -type f -print | shar -S -o /tmp/big.shar
@end example

If @code{-p} is specified on the command line, then the options
@code{-M}, @code{-B}, @code{-T}, @code{-z} and @code{-Z} may be
included in the standard input (on a line separate from file names).
The maximum number of lines of standard input, file names and options,
may not exceed 1024.

@end table

@node Splitting, Headers, Selecting, shar invocation
@subsection Splitting output

@table @code

@item -o @var{@var{prefix}}
@itemx --output-prefix=@var{prefix}
Save the archive to files @file{@var{prefix}.01} through
@file{@var{prefix}.@var{nnn}} instead of standard output.  This option
@emph{must} be used when the @code{-l} or the @code{-L} switches
are used.

When @var{prefix} contains any @samp{%} character, @var{prefix} is then
interpreted as a @code{sprintf} format, which should be able to display
a single decimal number.  When @var{prefix} does not contain such a
@samp{%} character, the string @samp{.%02d} is internally appended.

@item -l @var{size}
@itemx --whole-size-limit=@var{size}
Limit the output file size to @var{size} times 1024 bytes but don't
split input files.  This allows the recipient of the shell archives
to unpack them in any order.

@item -L @var{size}
@itemx --split-size-limit=@var{size}
Limit output file size to @var{size} times 1024 bytes and split files
if necessary.  The archives created with this option must be unpacked
in the correct order.  If the recipient of the shell archives wants to
put all of them in a single folder, she shall save them in the correct
order for @code{unshar}, used with option @code{-e}, to unpack them
all at once.  @xref{unshar invocation}.

For people used to saving all the shell archives into a single mail
folder, care must be taken to save them in the appropriate order.
For those having the appropriate tools (like Masanobu Umeda's
@code{rmailsort} package for GNU Emacs), shell archives can be saved
in any order, then sorted by increasing date (or send time) before
massive unpacking.

@end table

@node Headers, Stocking, Splitting, shar invocation
@subsection Controlling the shar headers

@table @code

@item -n @var{name}
@itemx --archive-name=@var{name}
Name of archive to be included in the header of the shar files.
Also see the @code{-a} switch further down.

@item -s @var{address}
@itemx --submitter=@var{address}
The @code{-s} option allows for overriding the email address for the
submitter, for when the default is not appropriate.  The automatically
determined address looks like @file{@var{username}@@@var{hostname}}.

@item -a
@itemx --net-headers
Allows automatic generation of headers:

@example
Submitted-by: @var{address}
Archive-name: @var{name}/part@var{nn}
@end example

The @var{name} must be given with the @code{-n} switch.  If name
includes a @samp{/}, then @samp{/part} isn't used. Thus
@samp{-n xyzzy} produces:
@example
xyzzy/part01
xyzzy/part02
@end example

@noindent
while @samp{-n xyzzy/patch} produces:
@example
xyzzy/patch01
xyzzy/patch02
@end example

@noindent
and @samp{-n xyzzy/patch01.} produces:
@example
xyzzy/patch01.01
xyzzy/patch01.02
@end example

@item -c
@itemx --cut-mark
Start the shar with a cut line.  A line saying @samp{Cut here} is
placed at the start of each output file.

@end table

@node Stocking, Transmission, Headers, shar invocation
@subsection Selecting how files are stocked

@table @code

@item -T
@itemx --text-files
Treat all files as text, regardless of their contents.

@item -B
@itemx --uuencode
Treat all files as binary, use @code{uuencode} prior to packing. This
increases the size of the archive. The recipient must have
@code{uudecode} in order to unpack.

@display
Use of @code{uuencode} is not appreciated by many on the net, because
people like to readily see, by mere inspection of a shell archive,
what it is about.
@end display

@item -M
@itemx --mixed-uuencode
Mixed mode.  Automatically determine if the files are text or binary
and archive correctly.  Files found to be binary are uuencoded prior
to packing.  This option is selected by default.

For a file is considered to be a text file, instead of a binary file,
all the following should be true simultaneously:
@enumerate
@item
The file does not contain any ASCII control character besides @key{BS}
(backspace), @key{HT} (horizontal tab), @key{LF} (new line), @key{FF}
(form feed) or @key{CR} (carriage return). The last check is needed on
MSDOS systems.
@item
The file does not contains a @key{DEL} (delete).
@item
The file contains no character with its eighth-bit set.
@item
The file, unless totally empty, terminates with a @key{LF} (newline).
@item
No line in the file contains more than 200 characters.  For counting
purpose, lines are separated by a @key{LF} (newline).
@end enumerate

@item -z
@itemx --gzip
Use @code{gzip} and @code{uuencode} on all files prior to packing.
The recipient must have @code{uudecode} and @code{gzip} (used with
@code{-d}) in order to unpack.

Usage of @code{-z} in net shars will cause you to be flamed off
the earth.

@item -g @var{level}
@itemx --level-for-gzip=@var{level}
When doing compression, use @code{-@var{level}} as a parameter to
@code{gzip}.  The @code{-g} option turns on the @code{-z} option
by default.  The default value is 9, that is, maximum compression.

@item -Z
@itemx --compress
Use @code{compress} and @code{uuencode} on all files prior to packing.
The recipient must have @code{uudecode} and @code{compress} (used
with @code{-d}) in order to unpack.  Option @code{-C} is a synonymous
for @code{-Z}, but is deprecated.

Usage of @code{-Z} in net shars will cause you to be flamed off
the earth.

@item -b @var{bits}
@itemx --bits-per-code=@var{bits}
When doing compression, use @code{-b@var{x}} as a parameter to
@code{compress}.  The @code{-B} option turns on the @code{-Z}
option by default.  The default value is 12, foreseeing the memory
limitations of some @code{compress} programs on smallish systems, at
@code{unshar} time.

@end table

@node Transmission, Kinds, Stocking, shar invocation
@subsection Protecting against transmission errors

Transmission of shell archives is not always free of errors.  So one
should make consistency checks on the receiving site.  A very simple
(and unreliable) method is running the UNIX @code{wc} tool on the output
file.  This can report the number of characters in the file.

As one can guess this does not catch all errors.  Especially changing of
a character value does not change the computed check sum.  To achieve
this goal better method were invented and standardized.  One very strong
is MD5 (MD = message digests).  This is standardized in RFC 1321.  The
produced shell scripts do not force the @code{md5sum} program to be
installed on the system.  This is necessary because it is not yet part
of every UNIX.  The program is however not necessary for producing the
shell archive.

@table @code

@item -w
@itemx --no-character-count
Do @emph{not} check with @samp{wc -c} after unpack.  The default is
to check.

@item -D
@itemx --no-md5-digest
Do @emph{not} check with @samp{md5sum} after unpack.  The default is
to check.

@item -F
@itemx --force-prefix
Prepend the prefix character to every line even if not required.
This option may slightly increase the size of the archive, especially
if @code{-B} or @code{-Z} is used.  Normally, the prefix character
is @samp{X}.  If the parameter to the @code{-d} option starts with
@samp{X}, then the prefix character becomes @samp{Y}.

@item -d @var{string}
@itemx --here-delimiter=@var{string}
Use @var{string} to delimit the files in the shar instead of
@samp{SHAR_EOF}.  This is for those who want to personalize their
shar files.

@end table

@node Kinds,  , Transmission, shar invocation
@subsection Producing different kinds of shars

@table @code

@item -V
@itemx --vanilla-operation
This option produces @dfn{vanilla} shars which rely only upon the
existence of @code{echo}, @code{test} and @code{sed} in the unpacking
environment.

The @code{-V} disables options offensive to the @dfn{network cop}
(or @dfn{brown shirt}).  It also changes the default from mixed mode
@code{-M} to text mode @code{-T}.  Warnings are produced if option
@code{-B}, @code{-z}, @code{-Z}, @code{-p} or @code{-M} is specified
(any of which does or might require @code{uudecode}, @code{gzip} or
@code{compress} in the unpacking environment).

@item -P
@itemx --no-piping
In the shar file, use a temporary file to hold the file to
@code{uudecode}, instead of using pipes.  This option is mandatory
when you know the unpacking @code{uudecode} is unwilling to merely
read its standard input.  Richard Marks wrote what is certainly the
most (in)famous of these, for MSDOS :-).

(Here is a side note from the maintainer.  Why isnt't this option
the default?  In the past history of @code{shar}, it was decided
that piping was better, surely because it is less demanding on disk
space, and people seem to be happy with this.  Besides, I think
that the @code{uudecode} from Richard Marks, on MSDOS, is wrong in
refusing to handle @code{stdin}.  So far that I remember, he has
the strong opinion that a program without any parameters should
give its @code{--help} output.  Besides that, should I say, his
@code{uuencode} and @code{uudecode} programs are full-featured, one
of the most complete set I ever saw.  But Richard will not release
his sources, he wants to stay in control.)

@item -x
@itemx --no-check-existing
Overwrite existing files without checking.  If neither @code{-x} nor
@code{-X} is specified, when unpacking itself, the shell archive will
check for and not overwrite existing files (unless @code{-c} is passed
as a parameter to the script when unpacking).

@item -X
@itemx --query-user
Interactively overwrite existing files.

Use of @code{-X} produces shars which @emph{will} cause problems
with some @code{unshar}-style procedures, particularily when used
together with vanilla mode (@code{-V}).  Use this feature mainly for
archives to be passed among agreeable parties.  Certainly, @code{-X}
is @emph{not} for shell archives which are to be submitted to Usenet
or other public networks.

The problem is that @code{unshar} programs or procedures often feed
@file{/bin/sh} from its standard input, thus putting @file{/bin/sh}
and the shell archive script in competition for input lines.  As an
attempt to alleviate this problem, @code{shar} will try to detect if
@file{/dev/tty} exists at the receiving site and will use it to read
user replies.  But this does not work in all cases, it may happen that
the receiving user will have to avoid using @code{unshar} programs
or procedures, and call @code{/bin/sh} directly.  In vanilla mode,
using @file{/dev/tty} is not even attempted.

@item -m
@itemx --no-timestamp
Avoid generating @code{touch} commands to restore the file modification
dates when unpacking files from the archive.

When the timestamp relationship is not preserved, some files like
@file{configure} or @file{*.info} may be uselessly remade after
unpacking.  This is why, when this option is not used, a special
effort is made to restore timestamps,

@item -Q
@itemx --quiet-unshar
Verbose @emph{off} at @code{unshar} time.  Disables the inclusion of
comments to be output when the archive is unpacked.

@item -f
@itemx --basename
Use only the last file name component of each input file name, ignoring
any prefix directories.  This is sometimes useful when building a shar
from several directories, or another directory.  If a directory name
is passed to @code{shar}, the substructure of that directory will be
restored whether @code{-f} is specified or not.

@end table

@node unshar invocation, Miscellaneous, shar invocation, Basic
@section Invoking the @code{unshar} program
@pindex unshar

The format of the @code{unshar} command is:

@example
unshar [ @var{option} ] @dots{} [ @var{file} @dots{} ]
@end example

Each @var{file} is processed in turn, as a shell archive or a
collection of shell archives.  If no files are given, then standard
input is processed instead.

Options:

@table @code

@item --version
Print the version number of the program on standard output, then
immediately exits.

@item --help
Print an help summary on standard output, then immediately exits.

@item -d @var{directory}
@itemx --directory=@var{directory}
Change directory to @var{directory} before unpacking any files.

@item -c
@itemx --overwrite
@item -f
@itemx --force
Passed as an option to the shar file.  Many shell archive scripts
(including those produced by @code{shar} 3.40 and newer) accepts
a @code{-c} argument to indicate that existing files should be
overwritten.

The option @code{-f} is provided for a more unique interface.  Many
programs (such as @code{cp} and @code{mv}) use this option to trigger
the very same action.

@item -e
@itemx --exit-0
This option exists mainly for people who collect many shell archives
into a single mail folder.  With this option, @code{unshar} isolates
each different shell archive from the others which have been put in the
same file, unpacking each in turn, from the beginning of the file
towards its end.  Its proper operation relies on the fact that many shar
files are terminated by a @w{@samp{exit 0}} at the beginning of a line.

Option @code{-e} is internally equivalent to @w{@code{-E "exit 0"}}.

@item -E @var{string}
@itemx --split-at=@var{string}
This option works like @code{-e}, but it allows you to specify the
string that separates archives if @samp{exit 0} isn't appropriate.

For example, noticing that most @file{.signatures} have a @samp{--} on
a line right before them, one can sometimes use @samp{--split-at=--}
for splitting shell archives which lack the @samp{exit 0} line at end.
The signature will then be skipped altogether with the headers of
the following message.

@end table

@node Miscellaneous,  , unshar invocation, Basic
@section Miscellaneous considerations

Here is a place-holder for many considerations which do not fit
elsewhere, while not worth a section for themselves.

Be careful that the output file(s) are not included in the inputs
or @code{shar} may loop until the disk fills up.  Be particularly
careful when a directory is passed to @code{shar} that the output
files are not in that directory (or a subdirectory of that directory).

When a directory is passed to @code{shar}, it may be scanned more
than once, to conserve memory.  Therefore, one should be careful to
not change the directory contents while @code{shar} is running.

No attempt is made to restore the protection and modification dates
for directories, even if this is done by default for files.  Thus, if
a directory is given to @code{shar}, the protection and modification
dates of corresponding unpacked directory may not match those of
the original.

Use of the @code{-M} or @code{-B} options will slow down the archive
process.  Use of the @code{-z} or @code{-Z} options may slow the
archive process considerably.

Let us conclude by a showing a few examples of @code{shar} usage:

@example
shar *.c > cprog.shar
shar -Q *.[ch] > cprog.shar
shar -B -l28 -oarc.sh. *.arc
shar -f /lcl/src/u*.c > u.sh
@end example

@noindent
The first shows how to make a shell archive out of all C program
sources.  The second produces a shell archive with all @file{.c}
and @file{.h} files, which unpacks silently.  The third gives a shell
archive of all uuencoded @file{.arc} files, into files @file{arc.sh.01}
through to @file{arc.sh.@var{nnn}}.  The last example gives a shell
archive which will use only the file names at unpack time.

@node Wrappers, Remsync, Basic, Top
@chapter Simple wrappers around @code{shar}

@menu
* Invoking mailshar::           The @code{mailshar} command and arguments
* Invoking mail-files::         The @code{mail-files} command and arguments
* Invoking find-mailer::        The @code{find-mailer} command and arguments
@end menu

@node Invoking mailshar, Invoking mail-files, Wrappers, Wrappers
@section The @code{mailshar} command and arguments

@node Invoking mail-files, Invoking find-mailer, Invoking mailshar, Wrappers
@section The @code{mail-files} command and arguments

@node Invoking find-mailer,  , Invoking mail-files, Wrappers
@section The @code{find-mailer} command and arguments

@node Remsync,  , Wrappers, Top
@chapter Remote synchronisation of directories

For using the @code{remsync} facility, besides @code{sharutils} of
course, you also need @code{perl}, GNU @code{tar}, GNU @code{findutils}
and @code{gzip}, all installed.  You also need a @code{sum} program
which is BSD-compatible, for example the one from GNU @code{textutils}.

The @code{remsync} program tries to maintain up-to-date copies of
whole hierarchy of files over many loosely connected sites, provided
there is at least some slow electronic mail between them.  It prepares
and sends out specially packaged files called @dfn{synchronization
packages}, and is able to processes them after reception.

There is no @emph{master} site, each site has an equal opportunity
to modify files, and modified files are propagated.  Among many
other commands, the @code{broadcast} command prepares and sends a
synchronization package from the current site to all others, while
the @code{process} command is used to apply synchronization packages
locally after reception from remote sites.  @code{remsync} will
never send a file to another site without being asked to with the
@code{broadcast} command, and besides the project synchronization
state files (always named @file{.remsync}), it will never modify a
file locally without being asked to with the @code{process} command.

The unit of transmission is a file, whatever its size may be.
Nothing less than whole files are being transmitted.  People deciding
to cooperate in keeping a synchronized set of files must have trust
each other, as each participant has the power of modifying the
contents of files at other sites.  When @code{remsync} is used by a
single individual travelling between many sites, as it is often the
case, this confidence problem should be easier to resolve :-).

The @code{process} command will modify a file without asking
confirmation, as long as there is no reason to believe that the file
has been modified at more than one place.  When some confusion arises
from the fact many people independently modified a single file, the
receiving user of conflicting files will have the duty of resolving
them into a merged version.  So, the merging has to be done at the
site where the discrepancy is observed, from where it is propagated
again to others participants.  There is no locking mechanism, so people
should use other means, like electronic mail, for telling each other
what they do, and which part of a project they are working on.

@menu
* Quick start::                 Quick start at using @code{remsync}
* Invoking remsync::            The @code{remsync} command and arguments
* Conveniences::                Automatic mechanisms in the @code{remsync} program
* Commands::                    Commands for @code{remsync}
* Internals::                   How @code{remsync} works
* Formats::                     Related file formats
* Xremsync::                    Format of the @file{.remsync} file
* Package::                     Format of transiting packages
* Alternatives::                Other means to synchronization
* Previous::                    Documentation for obsolete scripts
@end menu

@node Quick start, Invoking remsync, Remsync, Remsync
@section Quick start at using @code{remsync}

If you are in a real hurry, you can follow the recipe given here,
and postpone studying this manual further.  However, we will consider
only a simple case.  In any case, it is good to read the full example,
as it gives a good picture of the overall usage of @code{remsync}.

For any sizeable project, it might not be convenient to start with
one site having it all and the other site having nothing, because
this would cause the first synchronization to be huge.  It is more
practical to move over a copy of the project by other means, might it
be diskettes, tapes, or @code{mailshar}.  So let's presume both sites
have a copy of the project, not necessarily identical, but close.

For the following example, we presume that under the same
domain @file{champignac.land}, there are two machines named
@file{spirou} and @file{fantasio}.  Further, the participating
user on @file{spirou@@spirou.champignac.land} has @file{spirou}
for a login name, and similarily, the participating user on
@file{fantasio.champignac.land} has @file{fantasio} for a login name.
On the @file{spirou} machine, user @file{spirou} keeps the project
under his home, in directory @file{spirou-copy}, while on the
@file{fantasio} machine, user @file{fantasio} keeps the project under
his home, in directory @file{fantasio-copy}.  Of course, user names
might be the same, as well as the directories containing the project.
We use different names here just to make the example clearer.

Here is a full transcript of the initialization session, normally
executed only once, and slightly edited to make it more suitable for
this manual.  The example is broken down in little parts, allowing
explanations and comments.

@example
% cd ~/spirou-copy
% remsync
remsync (format *.*) - GNU sharutils *.*

>> mode init

init>> remote fantasio@@fantasio.champignac.land ~/fantasio-copy
* Directory `~/spirou-copy is not ready for synchronization
Should I prepare it for its first time (y/n)? [y]
Please enter a short project description: Zorglub project
What is your full email address, here? [spirou@@spirou.champignac.land]
@end example

@noindent
These commands prepare the @file{~/spirou-copy} hierarchy for
synchronization.  You should be located at the top directory of
the hierarchy at the time the command @code{remsync} is called.

The @samp{mode init} command instructs @code{remsync} that no files
should be sent in the synchronization package, only their checksum.
The goal here is to inform the other site of what we have, and what
we don't, somewhat disregarding the fact the other site still looks
like it has nothing yet.

The @code{remote} command is the key in establishing a synchronization
link.  It has two parameters, the first being the email address of the
partner at the other site (as seen from here, if this matters), the
second being the location of the directory where the package should
reside on the remote site (as seen from there).

Because there is no @file{.remsync} file in the project's top-level
directory,  @code{remsync} concludes this is a first synchronization,
and so, ask a few questions, often telling in square brackets what
answer would be implied by a mere @key{Return} or @key{Enter}.  If the
default reply seems inappropriate, just give the correct information.

@example
init>> broadcast

  Broadcasting to address `fantasio@@fantasio.champignac.land'
  Studying local files for their signature
  Registering file `file1'
  Registering file `file2'
  Registering file `file3'
* There were new registrations, please check them
Should I resume the current command (y/n)? [y]
Mailing shar to fantasio@@fantasio.champignac.land
Message queued
  Command `broadcast' done

init>> quit

%
@end example

The @code{broadcast} command produces an inventory of the project's
files at this end, and mail it to the other partners.  But before doing
so, because some new files were registered into the synchronization,
the user is given the opportunity of interrupting the command, if it
is felt that some registered file should really not be there.

The @code{quit} command exits @code{remsync}, but only once it created
the @file{.remsync} file on disk.

@emph{Then}, on @file{fantasio.champignac.land}, user @file{fantasio}
will receive the synchronization package, easily recognizable by the
fact the string @samp{.remsync.tar.gz} appears in the @code{Subject}
header of the message.  Let's assume @file{fantasio} saves the whole
message as file @file{/tmp/synchro-message}.  Then, @file{fantasio}
might use the following recipe:

@example
% cd /tmp
% unshar synchro-message
uudecoding file .remsync.tar.gz
% remsync process
  Exploding archive `/tmp/.remsync.tar.gz'

  Package being received:
    from address `spirou@@spirou.champignac.land'
    for project `Zorglub project'
  Visiting directory `~/fantasio-copy', remote was `~/spirou-copy'
  Initializing file `.remsync' from received information
  Studying local files for their signature
  Command `process' done
@end example

In that @samp{remsync process} call, the @code{process} command is
being given non-interactively, so @code{remsync} avoids unneeded
interactions and exits right away once the command is done.
But equivalently, @code{remsync} might be called without arguments,
the @code{process} command given interactively, and a @code{quit}
command later required to get out of @code{remsync}.

When receiving a synchronization package, @code{remsync} should be
executed in the directory where the file @file{.remsync.tar.gz} has
been unpacked, which might be quite unrelated to the project itself.
Here, @file{fantasio} executed @code{remsync} in @file{/tmp/}, while
the project resides in @file{~/fantasio-project}.  The synchronization
package itself contains enough information for @code{remsync} to
automatically visit the proper directory.

After this operation, @file{fantasio.champignac.land} has a
@file{.remsync} file in @file{~/fantasio-copy}, and the remote
synchronization initialization is completed.  Either @file{spirou}
or @file{fantasio} may then modify files on their respective machine.
If @file{spirou} modifies @file{file2} in the project, @file{spirou}
may execute:

@example
% cd ~/spirou-copy
% remsync broadcast
  Reading configuration for project `Zorglub project'

  Broadcasting to address `fantasio@@fantasio.champignac.land'
  Studying local files for their signature
  Packaging file `file2'
shar: Saving file2 (gzipped)
Mailing shar to fantasio@@fantasio.champignac.land
Message queued
  Command `broadcast' done
@end example

In fact, any time a participant later feel like sending modified files
to all partners, s/he just have to change the directory to the top of
the project hierarchy, then call @samp{remsync broadcast}.  Any time a
synchronization package is later received, at either end, the receiving
user should apply @code{unshar} to related electronic messages for
reconstructing the synchronization package @file{.remsync.tar.gz}, then
call @samp{remsync process} in the directory containing this package.

@node Invoking remsync, Conveniences, Quick start, Remsync
@section The @code{remsync} command and arguments

At the shell prompt, calling the command @code{remsync} without any
parameters initiates an interactive dialog, in which the user types
commands and receives feedback from the program.

The command @code{remsync}, given at the shell prompt, may have
arguments, in which case these arguments taken together form one
@code{remsync} interactive command.  However, @samp{--help} and
@samp{--version} options are interpreted especially, with their usual
effect in GNU.  Once this command has been executed, no more commands
are taken from the user and @code{remsync} terminates execution.
This allows for using @code{remsync} in some kind of batch mode.
It is unwise to redirect @code{remsync} standard input, because
user interactions might often be needed in ways difficult to predict
in advance.

The two most common usages of @code{remsync} are the commands:

@example
remsync b
remsync p
@end example

The first example executes the @code{broadcast} command, which sends
synchronization packages to all connected remote sites for the current
local directory tree.

The second example executes the @code{process} command, which studies
and complies with a synchronisation package saved in the current
directory (not necessarily into the synchronized directory tree), under
the usual file name @file{remsync.tar.gz}.

@menu
* Conveniences::                Automatic mechanisms in the @code{remsync} program
* Commands::                    Commands for @code{remsync}
@end menu

@node Conveniences, Commands, Invoking remsync, Remsync
@section Automatic mechanisms in the @code{remsync} program

The following points apply to many of the @code{remsync} commands.
We describe them here once and for all.

@itemize @bullet

@item
The file @file{.remsync} describes the various properties for the
current synchronization.  It is kept right in the top directory of a
synchronized directory tree.  Some commands may be executed without any
need for this file.  The program waits as far as possible before reading
it.

@item
If the @file{.remsync} file is not found when required, and only then,
the user is interactively asked to fill a questionnaire about it.

@item
If the @file{.remsync} file has been logically modified after having
been read, or if it just has been created, the program will save it back
on disk.  But it will do so only before reading another @file{.remsync}
file, or just before exit.  A preexisting @file{.remsync} will be
renamed to @file{.remsync.bak} before it is rewritten, when this is
done, any previous @file{.remsync.bak} file is discarded.

@item
Many commands refer to previously entered information by repeating this
information.  For example, one can refer to a particular @code{scan}
statement by entering the wildcard to be scanned by this statement.
An alternative method of specifying a statement consists in using the
decimal number which appears between square brackets in the result
of a @code{list} command.

@item
Whenever a site list must be given, it is a space separated list of
remote sites.  If the list is preceeded by a bang (@key{!}), the list is
complemented, that is, the sites that will be operated upon are all
those @emph{not} appearing in the list.  As a special case, if the site
list is completely empty, then all sites are selected.

@end itemize

@node Commands, Internals, Conveniences, Remsync
@section Commands for @code{remsync}

Program commands to @code{remsync} may be given interactively by the
user sitten at a terminal.  They can come from the arguments of the
@code{remsync} call at the shell level.  Internally, the @code{process}
command might obey many sub-commands found in a received synchronization
package.

Program commands are given one per line.  Lines beginning with a sharp
(@key{#}) and white lines are ignored, they are meant to increase
clarity or to introduce user comments.  With only a few exceptions,
commands are introduced by a keyword and often contains other keywords.
In all cases, the keywords specific to @code{remsync} may be abbreviated
to their first letter.  When there are many keywords in succession, the
space separating them may be omitted.  So the following commands are
all equivalent:

@example
list remote
l remote
list r
l r
listremote
lr
@end example

@noindent
while the following are not legal:

@example
l rem
lisremote
@end example

Below, for clarity, keywords are written in full and separated by
spaces.  Commands often accept parameters, which are then separated by
spaces.  All available commands are given in the table.  The first few
commands do not pre-require the file @file{.remsync}.  The last three
commands are almost never used interactively, but rather automatically
triggered while @code{process}'ing received synchronization packages.

@table @asis

@item @code{?}

Display a quick help summary of available commands.

@item @code{!} [ @var{shell-command} ]

If @var{shell-command} has been given, execute it right now as a shell
command.  When not given, rather start an interactive shell.  Exiting
from the shell will return to this program.  The started shell is taken
from the @code{SHELL} environment variable if set, else @code{sh} is
used.

@item @code{quit}

Leave the program normally and return to the shell.

@item @code{abort}

Leave the program with a nonzero exit status and return to the shell.
No attempt is made to save a logically modified @file{.remsync} file.

@item @code{visit} @var{directory}

Select another synchronized directory tree for any subsequent operation.
@var{directory} is the top directory of the synchronized directory tree.

@item @code{process} [ @var{file} ]

@item @code{list} [ @var{type} ]

List all known statements about some information @var{type}.  Allowable
keywords for @var{type} are @code{local}, @code{remote}, @code{scan},
@code{ignore} and @code{files}.  The keyword @code{files} asks for all
empty statements (see later).  If @var{type} is omitted, then list all
known statements for all types, except those given by @code{files}.

@item [ @code{create} ] @var{type} @var{value}

Create a new statement introducing a @var{value} for a given @var{type}.
Allowable keywords for @var{type} are @code{remote}, @code{scan} and
@code{ignore}.  The @code{create} keyword may be omitted.

For @code{create} @code{ignore}, when the pattern is preceeded by a bang
(@key{!}), the condition is reversed.  That is, only those files which
do match the pattern will be kept for synchronization.

@item @code{delete} @var{type} @var{value}

Delete an existing statement supporting some @var{value} for a given
@var{type}.  Allowable keywords for @var{type} are @code{remote},
@code{scan} and @code{ignore}.

@item @code{email} @var{remote} @var{value}

Modify the electronic mail address associated with some @var{remote}
site, giving it a new @var{value}.  The special @code{local} keyword for
@var{remote} may be used to modify the local electronic mail address.

@item @code{home} @var{remote} @var{value}

Modify the top directory of the synchronized directory tree associated
with some @var{remote} site, giving it a new @var{value}.  The special
@code{local} keyword for @var{remote} may be used to modify the local
top directory.

@item @code{broadcast} @var{site_list}

Send by electronic mail an update package to all sites from
@var{site_list}, containing for each site all and only those files which
are known to be different between the remote site and here.

@item @code{version} @var{version}

This command is not meant for interactive use.  It establishes the
@code{remsync} version needed to process the incoming commands.

@item @code{from} @var{site_list}

This command is not really meant for interactive use.  The first site
from the @var{site_list} is the remote site which originated the
synchronization package.  All the others are all the sites, including
here, which were meant to be synchronized by the @code{broadcast}
command that was issued at the originating remote site.

@item @code{sum} @var{file} @var{checksum}

This command is not really meant for interactive use.  It declares the
@var{checksum} value of a particular @var{file} at the originating
remote site.  Also, if at least one @code{sum} command is received, then
it is guaranteed that the originating remote site sent one @code{sum}
command for each and every file to be synchronized, so any found local
file which was not subject of any @code{sum} command does not exist
remotely.

@item @code{if} @var{file} @var{checksum} @var{packaged}

This command is not really meant for interactive use.  It directs the
@code{remsync} program to check if a local @var{file} has a given
@var{checksum}.  If the checksum agrees, then the local file will be
replaced by the @var{packaged} file, as found in the received
synchronization invoice.

@end table

@node Internals, Formats, Commands, Remsync
@section How @code{remsync} works

How does @code{remsync} keep track of what is in sync, and what isn't?
@xref{Xremsync}, for a the documentation on the @file{.remsync} file
format.  I understand that a mere description of the format does not
replace an explanation, but in the meantime, you might guess from the
format how the program works.

All files are summarized by a checksum, computed by the @code{sum} program.
There are a few variants of @code{sum} computing checksums in incompatible
ways, under the control of options.  @code{remsync} attempts to retrieve on
each site a compatible way to do it, and complains if it cannot.

@code{remsync} does not compare dates or sizes.  Experience shown that the
best version of a file is not necessarily the one with the latest
timestamp.  The best version for a site is the current version on this
site, as decided by its maintainer there, and this is this version
that will be propagated.

Each site has an idea of the checksum of a file for all other sites.
These checksums are not necessarily identical, for sites do not
necessarily propagate to all others, and the propagation network maybe
incomplete or asymmetrical in various ways.

Propagation is never done unattended.  The user on a site has to call
@code{remsync broadcast} to issue synchronization packages for other sites.
If this is never done, the local modifications will never leave the
site.  The user also has to call @code{remsync process} to apply received
synchronization packages.  Applying a package does not automatically
broadcast it further (maybe this could change?).

If a site @var{A} propagates some files to sites @var{B} and @var{D},
but not @var{C}, site @var{B} is informed that site @var{D} also
received these files, and site @var{D} is informed that site @var{B}
also received these files, so they will not propagate again the same
files to one another.  However, both site @var{B} and @var{D} are
susceptible to propagate further the same files to site @var{C}.

It may happen that a site refuses to update a file, or modifies a file
after having been received, or merges versions, or whatever.  So,
sites may have a wrong opinion of the file contents on other sites.
These differences level down after a few exchanges, and it is very
unlikely that a file would not be propagated when it should have.

This scheme works only when the various people handling the various
files have confidence in one each other.  If site @var{B} modifies a
file after having received it from site @var{A}, the file will
eventually be propagated back to site @var{A}.  If the original file
stayed undisturbed on site @var{A}, that is, if @code{remsync} proves
that site @var{B} correctly knew the checksum of the original file, then
the file will be replaced on site @var{A} without any user confirmation.
So, the user on site A has to trust the changes made by the user on site
@var{B}.

If the original file on site @var{A} had been modified after having been
sent in a synchronization package, than it is the responsibility of the
user on site @var{A} to correctly merge the local modifications with the
modifications observed in the file as received from site @var{B}.  This
responsibility is real, since the merged file will later be propagated
to the other sites in an authoritative way.

@node Formats, Xremsync, Internals, Remsync
@section Related file formats

@menu
* Xremsync::                    Format of the @file{.remsync} file
* Package::                     Format of transiting packages
@end menu

@node Xremsync, Package, Formats, Remsync
@section Format of the @file{.remsync} file

The @file{.remsync} file saves all the information a site needs for
properly synchronizing a directory tree with remote sites.  Even if it
is meant to be editable using any ASCII editor, it has a very precise
format and one should be very careful while modifying it directly,
if ever.  The @file{.remsync} file is better handled through the
@code{remsync} program and commands.

The @file{.remsync} file is made up of statements, one per line.  Each
line begins with a statement keyword followed by a single @key{TAB},
then by one or more parameters.  The keyword may be omitted, in this
case, the keyword is said to be @emph{empty}, and the line begins
immediately with the @key{TAB}.  After the @key{TAB}, if there are two
parameters or more, they should all be separated with a single space.
There should not be any space between the last parameter and the end of
line (unless there are explicit empty parameters).

The following table gives the possible keywords.  Their order of
presentation in the table is also the order of appearance in the
@file{.remsync} file.

@table @code

@item remsync
This statement identifies the @file{.remsync} format.  The only
parameter states the file format version.

@item local
This statement should appear exactly once, and has exactly two
parameters.  The first parameter gives the electronic mail address the
other sites should use for sending synchronization packages here.  The
second parameter gives the name of the local directory tree to
synchronize, in absolute notation.

@item remote
This statement may appear zero, one or more times.  Each occurrence
connects the synchronized directory tree to another tree on a remote
site.  The first parameter gives one electronic mail address where to
send remote synchronization packages.  The second parameter gives the
name of the corresponding directory tree for this remote electronic mail
address, in absolute notation.

@item scan
This statement may appear zero, one or more times.  When it does not
appear at all, the whole local directory tree will always be scanned,
searching for files to synchronize.  When the statement appears at least
once, the whole local directory tree will not be scanned, but only those
files or directories appearing in one of these statements.  Each
@code{scan} statement has exactly one parameter, giving one file or
directory to be studied.  These are usually given relative to top
directory of the local synchronization directory tree.  Shell wildcards
are acceptable.

@item ignore
This statement may appear zero, one or more times.  Each occurrence has
one parameter giving a regular expression, according to Perl syntax for
regular expressions.  These @var{regexp}s are applied against each file
resulting from the scan.  If any of the @code{ignore} expression matches
one of resulting file, the file is discarded and is not subject to
remote synchronization.

@end table

After all the statements beginning by the previous keywords, the
@file{.remsync} file usually contains many statements having the empty
keyword.  The empty keyword statement may appear zero, one or more
times.  Each occurrence list one file being remotely synchronized.  The
first parameter gives an explicit file name, usually given relative to
the top directory of the local synchronized directory tree.  Shell
wildcards are @emph{not} acceptable.

Besides the file name parameter, there are supplementary parameters to
each empty keyword statement, each corresponding to one remote statement
in the @file{.remsync} file.  The second parameter corresponds to the
first remote, the third parameter corresponds to the second remote, etc.
If there are more remote statements than supplementary parameters,
missing parameters are considered to be empty.

Each supplementary parameter usually gives the last known checksum
value for this particular file, as computed on its corresponding
@emph{remote} site.  The parameter contains a dash @kbd{-} while the
remote checksum is unknown.  The checksum value for the @emph{local}
copy of the file is never kept anywhere in the @file{.remsync} file.
The special value @samp{666} indicates a checksum from hell, used
when the remote file is known to exist, but for which contradictory
information has been received from various sources.

@node Package, Alternatives, Xremsync, Remsync
@section Format of synchronisation packages

Each synchronisation package is transmitted as a file named
@file{.remsync.tar.gz}, which has the format of a @code{tar} archive,
further compressed with the @code{gzip} program.  This archive always
contains a file named @file{.remsync-work/orders}, and zero or more
files named @file{.remsync-work/1}, @file{.remsync-work/2}, etc.
It contains no other files.  Each numbered file is actually a full,
non-modified file pertaining to the hierarchy of the project, as sent
from the remote site.

The @file{.remsync-work/orders} file drives the processing of the
received synchronization package.  This ASCII file format quite
closely resembles the @file{.remsync} format, which we do not explain
again here.  Only the keywords and their associated parameters are
different, and there is no empty keyword.  The following table gives
the possible keywords, in the order where they normally appear.

@table @code

@item format
@itemx title
@itemx here
@itemx remote
@itemx ignore
@itemx scan
All those keywords are used exactly the same way as within the
@file{.remsync} file, and their format is not explained again here.
They state the file format, project title, local and possibly many
remote identifications and directories, zero or more ignores, zero
or more scans; all of these exactly as known to the remote site who
created the synchronization package.  In particular, the @code{here}
line states the originating site of the package rather than the
receiving one; the receiving site should still be described by one
of the @code{remote} lines.

@item visit
This statement appears exactly once, and has one numeric parameter.
It specifies the zero-based index in the list of remote lines above.
The index identifies the receiving site, that is, the site to which
this package was sent.

@item copy
This statement appears exactly once, and has one or more numeric
parameters.  Each specifies a zero-based index in the list of remote
lines above.  All indices specify the set of all sites who where
broadcasted simultaneously, at the time this synchronization package
was issued.  The index specified by the @code{visit} line should also
be one of the indices of the @code{copy} lines.  The order in which
the indices are given is important, as it also establishes the order
in which file signatures are listed on the @code{check} lines below.

@item check
This statement may appear zero, one or more times.  Each occurrence
describes one file known to the project at the originating site, and
there is exactly one occurrence for each known file in the project.
Each @code{check} line has exactly @var{n}+2 parameters, where @var{n}
is the number of parameters of the @code{copy} command.  The first
parameter gives a file name, relative to the top directory.  The second
parameter gives the file signature for this file, as computed at the
originating site.  For each remote site presented in the @code{copy}
command, and exactly in the same order, each supplementary parameter
gives the originator's idea of the signature for the said file at
this remote site.  A dash (@kbd{-}) replaces the signature for a file
known @emph{not} to exist.

@item update
This statement may appear zero, one or more times.  Each occurrence
describes what to do with one of the @file{.remsync-work/@var{n}}
files, distributed within the synchronization package.  In fact,
there should be exactly as many @code{update} lines that there
are numbered files in the synchronization package.  Usually, each
@code{update} line immediately follows the corresponding @code{check}
line, and has exactly three parameters.  The first parameter gives
a file name in the project, relative to the top level directory of
the hierarchy.  The second parameter gives a file signature which the
said file should have at the receiving site, for it to be replaced
safely, with no questions asked (this is the originator's idea of
what the file signature @emph{was}, on the receiving site, prior to
its replacement).  A dash (@kbd{-}) replaces this signature for a
file known @emph{not} to exist.  The third parameter is the number
@var{n}, which indicates the file @file{.remsync-work/@var{n}} in
the synchronization package distribution which should replace the
corresponding project file at the receiving site.

@end table

@node Alternatives, Previous, Package, Remsync
@section Other means to synchronization

One correspondent thinks that perhaps the news distribution mechanism
could be pressed into service for this job.  I could have started
from C-news, say, instead of from scratch, and have progressively
bent C-news to behave like I wanted.

My feeling is that the route was shorter as I did it, from scratch,
that it would have been from C-news.  Of course, I could have
removed the heavy administrative details of C-news: the history and
@code{expire}, the daemons, the @code{cron} entries, etc., then added
the interactive features and specialized behaviors, but all this clean
up would certainly have took energies.  Right now, non counting the
subsidiary scripts and shar/unshar sources, the heart of the result
is a single (1200 lines) script written in Perl, which I find fairly
more smaller and maintainable than a patched C-news distribution
would have been.

@node Previous,  , Alternatives, Remsync
@section Documentation for obsolete scripts

This is merely a place holder for previous documentation, waiting that I
clean it up.  You have no interest in reading further down.

@menu
* mailsync::                    mailsync
* resync::                      resync
@end menu

@node mailsync, resync, Previous, Previous
@subsection mailsync

@example
Usage: mailsync [ OPTION ] ... [ EMAIL_ADDRESS ] [ DIRECTORY ]
   or: mailsync [ OPTION ] ... SYNC_DIRECTORY
@end example

Option -i simply sends a @code{ihave} package, with no bulk files.
Option -n inhibits any destructive operation and mailing.

In the first form of the call, find a synchronisation directory in
DIRECTORY aimed towards some EMAIL_ADDRESS, then proceed with this
synchronisation directory.  EMAIL_ADDRESS may be the name of a file
containing a distribution list.  If EMAIL_ADDRESS is not specified,
all the synchronisation directories at the top level in DIRECTORY are
processed in turn.  If DIRECTORY is not specified, the current
directory is used.

In the second form of the call, proceed only with the given
synchronisation directory SYNC_DIRECTORY.

For proceeding with a synchronisation directory, whatever the form of
the call was, this script reads the @code{ident} files it contains to set
the local user and directory and the remote user and directory.  Then,
selected files under the local directory which are modified in regard
to the corresponding files in the remote directory are turned into a
synchronisation package which is mailed to the remote user.

The list of selected files or directories to synchronize from the
local directory are given in the @code{list} file in the synchronisation
directory.  If this @code{list} file is missing, all files under the
local directory are synchronized.

What I usually do is to @code{cd} at the top of the directory tree to be
synchronized, then to type @code{mailsync} without parameters.  This will
automatically prepare as many synchronisation packages as there are
mirror systems, then email multipart shars to each of them.  Note that
the synchronisation package is not identical for each mirror system,
because they do not usually have the same state of synchronisation.

@code{mailsync} will refuse to work if anything needs to be hand cleaned
from a previous execution of @code{mailsync} or @code{resync}.  Check
for some remaining @file{_syncbulk} or @file{_synctemp} directory, or
for a @file{_syncrm} script.

@example
TODO:
- interrogate the user if @file{ident} file missing.
- automatically construct the local user address.
- create the synchronisation directory on the fly.
- avoid duplicating work as far as possible for multiple sends.
- have a quicker mode, depending on stamps, not on checksums.
- never send core, executables, backups, @file{.nsf*}, @file{*/_synctemp/*}, etc.
@end example

@node resync,  , mailsync, Previous
@subsection resync

@example
Usage: resync [ OPTION ]... TAR_FILE
   or: resync [ OPTION ]... UNTARED_DIRECTORY
@end example

Given a tar file produced by mailsync at some remote end and already
reconstructed on this end using unshar, or a directory containing the
already untared invoice, apply the synchronization package locally.

Option -n inhibits destroying or creating files, but does everything
else.  It will in particular create a synchronization directory if
necessary, produce the @file{_syncbulk} directory and the @file{_syncrm}
script.

The synchronization directory for the package is automatically
retrieved or, if not found, created and initialized.  @code{resync} keeps
telling you what it is doing.

There are a few cases when a resync should not complete without manual
intervention.  The common case is that several sites update the very
same files differently since they were last resync'ed, and then
mailsync to each other.  The prerequisite checksum will then fail, and
the files are then kept into the @file{_syncbulk} tree, which has a shape
similar to the directory tree in which the files where supposed to go.
For GNU Emacs users, a very handy package, called emerge, written by
Dale Worley <drw@@kutta.mit.edu>, helps reconciling two files
interactiveley.  The @file{_syncbulk} tree should be explicitely deleted
after the hand synchronisation.

Another case of human intervention is when files are deleted at the
mailsync'ing site.  By choice, all deletions on the receiving side are
accumulated in a @file{_syncrm} script, which is not executed automatically.
Explicitely executed, @file{_syncrm} will remove any file in the receiving
tree which does not exist anymore on the sender system.  I often edit
@file{_syncrm} before executing it, to remove the unwanted deletions (beware
the double negation :-).  The script removes itself.

All the temporary files, while resynchronizing, are held in @file{_synctemp},
which is deleted afterwards; if something goes wrong, this directory
should also be cleaned out by hand.  @code{resync} will refuse to work if
anything remains to be hand cleaned.

@display
TODO:
- interrogates the user if missing receiving directory in @file{ident}.
- allow @file{remote.sum} to be empty or non-existent.
@end display

@contents
@bye

@c Local variables:
@c texinfo-column-for-description: 32
@c End: