readme

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

No whitespace (except for the terminating line feed) is allowed before
or after the number.  The changes in each format are listed in wc.h.

The rest of the file contains one record for each directory entry.
Each record contains a number of ordered fields as described below.
The fields are terminated by a line feed (0x0a) character.  Empty
fields are represented by just the terminator.  Empty fields that are
only followed by empty fields may be omited from the record.  Records
are terminated by a form feed (0x0c) and a cosmetic line feed (0x0a).

The bytes representing the characters "\" and ASCII control characters
(0x01 - 0x1f and 0x7f) must be escaped when they occur in a field.
The escaping uses the syntax "\xHH", where "HH" are the two
hexadecimal digits (either upper- or lowercase) representing the
escaped byte.  No other bytes may be escaped.  NUL bytes are not
allowed.

A field may be boolean, in which case it can have either a value equal
to the field name, meaning true, or no value, meaning false.  Timestamps
are stored in the format produced by svn_time_to_cstring().  Revision
numbers are stored as decimal numbers.

The first entry has an empty name field and is the entry for this directory,
that is, the directory containing this administrative area.  This is
known as the "this_dir" entry.

The following fields are allowed; they are present in the order in
which they are described.  Except for boolean fields, the field names
are not present in the file.

name:
   The basename of this entry, or the empty string for the this_dir
   entry.  Required for all entries.

kind:
   The kind of this entry: `file' or `dir'.  Required for all entries. 

revision:
   The revision that the pristine text and properties of this entry
   represent.  Defaults to the revision of the this_dir entry, for
   which it is required.  Set to 0 for entries not yet in the
   repository.

url:
   The URL of the corresponding entry in the repository.  Required
   for the this_dir entry; for all other entries, the default is to
   append the URI-encoded entry name to the URL of the this_dir entry,
   as a path segment.

repos:
   The prefix of the URL which represents the repository root of this
   entry.  Defaults to the repository root of the this_dir entry.
   Optional for the this_dir entry, for compatibility.

schedule:
   The current scheduling for this entry: `add', `delete' or
   `replace'.  Defaults to normal scheduling.

text-time:
   For file entries, the timestamp of the working file when it was
   last known to be identical to the text base file.  Optional, no default.

checksum:
   For file entries, base-64-encoded MD5 checksum of the text-base
   file.  Optional, for backwards compatibility.

committed-date:
   The date of the committed-rev if available.  Optional, no default.

committed-rev:
   The last committed revision for this entry if this entry is in the
   repository.  Optional, no default.

last-author:
   The author of the `committed-rev' if available.  Optional, no default.

has-props:
   A boolean: true if there are any working properties for this entry.

has-prop-mods:
   A boolean: true if this entry has any property modifications.

cachable-props:
   A space-separated list of property names whose presence is cached
   in present-props.  Defaults to the value of the this_dir entry.
   For the this_dir entry, defaults to the empty list. 

present-props:
   A space-separated list of property names.  If a property name n is
   in this list, then the working props of this entry contains this
   property.  If cachable-props contains a property name n' but n' is
   absent from present-props, then the working props don't contain
   this property.  Defaults to the empty list.

conflict-old, conflict-new and conflict-wrk:
   Present if there is a text conflict, in which case these three
   fields specify the relative filenames of the three saved
   conflict files.

prop-reject-file:
   In case of a property conflict, this field is present and
   specifies the relative filename of the property reject file.

copied:
   A boolean: true if this entry was added with history; only allowed
   when schedule is add.  (### Why aren't the copyfrom attributes
   enough for this?)

copyfrom-url:
   If this entry is added with history, the URL of the copy source.
   Present iff copyfrom-rev is present.

copyfrom-rev:
   If this entry is added with history, the revision of the copy
   source.  Present iff copyfrom-url is present.

deleted:
   A boolean: true if this entry is deleted in its revision but exists
   in its parent's revision.  This is necessary because updates are
   not atomic: different bits of a working copy can be updated to
   different revisions at different times, and it's possible that
   this entry may be updated to a more recent revision (R) than its
   parent's revision (P).  If this entry is deleted in R, and the
   parent is trying to report its own state (based on P) to the
   repository, the parent cannot simply claim to be at P; the parent
   must also indicate that this particular entry is deleted because it
   is at R.

absent:
   A boolean: true if is an entry by this name in the repository but
   we don't know anything about it except its kind.

incomplete:
   A boolean: true if this entries file is not complete yet.  Used
   when updating.  This is only allowed on the this_dir entry; it
   allows update operations to be non-atomic, by marking the directory
   as still in the process of being updated.  If this update is
   interrupted for some reason, a later update will see that this
   directory is incomplete and Do The Right Thing.

uuid:
   The repository UUID of this entry.  Defaults to the UUID of the
   this_dir entry.  Optional, even for the this_dir entry, for
   backwards compatibility.

lock-token:
   The lock token URL if this entry is locked in the repository;
   absent otherwise.

lock-owner:
   The lock owner, iff there is a lock token.

lock-comment:
   The lock comment iff there is a lock token and the lock has a
   comment.

lock-creation-date:
   The lock creation date iff there is a lock token.

The only fields allowed in an entry for a directory (other than the
this_dir entry) are name, absent, deleted, schedule, copied,
copyfrom-url, copyfrom-rev and kind.  The other fields are only stored
in the this_dir entry for the directory in question.


XML-based entries format
------------------------

