<chapter id="svn-ch-2">
    <title>Grundlegende Konzepte    Basic Concepts</title>

  <simplesect>
      <para>This chapter is a short, casual introduction to Subversion.
      If you're new to version control, this chapter is definitely for
      you.  We begin with a discussion of general version control
      concepts, work our way into the specific ideas behind
      Subversion, and show some simple examples of Subversion in
	  use.
  
      Dieses Kapitel ist eine kurze, beiläufige Einleitung zur Subversion. 
	  Wenn Sie neu sind im Bereich Versionskontrolle, dann ist
	  dieses Kapitel definitiv für Sie.
	  Wir fangen mit einer Diskussion über allgemeine Konzepte bei
	  Versionkontrolle an und arbeiten uns in Richtung der speziellen Ideen
	  die hinter Subversion stehen vor und zeigen einige einfache Beispiele
      der Anwendung von Subversion.
  </para>
    
  <para>Obwohl die Beispiele in diesem Kapitel Leute zeigen,
      die Ansammlungen von Quellcode teilen, bedenken
      Sie, dass Subversion jede art von Dateikansammlungen verwalten
      kann. Das ist nich auf den Bereich Programmierung begrenzt.
      
	  Even though the examples in this chapter show people sharing
      collections of program source code, keep in mind that Subversion
      can manage any sort of file collection&mdash;it's not limited to
      helping computer programmers.</para>
  </simplesect>
  
  
  <sect1 id="svn-ch2-sect-1" > 
    <title>Das Repository</title>  
    
    <para>Subversion ist ein zentralisiertes System, um Informationen
       zu teilen. Seine Basis ist ein Repository, dass die Zentrale 
       Datenspeicherung darstellt. 
       Das Repository legt Informationen in Form eines 
       <firstterm>Dateisystem Baumes</firstterm> ab. Eine typische Hirarchie
       von Dateien und Verzeichnissen. Eine beliebige Anzahl von
       <firstterm>Clients</firstterm> verbinden sich mit dem Repository und
       lesen oder schreiben dann diese Datenen. Durch das schreiben der Daten,
       macht der Client die Informationen für die anderen Verfügbar. Durch das lesen
       erhält der Client Informationen von anderen.
        
        Subversion is a centralized system for sharing information.
      At its core is a repository, which is a central store of data.
      The repository stores information in the form of a
      <firstterm>filesystem tree</firstterm>&mdash;a typical hierarchy
      of files and directories.  Any number of
      <firstterm>clients</firstterm> connect to the repository, and
      then read or write to these files.  By writing data, a client
      makes the information available to others; by reading data, the
      client receives information from others.</para>

    <figure id="svn-ch2-dia1">
        <title>Ein typisches Client/Server System</title>
      <graphic fileref="images/ch02dia1.png"/>
    </figure>
    
    <para>Warum ist das interessant? So weit, klingt dass wie
        eine Definition eines typischen Dateiservers. Und in der Tat,
        das Repository <emphasis>ist</emphasis> eine Art von Dateiserver,
        aber nicht die Art, die Sie kennen.
        Das was dass Subversion Repository zu etwas besonderem macht, ist
        dass sich <emphasis>jede Änderung</emphasis> jemals in das Repository
        geschrieben wurde merkt. Jede Änderung an jeder Datei und eben auch
        die Änderung am Verzeichnissbaum selbst und zusätzlich das hinzufügen, löschen
        und Umordnen von Dateien und Verzeichnissen.
        
        So why is this interesting?  So far, this sounds like the
      definition of a typical file server.  And indeed, the repository
      <emphasis>is</emphasis> a kind of file server, but it's not your
      usual breed.  What makes the Subversion repository special is
      that <emphasis>it remembers every change</emphasis> ever written
      to it: every change to every file, and even changes to the
      directory tree itself, such as the addition, deletion, and
      rearrangement of files and directories.</para>

  <para>Wenn ein Client Daten vom Repository liest, sieht 
      er normalerweise nur die letzte Version des Dateisystembaumes.
      Der Client hat aber auch die Möglichkeit <emphasis>vorherige</emphasis>
      Zustände des Dateisystems anzusehen.
      Beispielsweise kann der Client die Frage stellen: <quote>Was beinhaltete
      das Verzeichnis letzen Mittwoch?</quote> oder <quote>Wer war
      die letzte Person, die diese Datei geändert hat und welche Änderungen
      wurden durchgeführt?</quote> Diese Art von Fragen sind Grundlegend 
      für jedes <firstterm>Versionkontrollsystem</firstterm>: Systeme,
      die dazu geschaffen wurden jede Veränderung aufzuzeichnen und 
      zu verfolgen über die Zeit.
          
      
      When a client reads data from the repository, it normally
      sees only the latest version of the filesystem tree.  But the
      client also has the ability to view
      <emphasis>previous</emphasis> states of the filesystem.  For
      example, a client can ask historical questions like, <quote>What
      did this directory contain last Wednesday?</quote> or <quote>Who
      was the last person to change this file, and what changes did
      they make?</quote> These are the sorts of questions that are at
      the heart of any <firstterm>version control system</firstterm>:
      systems that are designed to record and track changes to data
      over time.
    </para>
  </sect1>

  <sect1 id="svn-ch-2-sect-2">
      <title>Modelle der Versionierung    Versioning Models</title>
    
    <sect2 id="svn-ch-2-sect-2.1">
      <title>Das Problem des gemeinsamen Datei zugriffs     The Problem of File-Sharing</title>
      
      <para>Alle Versionskontrollsystem haben alle das gleiche 
          Fundamentale Problem zu lösen: Wie soll es ein System 
          Anwendern erlauben Informationen zu Teilen, aber davon
          abzuhalten durch Zufall gegenseitig auf die Füße zu treten?
          Es ist allzu einfach für Anwender sich durch Zufall 
          gegenseitig Änderungen im Repository zu überschreiben.
          
          All version control systems have to solve the same
        fundamental problem: how will the system allow users to share
        information, but prevent them from accidentally stepping on
        each other's feet?  It's all too easy for users to
        accidentally overwrite each other's changes in the
        repository.</para>

    <para>Betrachten wird das folgende Szenario: Angenommen, wir 
        habe zwei Kollegen, Harry und Sally. Sie haben sich beide 
        entschieden die gleiche Repository Datei zu gleichen Zeit
        zu bearbeiten. Wenn Harry seine Änderungen nun zuerst in das
        Repository speichert, dann ist es möglich (einige Momente
        später), dass Sally aus versehen die Änderungen
        mit Ihrer Version der Datei überschreibt.
        Während Harrys Version der Datei nicht für immer verloren ist
        (das System erinnert sich ja an jede Änderung), aber jede Änderung
        die Harry gemacht hat ist nicht in Sallys neuer Version zu sehen.
        Das liegt daran, dass Sally nie die Änderungen von Harry zu Anfang 
        gesehen hat. Harrys Arbiets ist doch gewissermaßen verloren, oder
        wenigstens nicht in der letzten Version der Datei möglichweise
        durch Zufall. Das ist definitiv eine Situations, die vermieden
        werden muß.

        
        Consider this scenario: suppose we have two co-workers,
        Harry and Sally.  They each decide to edit the same repository
        file at the same time.  If Harry saves his changes to the
        repository first, then it's possible that (a few moments
        later) Sally could accidentally overwrite them with her own
        new version of the file.  
        While Harry's version of the file
        won't be lost forever (because the system remembers every
        change), any changes Harry made <emphasis>won't</emphasis> be
        present in Sally's newer version of the file, because she
        never saw Harry's changes to begin with.  Harry's work is
        still effectively lost&mdash;or at least missing from the
        latest version of the file&mdash;and probably by accident.
        This is definitely a situation we want to avoid!</para>

      <figure id="svn-ch2-dia2">
        <title>The Problem to Avoid</title>
        <graphic fileref="images/ch02dia2.png"/>
      </figure>

      </sect2>
    
    <sect2 id="svn-ch-2-sect-2.2">
        <title>Die Lock-Modify-Unlock Lösung ???     The Lock-Modify-Unlock Solution</title>
      
        <para>Viele Versionskontrollsysteme verwenden ein 
            <firstterm>Sperren-Ändern-Entsperren<footnote>Lock-Modify-Unlock</footnote></firstterm> Modell um 
            das Problem auf diese Weise zu behandeln, wobei das eine sehr 
            einfache Lösungsmethode ist. In solchen Systemen erlaubt 
            das Repository genau einer Person eine Datei zur gleichen
            Zeit zu ändern. Zuerst müsste Harry die Datei <quote>sperren</quote>
            bevor er Änderungen an der Datei durchführen könnte. Das Sperren
            einer Datei ist ein wenig wie die Ausleihe eines Buches aus
            einer Bibliothek. Wenn Harry die Datei gesperrt hat, dann kann
            Sally keinerlei Änderungen an der Datei durchführen. Wenn Sie versucht
            die Datei zu Sperren, wird das Repository das verbieten. Alles 
            was Sie machen kann ist die Datei lesen und darauf warten, dass
            Harry mit seinen Änderungen fertig wird und die Sperre wieder aufhebt.
            Wenn Harry die Sperry wieder freigegeben hat ist nun Sally an der
            Reihe zu Sperren und Änderungen an der Datei zu machen.
            
            Many version control systems use a
        <firstterm>lock-modify-unlock</firstterm> model to address
        this problem, which is a very simple solution.  In such a
        system, the repository allows only one person to change a file
        at a time.  First Harry must <quote>lock</quote> the file
        before he can begin making changes to it.  Locking a file is a
        lot like borrowing a book from the library; if Harry has
        locked a file, then Sally cannot make any changes to it.  If
        she tries to lock the file, the repository will deny the
        request.  All she can do is read the file, and wait for Harry
        to finish his changes and release his lock.  After Harry
        unlocks the file, his turn is over, and now Sally can take her
        turn by locking and editing.</para>
      
      <figure id="svn-ch2-dia3">
        <title>Die Lock-Modify-Unlock Lösung ???     The Lock-Modify-Unlock Solution</title>
        <graphic fileref="images/ch02dia3.png"/>
      </figure>
      
      <para>Das Problem mit der Vorgehensweise ist, dass es 
          ein bisschen Einschränkend ist und oft zu einer Hürde 
          für die Anwender wird.
          
          The problem with the lock-modify-unlock model is that it's
        a bit restrictive, and often becomes a roadblock for
        users:</para>

      <itemizedlist>
        <listitem><para>
                <emphasis>Sperren kann zu Administrativen Problemen führen.
                    Locking may cause administrative problems.</emphasis>


            Manchmal sperrt Harry eine Datei und vergisst es.
            Unterdessen, weil Sally darauf wartet die Datei ändern zu
            können, sind Ihre Hände gefesselt (????)..
            Und dann geht Harry in Urlaub. Nun muß Sally zum Administrator
            rennen, um Harrys Sperre aufheben zu lassen. Das führt zu
            einer Menge unnötiger Verzögerungen und verschwendeter Zeit.
            
            
            Sometimes Harry will lock a file and then forget about it.
            Meanwhile, because Sally is still waiting to edit the file,
            her hands are tied.  And then Harry goes on vacation.  Now
            Sally has to get an administrator to release Harry's lock.
            The situation ends up causing a lot of unnecessary delay
            and wasted time.</para></listitem>
        
        <listitem><para>
                <emphasis>Sperren für zu unnötiger Anordnung der Arbeit ??? 
                    der Reihe nach ???
                    
                    Locking may cause unnecessary serialization.</emphasis>

            Was ist wenn Harry am Anfang eine Text Datei änderungen macht,
            und Sally möchte einfach am Ende der gleichen Datei Änderungen machen?
            Diese Änderungen überlappen sich überhaupt nicht. Sie könnten einfach
            die Datei gleichzeitig bearbeiten und es würde kein großer Nachteil
            würde entstehen, vorausgesetzt dass die Änderungen genau 
            zusammengeführt<footnote>merged</footnote> würden. 
            Es besteht keine Notwendigkeit für die Beiden abwechselnd zu 
            Arbeiten in dieser Situtaion.
            

            What if Harry is editing the beginning of a text file,
            and Sally simply wants to edit the end of the same file?
            These changes don't overlap at all.  They could easily
            edit the file simultaneously, and no great harm would
            come, assuming the changes were properly merged together.
            There's no need for them to take turns in this
            situation.</para></listitem>
    
        <listitem><para>
                <emphasis>Sperren kann zu einem falschen Gefühl von Sicherheit führen.
                    
                    Locking may create a false sense of security.</emphasis>


            Pretend that Harry locks and edits file A, while
            Sally simultaneously locks and edits file B.  But suppose
            that A and B depend on one another, and the changes made
            to each are semantically incompatible.  Suddenly A and B
            don't work together anymore. The locking system was
            powerless to prevent the problem&mdash;yet it somehow
            provided a false sense of security.  It's easy for Harry and
            Sally to imagine that by locking files, each is beginning a
            safe, insulated task, and thus inhibits them from
            discussing their incompatible changes early
            on.</para></listitem>
      </itemizedlist>

      </sect2>

    <sect2 id="svn-ch-2-sect-2.3">
      <title>The Copy-Modify-Merge Solution</title>
      
      <para>Subversion, CVS, and other version control systems use a
        <firstterm>copy-modify-merge</firstterm> model as an
        alternative to locking.  In this model, each user's client
        contacts the project repository and creates a personal
        <firstterm>working copy</firstterm>&mdash;a local reflection
        of the repository's files and directories.  Users then work in
        parallel, modifying their private copies.  Finally, the
        private copies are merged together into a new, final version.
        The version control system often assists with the merging, but
        ultimately a human being is responsible for making it happen
        correctly.</para>
      
      <para>Here's an example.  Say that Harry and Sally each create
        working copies of the same project, copied from the
        repository.  They work concurrently, and make changes to the
        same file A within their copies.  Sally saves her changes to
        the repository first.  When Harry attempts to save his changes
        later, the repository informs him that his file A is
        <firstterm>out-of-date</firstterm>.  In other words, that file
        A in the repository has somehow changed since he last copied
        it.  So Harry asks his client to <firstterm>merge</firstterm>
        any new changes from the repository into his working copy of
        file A.  Chances are that Sally's changes don't overlap with
        his own; so once he has both sets of changes integrated, he
        saves his working copy back to the repository.</para>

      <figure id="svn-ch2-dia4">
        <title>The Copy-Modify-Merge Solution</title>
        <graphic fileref="images/ch02dia4.png"/>
      </figure>
      
      <figure id="svn-ch2-dia5">
        <title>&hellip;Copy-Modify-Merge Continued</title>
        <graphic fileref="images/ch02dia5.png"/>
      </figure>

      <para>But what if Sally's changes <emphasis>do</emphasis> overlap
        with Harry's changes?  What then?  This situation is called a
        <firstterm>conflict</firstterm>, and it's usually not much of
        a problem.  When Harry asks his client to merge the latest
        repository changes into his working copy, his copy of file A
        is somehow flagged as being in a state of conflict: he'll be
        able to see both sets of conflicting changes, and manually
        choose between them.  Note that software can't automatically
        resolve conflicts; only humans are capable of understanding
        and making the necessary intelligent choices.  Once Harry has
        manually resolved the overlapping changes&mdash;perhaps after
        a discussion with Sally&mdash;he can safely save the
        merged file back to the repository.</para>

      <para>The copy-modify-merge model may sound a bit chaotic, but
        in practice, it runs extremely smoothly.  Users can work in
        parallel, never waiting for one another.  When they work on
        the same files, it turns out that most of their concurrent
        changes don't overlap at all; conflicts are infrequent.  And
        the amount of time it takes to resolve conflicts is far less
        than the time lost by a locking system.</para>

      <para>In the end, it all comes down to one critical factor: user
        communication.  When users communicate poorly, both syntactic
        and semantic conflicts increase.  No system can force users to
        communicate perfectly, and no system can detect semantic
        conflicts.  So there's no point in being lulled into a false
        promise that a locking system will somehow prevent conflicts;
        in practice, locking seems to inhibit productivity more than
        anything else.</para>
      
    </sect2>
    
  </sect1>
  
  <!-- How svn implements the philosophy -->
  <sect1 id="svn-ch-2-sect-3">
    <title>Subversion in Action</title>
    
    <sect2 id="svn-ch-2-sect-3.1">
      <title>Working Copies</title>
      
      <para>You've already read about working copies; now we'll
        demonstrate how the Subversion client creates and uses
        them.</para>
      
      <para>A Subversion working copy is an ordinary directory tree on
        your local system, containing a collection of files.  You can
        edit these files however you wish, and if they're source code
        files, you can compile your program from them in the usual
        way.  Your working copy is your own private work area:
        Subversion will never incorporate other people's changes, nor
        make your own changes available to others, until you
        explicitly tell it to do so.</para>

      <para>After you've made some changes to the files in your
        working copy and verified that they work properly, Subversion
        provides you with commands to <quote>publish</quote> your
        changes to the other people working with you on your project
        (by writing to the repository).  If other people publish their
        own changes, Subversion provides you with commands to merge
        those changes into your working directory (by reading from the
        repository).</para>

      <para>A working copy also contains some extra files, created and
        maintained by Subversion, to help it carry out these commands.
        In particular, each directory in your working copy contains a
        subdirectory named <filename>.svn</filename>, also known as
        the working copy <firstterm>administrative
        directory</firstterm>.  The files in each administrative
        directory help Subversion recognize which files contain
        unpublished changes, and which files are out-of-date with
        respect to others' work.</para>
      
      <para>A typical Subversion repository often holds the files (or
        source code) for several projects; usually, each project is a
        subdirectory in the repository's filesystem tree.  In this
        arrangement, a user's working copy will usually correspond to
        a particular subtree of the repository.</para>
      
      <para>For example, suppose you have a repository that contains
        two software projects.</para>

      <figure id="svn-ch2-dia6">
        <title>The Repository's Filesystem</title>
        <graphic fileref="images/ch02dia6.png"/>
      </figure>
      
      <para>In other words, the repository's root directory has two
        subdirectories: <filename>paint</filename> and
        <filename>calc</filename>.</para>

      <para>To get a working copy, you must <firstterm>check
        out</firstterm> some subtree of the repository.  (The term
        <quote>check out</quote> may sound like it has something to do
        with locking or reserving resources, but it doesn't; it simply
        creates a private copy of the project for you.) For example,
        if you check out <filename>/calc</filename>, you will get a
        working copy like this: </para>

