=============================================
zsync -- Zope filesystem synchronization tool
=============================================


Name
----

**zsync** - Zope filesystem synchronization tool


Synopsis
--------

**zsync** *command* [*command-options*...] [*args*]


Description
-----------

The **zsync** command is used to synchronize the representation of a
Zope 3 based website stored in the object database with a
directory-tree representation.  The **zsync** command "feels like" the
**cvs** and **svn** commands, but is different in that there is no
basic versioning model in **zsync**.

Like the **cvs** and **svn** programs, **zsync** requires a **zsync**
command and any arguments to that to be given on the command line.
The additional specific command given controls what operation is
performed.  The following commands are supported; names given in
parentheses are aliases supported for convenience:

**help** (h, ?)
  Display help text on **zsync** and individual commands.

**checkin** (ci)
  Add the target material to the object database.

**checkout** (co)
  Retrieve the serialized representation of a portion of the object
  database.

**commit**
  Integrate changes in the local representation objects into the
  object database.  If there are changes to the same objects in the
  object database, those changes must be merged into the local
  representation before the local changes can be committed.

**copy** (cp)
  Copy objects within a checkout (or across separate checkouts if the
  servers are configured similarly enough), or copy a file tree into a
  checkout.  The new objects will be scheduled for addition.

**update** (up)
  Retrieve updates from the object database.

**diff** (di)
  Report differences between the local representation and the data
  from which the modified copy was generated.  This command can be run
  *offline* (without any network access), so is useful when working
  from a disconnected system.

**add**
  Mark an object for addition to the object database.  The change is
  not made to the object database itself until the next **zsync
  commit**.

**mkdir**
  Create new directories and schedule them for addition.  The
  additions are not made to the object database itself until the next
  **zsync commit**.

**delete** (del remove rm)
  Mark an object for removal from the object database.  The change is
  not made to the object database itself until the next **zsync
  commit**.

**login**
  Store a basic authenication token for a server.

**logout**
  Discard a stored authenication token.