In format 6 and earlier, the entries file is stored in an XML based
format.  The entries file is an XML document with a top-level element
named `wc-entries'.  This element contains one or more `entries'
elements, one for each directory entry.  All XML elements in the
entries file are in the XML namespace "svn:".

All `entry' elements are empty, and can have the attributes
corresponding to fields of the non-XML format.

An attribute may be boolean, in which case it can have one of the
values `true' or `false'.  Boolean attributes default to `false' if
not present.  Timestamps are stored in the same format as in the
non-XML format.  Inheritence of values from the this_dir entry works
in the same way as in the non-XML format.

Fields added in format 7 and later are not allowed in the XML-based
format.  The attributes `has-props', `has-prop-mods', `cachable-props', 
and `present-props' are only valid in format 6.

In addition, the following attribute is allowed, which has no
corresponding field in the non-XML format:

`prop-time':
   Obsolete.  In format 5 and earlier this was similar to `text-time',
   but for the working props file.



Property storage
----------------

For each entry, there may be one base and one working properties file.
For files, these are named .svn/prop-base/foo.svn-base and
.svn/props/foo.svn-work, respectively.  For directories, these are
stored directly under .svn in .svn/dir-prop-base and .svn/dir-props,
respectively.  Property files are in the hashdump format produced by
svn_hash_write().  If the file contains no properties, it is either
empty or contains just the "END\n" delimiter.  The way properties are
stored changed in format 6; that way is described first.

In format 6 and later, the base-props file is present only if there
are any base properties.  The working props file is present only if
the entry has property modifications (i.e. its has-prop-mods
field is true).  Note that an existing, but empty working props
file means that there are property modifications, but no working
properties.

In formats 5 and earlier, base-props are handled the same, but a
non-existent working props file is equivalent to an empty file and the
working props file always contains the working properties.  The
`prop-time' attribute can be used to optimize detection of property
modifications.

In format 8 and beyond, wcprops are stored in a file called all-wcprops.
This file need not exist if no entry in the directory has any wcprops.
The file starts with all wcprops for the this_dir entry in hashdump format.
Then comes, for each entry that has wcprops, a line containing the basename
of the entry followed by the wcprops for that entry in hashdump format.

In format 7 and earlier, wcprops are stored in a similar fashion to
how base-props are stored, but they use .svn/dir-wcprops and
.svn/wcprops/foo.svn-work names for directory and file properties,
respectively.


How the client applies an update delta
--------------------------------------

Updating is more than just bringing changes down from the repository;
it's also folding those changes into the working copy.  Getting the
right changes is the easy part -- folding them in is hard.

Before we examine how Subversion handles this, let's look at what CVS
does:

   1. Unmodified portions of the working copy are simply brought
      up-to-date.  The server sends a forward diff, the client applies
      it.

   2. Locally modified portions are "merged", where possible.  That
      is, the changes from the repository are incorporated into the
      local changes in an intelligent way (if the diff application
      succeeds, then no conflict, else go to 3...)

   3. Where merging is not possible, a conflict is flagged, and *both*
      sides of the conflict are folded into the local file in such a
      way that it's easy for the developer to figure out what
      happened.  (And the old locally-modified file is saved under a
      temp name, just in case.)

It would be nice for Subversion to do things this way too;
unfortunately, that's not possible in every case.

CVS has a wonderfully simplifying limitation: it doesn't version
directories, so never has tree-structure conflicts.  Given that only
textual conflicts are possible, there is usually a natural way to
express both sides of a conflict -- just include the opposing texts
inside the file, delimited with conflict markers.  (Or for binary
files, make both revisions available under temporary names.)

While Subversion can behave the same way for textual conflicts, the
situation is more complex for trees.  There is sometimes no way for a
working copy to reflect both sides of a tree conflict without being
more confusing than helpful.  How does one put "conflict markers" into
a directory, especially when what was a directory might now be a file,
or vice-versa?

Therefore, while Subversion does everything it can to fold conflicts
intelligently (doing at least as well as CVS does), in extreme cases
it is acceptable for the Subversion client to punt, saying in effect
"Your working copy is too out of whack; please move it aside, check
out a fresh one, redo your changes in the fresh copy, and commit from
that."  (This response may also apply to subtrees of the working copy,
of course).

Usually it offers more detail than that, too.  In addition to the
overall out-of-whackness message, it can say "Directory foo was
renamed to bar, conflicting with your new file bar; file blah was
deleted, conflicting with your local change to file blah, ..." and so
on.  The important thing is that these are informational only -- they
tell the user what's wrong, but they don't try to fix it
automatically.

All this is purely a matter of *client-side* intelligence.  Nothing in
the repository logic or protocol affects the client's ability to fold
conflicts.  So as we get smarter, and/or as there is demand for more
informative conflicting updates, the client's behavior can improve and
punting can become a rare event.  We should start out with a _simple_
conflict-folding algorithm initially, though.


Text and Property Components
----------------------------

A Subversion working copy keeps track of *two* forks per file, much
like the way MacOS files have "data" forks and "resource" forks.  Each
file under revision control has its "text" and "properties" tracked
with different timestamps and different conflict (reject) files.  In
this vein, each file's status-line has two columns which describe the
file's state.

Examples:

  --  glub.c      --> glub.c is completely up-to-date.
  U-  foo.c       --> foo.c's textual component was updated.
  -M  bar.c       --> bar.c's properties have been locally modified
  UC  baz.c       --> baz.c has had both components patched, but a
                      local property change is creating a conflict.