<screen>
$ svn checkout http://svn.example.com/repos/calc
A  calc
A  calc/Makefile
A  calc/integer.c
A  calc/button.c

$ ls -a calc
Makefile  integer.c  button.c  .svn/
</screen>

      <para>The list of letter A's indicates that Subversion is adding
        a number of items to your working copy.  You now have a
        personal copy of the repository's <filename>/calc</filename>
        directory, with one additional
        entry&mdash;<filename>.svn</filename>&mdash;which holds the
        extra information needed by Subversion, as mentioned
        earlier.</para>

      <sidebar id="svn-ch-02-sidebar-1">
        <title>Repository URLs</title>

        <para>Subversion repositories can be accessed through many
          different methods&mdash;on local disk, or through various
          network protocols.  A repository location, however, is
          always a URL.  The URL schema indicates the access
          method:</para>

        <table id="svn-ch-02-table-1">
          <title>Repository Access URLs</title>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Schema</entry>
                <entry>Access Method</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><literal>file:///</literal></entry>
                <entry>direct repository access (on local disk)</entry>
              </row>
              <row>
                <entry><literal>http://</literal></entry>
                <entry>access via WebDAV protocol to Subversion-aware
                  Apache server</entry>
              </row>
              <row>
                <entry><literal>https://</literal></entry>
                <entry>same as <literal>http://</literal>, but with
                  SSL encryption.</entry>
              </row>
              <row>
                <entry><literal>svn://</literal></entry>
                <entry>access via custom protocol to an
                  <literal>svnserve</literal> server</entry>
              </row>
              <row>
                <entry><literal>svn+ssh://</literal></entry>
                <entry>same as <literal>svn://</literal>, but through
                  an SSH tunnel.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
 
        <para>For the most part, Subversion's URLs use the standard
          syntax, allowing for server names and port numbers to be
          specified as part of the URL.  Remember that the
          <literal>file:</literal> access method is valid only for
          locations on the same server as the client&mdash;in fact, in
          accordance with convention, the server name portion of the
          URL is required to be either absent or
          <literal>localhost</literal>:</para>
 
        <screen>