**resolve**
  Remove a conflict indicator for a file that has been updated on
  both the server and the working copy.  (This does not actually
  modify the file to resolve conflicts; this is used to tell **zsync**
  that you're done making changes to resolve the conflict.)

**revert**
  Restore targets to their unmodified state.

**status** (stat)
  Show the current status of the target material; whether it has been
  changed in the local representation, has been removed or added, or
  is unchanged.

Options for specific commands must be supplied after the name of the
specific command.


The **zsync add** Command
~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**add** [*add-options*] [*path*]

Options
+++++++

-f factory, --factory factory
  Specify the object factory to use for the object being added.

-t type, --type type           
  The type of the object to be created.  Normally only *factory* needs
  to be specified.


The **zsync checkin** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**checkin** [*checkin-options*] *target-url* [*path*]

Description
+++++++++++

Check an object representation into the repository.  The
representation may have been created by a checkout from a different
object database or from a different location in the target database.
If the metadata in the representation includes path information, that
is ignored in favor of the new name being assigned in the target
repository.

The new name is given as part of *target-url*.  The last component of
*target-url* is used as the local *path* if path is not specified.

The representation which is used as the source is not modified; it
does not become an equivalent of a checkout.  A separate **zsync
checkout** is needed to create a working copy on the local
filesystem.

Options
+++++++

-F file, --file file
  Set the message used for the transaction note to the contents of the
  file *file* (similar to the **-F** option for **cvs commit**).

-m msg, --message msg
  Set the message used for the transaction note to *msg* (similar to
  the **-m** option for **cvs commit**).


The **zsync checkout** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**checkout** *source-url* [*dir*]

Description
+++++++++++

Retrieve the serialized representation of a portion of the object
database.  The database and starting path to be retrieved are
specified as *source-url*.  The username may be specified as part of
*source-url* or via the **-u** option; the password may be included in
*source-url*, or an authentication token stored by **zsync login** may
be used, or **zsync** commands that access the Zope server will
request a password for each request.  The local representation is
stored in the directory *dir*, which defaults to the current
directory.

Options
+++++++

-u USER, --user USER
  Specify the username used in basic authentication to the Zope
  server.  This option is provided as a convenience as most people are
  unfamiliar with the URL syntax for specifying a user name.


The **zsync commit** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**commit** [*commit-options*] [*path* ...]

Description
+++++++++++

Integrate changes in the local representation objects into the object
database.  If there are changes to the same objects in the object
database, those changes must be merged into the local representation
before the local changes can be committed.

If *path* is given, only the named content objects are committed into
the repository.  If not given, the current directory and all
descendents are committed.

Options
+++++++

-F file, --file file
  Set the message used for the transaction note to the contents of the
  file *file* (similar to the **-F** option for **cvs commit**).

-m msg, --message msg
  Set the message used for the transaction note (similar to the **-m**
  option for **cvs commit**).

-r, --raise-on-conflicts
  Tell **zsync** to raise an exception on conflicts instead of simply
  reporting a list of paths for which conflicts are detected.


The **zsync copy** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**copy** [**-l** | **-R**] *source* [*dest*]

Description
+++++++++++

This command is used to copy objects in the database, and can also be
used to copy files into the database.  When *source* is an object in
the database, the copy includes all the type, extra, and annotation
data stored in the ``@@Zope/`` administrative directory.  The files
containing the body of the data (for files), and the extra and
annotations data, may be modified before committing the objects to the
database.  This may be of particular interest for information stored
in Dublin Core metadata annotations.

Options
+++++++

-l, --local
  If *source* is a directory, only copy the directory itself, not it's
  contents.  This option cannot be combined with the **-R** option.

-R, --recursive
  If *source* is a directory, copy the contents of the directory
  recursively.  (This is the default.)  This option cannot be combined
  with the **-l** option.


The **zsync delete** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**delete** *path* ...

Description
+++++++++++

The **delete** command has no specific options.  It requires at least
one *path* argument.


The **zsync diff** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**diff** [*diff-options*] [*path* ...]

Description
+++++++++++

If *path* is given, only the named content objects are considered.  If
not given, the current directory and all descendents are examined.

Options
+++++++

-b
  Ignore changes in the amount of white space.

-B
  Ignore changes that only insert or delete blank lines.

--brief
  Report only that changes exist, not the details of the change.

-c
  Generate a context diff.

-C num, --context num
  Set the number of lines of context information included on each side
  of changes to *num*.

-i
  Ignore changes in case; consider upper- andlower-case letters
  equivalent.

-N
  When the files to be diffed include files being added or deleted,
  perform comparisons between those files and ``/dev/null`` instead of
  complaining about them.

-u
  Generate a unified diff.

-U num, --unified num
  Use the unified output format, showing *num* (an integer) lines of
  context, or three if *num* is not given.  For proper operation,
  **patch** typically needs at least two lines of context.


The **zsync help** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**help** [*command* ...]

Description
+++++++++++

When used without specifying *command*, this displays general help on
using **zsync**.  When *command* is given, information about each
command listed is presented.


The **zsync login** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**login** [**-u** *user*] [*url*]

Description
+++++++++++

Store a basic authentication token in a per-user persistent cache.
This can be used to avoid storing the password as part of the URL used
to check out an object tree.  For example, to check out a portion of a
Zope site without storing the password in the tree, "log in" to the
site and then perform the checkout::

  % zsync login -u username http://example.com/
  Password for username at example.com:
  % zsync checkout http://username@example.com/some/directory/
  ...

If *user* or *url* are omitted, the values are selected from an
existing checkout in the current directory, if any.  If there is no
checkout in the current directory but *url* is given, the user will be
prompted for *user* interactively.  The only information used from the
URL are the protocol scheme (HTTP or HTTPS), the host and port, and
the username.

Options
+++++++

-u user, --user user
  Use *USER* for the username.  This overrides the username given via
  the URL; this is mostly intended for people who don't know (or don't
  want to admit knowing!) the obscure URL syntax for encoding the
  username for a site.


The **zsync logout** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**logout** [**-u** *user*] [*url*]

Description
+++++++++++

Remove an authentication token from the persistent storage created by
**zsync login**.

If *user* or *url* are omitted, the values are selected from an
existing checkout in the current directory, if any.  If there is no
checkout in the current directory but *url* is given, the user will be
prompted for *user* interactively.

After removing a token from the cache, **zsync** commands that access
the Zope server via a checkout URL that doesn't include a password
will require the user to enter their password interactively.

Options
+++++++

-u user, --user user
  Use *user* for the username.  This overrides the username given via
  the URL; this is mostly intended for people who don't know (or don't
  want to admit knowing!) the obscure URL syntax for encoding the
  username for a site.


The **zsync mkdir** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**mkdir** *path* ...

Description
+++++++++++

Create one or more directories and schedule them for addition.  The
additions are not made to the object database itself until the next
**zsync commit**.  Reverting these additions with **zsync revert**
will not cause the directories themselves to be removed.


The **zsync resolve** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**resolve** [*path* ...]

Description
+++++++++++

Clear conflict markers from each *path*.

The **resolve** command has no specific options.


The **zsync revert** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**revert** [*path* ...]

