4.1 Quick start at using 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 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 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 `champignac.land', there are two machines named `spirou' and `fantasio'. Further, the participating user on `spirou@spirou.champignac.land' has `spirou' for a login name, and similarily, the participating user on `fantasio.champignac.land' has `fantasio' for a login name. On the `spirou' machine, user `spirou' keeps the project under his home, in directory `spirou-copy', while on the `fantasio' machine, user `fantasio' keeps the project under his home, in directory `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.

% 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]

These commands prepare the `~/spirou-copy' hierarchy for synchronization. You should be located at the top directory of the hierarchy at the time the command remsync is called.

The `mode init' command instructs 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 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 `.remsync' file in the project's top-level directory, 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 Return or Enter. If the default reply seems inappropriate, just give the correct information.

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

%

The 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 quit command exits remsync, but only once it created the `.remsync' file on disk.

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

% 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

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

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

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

% 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

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 `remsync broadcast'. Any time a synchronization package is later received, at either end, the receiving user should apply unshar to related electronic messages for reconstructing the synchronization package `.remsync.tar.gz', then call `remsync process' in the directory containing this package.

This document was generated by Bruce Korb on June, 3 2006 using texi2html 1.76.