$ svn checkout file:///path/to/repos
&hellip;
$ svn checkout file://localhost/path/to/repos
&hellip;
</screen>

        <para>Also, users of the <literal>file:</literal> scheme on
          Windows platforms will need to use an unofficially
          <quote>standard</quote> syntax for accessing repositories
          that are on the same machine, but on a different drive than
          the client's current working drive.  Either of the two
          following URL path syntaxes will work where
          <literal>X</literal> is the drive on which the repository
          resides:</para>

        <screen>
C:\> svn checkout file:///X:/path/to/repos
&hellip;
C:\> svn checkout "file:///X|/path/to/repos"
&hellip;
</screen>
 
        <para>In the second syntax, you need to quote the URL so that
          the vertical bar character is not interpreted as a pipe.</para>

        <para>Note that a URL uses ordinary slashes even though the native
          (non-URL) form of a path on Windows uses backslashes.</para>

      </sidebar>

      <para>Suppose you make changes to <filename>button.c</filename>.
        Since the <filename>.svn</filename> directory remembers the
        file's modification date and original contents, Subversion can
        tell that you've changed the file.  However, Subversion does
        not make your changes public until you explicitly tell it to.
        The act of publishing your changes is more commonly known as
        <firstterm>committing</firstterm> (or <firstterm>checking
        in</firstterm>) changes to the repository.</para>

      <para>To publish your changes to others, you can use
        Subversion's <command>commit</command> command:</para>

