ch01-fundamental-concepts.xml - svnbook - Project Hosting on Google Code

‹r2867

r3661

Source path: svn/ tags/ en-1.4-final/ src/ en/ book/ ch01-fundamental-concepts.xml

<chapter id="svn.basic">
  <title>Fundamental Concepts</title>

  <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.</para>

  <para>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>


  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.basic.repository">
    <title>The Repository</title>

    <para>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.  <xref
      linkend="svn.basic.repository.dia-1"/> illustrates this.</para>

    <figure id="svn.basic.repository.dia-1">
      <title>A typical client/server system</title>
      <graphic fileref="images/ch02dia1.png"/>
    </figure>

    <para>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>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 he
      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 track changes to data over time.
    </para>
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.basic.vsn-models">
    <title>Versioning Models</title>

    <para>The core mission of a version control system is to enable
      collaborative editing and sharing of data.  But different
      systems use different strategies to achieve this.  It's
      important to understand these different strategies for a couple
      of reasons.  First, it will help you compare and contrast
      existing version control systems, in case you encounter other
      systems similar to Subversion.  Beyond that, it will also help
      you make more effective use of Subversion, since Subversion
      itself supports a couple of different ways of working.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.basic.vsn-models.problem-sharing">
      <title>The Problem of File-Sharing</title>
      
      <para>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>Consider the scenario shown in <xref
        linkend="svn.basic.vsn-models.problem-sharing.dia-1"/>.
        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.basic.vsn-models.problem-sharing.dia-1">
        <title>The problem to avoid</title>
        <graphic fileref="images/ch02dia2.png"/>
      </figure>

      </sect2>
    
    <!-- =============================================================== -->
    <sect2 id="svn.basic.vsn-models.lock-unlock">
      <title>The Lock-Modify-Unlock Solution</title>
      
      <para>Many version control systems use a
        <firstterm>lock-modify-unlock</firstterm> model to address the
        problem of many authors clobbering each other's work.  In this
        model, the repository allows only one person to change a file
        at a time.  This exclusivity policy is managed using locks.
        Harry must <quote>lock</quote> a file before he can begin
        making changes to it.  If Harry has locked a file, then Sally
        cannot also lock it, and therefore cannot make any changes to
        that file.  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, Sally can take her turn by locking and
        editing the file.  <xref
        linkend="svn.basic.vsn-models.lock-unlock.dia-1"/>
        demonstrates this simple solution.</para>
      
      <figure id="svn.basic.vsn-models.lock-unlock.dia-1">
        <title>The lock-modify-unlock solution</title>
        <graphic fileref="images/ch02dia3.png"/>
      </figure>
      
      <para>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>Locking may cause administrative
            problems.</emphasis>

            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>Locking may cause unnecessary
            serialization.</emphasis>

            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>Locking may create a false sense of
            security.</emphasis>

            Suppose Harry locks and edits file A, while Sally
            simultaneously locks and edits file B.  But what if 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 not bother discussing their
            incompatible changes early on.  Locking often becomes a
            substitute for real communication.</para>
        </listitem>
      </itemizedlist>

      </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.basic.vsn-models.copy-merge">
      <title>The Copy-Modify-Merge Solution</title>
      
      <para>Subversion, CVS, and many 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
        simultaneously and independently, 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.  <xref
        linkend="svn.basic.vsn-models.copy-merge.dia-1"/> and <xref
        linkend="svn.basic.vsn-models.copy-merge.dia-2"/> show this
        process.</para>


      <figure id="svn.basic.vsn-models.copy-merge.dia-1">
        <title>The copy-modify-merge solution</title>
        <graphic fileref="images/ch02dia4.png"/>
      </figure>
      
      <figure id="svn.basic.vsn-models.copy-merge.dia-2">
        <title>The copy-modify-merge solution (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 usually
        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
        sense of security that a locking system will somehow prevent
        conflicts; in practice, locking seems to inhibit productivity
        more than anything else.</para>
      
      <sidebar id="svn.basic.vsn-models.copy-merge.sb-1">
        <title>When Locking is Necessary</title>
        
        <para>While the lock-modify-unlock model is considered
          generally harmful to collaboration, there are still times
          when locking is appropriate.</para>

        <para>The copy-modify-merge model is based on the assumption
          that files are contextually mergeable: that is, that the
          majority of the files in the repository are line-based text
          files (such as program source code).  But for files with
          binary formats, such as artwork or sound, it's often
          impossible to merge conflicting changes.  In these
          situations, it really is necessary to users to take strict
          turns when changing the file.  Without serialized access,
          somebody ends up wasting time on changes that are ultimately
          discarded.</para>

        <para>While Subversion is still primarily a copy-modify-merge
          system, it still recognizes the need to lock an occasional
          file and thus provide mechanisms for this.  This feature is
          discussed later in this book, in
          <xref linkend="svn.advanced.locking"/>.</para>

      </sidebar>


    </sect2>
    
  </sect1>
  
  <!-- How svn implements the philosophy -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.basic.in-action">
    <title>Subversion in Action</title>
    
    <para>It's time to move from the abstract to the concrete.  In
      this section, we'll show real examples of Subversion being
      used.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.reposurls">
      <title>Subversion Repository URLs</title>
  
      <para>Throughout this book, Subversion uses URLs to identify
        versioned files and directories in Subversion repositories.
        For the most part, these URLs use the standard syntax,
        allowing for server names and port numbers to be specified as
        part of the URL:</para>
  
      <screen>
$ svn checkout http://svn.example.com:9834/repos
&hellip;
</screen>
  
      <para>But there are some nuances in Subversion's handling of URLs
        that are notable.  For example, URLs containing the
        <literal>file://</literal> access method (used for local
        repositories) must, in accordance with convention, have either a
        server name of <literal>localhost</literal> or no server name at
        all:</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:\&gt; svn checkout file:///X:/path/to/repos
