Commits

Anonymous committed 5bb9538

Removed svn-design.

Comments (0)

Files changed (4)

vipe/svn-design/index.html

-<HTML>
-<HEAD>
-<!-- Created by texi2html 1.56k from svn-design.texi on 25 October 2002 -->
-
-<TITLE>Subversion Design - Table of Contents</TITLE>
-</HEAD>
-<BODY>
-<H1>Subversion</H1>
-<ADDRESS>Jim Blandy &#60;<A HREF="mailto:<A HREF="mailto:jimb@redhat.com">jimb@redhat.com</A>"><A HREF="mailto:jimb@redhat.com">jimb@redhat.com</A></A>&#62;</ADDRESS>
-<ADDRESS>Karl Fogel &#60;<A HREF="mailto:<A HREF="mailto:kfogel@collab.net">kfogel@collab.net</A>"><A HREF="mailto:kfogel@collab.net">kfogel@collab.net</A></A>&#62;</ADDRESS>
-<ADDRESS>Ben Collins-Sussman &#60;<A HREF="mailto:<A HREF="mailto:sussman@collab.net">sussman@collab.net</A>"><A HREF="mailto:sussman@collab.net">sussman@collab.net</A></A>&#62;</ADDRESS>
-<P>
-<P><HR><P>
-<UL>
-<LI><A NAME="TOC1" HREF="svn-design.html#SEC1">Goals</A>
-<UL>
-<LI><A NAME="TOC2" HREF="svn-design.html#SEC2">Rename/removal/resurrection support</A>
-<LI><A NAME="TOC3" HREF="svn-design.html#SEC3">Text vs binary issues</A>
-<LI><A NAME="TOC4" HREF="svn-design.html#SEC4">I18N/Multilingual support</A>
-<LI><A NAME="TOC5" HREF="svn-design.html#SEC5">Branching and tagging</A>
-<LI><A NAME="TOC6" HREF="svn-design.html#SEC6">Miscellaneous new behaviors</A>
-<UL>
-<LI><A NAME="TOC7" HREF="svn-design.html#SEC7">Log messages</A>
-<LI><A NAME="TOC8" HREF="svn-design.html#SEC8">Client side diff plug-ins</A>
-<LI><A NAME="TOC9" HREF="svn-design.html#SEC9">Better merging</A>
-<LI><A NAME="TOC10" HREF="svn-design.html#SEC10">Conflicts resolution</A>
-</UL>
-</UL>
-<LI><A NAME="TOC11" HREF="svn-design.html#SEC11">Model</A>
-<UL>
-<LI><A NAME="TOC12" HREF="svn-design.html#SEC12">Working Directories and Repositories</A>
-<LI><A NAME="TOC13" HREF="svn-design.html#SEC13">Transactions and Revision Numbers</A>
-<LI><A NAME="TOC14" HREF="svn-design.html#SEC14">How Working Directories Track the Repository</A>
-<LI><A NAME="TOC15" HREF="svn-design.html#SEC15">Subversion Does Not Lock Files</A>
-<LI><A NAME="TOC16" HREF="svn-design.html#SEC16">Properties</A>
-<LI><A NAME="TOC17" HREF="svn-design.html#SEC17">Merging and Ancestry</A>
-</UL>
-<LI><A NAME="TOC18" HREF="svn-design.html#SEC18">Architecture</A>
-<UL>
-<LI><A NAME="TOC19" HREF="svn-design.html#SEC19">Client Layer</A>
-<LI><A NAME="TOC20" HREF="svn-design.html#SEC20">Network Layer</A>
-<LI><A NAME="TOC21" HREF="svn-design.html#SEC21">Filesystem Layer</A>
-</UL>
-<LI><A NAME="TOC22" HREF="svn-design.html#SEC22">Deltas</A>
-<UL>
-<LI><A NAME="TOC23" HREF="svn-design.html#SEC23">Text Deltas</A>
-<LI><A NAME="TOC24" HREF="svn-design.html#SEC24">Property Deltas</A>
-<LI><A NAME="TOC25" HREF="svn-design.html#SEC25">Tree Deltas</A>
-<LI><A NAME="TOC26" HREF="svn-design.html#SEC26">Postfix Text Deltas</A>
-<LI><A NAME="TOC27" HREF="svn-design.html#SEC27">Serializing Deltas via the "Editor" Interface</A>
-</UL>
-<LI><A NAME="TOC28" HREF="svn-design.html#SEC28">Client</A>
-<UL>
-<LI><A NAME="TOC29" HREF="svn-design.html#SEC29">Working copies and the working copy library</A>
-<UL>
-<LI><A NAME="TOC30" HREF="svn-design.html#SEC30">The layout of working copies</A>
-<LI><A NAME="TOC31" HREF="svn-design.html#SEC31">The working copy management library</A>
-</UL>
-<LI><A NAME="TOC32" HREF="svn-design.html#SEC32">The repository access library</A>
-<LI><A NAME="TOC33" HREF="svn-design.html#SEC33">The client operation library</A>
-</UL>
-<LI><A NAME="TOC34" HREF="svn-design.html#SEC34">Protocol</A>
-<LI><A NAME="TOC35" HREF="svn-design.html#SEC35">Server</A>
-<UL>
-<LI><A NAME="TOC36" HREF="svn-design.html#SEC36">Filesystem</A>
-<UL>
-<LI><A NAME="TOC37" HREF="svn-design.html#SEC37">Filesystem Overview</A>
-<LI><A NAME="TOC38" HREF="svn-design.html#SEC38">API</A>
-<LI><A NAME="TOC39" HREF="svn-design.html#SEC39">Repository Structure</A>
-<UL>
-<LI><A NAME="TOC40" HREF="svn-design.html#SEC40">Schema</A>
-<LI><A NAME="TOC41" HREF="svn-design.html#SEC41">Bubble-Up Method</A>
-<LI><A NAME="TOC42" HREF="svn-design.html#SEC42">Diffy Storage</A>
-</UL>
-<LI><A NAME="TOC43" HREF="svn-design.html#SEC43">Implementation</A>
-</UL>
-<LI><A NAME="TOC44" HREF="svn-design.html#SEC44">Repository Library</A>
-</UL>
-<LI><A NAME="TOC45" HREF="svn-design.html#SEC45">Future</A>
-<UL>
-<LI><A NAME="TOC46" HREF="svn-design.html#SEC46">High Priority Items</A>
-<UL>
-<LI><A NAME="TOC47" HREF="svn-design.html#SEC47">Annotation</A>
-<LI><A NAME="TOC48" HREF="svn-design.html#SEC48">Repository Conversion</A>
-</UL>
-<LI><A NAME="TOC49" HREF="svn-design.html#SEC49">Blue Sky Items</A>
-<UL>
-<LI><A NAME="TOC50" HREF="svn-design.html#SEC50">Server Grep</A>
-<LI><A NAME="TOC51" HREF="svn-design.html#SEC51">Scripting Language</A>
-<LI><A NAME="TOC52" HREF="svn-design.html#SEC52">Smart conflict resolution</A>
-<LI><A NAME="TOC53" HREF="svn-design.html#SEC53">Mirroring Servers</A>
-<LI><A NAME="TOC54" HREF="svn-design.html#SEC54">Inter-Repository Communication</A>
-<LI><A NAME="TOC55" HREF="svn-design.html#SEC55">SQL Back-End</A>
-<LI><A NAME="TOC56" HREF="svn-design.html#SEC56">Digital Signatures</A>
-<LI><A NAME="TOC57" HREF="svn-design.html#SEC57">SMTP access</A>
-</UL>
-</UL>
-<LI><A NAME="TOC58" HREF="svn-design.html#SEC58">License</A>
-</UL>
-<P><HR><P>
-This document was generated on 25 October 2002 using
-<A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>&nbsp;1.56k.
-</BODY>
-</HTML>

vipe/svn-design/svn-design.html