<screen>
$ svn commit button.c
Sending        button.c
Transmitting file data .
Committed revision 57.
</screen>

      <para>Now your changes to <filename>button.c</filename> have
        been committed to the repository; if another user checks out a
        working copy of <filename>/calc</filename>, they will see
        your changes in the latest version of the file.</para>

      <para>Suppose you have a collaborator, Sally, who checked out a
        working copy of <filename>/calc</filename> at the same time
        you did.  When you commit your change to
        <filename>button.c</filename>, Sally's working copy is left
        unchanged; Subversion only modifies working copies at the
        user's request.</para>

      <para>To bring her project up to date, Sally can ask
        Subversion to <firstterm>update</firstterm> her working copy,
        by using the Subversion <command>update</command> command.
        This will incorporate your changes into her working copy, as
        well as any others that have been committed since she checked
        it out.</para>

<screen>
$ pwd
/home/sally/calc

$ ls -a 
.svn/ Makefile integer.c button.c

$ svn update
U button.c
</screen>

      <para>The output from the <command>svn update</command> command
        indicates that Subversion updated the contents of
        <filename>button.c</filename>.  Note that Sally didn't need to
        specify which files to update; Subversion uses the information
        in the <filename>.svn</filename> directory, and further
        information in the repository, to decide which files need to
        be brought up to date.</para>
      
    </sect2>
    
    
    <sect2 id="svn-ch-2-sect-3.2">
      <title>Revisions</title>

      <para>An <command>svn commit</command> operation can publish
        changes to any number of files and directories as a single
        atomic transaction.  In your working copy, you can change
        files' contents, create, delete, rename and copy files and
        directories, and then commit the complete set of changes as a
        unit.</para>

      <para>In the repository, each commit is treated as an atomic
        transaction: either all the commit's changes take place, or
        none of them take place.  Subversion tries to retain this
        atomicity in the face of program crashes, system crashes,
        network problems, and other users' actions.</para>

      <para>Each time the repository accepts a commit, this creates a
        new state of the filesystem tree, called a
        <firstterm>revision</firstterm>.  Each revision is assigned a
        unique natural number, one greater than the number of the
        previous revision.  The initial revision of a freshly created
        repository is numbered zero, and consists of nothing but an
        empty root directory.</para>
      
      <para>A nice way to visualize the repository is as a series of
        trees.  Imagine an array of revision numbers, starting at 0,
        stretching from left to right.  Each revision number has a
        filesystem tree hanging below it, and each tree is a
        <quote>snapshot</quote> of the way the repository looked after
        each commit. </para>
      
      <figure id="svn-ch2-dia7">
        <title>The Repository</title>
        <graphic fileref="images/ch02dia7.png"/>
      </figure>


      <sidebar>
        <title>Global Revision Numbers</title>
         
        <para>Unlike those of many other version control systems,
          Subversion's revision numbers apply to <emphasis>entire
          trees</emphasis>, not individual files.  Each revision
          number selects an entire tree, a particular state of the
          repository after some committed change.  Another way to
          think about it is that revision N represents the state of
          the repository filesystem after the Nth commit.  When a
          Subversion user talks about <quote>revision 5 of
          <filename>foo.c</filename></quote>, they really mean
          <quote><filename>foo.c</filename> as it appears in revision 5.</quote>
          Notice that in general, revisions N and M of a file do
          <emphasis>not</emphasis> necessarily differ!  Because CVS
          uses per-file revisions numbers, CVS users might want to see
          <xref linkend="svn-ap-a"/> for more details.</para>
      </sidebar>

      <para>It's important to note that working copies do not always
        correspond to any single revision in the repository; they may
        contain files from several different revisions.  For example,
        suppose you check out a working copy from a repository whose
        most recent revision is 4:</para>