&hellip;
C:\&gt; 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.  Also, note
        that a URL uses forward slashes even though the native
        (non-URL) form of a path on Windows uses backslashes.</para>

      <note>
        <para>Subversion's <literal>file://</literal> URLs cannot be
          used in a regular web browser the way typical
          <literal>file://</literal> URLs can.  When you attempt to view
          a <literal>file://</literal> URL in a regular web browser, it
          reads and displays the contents of the file at that location
          by examining the filesystem directly.  However, Subversion's
          resources exist in a virtual filesystem (see <xref
          linkend="svn.developer.layerlib.repos" />), and your browser
          will not understand how to interact with that
          filesystem.</para>
      </note>
      
      <para>Finally, it should be noted that the Subversion client will
        automatically encode URLs as necessary, just like a web browser
        does.  For example, if a URL contains a space or upper-ASCII
        character:</para>
  
      <screen>
$ svn checkout "http://host/path with space/project/españa"
</screen>
      
      <para>&hellip;then Subversion will escape the unsafe characters
        and behave as if you had typed:</para>
  
      <screen>
$ svn checkout http://host/path%20with%20space/project/espa%C3%B1a
</screen>
  
      <para>If the URL contains spaces, be sure to place it within quote
        marks, so that your shell treats the whole thing as a single
        argument to the <command>svn</command> program.</para>
  
    </sect2>
  
    <!-- =============================================================== -->
    <sect2 id="svn.basic.in-action.wc">
      <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.  You can even have multiple
        working copies of the same project.</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, <literal>paint</literal> and
        <literal>calc</literal>.  Each project lives in its own
        top-level subdirectory, as shown in <xref
        linkend="svn.basic.in-action.wc.dia-1"/>.</para>


      <figure id="svn.basic.in-action.wc.dia-1">
        <title>The repository's filesystem</title>
        <graphic fileref="images/ch02dia6.png"/>
      </figure>
      
      <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/Makefile
