ch00-preface.xml - svnbook - Version Control With Subversion

Source path: svn/ tags/ en-1.5-final/ src/ en/ book/ ch00-preface.xml

‹r3305

r4266

<preface id="svn.preface">
  <title>Preface</title>

  <blockquote>
    <attribution>Greg Hudson, Subversion developer</attribution>
    <para><quote>It is important not to let the perfect become the
      enemy of the good, even when you can agree on what perfect is.
      Doubly so when you can't.  As unpleasant as it is to be trapped by
      past mistakes, you can't make any progress by being afraid of your
      own shadow during design.</quote></para>
  </blockquote>

  <para>
    <indexterm>
      <primary>Concurrent Versions System (CVS)</primary>
    </indexterm>

    In the world of open source software, the Concurrent Versions
    System (CVS) was the tool of choice for version control for many
    years.  And rightly so.  CVS was open source software itself, and
    its nonrestrictive modus operandi and support for networked
    operation allowed dozens of geographically dispersed programmers
    to share their work.  It fit the collaborative nature of the
    open source world very well.  CVS and its semi-chaotic development
    model have since become cornerstones of open source
    culture.</para>

  <para>But CVS was not without its flaws, and simply fixing those
    flaws promised to be an enormous effort.  Enter Subversion.
    Subversion was designed to be a successor to CVS, and its originators set
    out to win the hearts of CVS users in two ways&mdash;by creating
    an open source system with a design (and <quote>look and
    feel</quote>) similar to CVS, and by attempting to avoid most of
    CVS's noticeable flaws.  While the result isn't necessarily the
    next great evolution in version control design, Subversion
    <emphasis>is</emphasis> very powerful, very usable, and very
    flexible.  And for the most part, almost all newly started
    open source projects now choose Subversion instead of CVS.</para>

  <para>This book is written to document the 1.5 series of the
    Subversion version control system.  We have made every attempt to
    be thorough in our coverage.  However, Subversion has a thriving
    and energetic development community, so already a number
    of features and improvements are planned for future versions that may
    change some of the commands and specific notes in this
    book.</para>


  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.preface.audience">

    <title>Audience</title>
    
    <para>This book is written for computer-literate folk who want to
      use Subversion to manage their data.  While Subversion runs on a
      number of different operating systems, its primary user
      interface is command-line-based.  That command-line tool
      (<command>svn</command>), and some auxiliary programs, are the
      focus of this book.</para>

    <para>For consistency, the examples in this book assume that the reader
      is using a Unix-like operating system and is relatively comfortable
      with Unix and command-line interfaces.  That said, the
      <command>svn</command> program also runs on non-Unix platforms
      such as Microsoft Windows.  With a few minor exceptions, such as
      the use of backward slashes (<literal>\</literal>) instead of
      forward slashes (<literal>/</literal>) for path separators, the
      input to and output from this tool when run on Windows are
      identical to its Unix counterpart.</para>

    <para>Most readers are probably programmers or system
      administrators who need to track changes to source code.  This
      is the most common use for Subversion, and therefore it is the
      scenario underlying all of the book's examples.  But Subversion
      can be used to manage changes to any sort of
      information&mdash;images, music, databases, documentation, and
      so on.  To Subversion, all data is just data.</para>
    
    <para>While this book is written with the assumption that the
      reader has never used a version control system, we've also tried
      to make it easy for users of CVS (and other systems) to make a
      painless leap into Subversion.  Special sidebars may mention
      other version control systems from time to time, and Appendix B
      summarizes many of the differences between CVS and
      Subversion.</para>

    <para>Note also that the source code examples used throughout the
      book are only examples.  While they will compile with the proper
      compiler incantations, they are intended to illustrate a
      particular scenario and not necessarily to serve as examples of good
      programming style or practices.</para>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.preface.howread">
    <title>How to Read This Book</title>

    <para>Technical books always face a certain dilemma: whether to
      cater to <firstterm>top-down</firstterm>
      or to <firstterm>bottom-up</firstterm> learners.  A top-down
      learner prefers to read or skim documentation, getting a large
      overview of how the system works; only then does she actually
      start using the software.  A bottom-up learner is a <quote>learn by
      doing</quote> person&mdash;someone who just wants to dive into the
      software and figure it out as she goes, referring to book
      sections when necessary.  Most books tend to be written for one
      type of person or the other, and this book is undoubtedly biased
      toward top-down learners.  (And if you're actually reading this
      section, you're probably already a top-down learner yourself!)
      However, if you're a bottom-up person, don't despair.  While the
      book may be laid out as a broad survey of Subversion topics, the
      content of each section tends to be heavy with specific
      examples that you can try-by-doing.  For the impatient folks who
      just want to get going, you can jump right to
      <xref linkend="svn.intro"/>.</para>

    <para>Regardless of your learning style, this book aims to be
      useful to people of widely different backgrounds&mdash;from
      those with no previous experience in version control to
      experienced system administrators.  Depending on your own
      background, certain chapters may be more or less important to
      you.  The following can be considered a
      <quote>recommended reading list</quote> for various types of
      readers:</para>

    <variablelist>
      <varlistentry>
        <term>Experienced system administrators</term>
        <listitem>
          <para>The assumption here is that you've probably used
            version control before and are dying to get a
            Subversion server up and running ASAP.
            <xref linkend="svn.reposadmin"/> and
            <xref linkend="svn.serverconfig"/> will show you how to
            create your first repository and make it available over
            the network.  After that's done,
            <xref linkend="svn.tour"/> and
            <xref linkend="svn.forcvs"/> are the fastest routes to
            learning the Subversion client.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>New users</term>
        <listitem>
          <para>Your administrator has probably set up Subversion
            already, and you need to learn how to use the client.  If
            you've never used a version control system, then
            <xref linkend="svn.basic"/> is a vital introduction to the
            ideas behind version control.  <xref linkend="svn.tour"/>
            is a guided tour of the Subversion client.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Advanced users</term>
        <listitem>
          <para>Whether you're a user or administrator, eventually
            your project will grow larger.  You're going to want to
            learn how to do more advanced things with Subversion, such
            as how to use Subversion's property support
            (<xref linkend="svn.advanced"/>), how to use branches and
            perform merges (<xref linkend="svn.branchmerge"/>), how to
            configure runtime options
            (<xref linkend="svn.customization"/>), and other things.
            These chapters aren't critical at first, but be sure to
            read them once you're comfortable with the basics.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Developers</term>
        <listitem>
          <para>Presumably, you're already familiar with Subversion,
            and now want to either extend it or build new software on
            top of its many APIs.  <xref linkend="svn.developer"/> is
            just for you.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>The book ends with reference material&mdash;<xref
      linkend="svn.ref"/> is a reference guide for all Subversion
      commands, and the appendixes cover a number of useful topics.
      These are the chapters you're mostly likely to come back to
      after you've finished the book.</para>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.preface.conventions">
    <title>Conventions Used in This Book</title>
        
    <para>The following typographic conventions are used in this 
      book:</para>

    <variablelist>

      <varlistentry>
        <term>
          <userinput>Constant width</userinput>
        </term>
        <listitem>
          <para>Used for literal user input, command output, and
            command-line options</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <filename>Italic</filename>
        </term>
        <listitem>
          <para>Used for program and Subversion tool subcommand
            names, file and directory names, and new terms</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <replaceable>Constant width italic</replaceable>
        </term>
        <listitem>
          <para>Used for replaceable items in code and text</para>
        </listitem>
      </varlistentry>

    </variablelist>

    <para>Also, we sprinkled especially helpful or important bits of
      information throughout the book (in contextually relevant
      locations), set off visually so they're easy to find.  Look for
      the following icons as you read:</para>

    <note>
      <para>This icon designates a special point of interest.</para>
    </note>

    <tip>
      <para>This icon designates a helpful tip or recommended best
        practice.</para> 
    </tip>

    <warning>
      <para>This icon designates a warning.  Pay close attention to
        these to avoid running into problems.</para>
    </warning>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.preface.organization">
    <title>Organization of This Book</title>

    <para>The chapters that follow and their contents are listed
      here:</para>

      <variablelist>

        <varlistentry>
          <term><xref linkend="svn.basic"/></term>
          <listitem>
            <para>Explains the basics of version control and different
              versioning models, along with Subversion's repository,
              working copies, and revisions.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.tour"/></term>
          <listitem>
            <para>Walks you through a day in the life of a Subversion
              user.  It demonstrates how to use a Subversion client to
              obtain, modify, and commit data.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.advanced"/></term>
          <listitem>
            <para>Covers more complex features that regular users will
              eventually come into contact with, such as versioned
              metadata, file locking, and peg revisions.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.branchmerge"/></term>
          <listitem>
            <para>Discusses branches, merges, and tagging, including
              best practices for branching and merging, common
              use cases, how to undo changes, and how to easily swing
              from one branch to the next.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.reposadmin"/></term>
          <listitem>
            <para>Describes the basics of the Subversion repository,
              how to create, configure, and maintain a repository, and
              the tools you can use to do all of this.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.serverconfig"/></term>
          <listitem>
            <para>Explains how to configure your Subversion server and
              offers different ways to access your repository:
              <literal>HTTP</literal>, the <literal>svn</literal>
              protocol, and local disk access.  It also covers the details
              of authentication, authorization and anonymous
              access.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.customization"/></term>
          <listitem>
            <para>Explores the Subversion client configuration files,
              the handling of internationalized text, and how to make
              external tools cooperate with Subversion.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.developer"/></term>
          <listitem>
            <para>Describes the internals of Subversion, the
              Subversion filesystem, and the working copy
              administrative areas from a programmer's point of view.
              It also demonstrates how to use the public APIs to write a
              program that uses Subversion.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.ref"/></term>
          <listitem>
            <para>Explains in great detail every subcommand of
              <command>svn</command>, <command>svnadmin</command>, and
              <command>svnlook</command> with plenty of examples for
              the whole family!</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.intro"/></term>
          <listitem>
            <para>For the impatient, a whirlwind explanation of how to
              install Subversion and start using it immediately.  You
              have been warned.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.forcvs"/></term>
          <listitem>
            <para>Covers the similarities and differences between
              Subversion and CVS, with numerous suggestions on how to
              break all the bad habits you picked up from years of
              using CVS.  Included are descriptions of Subversion
              revision numbers, versioned directories, offline
              operations, <command>update</command>
              versus <command>status</command>, branches, tags, metadata,
              conflict resolution, and authentication.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.webdav"/></term>
          <listitem>
            <para>Describes the details of WebDAV and DeltaV and how
              you can configure your Subversion repository to be
              mounted read/write as a DAV share.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><xref linkend="svn.copyright"/></term>
          <listitem>
            <para>A copy of the Creative Commons Attribution License,
              under which this book is licensed.</para>
          </listitem>
        </varlistentry>

    </variablelist>

  </sect1>


  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.preface.free">
    <title>This Book Is Free</title>

    <para>This book started out as bits of documentation written by
      Subversion project developers, which were then coalesced into a
      single work and rewritten.  As such, it has always been under a
      free license (see <xref linkend="svn.copyright"/>).  In fact,
      the book was written in the public eye, originally as part of
      the Subversion project itself.  This means two things:</para>

    <itemizedlist>
      <listitem>
        <para>You will always find the latest version of this book in
          the book's own Subversion repository.</para>
      </listitem>

      <listitem>
        <para>You can make changes to this book and redistribute it
          however you wish&mdash;it's under a free license.  Your only
          obligation is to maintain proper attribution to the original
          authors.  Of course, we'd much rather you send feedback and
          patches to the Subversion developer community, instead of 
          distributing your private version of this book.</para>
      </listitem>
    </itemizedlist>
    
    <!-- O'REILLY SHOULD TWEAK THIS PARAGRAPH -->
    <para>The online home of this book's development and most of the
      volunteer-driven translation efforts regarding it is
      <ulink url="http://svnbook.red-bean.com"/>.  There you can find
      links to the latest releases and tagged versions of the book in
      various formats, as well as instructions for accessing the
      book's Subversion repository (where its DocBook XML source
      code lives).  Feedback is welcomed&mdash;encouraged, even.  Please
      submit all comments, complaints, and patches against the book
      sources to <email>svnbook-dev@red-bean.com</email>.</para>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.preface.acks">
    <title>Acknowledgments</title>

    <para>This book would not be possible (nor very useful) if
      Subversion did not exist.  For that, the authors would like to
      thank Brian Behlendorf and CollabNet for the vision to fund such
      a risky and ambitious new open source project; Jim Blandy for
      the original Subversion name and design&mdash;we love you, Jim;
      and Karl Fogel for being such a good friend and a great
      community leader, in that order.
      <footnote>
        <para>Oh, and thanks, Karl, for being too overworked to write
          this book yourself.</para>
      </footnote>
    </para>

    <para>Thanks to O'Reilly and our various editors: Chuck Toporek, Linda
      Mui, Tatiana Apandi, Mary Brady, and Mary Treseler.  Their patience and support
      has been tremendous.</para>

    <para>Finally, we thank the countless people who contributed to
      this book with informal reviews, suggestions, and patches.
      While this is undoubtedly not a complete list, this book would
      be incomplete and incorrect without their help: 

      Bhuvaneswaran A,
      David Alber,
      C. Scott Ananian,
      David Anderson,
      Ariel Arjona,
      Seth Arnold,
      Jani Averbach,
      Charles Bailey,
      Ryan Barrett,
      Francois Beausoleil,
      Brian R. Becker,
      Yves Bergeron,
      Karl Berry,
      Jennifer Bevan,
      Matt Blais,
      Jim Blandy,
      Phil Bordelon,
      Sietse Brouwer,
      Tom Brown,
      Zack Brown,
      Martin Buchholz,
      Paul Burba,
      Sean Callan-Hinsvark,
      Branko Cibej,
      Archie Cobbs,
      Jason Cohen,
      Ryan Cresawn,
      John R. Daily,
      Peter Davis,
      Olivier Davy,
      Robert P. J. Day,
      Mo DeJong,
      Brian Denny,
      Joe Drew,
      Markus Dreyer,
      Nick Duffek,
      Boris Dusek,
      Ben Elliston,
      Justin Erenkrantz,
      Jens M. Felderhoff,
      Kyle Ferrio,
      Shlomi Fish,
      Julian Foad,
      Chris Foote,
      Martin Furter,
      Vlad Georgescu,
      Peter Gervai,
      Dave Gilbert,
      Eric Gillespie,
      David Glasser,
      Marcel Gosselin,
      Lieven Govaerts,
      Steve Greenland,
      Matthew Gregan,
      Tom Gregory,
      Maverick Grey,
      Art Haas,
      Mark E. Hamilton,
      Eric Hanchrow,
      Liam Healy,
      Malte Helmert,
      Michael Henderson,
      Øyvind A. Holm,
      Greg Hudson,
      Alexis Huxley,
      Auke Jilderda,
      Toby Johnson,
      Jens B. Jorgensen,
      Tez Kamihira,
      David Kimdon,
      Mark Benedetto King,
      Robert Kleemann,
      Erik Kline,
      Josh Knowles,
      Andreas J. Koenig,
      Axel Kollmorgen,
      Nuutti Kotivuori,
      Kalin Kozhuharov,
      Matt Kraai,
      Regis Kuckaertz,
      Stefan Kueng,
      Steve Kunkee,
      Scott Lamb,
      Wesley J. Landaker,
      Benjamin Landsteiner,
      Vincent Lefevre,
      Morten Ludvigsen,
      Dennis Lundberg,
      Paul Lussier,
      Bruce A. Mah,
      Jonathon Mah,
      Karl Heinz Marbaise,
      Philip Martin,
      Feliciano Matias,
      Neil Mayhew,
      Patrick Mayweg,
      Gareth McCaughan,
      Craig McElroy,
      Simon McKenna,
      Christophe Meresse,
      Jonathan Metillon,
      Jean-Francois Michaud,
      Jon Middleton,
      Robert Moerland,
      Marcel Molina Jr.,
      Tim Moloney,
      Alexander Mueller,
      Tabish Mustufa,
      Christopher Ness,
      Roman Neuhauser,
      Mats Nilsson,
      Greg Noel,
      Joe Orton,
      Eric Paire,
      Dimitri Papadopoulos-Orfanos,
      Jerry Peek,
      Chris Pepper,
      Amy Lyn Pilato,
      Kevin Pilch-Bisson,
      Hans Polak,
      Dmitriy Popkov,
      Michael Price,
      Mark Proctor,
      Steffen Prohaska,
      Daniel Rall,
      Srinivasa Ramanujan,
      Jack Repenning,
      Tobias Ringstrom,
      Jason Robbins,
      Garrett Rooney,
      Joel Rosdahl,
      Christian Sauer,
      Ryan Schmidt,
      Jochem Schulenklopper,
      Jens Seidel,
      Daniel Shahaf,
      Larry Shatzer,
      Danil Shopyrin,
      Erik Sjoelund,
      Joey Smith,
      W. Snyder,
      Stefan Sperling,
      Robert Spier,
      M. S. Sriram,
      Russell Steicke,
      David Steinbrunner,
      Sander Striker,
      David Summers,
      Johan Sundstroem,
      Ed Swierk,
      John Szakmeister,
      Arfrever Frehtes Taifersar Arahesis,
      Robert Tasarz,
      Michael W. Thelen,
      Mason Thomas,
      Erik van der Kolk,
      Joshua Varner,
      Eric Wadsworth,
      Chris Wagner,
      Colin Watson,
      Alex Waugh,
      Chad Whitacre,
      Andy Whitcroft,
      Josef Wolf,
      Luke Worth,
      Hyrum Wright,
      Blair Zajac,
      Florian Zumbiehl,

      and the entire Subversion community.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.preface.acks.sussman">
      <title>From Ben Collins-Sussman</title>

      <para>Thanks to my wife Frances, who, for many months, got to
        hear <quote>But honey, I'm still working on the book,</quote>
        rather than the usual <quote>But honey, I'm still doing
        email.</quote>  I don't know where she gets all that patience!
        She's my perfect counterbalance.</para>

      <para>Thanks to my extended family and friends for their sincere
        encouragement, despite having no actual interest in the
        subject.  (You know, the ones who say, <quote>Ooh, you wrote a
        book?</quote> and then when you tell them it's a computer
        book, sort of glaze over.)</para>

      <para>Thanks to all my close friends, who make me a rich, rich man.
        Don't look at me that way&mdash;you know who you are.</para>

      <para>Thanks to my parents for the perfect low-level formatting
        and being unbelievable role models.  Thanks to my kids for the
        opportunity to pass that on.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.preface.acks.fitz">
      <title>From Brian W. Fitzpatrick</title>

      <para>Huge thanks to my wife Marie for being incredibly
        understanding, supportive, and most of all, patient.  Thank
        you to my brother Eric who first introduced me to Unix
        programming way back when.  Thanks to my Mom and Grandmother
        for all their support, not to mention enduring a Christmas
        holiday where I came home and promptly buried my head in my
        laptop to work on the book.</para>

      <para>To Mike and Ben:  it was a pleasure working with you on the
        book.  Heck, it's a pleasure working with you at work!</para>

      <para>To everyone in the Subversion community and the Apache
        Software Foundation, thanks for having me.  Not a day goes by
        where I don't learn something from at least one of you.
      </para>

      <para>Lastly, thanks to my grandfather, who always told me that
        <quote>freedom equals responsibility.</quote> I couldn't agree
        more.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.preface.acks.cmpilato">
      <title>From C. Michael Pilato</title>

      <para>Special thanks to Amy, my best friend and wife of more than
        ten incredible years, for her love and patient support, for
        putting up with the late nights, and for graciously enduring
        the version control processes I've imposed on her.  Don't
        worry, sweetheart&mdash;you'll be a TortoiseSVN wizard in no
        time!</para>

      <para>Gavin, you're able to read half of the words in this book
        yourself now; sadly, it's the other half that provide the key
        concepts.  And sorry, Aidan &mdash; I couldn't find a way to
        work Disney/Pixar characters into the text.  But Daddy loves
        you both, and can't wait to teach you about programming.</para>

      <para>Mom and Dad, thanks for your constant support and
        enthusiasm.  Mom- and Dad-in-law, thanks for all of the same
        <emphasis>plus</emphasis> your fabulous daughter.</para>

      <para>Hats off to Shep Kendall, through whom the world of
        computers was first opened to me; Ben Collins-Sussman, my
        tour guide through the open source world; Karl Fogel, you
        <emphasis>are</emphasis> my <filename>.emacs</filename>; Greg
        Stein, for oozing practical programming know-how; and Brian
        Fitzpatrick, for sharing this writing experience with me.
        To the many folks from whom I am constantly picking up new
        knowledge&mdash;keep dropping it!</para>

      <para>Finally, to the One who perfectly demonstrates creative
        excellence&mdash;thank You.</para>

    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.intro.whatis">

    <title>What Is Subversion?</title>
      
    <para>Subversion is a free/open source version control system.
      That is, Subversion manages files and directories, and the
      changes made to them, over time.  This allows you to recover
      older versions of your data or examine the history of how your
      data changed.  In this regard, many people think of a version
      control system as a sort of <quote>time machine.</quote></para>
    
    <para>Subversion can operate across networks, which allows it to
      be used by people on different computers.  At some level, the
      ability for various people to modify and manage the same set of
      data from their respective locations fosters collaboration.
      Progress can occur more quickly without a single conduit through
      which all modifications must occur.  And because the work is
      versioned, you need not fear that quality is the trade-off for
      losing that conduit&mdash;if some incorrect change is made to
      the data, just undo that change.</para>

    <para>Some version control systems are also software configuration
      management (SCM) systems.  These systems are specifically
      tailored to manage trees of source code and have many features
      that are specific to software development&mdash;such as natively
      understanding programming languages, or supplying tools for
      building software.  Subversion, however, is not one of these
      systems.  It is a general system that can be used to manage
      <emphasis>any</emphasis> collection of files.  For you, those
      files might be source code&mdash;for others, anything from
      grocery shopping lists to digital video mixdowns and
      beyond.</para>


    <!-- =============================================================== -->
    <sect2 id="svn.intro.righttool">
  
      <title>Is Subversion the Right Tool?</title>
  
      <para>If you're a user or system administrator pondering the use
        of Subversion, the first question you should ask yourself is:
        "Is this the right tool for the job?"  Subversion is a
        fantastic hammer, but be careful not to view every problem as
        a nail.</para>

      <para>If you need to archive old versions of files and
        directories, possibly resurrect them, or examine logs of how
        they've changed over time, then Subversion is exactly the
        right tool for you.  If you need to collaborate with people on
        documents (usually over a network) and keep track of who made
        which changes, then Subversion is also appropriate.  This is
        why Subversion is so often used in software development
        environments&mdash; working on a development team is an inherently social
        activity, and Subversion makes it easy to collaborate with
        other programmers.  Of course, there's a cost to using
        Subversion as well: administrative overhead.  You'll need to
        manage a data repository to store the information and all its
        history, and be diligent about backing it up.  When working
        with the data on a daily basis, you won't be able to copy,
        move, rename, or delete files the way you usually do.
        Instead, you'll have to do all of those things through
        Subversion.</para>

      <para>Assuming you're fine with the extra workflow, you should
        still make sure you're not using Subversion to solve a problem
        that other tools solve better.  For example, because
        Subversion replicates data to all the collaborators involved,
        a common misuse is to treat it as a generic distribution
        system.  People will sometimes use Subversion to distribute
        huge collections of photos, digital music, or software
        packages.  The problem is that this sort of data usually isn't
        changing at all.  The collection itself grows over time, but
        the individual files within the collection aren't being
        changed.  In this case, using Subversion
        is <quote>overkill.</quote>
        <footnote>
          <para>Or as a friend puts it, <quote>swatting a fly with a
            Buick.</quote></para>
        </footnote> 
        There are simpler tools that
        efficiently replicate data <emphasis>without</emphasis> the
        overhead of tracking changes, such as <command>rsync</command>
        or <command>unison</command>.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.intro.history">
  
      <title>Subversion's History</title>
  
      <para>
        <indexterm>
          <primary>Subversion</primary>
          <secondary>history of</secondary>
        </indexterm>

        In early 2000, CollabNet, Inc. (<ulink
        url="http://www.collab.net"/>) began seeking developers to
        write a replacement for CVS.  CollabNet offers a collaboration
        software suite called CollabNet Enterprise Edition (CEE), of
        which one component is version control.  Although CEE used CVS
        as its initial version control system, CVS's limitations were
        obvious from the beginning, and CollabNet knew it would
        eventually have to find something better.  Unfortunately, CVS
        had become the de facto standard in the open source world
        largely because there <emphasis>wasn't</emphasis> anything
        better, at least not under a free license.  So CollabNet
        determined to write a new version control system from scratch,
        retaining the basic ideas of CVS, but without the bugs and
        misfeatures.</para>
  
      <para>In February 2000, they contacted Karl Fogel, the author of
        <citetitle>Open Source Development with CVS</citetitle>
        (Coriolis, 1999), and asked if he'd like to work on this new
        project.  Coincidentally, at the time Karl was already
        discussing a design for a new version control system with his
        friend Jim Blandy.  In 1995, the two had started Cyclic
        Software, a company providing CVS support contracts, and
        although they later sold the business, they still used CVS every
        day at their jobs.  Their frustration with CVS had led Jim to
        think carefully about better ways to manage versioned data, and
        he'd already come up with not only the name
        <quote>Subversion,</quote> but also the basic design of
        the Subversion data store.  When CollabNet called, Karl
        immediately agreed to work on the project, and Jim got his
        employer, Red Hat Software, to essentially donate him to the
        project for an indefinite period of time.  CollabNet hired
        Karl and Ben Collins-Sussman, and detailed design work began
        in May 2000.  With the help of some well-placed prods from
        Brian Behlendorf and Jason Robbins of CollabNet, and from Greg
        Stein (at the time an independent developer active in the
        WebDAV/DeltaV specification process), Subversion quickly
        attracted a community of active developers.  It turned out
        that many people had encountered the same frustrating
        experiences with CVS and welcomed the chance to finally do
        something about it.</para>
  
      <para>The original design team settled on some simple goals.  They
        didn't want to break new ground in version control methodology,
        they just wanted to fix CVS.  They decided that Subversion would
        match CVS's features and preserve the same development model,
        but not duplicate CVS's most obvious flaws.  And although it did
        not need to be a drop-in replacement for CVS, it should be
        similar enough that any CVS user could make the switch with
        little effort.</para>
  
      <para>After 14 months of coding, Subversion became
        <quote>self-hosting</quote> on August 31, 2001.  That is,
        Subversion developers stopped using CVS to manage Subversion's
        own source code and started using Subversion instead.</para>
  
      <para>While CollabNet started the project, and still funds a large
        chunk of the work (it pays the salaries of a few full-time
        Subversion developers), Subversion is run like most open source
        projects, governed by a loose, transparent set of rules that
        encourage meritocracy.  CollabNet's copyright license is fully
        compliant with the Debian Free Software Guidelines.  In other
        words, anyone is free to download, modify, and redistribute
        Subversion as he pleases; no permission from CollabNet or anyone
        else is required.</para>
  
    </sect2>
  
    <!-- =============================================================== -->
    <sect2 id="svn.intro.architecture">
  
      <title>Subversion's Architecture</title>
  
      <para><xref linkend="svn.intro.architecture.dia-1"/> illustrates
        a <quote>mile-high</quote> view of Subversion's
        design.</para>
      
      <figure id="svn.intro.architecture.dia-1">
        <title>Subversion's architecture</title>
        <graphic fileref="images/ch01dia1.png"/>
      </figure>
  
      <para>On one end is a Subversion repository that holds all of your
        versioned data.  On the other end is your Subversion client
        program, which manages local reflections of portions of that
        versioned data (called <quote>working copies</quote>).  Between
        these extremes are multiple routes through various Repository
        Access (RA) layers.  Some of these routes go across computer
        networks and through network servers which then access the
        repository.  Others bypass the network altogether and access the
        repository directly.</para>
  
    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.intro.components">
  
      <title>Subversion's Components</title>
      
      <para>Subversion, once installed, has a number of different
        pieces.  The following is a quick overview of what you get.
        Don't be alarmed if the brief descriptions leave you scratching
        your head&mdash;<emphasis>plenty</emphasis> more pages
        in this book are devoted to alleviating that confusion.</para>
  
      <variablelist>
        <varlistentry>
          <term>svn</term>
          <listitem>
            <para>The command-line client program</para>
          </listitem>
        </varlistentry>
  
        <varlistentry>
          <term>svnversion</term>
          <listitem>
            <para>A program for reporting the state (in terms of
              revisions of the items present) of a working copy</para>
          </listitem>
        </varlistentry>
  
        <varlistentry>
          <term>svnlook</term>
          <listitem>
            <para>A tool for directly inspecting a Subversion repository</para>
          </listitem>
        </varlistentry>
  
        <varlistentry>
          <term>svnadmin</term>
          <listitem>
            <para>A tool for creating, tweaking, or repairing a Subversion
              repository</para>
          </listitem>
        </varlistentry>
  
        <varlistentry>
          <term>mod_dav_svn</term>
          <listitem>
            <para>A plug-in module for the Apache HTTP Server, used to
              make your repository available to others over a
              network</para>
          </listitem>
        </varlistentry>
  
        <varlistentry>
          <term>svnserve</term>
          <listitem>
            <para>A custom standalone server program, runnable as a
              daemon process or invokable by SSH; another way to make
              your repository available to others over a network.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>svndumpfilter</term>
          <listitem>
            <para>A program for filtering Subversion repository dump
              streams</para>
          </listitem>
        </varlistentry>
  
        <varlistentry>
          <term>svnsync</term>
          <listitem>
            <para>A program for incrementally mirroring one
            repository to another over a network</para>
          </listitem>
        </varlistentry>

      </variablelist>

    </sect2>

  <!-- =============================================================== -->
    <sect2 id="svn.intro.whatsnew">

      <title>What's New in Subversion</title>

      <para>The first edition of this book was released in 2004,
        shortly after Subversion had reached 1.0.  Over the following
        four years Subversion released five major new versions, fixing
        bugs and adding major new features.  While we've managed to
        keep the online version of this book up to date, we're
        thrilled that the second edition from O'Reilly now covers
        Subversion up through release 1.5, a major milestone for the
        project.  Here's a quick summary of major new changes since
        Subversion 1.0.  Note that this is not a complete list; for
        full details, please visit Subversion's web site at
        <ulink url="http://subversion.tigris.org"/>.</para>

      <variablelist>

        <varlistentry>
          <term>Subversion 1.1 (September 2004)</term>
          <listitem>
            <para>Release 1.1 introduced FSFS, a flat-file repository
              storage option for the repository.  While the Berkeley DB
              backend is still widely used and supported, FSFS has
              since become the default choice for
              newly created repositories due to its low barrier to
              entry and minimal maintenance requirements.  Also in
              this release came the ability to put symbolic links
              under version control, auto-escaping of URLs, and a
              localized user interface.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Subversion 1.2 (May 2005)</term>
          <listitem>
            <para>Release 1.2 introduced the ability to create
              server-side locks on files, thus serializing commit
              access to certain resources.  While Subversion is still
              a fundamentally concurrent version control system,
              certain types of binary files (e.g. art assets)
              cannot be merged together.  The locking feature fulfills
              the need to version and protect such resources.  With
              locking also came a complete WebDAV auto-versioning
              implementation, allowing Subversion repositories to be
              mounted as network folders.  Finally, Subversion 1.2
              began using a new, faster binary-differencing algorithm
              to compress and retrieve old versions of files.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Subversion 1.3 (December 2005)</term>
          <listitem>
            <para>Release 1.3 brought path-based authorization
              controls to the <command>svnserve</command> server,
              matching a feature formerly found only in the Apache
              server.  The Apache server, however, gained some new
              logging features of its own, and Subversion's API
              bindings to other languages also made great leaps
              forward.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Subversion 1.4 (September 2006)</term>
          <listitem>
            <para>Release 1.4 introduced a whole new
              tool&mdash;<command>svnsync</command>&mdash;for doing
              one-way repository replication over a network.  Major
              parts of the working copy metadata were revamped to no
              longer use XML (resulting in client-side speed gains),
              while the Berkeley DB repository backend gained the
              ability to automatically recover itself after a server
              crash.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Subversion 1.5 (June 2008)</term>
          <listitem>
            <para>Release 1.5 took much longer to finish than prior
              releases, but the headliner feature was gigantic:
              semi-automated tracking of branching and merging.  This
              was a huge boon for users, and pushed Subversion far
              beyond the abilities of CVS and into the ranks of
              commercial competitors such as Perforce and ClearCase.
              Subversion 1.5 also introduced a bevy of other
              user-focused features, such as interactive resolution of
              file conflicts, partial checkouts, client-side
              management of changelists, powerful new syntax for
              externals definitions, and SASL authentication support for
              the <command>svnserve</command> server.</para>
          </listitem>
        </varlistentry>

      </variablelist>

    </sect2>

  </sect1>

</preface>

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

Show details Hide details

Change log

r3306 by cmpilato on Sep 15, 2008 Diff

Tag 1.5 version of the English book (also
known "Version Control With
Subversion, second edition", or "ISBN 10:
0-596-51033-0", or "ISBN 13:
9780596510336", or "Pilato's Bane", or
...)

Go to:

Older revisions

r3301 by cmpilato on Sep 12, 2008 Diff

* src/en/book/ch00-preface.xml,
* src/en/book/ch03-advanced-
topics.xml,
* src/en/book/ch05-repository-
admin.xml,
...

r3287 by cmpilato on Sep 3, 2008 Diff

Minor fixes.  Patch by Øyvind A. Holm
<sunny {at} sunbase.org>.

* src/en/book/appc-webdav.xml
  Refer to Adobe as the producer of
...

r3266 by sussman on Aug 11, 2008 Diff

ch00-preface.xml:  add one more name
to acknowledgements.

All revisions of this file

File info

Size: 45342 bytes, 1113 lines

View raw file

File properties

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