readme

subversion-1.4.3-1.tar.gz 配置svn的源码

     Oh Most High and Fragrant Emacs, please be in -*- text -*- mode!

This is the library described in the section "The working copy
management library" of svn-design.texi.  It performs local operations
in the working copy, tweaking administrative files and versioned data.
It does not communicate directly with a repository; instead, other
libraries that do talk to the repository call into this library to
make queries and changes in the working copy.


The Problem We're Solving
-------------------------

The working copy is arranged as a directory tree, which, at checkout,
mirrors a tree rooted at some node in the repository.  Over time, the
working copy accumulates uncommitted changes, some of which may affect
its tree layout.  By commit time, the working copy's layout could be
arbitrarily different from the repository tree on which it was based.

Furthermore, updates/commits do not always involve the entire tree, so
it is possible for the working copy to go a very long time without
being a perfect mirror of some tree in the repository.


One Way We're Not Solving It
----------------------------

Updates and commits are about merging two trees that share a common
ancestor, but have diverged since that ancestor.  In real life, one of
the trees comes from the working copy, the other from the repository.
But when thinking about how to merge two such trees, we can ignore the
question of which is the working copy and which is the repository,
because the principles involved are symmetrical.

Why do we say symmetrical?

It's tempting to think of a change as being either "from" the working
copy or "in" the repository.  But the true source of a change is some
committer -- each change represents some developer's intention toward
a file or a tree, and a conflict is what happens when two intentions
are incompatible (or their compatibility cannot be automatically
determined).

It doesn't matter in what order the intentions were discovered --
which has already made it into the repository versus which exists only
in someone's working copy.  Incompatibility is incompatibility,
independent of timing.

In fact, a working copy can be viewed as a "branch" off the
repository, and the changes committed in the repository *since* then
represent another, divergent branch.  Thus, every update or commit is
a general branch-merge problem:

   - An update is an attempt to merge the repository's branch into the
     working copy's branch, and the attempt may fail wholly or
     partially depending on the number of conflicts.

   - A commit is an attempt to merge the working copy's branch into
     the repository.  The exact same algorithm is used as with
     updates, the only difference being that a commit must succeed
     completely or not at all.  That last condition is merely a
     usability decision: the repository tree is shared by many
     people, so folding both sides of a conflict into it to aid
     resolution would actually make it less usable, not more.  On the
     other hand, representing both sides of a conflict in a working
     copy is often helpful to the person who owns that copy.

So below we consider the general problem of how to merge two trees
that have a common ancestor.  The concrete tree layout discussed will
be that of the working copy, because this library needs to know
exactly how to massage a working copy from one state to another.


Structure of the Working Copy
-----------------------------

Working copy meta-information is stored in .svn/ subdirectories,
analogous to CVS/ subdirs.  See the separate sections below for more details.

  .svn/format                   /* Deprecated in post 1.3 working copies. */
       entries                  /* Various adm info for each directory entry */
       dir-props                /* Working properties for this directory */
       dir-prop-base            /* Pristine properties for this directory */
       dir-prop-revert          /* Dir base-props for revert, if any */
       lock                     /* If existent, tells others this dir is busy
                                   */
       log                      /* Operations log, if any (for rollback
                                   crash-recovery) */
       log.N                    /* Additional ops logs (N is an integer
                                   >= 1) */
       text-base/               /* Pristine repos revisions of the files... */
            foo.c.svn-base      /* Repos revision of foo.c. */
            foo.c.svn-revert    /* Text-base used when reverting, if any. */
       props/                   /* Working properties for files in this dir */
            foo.c.svn-work      /* Stores foo.c's working props */
       prop-base/               /* Pristine properties for files in this dir */
            foo.c.svn-base      /* Stores foo.c's pristine props */
            foo.c.svn-revert       /* Props base when reverting, if any */
       wcprops/                 /* Obsolete in format 7 and beyond. */
            foo.c.svn-work
       dir-wcprops              /* Obsolete in format 7 and beyond.
       all-wcprops              /* Special 'wc' props for files in this dir */
       tmp/                     /* Local tmp area */
            ./                  /* Adm files are written directly here */
            text-base/          /* tmp area for base files */
            prop-base/          /* tmp area for base props */
            props/              /* tmp area for props */
       empty-file               /* Obsolete, no longer used, not present in
                                   post-1.3 working copies */

`format':
   Says what version of the working copy adm format this is (so future
   clients can be backwards compatible easily).

   This file is deprecated and present for backwards compatibility.
   It may be removed in the future.

`entries':
   This file holds revision numbers and other information for this
   directory and its files, and records the presence of subdirs (but
   does not record much other information about them, as the subdirs
   do that themselves).  See below for more information.

   Since format 7, this file also contains the format number of this
   working copy directory.

   Also, the presence of this file means that the entire process of
   creating the adm area was completed, because this is always the
   last file created.  Of course, that's no guarantee that someone
   didn't muck things up afterwards, but it's good enough for
   existence-checking.

`dir-props':
   Properties for this directory.  These are the "working" properties
   that may be changed by the user.

`dir-prop-base':
   Same as `dir-props', except this is the pristine copy;  analogous to
   the "text-base" revisions of files.  The last up-to-date copy of the
   directory's properties live here. 

`dir-prop-revert':
   In a schedule-replace situation for this directory, this holds the
   base-props for the deleted version of the directory (i.e., the
   version that is being replaced).  If this file doesn't exist, the
   `dir-prop-base' file is used.

`lock':
   Present if some client is using this .svn/ subdir for anything that
   requires write access.