A    calc/integer.c
A    calc/button.c
Checked out revision 56.

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

      <para>The list of letter A's in the left margin 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>
 
      <para>Suppose you make changes to <filename>button.c</filename>.
        Since the <filename>.svn</filename> directory remembers the
        file's original modification date and 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 -m "Fixed a typo in 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, with a note describing your
        change (namely, that you fixed a typo).  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
Updated to revision 57.
</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>

      <sidebar id="svn.basic.in-action.wc.sb-1">
        <title>Repository URLs</title>

        <para>Subversion repositories can be accessed through many
          different methods&mdash;on local disk, or through various
          network protocols, depending on how your administrator has
          set things up for you.  A repository location, however, is
          always a URL.
          <xref linkend="svn.basic.in-action.wc.tbl-1"/> describes how
          different URL schemes map to the available access
          methods.</para>

        <table id="svn.basic.in-action.wc.tbl-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 more information on how Subversion parses URLs, see
        <xref linkend="svn.advanced.reposurls"/>.  For more
        information on the different types of network servers
        available for Subversion, see
        <xref linkend="svn.serverconfig"/>.</para>

      </sidebar>
      
    </sect2>
    
    
    <!-- =============================================================== -->
    <sect2 id="svn.basic.in-action.revs">
      <title>Revisions</title>

      <para>An <command>svn commit</command> operation publishes
        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; then commit a complete set of changes as an
        atomic transaction.</para>

      <para>By <quote>atomic transaction</quote>, we mean simply this:
        either all of the changes happen in the repository, or none of
        them happen.  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><xref linkend="svn.basic.in-action.revs.dia-1"/> illustrates a nice way to
        visualize the repository.  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 a commit.</para>

      <figure id="svn.basic.in-action.revs.dia-1">
        <title>The repository</title>
        <graphic fileref="images/ch02dia7.png"/>
      </figure>

      <sidebar>
        <title>Global Revision Numbers</title>

        <para>Unlike most 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 Subversion users talk
          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!  Many
          other version control systems use per-file revision numbers,
          so this concept may seem unusual at first. (Former CVS users
          might want to see <xref linkend="svn.forcvs"/> 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 change 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.basic.in-action.track-repos">
      <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.  An <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 you last updated.  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 latest 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.tour.cycle.examine.status" />.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.basic.in-action.mixedrevs">
      <title>Mixed Revision Working Copies</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 files and directories with a
        mix of different working revision numbers.  Unfortunately,
        this flexibility tends to confuse a number of new users.  If
        the earlier example showing mixed revisions perplexed you,
        here's a primer on both why the feature exists and how to make
        use of it.</para>

      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
      <sect3 id="svn.basic.in-action.mixedrevs.update-commit">
        <title>Updates and Commits are Separate</title>

        <para>One of the fundamental rules of Subversion is that
          a <quote>push</quote> action does not cause
          a <quote>pull</quote>, nor the other way around.  Just
          because you're ready to submit new changes to the repository
          doesn't mean you're ready to receive changes from other
          people.  And if you have new changes still in progress,
          then <command>svn update</command> should gracefully merge
          repository changes into your own, rather than forcing you to
          publish them.</para>

        <para>The main side-effect of this rule is that it means a
          working copy has to do extra bookkeeping to track mixed
          revisions, and be tolerant of the mixture as well.  It's
          made more complicated by the fact that directories
          themselves are versioned.</para>

        <para>For example, suppose you have a working copy entirely at
          revision 10.  You edit the
          file <filename>foo.html</filename> and then perform
          an <command>svn commit</command>, which creates revision 15
          in the repository.  After the commit succeeds, many new
          users would expect the working copy to be entirely at
          revision 15, but that's not the case!  Any number of changes
          might have happened in the repository between revisions 10
          and 15.  The client knows nothing of those changes in the
          repository, since you haven't yet run <command>svn
          update</command>, and <command>svn commit</command> doesn't
          pull down new changes.  If, on the other hand,
          <command>svn commit</command> <emphasis>were</emphasis> to
          automatically download the newest changes, then it would be
          possible to set the entire working copy to revision
          15&mdash;but then we'd be breaking the fundamental rule
          of <quote>push</quote> and <quote>pull</quote> remaining
          separate actions.  Therefore the only safe thing the
          Subversion client can do is mark the one
          file&mdash;<filename>foo.html</filename>&mdash;as being at
          revision 15.  The rest of the working copy remains at
          revision 10.  Only by running <command>svn update</command>
          can the latest changes be downloaded, and the whole working
          copy be marked as revision 15.</para>


      </sect3>

      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
      <sect3 id="svn.basic.in-action.mixedrevs.normal">
        <title>Mixed revisions are normal</title>
          
        <para>The fact is, <emphasis>every time</emphasis> you run
          <command>svn commit</command>, your working copy ends up
          with some mixture of revisions.  The things you just
          committed are marked as having larger working revisions than
          everything else.  After several commits (with no updates
          in-between) your working copy will contain a whole mixture
          of revisions.  Even if you're the only person using the
          repository, you will still see this phenomenon.  To examine
          your mixture of working revisions, use the <command>svn
          status --verbose</command> command (see <xref
          linkend="svn.tour.cycle.examine.status"/> for more
          information.)</para>

        <para>Often, new users are completely unaware that their
          working copy contains mixed revisions.  This can be
          confusing, because many client commands are sensitive to the
          working revision of the item they're examining.  For
          example, the <command>svn log</command> command is used to
          display the history of changes to a file or directory (see
          <xref linkend="svn.tour.history.log"/>).  When the user
          invokes this command on a working copy object, they expect
          to see the entire history of the object.  But if the
          object's working revision is quite old (often because
          <command>svn update</command> hasn't been run in a long
          time), then the history of the <emphasis>older</emphasis>
          version of the object is shown.</para>

      </sect3>

      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
      <sect3 id="svn.basic.in-action.mixedrevs.useful">
        <title>Mixed revisions are useful</title>

        <para>If your project is sufficiently complex, you'll discover
          that it's sometimes nice to forcibly <firstterm>backdate</firstterm>
          (or, update to a revision older than the one you already
          have) portions of your working copy to an earlier revision; you'll
          learn how to do that in <xref linkend="svn.tour"/>.  Perhaps
          you'd like to test an earlier version of a sub-module
          contained in a subdirectory, or perhaps you'd like to figure
          out when a bug first came into existence in a specific file.
          This is the <quote>time machine</quote> aspect of a version
          control system&mdash;the feature which allows you to move
          any portion of your working copy forward and backward in
          history.</para>

      </sect3>

      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
      <sect3 id="svn.basic.in-action.mixedrevs.limits">
        <title>Mixed revisions have limitations</title>

        <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 <xref
          linkend="svn.advanced"/>.  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>

      </sect3>

    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.basic.summary">
    <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 <quote>copy-modify-merge</quote>
          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 move 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:
-->

Show details Hide details

Change log

r2868 by cmpilato on Aug 18, 2007 Diff

Ahem.  Consistify the tag name.

Go to:

Older revisions

r2867 by cmpilato on Aug 18, 2007 Diff

Tag the 1.4 version of the English
book.

r2859 by cmpilato on Aug 15, 2007 Diff

s/schema/scheme/ when talking about
URLs.  Fix some other uses of 'schema'
to
use more common terminology.

r2855 by cmpilato on Aug 15, 2007 Diff

Make 'backdate' into a <firstterm>,
with a concise explanation.

All revisions of this file

File info

Size: 44201 bytes, 971 lines

View raw file

File properties

svn:mime-type: text/xml
svn:eol-style: native