-<HTML>
-<HEAD>
-<!-- Created by texi2html 1.56k from svn-design.texi on 25 October 2002 -->
-
-<TITLE>Subversion Design</TITLE>
-</HEAD>
-<BODY>
-<H1>Subversion</H1>
-<ADDRESS>Jim Blandy &#60;<A HREF="mailto:<A HREF="mailto:jimb@redhat.com">jimb@redhat.com</A>"><A HREF="mailto:jimb@redhat.com">jimb@redhat.com</A></A>&#62;</ADDRESS>
-<ADDRESS>Karl Fogel &#60;<A HREF="mailto:<A HREF="mailto:kfogel@collab.net">kfogel@collab.net</A>"><A HREF="mailto:kfogel@collab.net">kfogel@collab.net</A></A>&#62;</ADDRESS>
-<ADDRESS>Ben Collins-Sussman &#60;<A HREF="mailto:<A HREF="mailto:sussman@collab.net">sussman@collab.net</A>"><A HREF="mailto:sussman@collab.net">sussman@collab.net</A></A>&#62;</ADDRESS>
-<P>
-<P><HR><P>
-
-
-<H1><A NAME="SEC1" HREF="svn-design_toc.html#TOC1">Goals</A></H1>
-
-<P>
-The goal of the Subversion project is to write a version control system
-that takes over CVS's current and future user base <A NAME="DOCF1" HREF="svn-design_foot.html#FOOT1">(1)</A>. The first release has all the major features of CVS, plus
-certain new features that CVS users often wish they had.  In general,
-Subversion works like CVS, except where there's a compelling reason to
-be different.
-
-
-<P>
-So what does Subversion have that CVS doesn't?
-
-
-
-<UL>
-<LI>
-
-It versions directories, file-metadata, renames, copies and
-removals/resurrections.  In other words, Subversion records the changes
-users make to directory trees, not just changes to file contents.
-
-<LI>
-
-Tagging and branching are constant-time and constant-space.
-
-<LI>
-
-It is natively client-server, hence much more maintainable than CVS.
-(In CVS, the client-server protocol was added as an afterthought.
-This means that most new features have to be implemented twice, or at
-least more than once: code for the local case, and code for the
-client-server case.)
-
-<LI>
-
-The repository is organized efficiently and comprehensibly.  (Without
-going into too much detail, let's just say that CVS's repository
-structure is showing its age.)
-
-<LI>
-
-Commits are atomic.  Each commit results in a single revision number,
-which refers to the state of the entire tree.  Files no longer have
-their own revision numbers.
-
-<LI>
-
-The locking scheme is only as strict as absolutely necessary.
-Reads are never locked, and writes lock only the files being
-written, for only as long as needed.
-
-<LI>
-
-It has internationalization support.
-
-<LI>
-
-It handles binary files gracefully (experience has shown that CVS's
-binary file handling is prone to user error).
-
-<LI>
-
-It takes advantage of the Net's experience with CVS by choosing better
-default behaviors for certain situations.
-
-</UL>
-
-<P>
-Some of these advantages are clear and require no further discussion.
-Others are not so obvious, and are explained in greater detail below.
-
-
-
-
-<H2><A NAME="SEC2" HREF="svn-design_toc.html#TOC2">Rename/removal/resurrection support</A></H2>
-
-<P>
-Full rename support means you can trace through ancestry by name
-<EM>or</EM> by entity.  For example, if you say "Give me revision 12 of
-foo.c", do you mean revision 12 of the file whose name is <EM>now</EM>
-foo.c (but perhaps it was named bar.c back at revision 12), or the file
-whose name was foo.c in revision 12 (perhaps that file no longer exists,
-or has a different name now)?  In Subversion, both interpretations are
-available to the user.
-
-
-<P>
-(Note:  we've not yet implemented this, but it wouldn't be too hard.
-People are advocating switches to 'svn log' that cause history to be
-traced backwards either by entity or by path.)
-
-
-
-
-<H2><A NAME="SEC3" HREF="svn-design_toc.html#TOC3">Text vs binary issues</A></H2>
-
-<P>
-Historically, binary files have been problematic in CVS for two
-unrelated reasons: keyword expansion, and line-end conversion.
-<BR>
-
-<UL>
-<LI>
-
-<EM>Keyword expansion</EM> is when CVS expands "$Revision: 1.1 $" into "$Revision
-1.1$", for example.  There are a number of keywords in CVS: "$Author: sussman $",
-"$Date: 2001/06/04 22:00:52 $", and so on.
-<BR>
-<LI>
-
-<EM>Line-end conversion</EM> is when CVS gives plaintext files the
-appropriate line-ending conventions for the working copy's platform.
-For example, Unix working copies use LF, but Windows working copies use
-CRLF.  (Like CVS, the Subversion repository stores text files in Unix LF
-format).
-</UL>
-
-<P>
-<BR>
-Both keyword substitution and line-end conversion are sensible only for
-plain text files.  CVS only recognizes two file types anyway: plaintext
-and binary.  And CVS assumes files are plain text unless you tell it
-otherwise.
-
-
-<P>
-Subversion recognizes the same two types.  The question is, how does
-it determine a file's type?  Experience with CVS suggests that
-assuming text unless told otherwise is a losing strategy -- people
-frequently forget to mark images and other opaque formats as binary,
-then later they wonder why CVS mangled their data.  So Subversion will
-not mangle data: when moving over the network, or when being stored in
-the repository, it treats all files as binary.  In the working copy, a
-tweakable meta-data property indicates whether to treat the file as
-text or binary for purposes of whether or not to allow contextual
-merging during updates.
-
-
-<P>
-Users can turn line-end conversion on or off per file by tweaking
-meta-data.  Files do <EM>not</EM> undergo keyword substitution by
-default, on the theory that if someone wants substitution and isn't
-getting it, they'll look in the manual; but if they are getting it and
-didn't want it, they might just be confused and not know what to do.
-Users can turn substitution on or off per file.
-
-
-<P>
-Both of these changes are done on the client side; the repository does
-not even know about them.
-
-
-
-
-<H2><A NAME="SEC4" HREF="svn-design_toc.html#TOC4">I18N/Multilingual support</A></H2>
-
-<P>
-Subversion is internationalized -- commands, user messages, and errors
-can be customized to the appropriate human language at build-time (or
-run time, if that's not much harder).
-
-
-<P>
-File names and contents may be multilingual; Subversion does not assume
-an ASCII-only universe.  For purposes of keyword expansion and line-end
-conversion, Subversion also understands the UTF-* encodings (but not
-necessarily all of them by the first release).
-
-
-
-
-<H2><A NAME="SEC5" HREF="svn-design_toc.html#TOC5">Branching and tagging</A></H2>
-
-<P>
-Subversion supports branching and tagging with one efficient operation:
-`clone'.  To clone a tree is to copy it, to create another tree exactly
-like it (except that the new tree knows its ancestry relationship to the
-old one).
-
-
-<P>
-At the moment of creation, a clone requires only a small, constant
-amount of space in the repository -- most of its storage is shared with
-the original tree.  If you never commit anything on the clone, then it's
-just like a CVS tag.  If you start committing on it, then it's a branch.
-Voila!  This also implies CVS's "vendor branching" feature, since
-Subversion has real rename and directory support.
-
-
-
-
-<H2><A NAME="SEC6" HREF="svn-design_toc.html#TOC6">Miscellaneous new behaviors</A></H2>
-
-
-
-<H3><A NAME="SEC7" HREF="svn-design_toc.html#TOC7">Log messages</A></H3>
-
-<P>
-Subversion has a flexible log message policy (a small matter, but one
-dear to our hearts).
-
-
-<P>
-Log messages should be a matter of project policy, not version control
-software policy.  If a user commits with no log message, then Subversion
-defaults to an empty message.  (CVS tries to require log messages, but
-fails: we've all seen empty log messages in CVS, where the user
-committed with deliberately empty quotes.  Let's stop the madness now.)
-
-
-
-
-<H3><A NAME="SEC8" HREF="svn-design_toc.html#TOC8">Client side diff plug-ins</A></H3>
-
-<P>
-Subversion supports client-side plug-in diff programs.
-
-
-<P>
-There is no need for Subversion to have every possible diff mechanism
-built in.  It can invoke a user-specified client-side diff program on
-the two revisions of the file(s) locally.
-
-
-<P>
-(Note:  This feature does not exist yet, but is planned for post-1.0.)
-
-
-
-
-<H3><A NAME="SEC9" HREF="svn-design_toc.html#TOC9">Better merging</A></H3>
-
-<P>
-Subversion remembers what has already been merged in and what hasn't,
-thereby avoiding the problem, familiar to CVS users, of spurious
-conflicts on repeated merges.
-
-
-<P>
-(Note:  This feature does not exist yet, but is planned for post-1.0.)
-
-
-<P>
-For details, See section <A HREF="svn-design.html#SEC17">Merging and Ancestry</A>.
-
-
-
-
-<H3><A NAME="SEC10" HREF="svn-design_toc.html#TOC10">Conflicts resolution</A></H3>
-
-<P>
-For text files, Subversion resolves conflicts similarly to CVS, by
-folding repository changes into the working files with conflict
-markers.  But, for <EM>both</EM> text and binary files, Subversion also
-always puts the old and new pristine repository revisions into
-temporary files, and the pristine working copy revision in another
-temporary file.
-
-
-<P>
-Thus, for any conflict, the user has four files readily at hand:
-
-
-
-<OL>
-<LI>the original working copy file with local mods
-
-<LI>the older repository file
-
-<LI>the newest repository file
-
-<LI>the merged file, with conflict markers
-
-</OL>
-
-<P>
-and in a binary file conflict, the user has all but the last.
-
-
-<P>
-When the conflict has been resolved and the working copy is committed,
-Subversion automatically removes the temporary pristine files.
-
-
-<P>
-A more general solution would allow plug-in merge resolution tools on
-the client side; but this is not scheduled for the first release
-(see section <A HREF="svn-design.html#SEC45">Future</A>).  Note that users can use their own merge tools anyway,
-since all the original files are available.
-
-
-<H1><A NAME="SEC11" HREF="svn-design_toc.html#TOC11">Model</A></H1>
-
-<P>
-This chapter explains the user's view of Subversion -- what "objects"
-you interact with, how they behave, and how they relate to each other.
-
-
-
-
-<H2><A NAME="SEC12" HREF="svn-design_toc.html#TOC12">Working Directories and Repositories</A></H2>
-
-<P>
-Suppose you are using Subversion to manage a software project.  There
-are two things you will interact with: your working directory, and the
-repository.
-
-
-<P>
-Your <EM>working directory</EM> is an ordinary directory tree, on your
-local system, containing your project's sources.  You can edit these
-files and compile your program from them in the usual way.  Your working
-directory is your own private work area: Subversion never changes the
-files in your working directory, or publishes the changes you make
-there, until you explicitly tell it to do so.
-
-
-<P>
-After you've made some changes to the files in your working directory,
-and verified that they work properly, Subversion provides commands to
-publish your changes to the other people working with you on your
-project.  If they publish their own changes, Subversion provides
-commands to incorporate those changes into your working directory.
-
-
-<P>
-A working directory contains some extra files, created and maintained by
-Subversion, to help it carry out these commands.  In particular, these
-files help Subversion recognize which files contain unpublished changes,
-and which files are out-of-date with respect to others' work.
-
-
-<P>
-While your working directory is for your use alone, the <EM>repository</EM>
-is the common public record you share with everyone else working on the
-project.  To publish your changes, you use Subversion to put them in the
-repository.  (What this means, exactly, we explain below.)  Once your
-changes are in the repository, others can tell Subversion to incorporate
-your changes into their working directories.  In a collaborative
-environment like this, each user will typically have their own working
-directory (or perhaps more than one), and all the working directories
-will be backed by a single repository, shared amongst all the users.
-
-
-<P>
-A Subversion repository holds a single directory tree, and records the
-history of changes to that tree.  The repository retains enough
-information to recreate any prior state of the tree, compute the
-differences between any two prior trees, and report the relations
-between files in the tree -- which files are derived from which other
-files.
-
-
-<P>
-A Subversion repository can hold the source code for several projects;
-usually, each project is a subdirectory in the tree.  In this
-arrangement, a working directory will usually correspond to a particular
-subtree of the repository.
-
-
-<P>
-For example, suppose you have a repository laid out like this:
-
-<PRE>
-/trunk/paint/Makefile
-             canvas.c
-             brush.c
-       write/Makefile
-             document.c
-             search.c
-</PRE>
-
-<P>
-In other words, the repository's root directory has a single
-subdirectory named <TT>`trunk'</TT>, which itself contains two
-subdirectories: <TT>`paint'</TT> and <TT>`write'</TT>.
-
-
-<P>
-To get a working directory, you must <EM>check out</EM> some subtree of the
-repository.  If you check out <TT>`/trunk/write'</TT>, you will get a working
-directory like this:
-
-<PRE>
-write/Makefile
-      document.c
-      search.c
-      .svn/
-</PRE>
-
-<P>
-This working directory is a copy of the repository's <TT>`/trunk/write'</TT>
-directory, with one additional entry -- <TT>`.svn'</TT> -- which holds the
-extra information needed by Subversion, as mentioned above.
-
-
-<P>
-Suppose you make changes to <TT>`search.c'</TT>.  Since the <TT>`.svn'</TT>
-directory remembers the file's modification date and original contents,
-Subversion can tell that you've changed the file.  However, Subversion
-does not make your changes public until you explicitly tell it to.
-
-
-<P>
-To publish your changes, you can use Subversion's <SAMP>`commit'</SAMP> command:
-
-<PRE>
-$ pwd
-/home/jimb/write
-$ ls -a
-.svn/   Makefile   document.c    search.c
-$ svn commit search.c
-$
-</PRE>
-
-<P>
-Now your changes to <TT>`search.c'</TT> have been committed to the
-repository; if another user checks out a working copy of
-<TT>`/trunk/write'</TT>, they will see your text.
-
-
-<P>
-Suppose you have a collaborator, Felix, who checked out a working
-directory of <TT>`/trunk/write'</TT> at the same time you did.  When you
-commit your change to <TT>`search.c'</TT>, Felix's working copy is left
-unchanged; Subversion only modifies working directories at the user's
-request.
-
-
-<P>
-To bring his working directory up to date, Felix can use the Subversion
-<SAMP>`update'</SAMP> command.  This will incorporate your changes into his
-working directory, as well as any others that have been committed since
-he checked it out.
-
-<PRE>
-$ pwd
-/home/felix/write
-$ ls -a
-.svn/    Makefile    document.c    search.c
-$ svn update
-U search.c
-$
-</PRE>
-
-<P>
-The output from the <SAMP>`svn update'</SAMP> command indicates that Subversion
-updated the contents of <TT>`search.c'</TT>.  Note that Felix didn't need to
-specify which files to update; Subversion uses the information in the
-<TT>`.svn'</TT> directory, and further information in the repository, to
-decide which files need to be brought up to date.
-
-
-<P>
-We explain below what happens when both you and Felix make changes to
-the same file.
-
-
-
-
-<H2><A NAME="SEC13" HREF="svn-design_toc.html#TOC13">Transactions and Revision Numbers</A></H2>
-
-<P>
-A Subversion <SAMP>`commit'</SAMP> operation can publish changes to any number
-of files and directories as a single atomic transaction.  In your
-working directory, you can change files' contents, create, delete,
-rename and copy files and directories, and then commit the completed set
-of changes as a unit.
-
-
-<P>
-In the repository, each commit is treated as an atomic transaction:
-either all the commit's changes take place, or none of them take place.
-Subversion tries to retain this atomicity in the face of program
-crashes, system crashes, network problems, and other users' actions.  We
-may call a commit a <EM>transaction</EM> when we want to emphasize its
-indivisible nature.
-
-
-<P>
-Each time the repository accepts a transaction, this creates a new state
-of the tree, called a <EM>revision</EM>.  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 an empty root directory.
-
-
-<P>
-Since each transaction creates a new revision, with its own number, we
-can also use these numbers to refer to transactions; transaction <VAR>n</VAR>
-is the transaction which created revision <VAR>n</VAR>.  There is no
-transaction numbered zero.
-
-
-<P>
-Unlike those of many other systems, Subversion's revision numbers apply
-to an entire tree, not individual files.  Each revision number selects an
-entire tree.
-
-
-<P>
-It's important to note that working directories 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 directory from a repository whose most recent revision is 4:
-
-<PRE>
-write/Makefile:4
-      document.c:4
-      search.c:4
-</PRE>
-
-<P>
-At the moment, this working directory corresponds exactly to revision 4
-in the repository.  However, suppose you make a change to
-<TT>`search.c'</TT>, and commit that change.  Assuming no other commits have
-taken place, your commit will create revision 5 of the repository, and
-your working directory will look like this:
-
-<PRE>
-write/Makefile:4
-      document.c:4
-      search.c:5
-</PRE>
-
-<P>
-Suppose that, at this point, Felix commits a change to
-<TT>`document.c'</TT>, creating revision 6.  If you use <SAMP>`svn update'</SAMP> to
-bring your working directory up to date, then it will look like this:
-
-<PRE>
-write/Makefile:6
-      document.c:6
-      search.c:6
-</PRE>
-
-<P>
-Felix's changes to <TT>`document.c'</TT> will appear in your working copy of
-that file, and your change will still be present in <TT>`search.c'</TT>.  In
-this example, the text of <TT>`Makefile'</TT> is identical in revisions 4, 5,
-and 6, but Subversion will mark your working copy with revision 6 to
-indicate that it is still current.  So, after you do a clean update at
-the root of your working directory, your working directory will
-generally correspond exactly to some revision in the repository.
-
-
-
-
-<H2><A NAME="SEC14" HREF="svn-design_toc.html#TOC14">How Working Directories Track the Repository</A></H2>
-
-<P>
-For each file in a working directory, Subversion records two essential
-pieces of information:
-
-<UL>
-<LI>
-
-what revision of what repository file your working copy is based on (this is called the file's <EM>base revision</EM>), and
-<LI>
-
-a timestamp recording when the local copy was last updated.
-</UL>
-
-<P>
-Given this information, by talking to the repository, Subversion can
-tell which of the following four states a file is in:
-
-<UL>
-<LI>
-
-<B>Unchanged, and current.</B>  The file is unchanged in the working
-directory, and no changes to that file have been committed to the
-repository since its base revision.
-<LI>
-
-<B>Locally changed, and current</B>.  The file has been changed in the
-working directory, and no changes to that file have been committed to
-the repository since its base revision.  There are local changes that
-have not been committed to the repository.
-<LI>
-
-<B>Unchanged, and out-of-date</B>.  The file has not been changed in the
-working directory, but it has been changed in the repository.  The file
-should eventually be updated, to make it current with the public
-revision.
-<LI>
-
-<B>Locally changed, and out-of-date</B>.  The file has been changed both
-in the working directory, and in the repository.  The file should be
-updated; Subversion will attempt to merge the public changes with the
-local changes.  If it can't complete the merge in a plausible way
-automatically, Subversion leaves it to the user to resolve the conflict.
-</UL>
-
-
-
-<H2><A NAME="SEC15" HREF="svn-design_toc.html#TOC15">Subversion Does Not Lock Files</A></H2>
-
-<P>
-Subversion does not prevent two users from making changes to the same
-file at the same time.  For example, if both you and Felix have checked
-out working directories of <TT>`/trunk/write'</TT>, Subversion will allow
-both of you to change <TT>`write/search.c'</TT> in your working directories.
-Then, the following sequence of events will occur:
-
-<UL>
-<LI>
-
-Suppose Felix tries to commit his changes to <TT>`search.c'</TT> first.  His
-commit will succeed, and his text will appear in the latest revision in
-the repository.
-<LI>
-
-When you attempt to commit your changes to <TT>`search.c'</TT>, Subversion
-will reject your commit, and tell you that you must update
-<TT>`search.c'</TT> before you can commit it.
-<LI>
-
-When you update <TT>`search.c'</TT>, Subversion will try to merge Felix's
-changes from the repository with your local changes.  By default,
-Subversion merges as if it were applying a patch: if your local changes
-do not overlap textually with Felix's, then all is well; otherwise,
-Subversion leaves it to you to resolve the overlapping
-changes.  In either case,
-Subversion carefully preserves a copy of the original pre-merge text.
-<LI>
-
-Once you have verified that Felix's changes and your changes have been
-merged correctly, you can commit the new revision of <TT>`search.c'</TT>,
-which now contains everyone's changes.
-</UL>
-
-<P>
-Some version control systems provide "locks", which prevent others
-from changing a file once one person has begun working on it.  In our
-experience, merging is preferable to locks, because:
-
-<UL>
-<LI>
-
-changes usually do not conflict, so Subversion's behavior does the right
-thing by default, while locking can interfere with legitimate work;
-<LI>
-
-locking can prevent conflicts within a file, but not conflicts between
-files (say, between a C header file and another file that includes it),
-so it doesn't really solve the problem; and finally,
-<LI>
-
-people often forget that they are holding locks, resulting in
-unnecessary delays and friction.
-</UL>
-
-<P>
-Of course, the merge process needs to be under the users' control.
-Patch is not appropriate for files with rigid formats, like images or
-executables.  Subversion allows users to customize its merging
-behavior on a per-file basis.  You can direct Subversion to refuse to
-merge changes to certain files, and simply present you with the two
-original texts to choose from.  (Or, someday, you can direct
-Subversion to merge using a tool which respects the semantics of the
-file format.)
-
-
-
-
-<H2><A NAME="SEC16" HREF="svn-design_toc.html#TOC16">Properties</A></H2>
-
-<P>
-Files generally have interesting attributes beyond their contents:
-mime-types, executable permissions, EOL styles, and so on.  Subversion
-attempts to preserve these attributes, or at least record them, when
-doing so would be meaningful.  However, different operating systems
-support very different sets of file attributes: Windows NT supports
-access control lists, while Linux provides only the simpler
-traditional Unix permission bits.
-
-
-<P>
-In order to interoperate well with clients on many different operating
-systems, Subversion supports <EM>property lists</EM>, a simple,
-general-purpose mechanism which clients can use to store arbitrary
-out-of-band information about files.
-
-
-<P>
-A property list is a set of name / value pairs.  A property name is an
-arbitrary text string, expressed as a Unicode UTF-8 string, canonically
-decomposed and ordered.  A property value is an arbitrary string of
-bytes.  Property values may be of any size, but Subversion may not
-handle very large property values efficiently.  No two properties in a
-given a property list may have the same name.  Although the word `list'
-usually denotes an ordered sequence, there is no fixed order to the
-properties in a property list; the term `property list' is historical.
-
-
-<P>
-Each revision number, file, directory, and directory entry in the
-Subversion repository, has its own property list.  Subversion puts these
-property lists to several uses:
-
-<UL>
-<LI>
-
-Clients can use properties to store file attributes, as described above.
-<LI>
-
-The Subversion server uses properties to hold attributes of its own,
-and allow clients to read and modify them.  For example, someday a
-hypothetical <SAMP>`svn-acl'</SAMP> property might hold an access control list
-which the Subversion server uses to regulate access to repository
-files.
-<LI>
-
-Users can invent properties of their own, to store arbitrary information
-for use by scripts, build environments, and so on.  Names of user
-properties should be URI's, to avoid conflicts between organizations.
-</UL>
-
-<P>
-Property lists are versioned, just like file contents.  You can change
-properties in your working directory, but those changes are not visible
-in the repository until you commit your local changes.  If you do commit
-a change to a property value, other users will see your change when they
-update their working directories.
-
-
-
-
-<H2><A NAME="SEC17" HREF="svn-design_toc.html#TOC17">Merging and Ancestry</A></H2>
-
-<P>
-[WARNING:  this section was written in May 2000, at the very beginning
-of the Subversion project.  This functionality probably will not exist
-in Subversion 1.0, but it's planned for post-1.0.  The problem should
-be reasonably solvable by recording merge data in 'properties'.]
-
-
-<P>
-Subversion defines merges the same way CVS does: to merge means to take
-a set of previously committed changes and apply them, as a patch, to a
-working copy.  This change can then be committed, like any other change.
-(In Subversion's case, the patch may include changes to directory trees,
-not just file contents.)
-
-
-<P>
-As defined thus far, merging is equivalent to hand-editing the working
-copy into the same state as would result from the patch application.  In
-fact, in CVS there <EM>is</EM> no difference -- it is equivalent to just
-editing the files, and there is no record of which ancestors these
-particular changes came from.  Unfortunately, this leads to conflicts
-when users unintentionally merge the same changes again.  (Experienced
-CVS users avoid this problem by using branch- and merge-point tags, but
-that involves a lot of unwieldy bookkeeping.)
-
-
-<P>
-In Subversion, merges are remembered by recording <EM>ancestry sets</EM>.
-A revision's ancestry set is the set of all changes "accounted for" in
-that revision.  By maintaining ancestry sets, and consulting them when
-doing merges, Subversion can detect when it would apply the same patch
-twice, and spare users much bookkeeping.  Ancestry sets are stored as
-properties.
-
-
-<P>
-In the examples below, bear in mind that revision numbers usually refer
-to changes, rather than the full contents of that revision.  For example,
-"the change A:4" means "the delta that resulted in A:4", not "the full
-contents of A:4".
-
-
-<P>
-The simplest ancestor sets are associated with linear histories.  For
-example, here's the history of a file A:
-
-
-
-<PRE>
-
- _____        _____        _____        _____        _____
-|     |      |     |      |     |      |     |      |     |
-| A:1 |-----&#62;| A:2 |-----&#62;| A:3 |-----&#62;| A:4 |-----&#62;| A:5 |
-|_____|      |_____|      |_____|      |_____|      |_____|
-
-</PRE>
-
-<P>
-The ancestor set of A:5 is:
-
-
-
-<PRE>
-
-  { A:1, A:2, A:3, A:4, A:5 }
-
-</PRE>
-
-<P>
-That is, it includes the change that brought A from nothing to A:1, the
-change from A:1 to A:2, and so on to A:5.  From now on, ranges like this
-will be represented with a more compact notation:
-
-
-
-<PRE>
-
-  { A:1-5 }
-
-</PRE>
-
-<P>
-Now assume there's a branch B based, or "rooted", at A:2.  (This
-postulates an entirely different revision history, of course, and the
-global revision numbers in the diagrams will change to reflect it.)
-Here's what the project looks like with the branch:
-
-
-
-<PRE>
-
- _____        _____        _____        _____        _____        _____
-|     |      |     |      |     |      |     |      |     |      |     |
-| A:1 |-----&#62;| A:2 |-----&#62;| A:4 |-----&#62;| A:6 |-----&#62;| A:8 |-----&#62;| A:9 |
-|_____|      |_____|      |_____|      |_____|      |_____|      |_____|
-                \
-                 \
-                  \  _____        _____        _____
-                   \|     |      |     |      |     |
-                    | B:3 |-----&#62;| B:5 |-----&#62;| B:7 |
-                    |_____|      |_____|      |_____|
-
-</PRE>
-
-<P>
-If we produce A:9 by merging the B branch back into the trunk
-
-
-
-<PRE>
-
- _____        _____        _____        _____        _____        _____
-|     |      |     |      |     |      |     |      |     |      |     |
-| A:1 |-----&#62;| A:2 |-----&#62;| A:4 |-----&#62;| A:6 |-----&#62;| A:8 |---.-&#62;| A:9 |
-|_____|      |_____|      |_____|      |_____|      |_____|  /   |_____|
-                \                                            |
-                 \                                           |
-                  \  _____        _____        _____        /
-                   \|     |      |     |      |     |      /
-                    | B:3 |-----&#62;| B:5 |-----&#62;| B:7 |---&#62;-'
-                    |_____|      |_____|      |_____|
-
-</PRE>
-
-<P>
-then what will A:9's ancestor set be?
-
-
-
-<PRE>
-
-  { A:1, A:2, A:4, A:6, A:8, A:9, B:3, B:5, B:7}
-
-</PRE>
-
-<P>
-or more compactly:
-
-
-
-<PRE>
-
-  { A:1-9, B:3-7 }
-
-</PRE>
-
-<P>
-(It's all right that each file's ranges seem to include non-changes;
-this is just a notational convenience, and you can think of the
-non-changes as either not being included, or being included but being
-null deltas as far as that file is concerned).
-
-
-<P>
-All changes along the B line are accounted for (changes B:3-7), and so
-are all changes along the A line, including both the merge and any
-non-merge-related edits made before the commit.
-
-
-<P>
-Although this merge happened to include all the branch changes, that
-needn't be the case.  For example, the next time we merge the B line
-
-
-
-<PRE>
-
- _____     _____     _____     _____     _____      _____      _____
-|     |   |     |   |     |   |     |   |     |    |     |    |     |
-| A:1 |--&#62;| A:2 |--&#62;| A:4 |--&#62;| A:6 |--&#62;| A:8 |-.-&#62;| A:9 |-.-&#62;|A:11 |
-|_____|   |_____|   |_____|   |_____|   |_____| |  |_____| |  |_____|
-             \                                  /          |
-              \                                /           |
-               \  _____     _____     _____   / _____      |
-                \|     |   |     |   |     | / |     |    /
-                 | B:3 |--&#62;| B:5 |--&#62;| B:7 |--&#62;|B:10 |-&#62;-'
-                 |_____|   |_____|   |_____|   |_____|
-
-</PRE>
-
-<P>
-Subversion will know that A's ancestry set already contains B:3-7, so
-only the difference between B:7 and B:10 will be applied.  A's new
-ancestry will be
-
-
-
-<PRE>
-
-  { A:1-11, B:3-10 }
-
-</PRE>
-
-<P>
-But why limit ourselves to contiguous ranges?  An ancestry set is truly
-a set -- it can be any subset of the changes available:
-
-
-
-<PRE>
-
- _____        _____        _____        _____        _____        _____
-|     |      |     |      |     |      |     |      |     |      |     |
-| A:1 |-----&#62;| A:2 |-----&#62;| A:4 |-----&#62;| A:6 |-----&#62;| A:8 |--.--&#62;|A:10 |
-|_____|      |_____|      |_____|      |_____|      |_____| /    |_____|
-                |                                          /
-                |                ______________________.__/
-                |               /                      |
-                |              /                       |
-                \           __/_                      _|__
-                 \         {    }                    {    }
-                  \  _____        _____        _____        _____
-                   \|     |      |     |      |     |      |     |
-                    | B:3 |-----&#62;| B:5 |-----&#62;| B:7 |-----&#62;| B:9 |-----&#62;
-                    |_____|      |_____|      |_____|      |_____|
-
-</PRE>
-
-<P>
-In this diagram, the change from B:3-5 and the change from B:7-9 are
-merged into a working copy whose ancestry set (so far) is { A:1-8
-} plus any local changes.  After committing, A:10's ancestry set is
-
-
-
-<PRE>
-
-  { A:1-10, B:5, B:9 }
-
-</PRE>
-
-<P>
-Clearly, saying "Let's merge branch B into A" is a little ambiguous.  It
-usually means "Merge all the changes accounted for in B's tip into A",
-but it <EM>might</EM> mean "Merge the single change that resulted in B's
-tip into A".
-
-
-<P>
-Any merge, when viewed in detail, is an application of a particular set
-of changes -- not necessarily adjacent ones -- to a working copy.  The
-user-level interface may allow some of these changes to be specified
-implicitly.  For example, many merges involve a single, contiguous range
-of changes, with one or both ends of the range easily deducible from
-context (i.e., branch root to branch tip).  These inference rules are
-not specified here, but it should be clear in most contexts how they
-work.
-
-
-<P>
-Because each node knows its ancestors, Subversion never merges the same
-change twice (unless you force it to).  For example, if after the above
-merge, you tell Subversion to merge all B changes into A, Subversion
-will notice that two of them have already been merged, and so merge only
-the other two changes, resulting in a final ancestry set of:
-
-
-
-<PRE>
-
-  { A:1-10, B:3-9 }
-
-</PRE>
-
-<P>
-This description of merging and ancestry applies to both intra- and
-inter-repository merges.  However, inter-repository merging will
-probably not be implemented until a future release of Subversion
-(see section <A HREF="svn-design.html#SEC45">Future</A>).
-
-
-<H1><A NAME="SEC18" HREF="svn-design_toc.html#TOC18">Architecture</A></H1>
-
-<P>
-Subversion is conceptually divided into a number of separable layers.
-
-
-<P>
-Assuming that the programmatic interface of each layer is well-defined,
-it is easy to customize the different parts of the system.  Contributors
-can write new client apps, new network protocols, new server processes,
-new server features, and new storage back-ends.
-
-
-<P>
-The following diagram illustrates the "layered" architecture, and where
-each particular interface lies.
-
-
-
-<PRE>
-                    +--------------------+
-                    | commandline or GUI |
-                    |    client app      |
-         +----------+--------------------+----------+ &#60;=== Client interface
-         |              Client Library              |
-         |                                          |
-         |        +----+                            |
-         |        |    |                            |
- +-------+--------+    +--------------+--+----------+ &#60;=== Network interface
- | Working Copy   |    |    Remote    |  | Local    |
- | Management lib |    | Repos Access |  | Repos    |
- +----------------+    +--------------+  | Access   |
-                       |     neon     |  |          |
-                       +--------------+  |          |
-                          ^              |          |
-                         /               |          |
-                   DAV  /                |          |
-                       /                 |          |
-                      v                  |          |
-              +---------+                |          |
-              |         |                |          |
-              | Apache  |                |          |
-              |         |                |          |
-              +---------+                |          |
-              | mod_DAV |                |          |
-            +-------------+              |          |
-            | mod_DAV_SVN |              |          |
- +----------+-------------+--------------+----------+ &#60;=== Filesystem interface
- |                                                  |
- |               Subversion Filesystem              |
- |                                                  |
- +--------------------------------------------------+
-
-</PRE>
-
-
-
-<H2><A NAME="SEC19" HREF="svn-design_toc.html#TOC19">Client Layer</A></H2>
-
-<P>
-The Subversion client, which may be either command-line or GUI, draws on
-three libraries.
-
-
-<P>
-The working copy library, <TT>`libsvn_wc'</TT>, provides an API for
-managing the client's working copy of a project.  This includes
-operations like renaming or removal of files, patching files,
-extracting local diffs, and routines for maintaining administrative
-files in the <TT>`.svn/'</TT> directory.
-
-
-<P>
-The repository_access library, <TT>`libsvn_ra'</TT>, provides an API for
-exchanging information with a Subversion repository.  This includes
-the ability to read files, write new revisions of files, and ask the
-repository to compare a working copy against its latest revision.
-Note that there are two implementations of this interface: one
-designed to talk to a repository over a network, and one designed to
-work with a repository on local disk.  Any number of interface
-implementations can exist.
-
-
-<P>
-The client library, <TT>`libsvn_client'</TT> provides general client
-functions such as <CODE>update()</CODE> and <CODE>commit()</CODE>, which may
-involve one or both of the other two client libraries.
-<TT>`libsvn_client'</TT> should, in theory, provide an API that allows
-anyone to write a Subversion client application.
-
-
-<P>
-For details, See section <A HREF="svn-design.html#SEC28">Client</A>.
-
-
-
-
-<H2><A NAME="SEC20" HREF="svn-design_toc.html#TOC20">Network Layer</A></H2>
-
-<P>
-The network layer's job is to move the repository API requests over a
-wire.
-
-
-<P>
-On the client side, a network library (<TT>`libneon'</TT>) translates
-these requests into a set of HTTP WebDAV/DeltaV requests.  The
-information is sent over TCP/IP to an Apache server.  Apache is used
-for the following reasons:
-
-
-
-<UL>
-<LI>
-
-it is time-tested and extremely stable;
-<LI>
-
-it has built-in load-balancing;
-<LI>
-
-it has built-in proxy and firewall support;
-<LI>
-
-it has authentication and encryption features;
-<LI>
-
-it allows client-side caching;
-<LI>
-
-it has an extensible module system
-</UL>
-
-<P>
-Our rationale is that any attempt to write a dedicated "Subversion
-server" (with a "Subversion protocol") would inevitably end up
-evolving towards Apache's already-existing feature set.  (However,
-Subversion's layered architecture certainly doesn't <EM>prevent</EM>
-anyone from writing a totally new network access implementation.)
-
-
-<P>
-An Apache module (<TT>`mod_dav_svn'</TT>) translates the DAV requests into
-API calls against a particular repository.
-
-
-<P>
-For details, See section <A HREF="svn-design.html#SEC34">Protocol</A>.
-
-
-
-
-<H2><A NAME="SEC21" HREF="svn-design_toc.html#TOC21">Filesystem Layer</A></H2>
-
-<P>
-When the requests reach a particular repository, they are interpreted
-by the <EM>Subversion Filesystem library</EM>, <TT>`libsvn_fs'</TT>.  The
-Subversion Filesystem is a custom Unix-like filesystem, with a twist:
-writes are revisioned and atomic, and no data is ever deleted!  This
-filesystem is currently implemented on top of a normal filesystem,
-using Berkeley DB files.
-
-
-<P>
-For a more detailed explanation: See section <A HREF="svn-design.html#SEC35">Server</A>.
-
-
-<H1><A NAME="SEC22" HREF="svn-design_toc.html#TOC22">Deltas</A></H1>
-
-<P>
-Subversion uses three kinds of deltas:
-
-
-
-<UL>
-<LI>
-
-A <B><EM>tree delta</EM></B> describes the difference between two arbitrary
-directory trees, the way a traditional patch describes the difference
-between two files.  For example, the delta between directories A and B
-could be applied to A, to produce B.
-
-Tree deltas can also carry ancestry information, indicating how the
-files in one tree are related to files in the other tree.  And deltas
-can describe changes to file meta-information, like permission bits,
-creation dates, and so on.  The repository and working copy use deltas
-to communicate changes.
-
-<LI>
-
-A <B><EM>text delta</EM></B> describes changes to a string of bytes, such as the
-contents of a file.  It is analogous to traditional patch format, except
-that it works equally well on binary and text files, and is not
-invertible (because context and deleted data are not recorded).
-
-<LI>
-
-A <B><EM>property delta</EM></B> describes changes to a list of named
-properties (see section <A HREF="svn-design.html#SEC16">Properties</A>).
-</UL>
-
-<P>
-The term <EM>delta</EM> without qualification generally means a tree delta,
-unless some other meaning is clear from context.
-
-
-<P>
-In the examples below, deltas will be described in XML, which happens
-to be Subversion's (now mostly defunct) import/export patch format.
-However, note that deltas are an abstract data structure, of which the
-XML format is merely one representation.  Later, we will describe
-other representations: for example, there is a serialized
-representation (useful for streaming protocols, among other things),
-and a db-style representation, used for repository storage.  The
-various representations of a given delta are (in theory, anyway)
-perfectly isomorphic to one another, since they describe the same
-underlying structure.
-
-
-
-
-<H2><A NAME="SEC23" HREF="svn-design_toc.html#TOC23">Text Deltas</A></H2>
-
-<P>
-A text delta describes the difference between two strings of bytes, the
-<EM>source</EM> string and the <EM>target</EM> string.  Given a source string
-and a target string, we can compute a text delta; given a source string
-and a delta, we can reconstruct the target string.  However, note that
-deltas are not invertible: you cannot always reconstruct the source
-string given the target string and delta.
-
-
-<P>
-The standard Unix "diff" format is one possible representation for
-text deltas; however, diffs are not ideal for internal use by a revision
-control system, for several reasons:
-
-<UL>
-<LI>
-
-Diffs are line-oriented, which makes them human-readable, but sometimes
-makes them perform poorly on binary files.
-<LI>
-
-Diffs represent a series of replacements, exchanging selected ranges of
-the old text with new text; again, this is easy for humans to read, but
-it is more expensive to compute and less compact than some alternatives.
-</UL>
-
-<P>
-Instead, Subversion uses the VDelta binary-diffing algorithm, as
-described in <CITE>Hunt, J. J., Vo, K.-P., and Tichy, W. F.  An
-empirical study of delta algorithms.  Lecture Notes in Computer Science
-1167 (July 1996), 49-66.</CITE>  Currently, the output of this algorithm is
-stored in a custom data format called <EM>svndiff</EM>, invented by Greg
-Hudson &#60;<A HREF="mailto:ghudson@mit.edu">ghudson@mit.edu</A>&#62;, a Subversion developer.
-
-
-<P>
-The concrete form of a text delta is a well-formed XML element, having
-the following form:
-
-<PRE>
-&#60;text-delta&#62;<VAR>data</VAR>&#60;/text-delta&#62;
-</PRE>
-
-<P>
-Here, <VAR>data</VAR> is the raw svndiff data, encoded in the MIME Base64
-format.
-
-
-
-
-<H2><A NAME="SEC24" HREF="svn-design_toc.html#TOC24">Property Deltas</A></H2>
-
-<P>
-A property delta describes changes to a property list, of the sort
-associated with files, directories, and directory entries, and revision
-numbers (see section <A HREF="svn-design.html#SEC16">Properties</A>).  A property delta can record creating,
-deleting, and changing the text of any number of properties.
-
-
-<P>
-A property delta is an unordered set of name/change pairs.  No two
-pairs within a given property delta have the same name.  A pair's name
-indicates the property affected, and the change indicates what happens
-to its value.  There are two kinds of changes:
-<DL COMPACT>
-
-<DT><CODE>set <VAR>value</VAR></CODE>
-<DD>
-Change the value of the named property to the byte string <VAR>value</VAR>.
-If there is no property with the given name, one is added to the
-property list.
-<DT><CODE>delete</CODE>
-<DD>
-Remove the named property from the property list.
-</DL>
-
-<P>
-At the moment, the <CODE>set</CODE> command can either create or change a
-property value.  However, this simplification means that the server
-cannot distinguish between a client which believes it is creating a
-value afresh, and a client which believes it is changing the value of an
-existing property.  It may simplify conflict detection to divide
-<CODE>set</CODE> into two separate <CODE>add</CODE> and <CODE>change</CODE> operations.
-
-
-<P>
-In the future, we may add a <CODE>text-delta</CODE> change, which specifies a
-change to an existing property's value as a text delta.  This would give
-us a compact way to describe small changes to large property values.
-
-
-<P>
-The concrete form of a property delta is a well-formed XML element,
-having the following form:
-
-<PRE>
-&#60;property-delta&#62;<VAR>change</VAR>...&#60;/property-delta&#62;
-</PRE>
-
-<P>
-Each <VAR>change</VAR> in a property delta has one of the following forms:
-
-<PRE>
-&#60;set name='<VAR>name</VAR>'&#62;<VAR>value</VAR>&#60;/set&#62;
-&#60;delete name='<VAR>name</VAR>'/&#62;
-</PRE>
-
-<P>
-The <VAR>name</VAR> attribute of a <CODE>set</CODE> or <CODE>delete</CODE> element gives
-the name of the property to change.  The <VAR>value</VAR> of a <CODE>set</CODE>
-element gives the new value of the property.
-
-
-<P>
-If either the property name or the property value contains the
-characters <SAMP>`&#38;'</SAMP>, <SAMP>`&#60;'</SAMP>, or <SAMP>`''</SAMP>, they should be replaced with
-the sequences <SAMP>`&#38;#38'</SAMP>, <SAMP>`&#38;#60'</SAMP>, or <SAMP>`&#38;#39'</SAMP>, respectively.
-
-
-
-
-<H2><A NAME="SEC25" HREF="svn-design_toc.html#TOC25">Tree Deltas</A></H2>
-
-<P>
-A tree delta describes changes between two directory trees, the
-<EM>source tree</EM> and the <EM>target tree</EM>.  Tree deltas can describe
-copies, renames, and deletions of files and directories, changes to file
-contents, and changes to property lists.  A tree delta can also carry
-information about how the files in the target tree are derived from the
-files in the source tree, if this information is available.
-
-
-<P>
-The format for tree deltas described here is easy to compute from a
-Subversion working directory, and easy to apply to a Subversion
-repository.  Furthermore, the size of a tree delta in this format is
-independent of the commands used to produce the target tree -- it
-depends only on the degree of difference between the source and target
-trees.
-
-
-<P>
-A tree delta is interpreted in the context of three parameters:
-
-<UL>
-<LI>
-
-<VAR>source-root</VAR>, the name of the directory to which this complete
-tree delta applies,
-<LI>
-
-<VAR>revision</VAR>, indicating a particular revision of ...
-<LI>
-
-<VAR>source-dir</VAR>, which is a directory in the source tree that we are
-currently modifying to yield ...
-<LI>
-
-... <EM>target-dir</EM> -- the directory we're constructing.
-</UL>
-
-<P>
-When we start interpreting a tree delta, <VAR>source-root</VAR>,
-<VAR>source-dir</VAR>, and <VAR>target-dir</VAR> are all equal.  As we walk the
-tree delta, <VAR>target-dir</VAR> walks the tree we are constructing, and
-<VAR>source-dir</VAR> walks the corresponding portion of the source tree,
-which we use as the original.  <VAR>Source-root</VAR> remains constant as we
-walk the delta; we may use it to choose new source trees.
-
-
-<P>
-A tree delta is a list of changes of the form
-
-<PRE>
-&#60;tree-delta&#62;<VAR>change</VAR>...&#60;/tree-delta&#62;
-</PRE>
-
-<P>
-which describe how to edit the contents of <VAR>source-dir</VAR> to yield
-<VAR>target-dir</VAR>.  There are three kinds of changes:
-<DL COMPACT>
-
-<DT><CODE>&#60;delete name='<VAR>name</VAR>'/&#62;</CODE>
-<DD>
-<VAR>Source-dir</VAR> has an entry named <VAR>name</VAR>, which is not present in
-<VAR>target-dir</VAR>.
-
-<DT><CODE>&#60;add name='<VAR>name</VAR>'&#62;<VAR>content</VAR>&#60;/add&#62;</CODE>
-<DD>
-<VAR>target-dir</VAR> has an entry named <VAR>name</VAR>, which is not present in
-<VAR>source-dir</VAR>; <VAR>content</VAR> describes the file or directory to which
-the new directory entry refers.
-
-<DT><CODE>&#60;open name='<VAR>name</VAR>'&#62;<VAR>content</VAR>&#60;/open&#62;</CODE>
-<DD>
-Both <VAR>source-dir</VAR> and <VAR>target-dir</VAR> have an entry named
-<VAR>name</VAR>, which has changed; <VAR>content</VAR> describes the new file or
-directory.
-
-</DL>
-<P>
-Any entries in <VAR>source-dir</VAR> whose names aren't mentioned are assumed
-to appear unchanged in <VAR>target-dir</VAR>.  Thus, an empty
-<CODE>tree-delta</CODE> element indicates that <VAR>target-dir</VAR> is identical
-to <VAR>source-dir</VAR>.
-
-
-<P>
-In the change descriptions above, each <VAR>content</VAR> takes one of the
-following forms:
-<DL COMPACT>
-
-<DT><CODE>&#60;file <VAR>ancestor</VAR>&#62;<VAR>prop-delta</VAR> <VAR>text-delta</VAR>&#60;/file&#62;</CODE>
-<DD>
-The given <VAR>target-dir</VAR> entry refers to a file, <VAR>f</VAR>.
-<VAR>Ancestor</VAR> indicates which file in the source tree <VAR>f</VAR> is
-derived from, if any.
-
-<VAR>Prop-delta</VAR> is a property delta describing how <VAR>f</VAR>'s properties
-differ from that ancestor; it may be omitted, indicating that the
-properties are unchanged.
-
-<VAR>Text-delta</VAR> is a text delta describing how to construct <VAR>f</VAR>
-from that ancestor; it may also be omitted, indicating that <VAR>f</VAR>'s
-text is identical to its ancestor's.
-
-<DT><CODE>&#60;file <VAR>ancestor</VAR>/&#62;</CODE>
-<DD>
-An abbreviation for <CODE>&#60;file <VAR>ancestor</VAR>&#62;&#60;/file&#62;</CODE> -- a file
-element with no property or text delta, thus describing a file identical
-to its ancestor.
-
-<DT><CODE>&#60;directory <VAR>ancestor</VAR>&#62;<VAR>prop-delta</VAR> <VAR>tree-delta</VAR>&#60;/directory&#62;</CODE>
-<DD>
-The given <VAR>target-dir</VAR> entry refers to a subdirectory, <VAR>sub</VAR>.
-<VAR>Ancestor</VAR> indicates which directory in the source tree <VAR>sub</VAR> is
-derived from, if any.
-
-<VAR>Prop-delta</VAR> is a property delta describing how <VAR>sub</VAR>'s
-properties differ from that ancestor; it may be omitted, indicating that
-the properties are unchanged.
-
-<VAR>Tree-delta</VAR> describes how to construct <VAR>sub</VAR> from that
-ancestor; it may be omitted, indicating that the directory is identical
-to its ancestor.  <VAR>Tree-delta</VAR> should be interpreted with a new
-<VAR>target-dir</VAR> of <TT>`<VAR>target-dir</VAR>/<VAR>name</VAR>'</TT>.
-
-Since <VAR>tree-delta</VAR> is itself a complete tree delta structure, tree
-deltas are themselves trees, whose structure is a subgraph of the target
-tree.
-
-<DT><CODE>&#60;directory <VAR>ancestor</VAR>/&#62;</CODE>
-<DD>
-An abbreviation for <CODE>&#60;directory <VAR>ancestor</VAR>&#62;&#60;/directory&#62;</CODE> -- a
-directory element with no property or tree delta, thus describing a
-directory identical to its ancestor.
-
-</DL>
-
-<P>
-The <VAR>content</VAR> of a <CODE>add</CODE> or <CODE>open</CODE> tag may also contain
-a property delta, describing changes to the properties of that
-<EM>directory entry</EM>.
-
-
-<P>
-In the <CODE>file</CODE> and <CODE>directory</CODE> elements described above, each
-<VAR>ancestor</VAR> has one of the following forms:
-<DL COMPACT>
-
-<DT><CODE>ancestor='<VAR>path</VAR>'</CODE>
-<DD>
-The ancestor of the new or changed file or directory is
-<TT>`<VAR>source-root</VAR>/<VAR>path</VAR>'</TT>, in <VAR>revision</VAR>.  When this
-appears as an attribute of a <CODE>file</CODE> element, the element's text
-delta should be applied to <TT>`<VAR>source-root</VAR>/<VAR>path</VAR>'</TT>.  When
-this appears as an attribute of a <CODE>directory</CODE> element,
-<TT>`<VAR>source-root</VAR>/<VAR>path</VAR>'</TT> should be the new <VAR>source-dir</VAR>
-for interpreting that element's tree delta.
-
-<DT><CODE>new='true'</CODE>
-<DD>
-This indicates that the file or directory has no ancestor in the source
-tree.  When followed by a <VAR>text-delta</VAR>, that delta should be applied
-to the empty file to yield the new text; when followed by a
-<VAR>tree-delta</VAR>, that delta should be evaluated as if <VAR>source-dir</VAR>
-were an imaginary empty directory.
-
-<DT><CODE><VAR>nothing</VAR></CODE>
-<DD>
-If neither an <CODE>ancestor</CODE> nor a <CODE>new</CODE> attribute is given, this
-is an abbreviation for <CODE>ancestor='<VAR>source-dir</VAR>/<VAR>name</VAR>'</CODE>,
-with the same revision number.  This makes the common case -- files or
-directories modified in place -- more compact.
-
-</DL>
-
-<P>
-If the <VAR>ancestor</VAR> spec is not <CODE>new='true'</CODE>, it may also contain
-the text <CODE>revision='<VAR>rev</VAR>'</CODE>, indicating a new value for
-<VAR>revision</VAR>, in which we should find the ancestor.
-
-
-<P>
-If a filename or path appearing as a <VAR>name</VAR> or <VAR>path</VAR> in the
-description above contains the characters <SAMP>`&#38;'</SAMP>, <SAMP>`&#60;'</SAMP>, or
-<SAMP>`''</SAMP>, they should be replaced with the sequences <SAMP>`&#38;#38;'</SAMP>,
-<SAMP>`&#38;#60;'</SAMP>, or <SAMP>`&#38;#39;'</SAMP>, respectively.
-
-
-<P>
-Suppose we have the following source tree:
-
-<PRE>
-/dir1/file1
-      file2
-      dir2/file3
-           file4
-      dir3/file5
-           file6
-</PRE>
-
-<P>
-  
-If we edit the contents of <TT>`/dir1/file1'</TT>, we can describe the
-effect on the tree with the following tree delta, to be applied to the
-root:
-
-<PRE>
-&#60;tree-delta&#62;
-  &#60;open name='dir1'&#62;
-    &#60;directory&#62;
-      &#60;tree-delta&#62;
-        &#60;open name='file1'&#62;
-          &#60;file&#62;<VAR>text-delta</VAR>&#60;/file&#62;
-        &#60;/open&#62;
-      &#60;/tree-delta&#62;
-    &#60;/directory&#62;
-  &#60;/open&#62;
-&#60;/tree-delta&#62;
-</PRE>
-
-<P>
-The outer <CODE>tree-delta</CODE> element describes the changes made to the root
-directory.  Within the root directory, there are changes in <TT>`dir1'</TT>,
-described by the nested <CODE>tree-delta</CODE>.  Within <TT>`/dir1'</TT>, there are
-changes in <TT>`file1'</TT>, described by the <VAR>text-delta</VAR>.
-
-
-<P>
-If we had edited both <TT>`/dir1/file1'</TT> and <TT>`/dir1/file2'</TT>, then
-there would simply be two <CODE>open</CODE> elements in the inner
-<CODE>tree-delta</CODE>.
-
-
-<P>
-As another example, starting from the same source tree, suppose we
-rename <TT>`/dir1/file1'</TT> to <TT>`/dir1/file8'</TT>:
-
-<PRE>
-&#60;tree-delta&#62;
-  &#60;open name='dir1'&#62;
-    &#60;directory&#62;
-      &#60;tree-delta&#62;
-        &#60;delete name='file1'/&#62;
-        &#60;add name='file8'&#62;
-          &#60;file ancestor='/dir1/file1'/&#62;
-        &#60;/add&#62;
-      &#60;/tree-delta&#62;
-    &#60;/directory&#62;
-  &#60;/open&#62;
-&#60;/tree-delta&#62;
-</PRE>
-
-<P>
-As above, the inner <CODE>tdelta</CODE> describes how <TT>`/dir1'</TT> has
-changed: the entry for <TT>`/dir1/file1'</TT> has disappeared, but there is
-a new entry, <TT>`/dir1/file8'</TT>, which is derived from and textually
-identical to <TT>`/dir1/file1'</TT> in the source directory.  This is just
-an indirect way of describing the rename.
-
-
-<P>
-Why is it necessary to be so indirect?  Consider the delta representing
-the result of:
-
-<OL>
-<LI>
-
-renaming <TT>`/dir1/file1'</TT> to <TT>`/dir1/tmp'</TT>,
-<LI>
-
-renaming <TT>`/dir1/file2'</TT> to <TT>`/dir1/file1'</TT>, and
-<LI>
-
-renaming <TT>`/dir1/tmp'</TT> to <TT>`/dir1/file2'</TT>
-</OL>
-
-<P>
-(in other words, exchanging <TT>`file1'</TT> and <TT>`file2'</TT>):
-
-<PRE>
-&#60;tree-delta&#62;
-  &#60;open name='dir1'&#62;
-    &#60;directory&#62;
-      &#60;tree-delta&#62;
-        &#60;open name='file1'&#62;
-          &#60;file ancestor='/dir1/file2'/&#62;
-        &#60;/open&#62;
-        &#60;open name='file2'&#62;
-          &#60;file ancestor='/dir1/file1'/&#62;
-        &#60;/open&#62;
-      &#60;/tree-delta&#62;
-    &#60;/directory&#62;
-  &#60;/open&#62;
-&#60;/tree-delta&#62;
-</PRE>
-
-<P>
-The indirectness allows the tree delta to capture an arbitrary
-rearrangement without resorting to temporary filenames.
-
-
-<P>
-Another example, starting from the same source tree:
-
-<OL>
-<LI>
-
-rename <TT>`/dir1/dir2'</TT> to <TT>`/dir1/dir4'</TT>,
-<LI>
-
-rename <TT>`/dir1/dir3'</TT> to <TT>`/dir1/dir2'</TT>, and
-<LI>
-
-move <TT>`file3'</TT> from <VAR>/dir1/dir4</VAR> to <VAR>/dir1/dir2</VAR>.
-</OL>
-
-<P>
-Note that <TT>`file3'</TT>'s path has remained the same, even though the
-directories around it have changed.  Here is the tree delta:
-
-<PRE>
-&#60;tree-delta&#62;
-  &#60;open name='dir1'&#62;
-    &#60;directory&#62;
-      &#60;tree-delta&#62;
-        &#60;open name='dir2'&#62;
-          &#60;directory ancestor='/dir1/dir3'&#62;
-            &#60;tree-delta&#62;
-              &#60;add name='file3'&#62;
-                &#60;file ancestor='/dir1/dir2/file3'/&#62;
-              &#60;/add&#62;
-            &#60;/tree-delta&#62;
-          &#60;/directory&#62;
-        &#60;/open&#62;
-        &#60;delete name='dir3'/&#62;
-        &#60;add name='dir4'&#62;
-          &#60;directory ancestor='/dir1/dir2'&#62;
-            &#60;tree-delta&#62;
-              &#60;delete name='file3'/&#62;
-            &#60;/tree-delta&#62;
-          &#60;/directory&#62;
-        &#60;/add&#62;
-      &#60;/tree-delta&#62;
-    &#60;/directory&#62;
-  &#60;/open&#62;
-&#60;/tree-delta&#62;
-</PRE>
-
-<P>
-In other words:
-
-<UL>
-<LI>
-
-<TT>`/dir1'</TT> has changed;
-<LI>
-
-the new directory <TT>`/dir1/dir2'</TT> is derived from the old
-<TT>`/dir1/dir3'</TT>, and contains a new entry <TT>`file3'</TT>, derived from
-the old <TT>`/dir1/dir2/file3'</TT>;
-<LI>
-
-there is no longer any <TT>`/dir1/dir3'</TT>; and
-<LI>
-
-the new directory <TT>`/dir1/dir4'</TT> is derived from the old
-<TT>`/dir1/dir2'</TT>, except that its entry for <TT>`file3'</TT> is now gone.
-</UL>
-
-<P>
-Some more possible maneuvers, left as exercises for the reader:
-
-<UL>
-<LI>
-
-Delete <TT>`dir2'</TT>, and then create a file named <TT>`dir2'</TT>.
-<LI>
-
-Rename <TT>`/dir1/dir2'</TT> to <TT>`/dir1/dir4'</TT>; move <TT>`file2'</TT> into
-<TT>`/dir1/dir4'</TT>; and move <TT>`file3'</TT> into <VAR>/dir1/dir3</VAR>.
-<LI>
-
-Move <TT>`dir2'</TT> into <TT>`dir3'</TT>, and move <TT>`dir3'</TT> into <TT>`/'</TT>.
-</UL>
-
-
-
-<H2><A NAME="SEC26" HREF="svn-design_toc.html#TOC26">Postfix Text Deltas</A></H2>
-
-<P>
-It is sometimes useful to represent a set of changes to a tree without
-providing text deltas in the middle of the stream.  Text deltas are
-often large and expensive to compute, and tree deltas can be useful
-without them.  For example, one can detect whether two changes might
-conflict -- whether they change the same file, for example -- without
-knowing exactly how the conflicting files changed.
-
-
-<P>
-For this reason, our XML representation of a tree delta allows the text
-deltas to come <EM>after</EM> the &#60;/tree-delta&#62; closure.  This allows the
-client to receive early notice of conflicts:  during a <CODE>svn commit</CODE>
-command, the client sends a tree-delta to the server, which can check
-for skeletal conflicts and reject the commit, before the client takes the
-time to transmit the (possibly large) textual changes.  This potentially
-saves quite a bit of network traffic.
-
-
-<P>
-In terms of XML, postfix text deltas are split into two parts.  The
-first part appears "in-line" and contains a reference ID.  The second
-part appears after the tree delta is complete.  Here's an example:
-
-
-
-<PRE>
- &#60;tree-delta&#62;
-   &#60;open name="foo.c"&#62;
-      &#60;file&#62;
-        &#60;text-delta-ref id="123"&#62;
-      &#60;/file&#62;
-   &#60;/open&#62;
-   &#60;add name="bar.c"&#62;
-      &#60;file&#62;
-        &#60;text-delta-ref id="456"&#62;
-      &#60;/file&#62;
-    &#60;/add&#62;
- &#60;/tree-delta&#62;
- &#60;text-delta id="123"&#62;<EM>data</EM>&#60;/text-delta&#62;
- &#60;text-delta id="456"&#62;<EM>data</EM>&#60;/text-delta&#62;
-</PRE>
-
-
-
-<H2><A NAME="SEC27" HREF="svn-design_toc.html#TOC27">Serializing Deltas via the "Editor" Interface</A></H2>
-
-<P>
-The static XML forms above are useful as an import/export format, and as
-a visualization aid, but we also need a way to express a delta as a
-<EM>series of operations</EM>, to implement directory tree diffing and
-patching.  Subversion defines a standard set of such operations in the
-vtable <CODE>svn_delta_edit_fns_t</CODE>, a set of function prototypes which
-anyone may implement (see <TT>`svn_delta.h'</TT>).
-
-
-<P>
-Each function in an instance of <CODE>svn_delta_editor_t</CODE>
-(colloquially known as an <EM>editor</EM>) implements some distinct subtask
-of editing a directory tree.  In fact, if you compare the editor
-function prototypes to the XML elements described previously, you'll
-notice a fairly strict correspondence: there's one function for
-replacing a directory, another function for replacing a file, one for
-adding a directory, another for adding a file, a function for deleting,
-and so on.
-
-
-<P>
-Although the editor interface was designed around the general idea of
-making changes to a directory tree, a specific implementation's behavior
-depends on its role.  For example, the versioning filesystem library
-offers an editor that creates new revisions, while the working copy
-library offers an editor that updates working copies.  And the network
-layer offers an editor that turns editing calls into wire protocol,
-which is then converted back into editing calls on the other side!  All
-of these different tasks can share a single interface, because they are
-all fundamentally about the same thing: expressing and applying
-differences between directory trees.
-
-
-<P>
-Like the XML forms, a series of editor calls must follow certain nesting
-conventions; these conventions are implicit in the interface, in that
-some of the functions take arguments that can only be obtained from
-previous calls to other editor functions.
-
-
-<P>
-Editors can best be understood by watching one work on a real directory
-tree.  For example:
-
-
-<P>
-Suppose that the user has made a number of local changes to her working
-copy and wants to commit them to the repository.  Let's represent her
-changes with the same tree-delta from a previous example.  Notice that
-she has also made textual modifications to <TT>`file3'</TT>; hence the
-in-line <CODE>&#60;text-delta&#62;</CODE>:
-
-
-
-<PRE>
-&#60;tree-delta&#62;
-  &#60;open name='dir1'&#62;
-    &#60;directory&#62;
-      &#60;tree-delta&#62;
-        &#60;open name='dir2'&#62;
-          &#60;directory ancestor='/dir1/dir3'&#62;
-            &#60;tree-delta&#62;
-              &#60;add name='file3'&#62;
-                &#60;file ancestor='/dir1/dir2/file3'&#62;
-                  &#60;text-delta&#62;<EM>data</EM>&#60;/text-delta&#62;
-                &#60;/file&#62;
-              &#60;/add&#62;
-            &#60;/tree-delta&#62;
-          &#60;/directory&#62;
-        &#60;/open&#62;
-        &#60;delete name='dir3'/&#62;
-        &#60;add name='dir4'&#62;
-          &#60;directory ancestor='/dir1/dir2'&#62;
-            &#60;tree-delta&#62;
-              &#60;delete name='file3'/&#62;
-            &#60;/tree-delta&#62;
-          &#60;/directory&#62;
-        &#60;/add&#62;
-      &#60;/tree-delta&#62;
-    &#60;/directory&#62;
-  &#60;/open&#62;
-&#60;/tree-delta&#62;
-</PRE>
-
-<P>
-So how does the client send this information to the server?
-
-
-<P>
-In a nutshell: the tree-delta is <EM>streamed</EM> over the network, as a
-series of individual commands given in depth-first order.
-
-
-<P>
-Let's be more specific.  The server presents the client with an object
-of type <CODE>struct svn_delta_edit_fns_t</CODE>, colloquially known as an
-<EM>editor</EM>.  An editor is really just table of functions; each
-function makes a change to a filesystem.  Agent A (who has a private
-filesystem) presents an editor to agent B.  Agent B then calls the
-editor's functions to change A's filesystem.  B is said to be
-<EM>driving</EM> the editor.
-
-
-<P>
-As Karl Fogel likes to describe the process, if one thinks of the
-tree-delta as a lion, the editor is a "hoop" that the lion jumps through
--- each portion of the lion being decomposed through time.
-
-
-<P>
-B cannot call the functions in any willy-nilly order; there are some
-logical restrictions.  In particular, as B drives the editor, it
-receives opaque data structures which represent directories and files.
-It must use and pass these structures, known as <EM>batons</EM>, to make
-further function calls.
-
-
-<P>
-As an example, let's watch how the client would transmit the above
-tree-delta to the repository.  (The description below is slightly
-simplified.  For exact interface details, see
-<TT>`subversion/include/svn_delta.h'</TT>.)
-
-
-<P>
-[Note:  in the examples below, and throughout Subversion's code base,
-you'll see references to 'baton' objects.  This is simply a project
-convention, a name given to structures that define contexts for
-functions.  Many APIs call these structures 'userdata'.  In
-Subversion, we like the term 'baton', because it reminds us of one
-function "handing off" context to another function.]
-
-
-
-<OL>
-
-<LI>
-
-The repository hands an "editor" to the client.
-
-<LI>
-
-The client begins by calling
-
-    <CODE>root_baton = editor-&#62;open_root();</CODE>
-
-The client now has an opaque object, <EM>root_baton</EM>, which represents
-the root of the repository's filesystem.
-
-<LI>
-
-<CODE>dir1_baton = editor-&#62;open_dir("dir1", root_baton);</CODE>
-
-Notice that <EM>root_baton</EM> gives the client free license to make any
-changes it wants in the repository's root directory -- until, of course,
-it calls <CODE>editor-&#62;close_dir(root_baton)</CODE>.
-
-The first change made was a replacement of <TT>`dir1'</TT>.  In return, the
-client now has a new opaque data structure that can be used to change
-<TT>`dir1'</TT>.
-
-<LI>
-
-<CODE>dir2_baton = editor-&#62;open_dir("dir2", "/dir1/dir3", dir1_baton);</CODE>
-
-The <EM>dir1_baton</EM> is now used to open <TT>`dir2'</TT> with a
-directory whose ancestor is <TT>`/dir1/dir3'</TT>.
-
-<LI>
-
-<CODE>file_baton = editor-&#62;add_file("file3", "/dir1/dir2/file3", dir2_baton);</CODE>
-
-Edits are now made to <TT>`dir2'</TT> (using <EM>dir2_baton</EM>).  In
-particular, a new file is added to this directory whose ancestor is
-<TT>`/dir1/dir2/file3'</TT>. 
-
-<LI>
-
-Now the text-delta associated with <EM>file_baton</EM> needs to be
-transmitted:
-
-  <CODE>window_handler = editor-&#62;apply_textdelta(file_baton);</CODE>
-
-Text-deltas themselves, for network efficiency, are streamed in
-"chunks".  So instead of receiving a baton object, we now have a routine
-that is able to receive any number of small "windows" of text-delta
-data.
-
-We won't go into the details of the <CODE>svn_txdelta_*</CODE> functions right
-here;  but suffice it to say that these routines are used for sending
-svndiff data to the <EM>window_handler</EM> routine.
-
-<LI>
-
-<CODE>editor-&#62;close_file(file_baton);</CODE>
-
-The client is done sending the file's text-delta, so it releases the
-file baton.
-
-<LI>
-
-<CODE>editor-&#62;close_dir(dir2_baton));</CODE>
-
-The client is done making changes to <TT>`dir2'</TT>, so it releases its
-baton as well.
-
-<LI>
-
-The client isn't yet finished with <TT>`dir1'</TT>, however; it makes two
-more edits:
-
-  <CODE>editor-&#62;delete_item("dir3", dir1_baton);</CODE> <BR>
-  <CODE>dir4_baton = editor-&#62;add_dir("dir4", "/dir1/dir2", dir1_baton);</CODE>
-
-<EM>(The function's name is <CODE>delete_item</CODE> rather than
-<CODE>delete</CODE> to avoid gratuitous incompatibility with C++, where
-<CODE>delete</CODE> is a reserved keyword.)</EM>
-
-<LI>
-
-Within the directory <TT>`dir4'</TT> (whose ancestry is <TT>`/dir1/dir2'</TT>),
-the client removes a file:
-
-  <CODE>editor-&#62;delete_item("file3", dir4_baton);</CODE>
-
-<LI>
-
-The client is now finished with both <TT>`dir4'</TT>, as well as its parent
-<TT>`dir1'</TT>:
-
-  <CODE>editor-&#62;close_dir(dir4_baton);</CODE> <BR>
-  <CODE>editor-&#62;close_dir(dir1_baton);</CODE>
-
-<LI>
-