<screen>
calc/Makefile:4
     integer.c:4
     button.c:4
</screen>

      <para>At the moment, this working directory corresponds exactly
        to revision 4 in the repository.  However, suppose you make a
        change to <filename>button.c</filename>, and commit that
        change.  Assuming no other commits have taken place, your
        commit will create revision 5 of the repository, and your
        working copy will now look like this:</para>

<screen>
calc/Makefile:4
     integer.c:4
     button.c:5
</screen>

      <para>Suppose that, at this point, Sally commits a change to
        <filename>integer.c</filename>, creating revision 6.  If you
        use <command>svn update</command> to bring your working copy
        up to date, then it will look like this:</para>

<screen>
calc/Makefile:6
     integer.c:6
     button.c:6
</screen>

      <para>Sally's changes to <filename>integer.c</filename> will
        appear in your working copy, and your change will still be
        present in <filename>button.c</filename>.  In this example,
        the text of <filename>Makefile</filename> is identical in
        revisions 4, 5, and 6, but Subversion will mark your working
        copy of <filename>Makefile</filename> with revision 6 to
        indicate that it is still current.  So, after you do a clean
        update at the top of your working copy, it will generally
        correspond to exactly one revision in the repository.</para>

    </sect2>
    
    
    <sect2 id="svn-ch-2-sect-3.3">
      <title>How Working Copies Track the Repository</title>
      
      <para>For each file in a working directory, Subversion records
        two essential pieces of information in the
        <filename>.svn/</filename> administrative area:</para>
      
      
      <itemizedlist>
        <listitem><para>what revision your working file is based on
            (this is called the file's <firstterm>working
             revision</firstterm>), and</para></listitem>
        
        <listitem><para>a timestamp recording when the local copy was
            last updated by the repository.</para></listitem>
      </itemizedlist>

      <para>Given this information, by talking to the repository,
        Subversion can tell which of the following four states a
        working file is in:</para>

      <variablelist>
        <varlistentry>
          <term>Unchanged, and current</term> 

          <listitem><para>The file is unchanged in the working
          directory, and no changes to that file have been committed
          to the repository since its working revision.  A
          <command>svn commit</command> of the file will do nothing,
          and an <command>svn update</command> of the file will do
          nothing. </para></listitem>
        </varlistentry>
        
        <varlistentry>
          <term>Locally changed, and current</term>

          <listitem><para>The file has been changed in the working
          directory, and no changes to that file have been committed
          to the repository since its base revision.  There are local
          changes that have not been committed to the repository, thus
          an <command>svn commit</command> of the file will succeed in
          publishing your changes, and an <command>svn update</command>
          of the file will do nothing.</para></listitem>
        </varlistentry>
        
        <varlistentry>
          <term>Unchanged, and out-of-date</term> 

          <listitem><para>The file has not been changed in the working
          directory, but it has been changed in the repository.  The
          file should eventually be updated, to make it current with
          the public revision.  An <command>svn commit</command> of the
          file will do nothing, and an <command>svn update</command> of
          the file will fold the latest changes into your working
          copy.</para></listitem>
        </varlistentry>
        
        <varlistentry>
          <term>Locally changed, and out-of-date</term>

          <listitem><para>The file has been changed both in the
          working directory, and in the repository.  An <command>svn
          commit</command> of the file will fail with an
          <quote>out-of-date</quote> error.  The file should be
          updated first; an <command>svn update</command> command will
          attempt to merge the public changes with the local changes.
          If Subversion can't complete the merge in a plausible way
          automatically, it leaves it to the user to resolve the
          conflict.</para></listitem>
        </varlistentry>
      </variablelist>
      
      
      <para>This may sound like a lot to keep track of, but the
        <command>svn status</command> command will show you the state
        of any item in your working copy.  For more information on
        that command, see <xref linkend="svn-ch-3-sect-4.3.1" />.</para>
     
    </sect2>
    
    <sect2 id="svn-ch-2-sect-3.4">
      <title>The Limitations of Mixed Revisions</title>

      <para>As a general principle, Subversion tries to be as flexible
        as possible.  One special kind of flexibility is the ability
        to have a working copy containing mixed revision
        numbers.</para>

      <para>At first, it may not be entirely clear why this sort of
        flexibility is considered a feature, and not a liability.
        After completing a commit to the repository, the freshly
        committed files and directories are at more recent working
        revision than the rest of the working copy.  It looks like a
        bit of a mess.  As demonstrated earlier, the working copy can
        always be brought to a single working revision by running
        <command>svn update</command>.  Why would someone
        <emphasis>deliberately</emphasis> want a mixture of working
        revisions?</para>

      <para>Assuming your project is sufficiently complex, you'll
        discover that it's sometimes nice to forcibly
        <quote>backdate</quote> portions of your working copy to an
        earlier revision; you'll learn how to do that in Chapter 3.
        Perhaps you'd like to test an earlier version of a sub-module,
        contained in a subdirectory, or perhaps you'd like to examine
        a number of previous versions of a file in the context of the
        latest tree.</para>
        
      <para>However you make use of mixed-revisions in your working
        copy, there are limitations to this flexibility.</para>

      <para>First, you cannot commit the deletion of a file or
        directory which isn't fully up-to-date.  If a newer version of
        the item exists in the repository, your attempt to delete will
        be rejected, to prevent you from accidentally
        destroying changes you've not yet seen.</para>

      <para>Second, you cannot commit a metadata change to a directory
        unless it's fully up-to-date.  You'll learn about attaching
        <quote>properties</quote> to items in Chapter 6.  A
        directory's working revision defines a specific set of entries
        and properties, and thus committing a property change to an
        out-of-date directory may destroy properties you've not yet
        seen.</para>

    </sect2>

  </sect1>

  <sect1 id="svn-ch-2-sect-4">
    <title>Summary</title>
    
    <para>We've covered a number of fundamental Subversion concepts in
    this chapter:</para>

    <itemizedlist>
      <listitem>
        <para>We've introduced the notions of the central repository,
          the client working copy, and the array of repository
          revision trees.</para>
      </listitem>

      <listitem>
        <para>We've seen some simple examples of how two collaborators
        can use Subversion to publish and receive changes from one
        another, using the 'copy-modify-merge' model.</para>
      </listitem>

      <listitem>
        <para>We've talked a bit about the way Subversion tracks and
          manages information in a working copy.</para>
      </listitem>

    </itemizedlist>
    
    <para>At this point, you should have a good idea of how Subversion
    works in the most general sense.  Armed with this knowledge, you
    should now be ready to jump into the next chapter, which is a
    detailed tour of Subversion's commands and features. </para>
      
  </sect1>

</chapter>

<!--
local variables: 
sgml-parent-document: ("book.xml" "chapter")
end:
-->
