<chapter id="client">
  <title>Client &mdash; How the client works</title>

  <simplesect>
    <para>The Subversion client is built on three libraries.  One operates
      strictly on the working copy and does not talk to the repository.
      Another talks to the repository but never changes the working copy.  The
      third library uses the first two to provide operations such as
      <literal>commit</literal> and <literal>update</literal> &ndash;
      operations which need to both talk to the repository and change the
      working copy.</para>

    <para>The initial client is a Unix-style command-line tool (like standard
      CVS), but it should be easy to write a GUI client as well, based on the
      same libraries.  The libraries capture the core Subversion functionality,
      segregating it from user interface concerns.</para>

    <para>This chapter describes the libraries, and the physical layout of
      working copies.</para>
  </simplesect>

  <sect1 id="client.wc">
    <title>Working copies and the working copy library</title>

    <para>Working copies are client-side directory trees containing both
      versioned data and Subversion administrative files.  The functions in the
      working copy management library are the only functions in Subversion
      which operate on these trees.</para>

    <sect2 id="client.wc.layout">
      <title>The layout of working copies</title>

      <para>This section gives an overview of how
        working copies are arranged physically, but is not a full specification
        of working copy layout.</para>

      <para>As with CVS, Subversion working copies are simply directory trees
        with special administrative subdirectories, in this case named ".svn"
        instead of "CVS":</para>

      <programlisting>
                             myproj
                             / | \
               _____________/  |  \______________
              /                |                 \
           .svn               src                doc
        ___/ | \___           /|\             ___/ \___
       |     |     |         / | \           |         |
      base  ...   ...       /  |  \     myproj.texi  .svn
                           /   |   \              ___/ | \___
                      ____/    |    \____        |     |     |
                     |         |         |      base  ...   ...
                   .svn      foo.c     bar.c     |
                ___/ | \___                      |
               |     |     |                     |
             base   ...   ...               myproj.texi
          ___/ \___
         |         |
       foo.c     bar.c