Description
+++++++++++

Restore targets to their unmodified state.  Files which have been
modified are overwritten by pristine copies of the data from
``@@Zope/Original/`` and scheduled additions and deletions are
de-scheduled.  Additions that are de-scheduled do not cause the
working copy of the file to be removed.


The **zsync status** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**status** [*path* ...]

Description
+++++++++++

The **status** command has no specific options.


The **zsync update** Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Synopsis
++++++++

**update** [*path* ...]

Description
+++++++++++

The **update** command has no specific options.


Security Notes
--------------

- The ``@@Zope/Root`` file can contain the username and password with
  which the checkout was made.  Since this will typically allow access
  with content management priviledges, this file should not be shared
  carelessly.  The **zsync login** command can be used to avoid
  including the password in this file.

- The ``~/.zsyncpass`` file contains basic authentication tokens; the
  permissions on that file should be protected against unintentional
  modification.  See the description of this file in `~/.zsyncpass`_
  below.


Files
-----

When **zsync** is used to checkout a Zope 3 website (or a portion of a
site), it creates a directory structure on the local filesystem which
mirrors the containment hierarchy of the object database underlying
the application server.  The directory structure includes both content
data and metadata used to support **zsync** operation.

Since content in the object database can be fairly sophisticated
internally, not all object types may naturally serialize into single
files.  To accomodate the **zsync** support information and the
complex data requirements for content objects, every directory that
contains database objects contains an additional directory named
``@@Zope/`` that contains the additional information needed.

An ``@@Zope/`` directory contains the following:

``Entries.xml``
  A file containing supplemental information needed for filesystem
  synchronization.  This is managed by **zsync**; you should never
  need to peek inside here.

``Annotations/``
  A directory that contains annotation data for the objects in the
  content directory.  This directory contains child directories with
  the same name as the content objects, and each of those diretories
  has a file for each annotation; the file names there are the names
  of the annotations, and the contents of those files are the
  serializations of the annotation values.
  This is only present if there are objects in the content directory
  which have annotations.

``Extra/``
  Objects which require data beyond what's present in their basic
  serialized form to restore object state will cause it to be written
  here.  This directory contains child directories with the same name
  as the content objects, and each of those diretories has a file for
  each piece of named additional information.
  This is only present if there are objects in the content directory
  which have "extra" data.

  As an example, a File content object may have the MIME content type
  of the file stored as the ``contentType`` value in the ``Extra/``
  directory.  If the content object is named ``foo.ext``, the content
  type information would be stored in the file
  ``@@Zope/Extra/foo.ext/contentType``.

``Original/``
  A directory that contains a copy of the unmodified content data.
  This is only present if there are non-container content objects in
  the content directory.

``Root``
  File that gives the base URL for the checkout represented by the
  filesystem representation.  The URL must include the username and
  password needed for authentication, so care must be taken in sharing
  access to a checkout.  This only exists in the ``@@Zope/`` directory
  for the top-level checkout.

One additional file is used if the **zsync login** command is used:

.. _~/.zsyncpass:

``~/.zsyncpass``
  Cache of authentication tokens.  The tokens stored in this file are
  unlikely to be particularly useful if you aren't creating HTTP
  requests directly, but are not stored in a secure manner.  You
  should be careful about the permissions on this file: it should be
  readable and writable by the owner, and not be anyone else.  The
  file is created with the correct permissions by **zsync login**, but
  **zsync** will not complain or ignore the file if the permissions
  are more permissive than necessary.  **zsync** will *only* create
  this file if the **zsync login** command is used.


Reporting Bugs
--------------

Bugs in **zsync** and the filesystem synchronization support in Zope 3
should be reported via the `Zope 3 Development Issue Collector`_, an
online reporting tool that allows you to enter reports directly into
our bug-tracking system.


See Also
--------

There are two interesting and directly relevant articles in the `Zope 3
wiki`_:

* The |FSSYNC|_ is the initial proposal for a way to synchronize
  copies of a Zope-based website between a filesystem-based
  representation and the database backing the live site.

* Bundles are discussed in |TTWSITE|_; this gives more information on
  the motivation and goals surrounding this work.

The |zbundle|_ documentation provides support for managing bundles
using a **zsync** checkout.


Copyright
---------

Copyright (c) 2003 `Zope Corporation`_ and Contributors.
All Rights Reserved.

This software is subject to the provisions of the `Zope Public
License`_, Version 2.1 (ZPL).  A copy of the ZPL should accompany
this distribution.  THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL
EXPRESS OR IMPLIED WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST
INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.

.. include:: links.rst
