ch00.xml - svnbook - Project Hosting on Google Code

‹r1121

r3653

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

<preface id="svn-ch-0">
  <title>Preface</title>
  
  <simplesect>
    
    <blockquote>
      <para><quote>If C gives you enough rope to hang yourself, think
        of Subversion as a sort of rope storage facility.</quote>
        &mdash;Brian W. Fitzpatrick</para>
    </blockquote>

    <para>In the world of open-source software, the Concurrent
      Versions System (CVS) has long been the tool of choice for
      version control.  And rightly so.  CVS itself is free software,
      and its non-restrictive <foreignphrase>modus
      operandi</foreignphrase> and support for networked
      operation&mdash;which allow dozens of geographically dispersed
      programmers to share their work&mdash;fits the collaborative
      nature of the open-source world very well.  CVS and its
      semi-chaotic development model have become cornerstones of
      open-source culture.
    </para>

    <para>But like many tools, CVS is starting to show its age.
      Subversion is a relatively new version control system designed
      to be the successor to CVS.  The designers set out to win the
      hearts of CVS users in two ways: by creating an open-source
      system with a design (and <quote>look and feel</quote>) similar
      to CVS, and by attempting to fix 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.
    </para>

    <para>This book is written to document the 1.0 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 there are already a
      number of features and improvements planned for future versions
      of Subversion that may change some of the commands and specific
      notes in this book.
    </para>

  </simplesect>


  <!-- ================================================================= -->
  <!-- ======================== SECTION 1 ============================== -->
  <!-- ================================================================= -->
  <sect1 id="svn-ch-0-sect-1">

    <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.  It is that command-line tool
      (<command>svn</command>) which is discussed and used in this
      book.  For consistency, the examples in this book assume the
      reader is using a Unix-like operating system, and is relatively
      comfortable with Unix and command-line interfaces.</para>

    <para>That said, the <command>svn</command> program also runs on
      non-Unix platforms like 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.  However, Windows users may find more success
      by running the examples inside the Cygwin Unix emulation
      environment.</para>

    <para>Most readers are probably programmers or sysadmins 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: 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 version control, we've also tried to make
      it easy for users of CVS to make a painless leap into
      Subversion.  Special sidebars may discuss CVS from time to time,
      and a special appendix summarizes most of the differences
      between CVS and Subversion.</para>

  </sect1>

  <!-- ================================================================= -->
  <!-- ======================== SECTION 2 ============================== -->
  <!-- ================================================================= -->
  <sect1 id="svn-ch-0-sect-2">
    <title>How to Read this Book</title>

    <para>This book aims to be useful to people of widely different
      backgrounds&mdash;from people with no previous experience in
      version control to experienced sysadmins.  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 sysadmins</term>
        <listitem>
          <para>The assumption here is that you've probably used CVS
            before, and are dying to get a Subversion server up and
            running ASAP.  Chapters 5 and 6 will show you how to create
            your first repository and make it available over the
            network.  After that's done, chapter 3 and appendix A are
            the fastest routes to learning the Subversion client while
            drawing on your CVS experience.</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 (like CVS),
            then chapters 2 and 3 are a vital introduction.  If you're
            already an old hand at CVS, chapter 3 and appendix A are
            the best place to start.</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 branches and perform merges (chapter 4),
            how to use Subversion's property support, how to configure
            runtime options (chapter 7), and other things.  Chapters 4
            and 7 aren't vital 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.  Chapter 8 is just for you.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>The book ends with reference material&mdash;chapter 9 is a
      reference guide for all Subversion commands, and the appendices
      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>

  <!-- ================================================================= -->
  <!-- ======================== SECTION 3 ============================== -->
  <!-- ================================================================= -->
  <sect1 id="svn-ch-0-sect-3">
    <title>Conventions Used in This Book</title>
    
    <para>This section covers the various conventions used in this
      book.</para>
    
    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-0-sect3.1">
      <title>Typographic Conventions</title>
      
      <variablelist>
        
        <varlistentry>
          <term><command>Constant width</command></term>
          <listitem>
            <para>Used for commands, command output, and switches</para>
          </listitem>
        </varlistentry>

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

        <varlistentry>
          <term><filename>Italic</filename></term>
          <listitem>
            <para>Used for file and directory names</para>
          </listitem>
        </varlistentry>
        
      </variablelist>

    </sect2>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-0-sect3.2">
      <title>Icons</title>


      <note>
        <para>This icon designates a note relating to the surrounding
          text.</para>
      </note>

      <tip>
        <para>This icon designates a helpful tip relating to the surrounding
          text.</para>
      </tip>

      <warning>
        <para>This icon designates a warning relating to the surrounding
          text.</para>
      </warning>
    </sect2>

    <para>Note that the source code examples are just
      that&mdash;examples. While they will compile with the proper
      compiler incantations, they are intended to illustrate the
      problem at hand, not necessarily serve as examples of good
      programming style.</para>

  </sect1>

  <!-- ================================================================= -->
  <!-- ======================== SECTION 4 ============================== -->
  <!-- ================================================================= -->
  <sect1 id="svn-ch-0-sect-4">
    <title>Organization of This Book</title>

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

      <variablelist>
        
        <varlistentry>
          <term>Chapter 1, <emphasis>Introduction</emphasis></term>
          <listitem>
            <para>Covers the history of Subversion as well as its
              features, architecture, components, and install
              methods.  Also includes a quick-start guide.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Chapter 2, <emphasis>Basic Concepts</emphasis></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>Chapter 3, <emphasis>Guided Tour</emphasis></term>
          <listitem>
            <para>Walks you through a day in the life of a Subversion
              user.  It demonstrates how to use Subversion to obtain,
              modify, and commit data.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Chapter 4, <emphasis>Branching and Merging</emphasis></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>Chapter 5, <emphasis>Repository
            Administration</emphasis></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>Chapter 6, <emphasis>Server Configuration</emphasis></term>
          <listitem>
            <para>Explains how to configure your Subversion server and
              the three ways to access your repository:
              <literal>HTTP</literal>, the <literal>svn</literal>
              protocol, and local access.  It also covers the details
              of authentication, authorization and anonymous
              access.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Chapter 7, <emphasis>Advanced Topics</emphasis></term>
          <listitem>
            <para>Explores the Subversion client configuration files,
              file and directory properties, how to
              <literal>ignore</literal> files in your working copy,
              how to include external trees in your working copy, and
              lastly, how to handle vendor branches.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Chapter 8, <emphasis>Developer Information</emphasis></term>
          <listitem>
            <para>Describes the internals of Subversion, the
              Subversion filesystem, and the working copy
              administrative areas from a programmer's point of view.
              Demonstrates how to use the public APIs to write a
              program that uses Subversion, and most importantly, how
              to contribute to the development of Subversion.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Chapter 9, <emphasis>Subversion Complete
            Reference</emphasis></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>Appendix A, <emphasis>Subversion for CVS
            Users</emphasis></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>
              vs. <command>status</command>, branches, tags, metadata,
              conflict resolution, and authentication.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Appendix B, <emphasis>Troubleshooting</emphasis></term>
          <listitem>
            <para>Addresses common problems and difficulties using and
              building Subversion.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Appendix C, <emphasis>WebDAV and
            Autoversioning</emphasis></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>Appendix D, <emphasis>Third Party Tools</emphasis></term>
          <listitem>
            <para>Discusses tools that support or use Subversion,
              including alternative client programs, repository
              browser tools, and so on.</para>
          </listitem>
        </varlistentry>

    </variablelist>

  </sect1>

  <!-- ================================================================= -->
  <!-- ======================== SECTION 5 ============================== -->
  <!-- ================================================================= -->
  <sect1 id="svn-ch-0-sect-5">
    <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, as a part of Subversion.
      This means two things:</para>

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

      <listitem>
        <para>You can distribute and make changes to this book however
          you wish&mdash;it's under a free license.  Of course,
          rather than distribute your own private version of this
          book, we'd much rather you send feedback and patches to the
          Subversion developer community.  See <xref
          linkend="svn-ch-8-sect-6"/> to learn about joining this
          community.</para>
      </listitem>
    </itemizedlist>
    
    <para>You can send publishing comments and questions to O'Reilly
      here: ###insert boilerplate.</para>


    <para>A relatively recent online version of this book can be found
      at <systemitem
      class="url">http://svnbook.red-bean.com</systemitem>.</para>

  </sect1>

  <!-- ================================================================= -->
  <!-- ======================== SECTION 6 ============================== -->
  <!-- ================================================================= -->
  <sect1 id="svn-ch-0-sect-6">
    <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;
      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 editors, Linda Mui and Tatiana
      Diaz for their patience and support.</para>

    <para>Finally, we thank the countless people who contributed to
      this book with informal reviews, suggestions, and fixes: While
      this is undoubtedly not a complete list, this book would be
      incomplete and incorrect without the help of: Jani Averbach,
      Ryan Barrett, Francois Beausoleil, Jennifer Bevan, Matt Blais,
      Zack Brown, Martin Buchholz, Brane Cibej, John R. Daily, Peter
      Davis, Olivier Davy, Robert P. J. Day, Mo DeJong, Brian Denny,
      Joe Drew, Nick Duffek, Ben Elliston, Justin Erenkrantz, Shlomi
      Fish, Julian Foad, Chris Foote, Martin Furter, Dave Gilbert,
      Eric Gillespie, Matthew Gregan, Art Haas, Greg Hudson, Alexis
      Huxley, Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark
      Benedetto King, Andreas J. Koenig, Nuutti Kotivuori, Matt Kraai,
      Scott Lamb, Vincent Lefevre, Morten Ludvigsen, Paul Lussier,
      Bruce A. Mah, Philip Martin, Feliciano Matias, Patrick Mayweg,
      Gareth McCaughan, Jon Middleton, Tim Moloney, Mats Nilsson, Joe
      Orton, Amy Lyn Pilato, Kevin Pilch-Bisson, Dmitriy Popkov,
      Michael Price, Mark Proctor, Steffen Prohaska, Daniel Rall,
      Tobias Ringstrom, Garrett Rooney, Joel Rosdahl, Christian Sauer,
      Larry Shatzer, Russell Steicke, Sander Striker, Erik Sjoelund,
      Johan Sundstroem, John Szakmeister, Mason Thomas, Eric
      Wadsworth, Colin Watson, Alex Waugh, Chad Whitacre, Josef Wolf,
      Blair Zajac, and the entire Subversion community.</para>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-0-sect-6.1">
      <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 for their sincere
        encouragement, despite having no actual interest in the
        subject.  (You know, the ones who say, <quote>Ooh, you're
        writing 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>

    </sect2>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-0-sect-6.2">
      <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-ch-0-sect-6.3">
      <title>From C. Michael Pilato</title>

      <para>Special thanks to my wife, Amy, for her love and patient
        support, for putting up with late nights, and for even
        reviewing entire sections of this book&mdash;you always go the
        extra mile, and do so with incredible grace.  Gavin, when
        you're old enough to read, I hope you're as proud of your
        Daddy as he is of you.  Mom and Dad (and the rest of the
        family), thanks for your constant support and enthusiasm.</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&mdash;you
        <emphasis>are</emphasis> my <filename>.emacs</filename>; Greg
        Stein, for oozing practical programming know-how; Brian
        Fitzpatrick&mdash;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>
</preface>

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

Show details Hide details

Change log

r1122 by cmpilato on Feb 25, 2005 Diff

Rename tag to associate with English
version only.

Go to:

Older revisions

r1107 by sussman on Feb 23, 2005 Diff

Create 'book-1.0-final' tag.  This is
a snapshot of the last version
of the book's trunk before we started
documenting 1.1 features.

r601 by blair on May 26, 2004 Diff

Fix typos, missing words, and missing
punctuation.  Patch submitted by
Michael W Thelen <thelenm@cs.utah.edu>
.

...

r597 by sussman on May 18, 2004 Diff

Put book under a free documentation
license.

* doc/book/book/copyright.xml: switch
book's license to Creative
...

All revisions of this file

File info

Size: 22997 bytes, 540 lines

View raw file

File properties

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