</programlisting>

      <para>Each <filename>dir/.svn/</filename> directory records the files in
        <filename>dir</filename>, their revision numbers and property lists,
        pristine revisions of all the files (for client-side delta generation),
        the repository from which <filename>dir</filename> came, and any local
        changes (such as uncommitted adds, deletes, and renames) that affect
        <filename>dir</filename>.</para>

      <para>Although it would often be possible to deduce certain information
        (such as the original repository) by examining parent directories, this
        is avoided in favor of making each directory be as much a
        self-contained unit as possible.</para>

      <para>For example, immediately after a checkout the administrative
        information for the entire working tree <emphasis>could</emphasis> be
        stored in one top-level file.  But subdirectories instead keep track of
        their own revision information.  This would be necessary anyway once
        the user starts committing new revisions for particular files, and it
        also makes it easier for the user to prune a big, complete tree into a
        small subtree and still have a valid working copy.</para>

      <para>The <filename>.svn</filename> subdir contains:</para>

      <itemizedlist mark="bullet">
          <listitem><para>A <filename>format</filename> file, which indicates
              which version of the working copy adm format this is (so future
              clients can be backwards compatibleeasily).</para></listitem>
          
          <listitem><para>A <filename>text-base</filename> directory,
              containing the pristine repository revisions of the files in the
              corresponding working directory</para></listitem>
          
          <listitem><para>An <filename>entries</filename> file, which holds
              revision numbers and other information for this directory and its
              files, and records the presence of subdirs.  It also contains the
              repository URLs that each file and directory came from. It may
              help to think of this file as the functional equivalent of the
              <filename>CVS/Entries</filename> file.</para></listitem>

          <listitem><para>A <filename>props</filename> directory, containing
              property names and values for each file in the working
              directory.</para></listitem>

          <listitem><para>A <filename>prop-base</filename> directory,
              containing pristine property names and values for each file in
              the working directory.</para></listitem>

          <listitem><para>A <filename>dir-props</filename> file, recording
              properties for this directory.</para></listitem>

          <listitem><para>A <filename>dir-prop-base</filename> file, recording
              pristine properties for thisdirectory.</para></listitem>

          <listitem><para>A <filename>lock</filename> file, whose presence
              implies that some client is currently operating on the
              administrative area.</para></listitem>

          <listitem><para>A <filename>tmp</filename> directory, for holding
              scratch-work and helping make working copy operations more
              crash-proof.</para></listitem>

          <listitem><para>A <filename>log</filename> file.  If present,
              indicates a list of actions that need to be taken to complete a
              working-copy-operation that is still "in
              progress".</para></listitem>
        </itemizedlist>

      <para>You can read much more about these files in the file
        <filename>subversion/libsvn_wc/README</filename>.</para>
    </sect2>

    <sect2 id="client.wc.library">
      <title>The working copy management library</title>

      <itemizedlist mark="bullet">
        <listitem><para><emphasis role="bold">Requires:</emphasis>  
          <itemizedlist mark="minus">
            <listitem><para>a working copy</para></listitem>
          </itemizedlist>
        </para></listitem>
        <listitem><para><emphasis role="bold">Provides:</emphasis>  
          <itemizedlist mark="minus">
            <listitem><para>ability to manipulate the working copy's versioned
                data</para></listitem>
            <listitem><para>ability to manipulate the working copy's
                administrative files</para></listitem>
          </itemizedlist>
        </para></listitem>
      </itemizedlist>

      <para>This library performs "offline" operations on the working copy, and
        lives in <filename>subversion/libsvn_wc/</filename>.</para>

      <para>The API for <replaceable>libsvn_wc</replaceable> is always
        evolving;  please read the header file for a detailed description:
        <filename>subversion/include/svn_wc.h</filename>.</para>
    </sect2>
  </sect1>

  <sect1 id="client.libsvn_ra">
    <title>The repository access library</title>

    <itemizedlist mark="bullet">
      <listitem><para><emphasis role="bold">Requires:</emphasis>  
        <itemizedlist mark="minus">
          <listitem><para>network access to a Subversion
              server</para></listitem>
        </itemizedlist>
      </para></listitem>
      <listitem><para><emphasis role="bold">Provides:</emphasis>  
        <itemizedlist mark="minus">
          <listitem><para>the ability to interact with a
              repository</para></listitem>
        </itemizedlist>
      </para></listitem>
    </itemizedlist>

    <para>This library performs operations involving communication with the
      repository.</para>

    <para>The interface defined in
      <filename>subversion/include/svn_ra.h</filename> provides a uniform
      interface to both local and remote repository access.</para>

    <para>Specifically, <replaceable>libsvn_ra_dav</replaceable> will provide
      this interface and speak to repositories using DAV requests.  At some
      future point, another library <replaceable>libsvn_ra_local</replaceable>
      will provide the same interface &ndash; but will link directly to the
      filesystem library for accessing local disk repositories.</para>
  </sect1>

  <sect1 id="client.libsvn_client">
    <title>The client operation library</title>
    
    <itemizedlist mark="bullet">
      <listitem><para><emphasis role="bold">Requires:</emphasis>  
        <itemizedlist mark="minus">
          <listitem><para>the working copy management library</para></listitem>
          <listitem><para>a repository access library</para></listitem>
        </itemizedlist>
      </para></listitem>
      <listitem><para><emphasis role="bold">Provides:</emphasis>  
        <itemizedlist mark="minus">
          <listitem><para>all client-side Subversion commands</para></listitem>
        </itemizedlist>
      </para></listitem>
    </itemizedlist>

    <para>These functions correspond to user-level client commands.  In theory,
      any client interface (command-line, GUI, emacs, Python, etc.) should be
      able to link to <replaceable>libsvn_client</replaceable> and have the
      ability to act as a full-featured Subversion client.</para>

    <para>Again, the detailed API can be found in
      <filename>subversion/include/svn_client.h</filename>.</para>
  </sect1>
</chapter>