`log' and `log.N':
   These files (XML fragments) hold a log of actions that are about to be
   done, or are in the process of being done.  Each action is of the
   sort that, given a log entry for it, either it is okay to do the
   action again (i.e., the action is idempotent), or else one can tell
   unambiguously whether or not the action was successfully done.
   Thus, in recovering from a crash or an interrupt, the wc library
   reads over the log file, ignoring those actions that have already
   been done, and doing the ones that have not.  When all the actions
   in log have been done, the log files are removed.

   Some operations produce more than one log file.  The first log file
   is named `log', the next `log.1' and so on.  Processing the log
   files starts at `log' and stops after `log.N' when there is no `log.N+1'
   (counting the first log file as `log.0'; it is named `log' for
   compatibility.)

   Soon there will be a general explanation/algorithm for using the
   log file; for now, this example gives the flavor:

   To do a fresh checkout of `iota' in directory `.'

      1. add_file() produces the new ./.svn/tmp/.svn/entries, which
         probably is the same as the original `entries' file since
         `iota' is likely to be the same revision as its parent
         directory.  (But not necessarily...)

      2. apply_textdelta() hands window_handler() to its caller.

      3. window_handler() is invoked N times, constructing
         ./.svn/tmp/iota

      4. finish_file() is called.  First, it creates `log' atomically,
         with the following items,

            <mv src=".svn/tmp/iota" dst=".svn/text-base/iota">
            <mv src=".svn/tmp/.svn/entries" dst=".svn/entries">
            <merge src=".svn/text-base/iota" dst="iota">

         Then it does the operations in the log file one by one.
         When it's done, it removes the log.

   To recover from a crash:

      1. Look for a log file.  

           A. If none, just "rm -r tmp/*".

           B. Else, run over the log file from top to bottom,
              attempting to do each action.  If an action turns out to
              have already been done, that's fine, just ignore it.
              When done, remove the log file.


   Note that foo/.svn/log always uses paths relative to foo/, for
   example, this:
   
       <!-- THIS IS GOOD -->
       <mv name=".svn/tmp/prop-base/name"
           dest=".svn/prop-base/name">
           
   rather than this:

       <!-- THIS WOULD BE BAD -->
       <mv name="/home/joe/project/.svn/tmp/prop-base/name"
           dest="/home/joe/project/.svn/prop-base/name">

   or this:

       <!-- THIS WOULD ALSO BE BAD -->
       <mv name="tmp/prop-base/name"
           dest="prop-base/name">

   The problem with the second way is that is violates the
   separability of .svn subdirectories -- a subdir should be operable
   independent of its location in the local filesystem.  

   The problem with the third way is that it can't conveniently refer
   to the user's actual working files, only to files inside .svn/.

`tmp':
   A shallow mirror of the working directory (i.e., the parent of the
   .svn/ subdirectory), giving us reproducible tmp names.

   When the working copy library needs a tmp file for something in the
   .svn dir, it uses tmp/thing, for example .svn/tmp/entries, or
   .svn/tmp/text-base/foo.c.svn-base.  When temp file with a unique name
   is needed, use the `.tmp' extension to distinguish it from temporary
   admin files with well-known names.

   See discussion of the `log' file for more details.

`text-base/':
   Each file in text-base/ is a pristine repository revision of that
   file, corresponding to the revision indicated in `entries'.  These
   files are used for sending diffs back to the server, etc.

   A file named `foo.c' in the working copy will be named `foo.c.svn-base'
   in this directory.

   For a file scheduled for replacement, the text-base of the deleted
   entry may be stored in `foo.c.svn-revert'.

`prop-base/':
   Pristine repos properties for those files, in hashdump format.  Named
   with the extension `.svn-base'.

   For an entry scheduled for replacement, the text-base of the deleted
   entry may be stored in `foo.c.svn-revert'.

   
`props/':
   The non-pristine (working copy) of each file's properties.  These
   are where local modifications to properties live.  The files in this
   directory are given `.svn-work' extensions.

   Notice that right now, Subversion's ability to handle metadata
   (properties) is a bit limited:

   1. Properties are not "streamy" the same way a file's text is.
      Properties are held entirely in memory.

   2. Property *lists* are also held entirely in memory.  Property
      lists move back and forth between hashtables and our disk-based
      `hashdump' format.  Anytime a user wishes to read or write an
      individual property, the *entire* property list is loaded from
      disk into memory, and written back out again.  Not exactly a
      paradigm of efficiency!

   In other words, for Subversion 1.0, properties work sufficiently,
   but shouldn't be abused.  They work fine for storing information
   like ACLs, permissions, ownership, and notes; but users shouldn't
   be trying to store 30 meg PNG files.  :)

'all-wcprops/':
   Some properties are never seen or set by the user, and are never
   stored in the repository filesystem.  They are created by the
   networking layer (DAV right now) and need to be secretly saved and
   retrieved, much like a web browser stores "cookies".  Special wc
   library routines allow the networking layer to get and set these
   properties.  

   Note that because these properties aren't being versioned, we don't
   bother to keep pristine forms of them in a 'base' area.

`empty-file':
   This file was added in format 4 and earlier.  This was used to
   create file diffs against the empty file (i.e. for adds and
   deletes).

`README':
   This file was removed in format 5.  It used to contain a short text
   saying what this directory is for and warning users not to alter
   its contents.
   
The entries file
----------------

This section describes the entries file as of format 7 and beyond.  See below
for the older XML-based format.

The entries file is a text file.  The character encoding of the file
is UTF-8 with no BOM (byte order mark) allowed at the beginning.  All
whitespace is significant.

The file starts with a decimal number which is the format version of
this working copy directory, followed by a line feed (0x0a) character.