readme

linux subdivision ying gai ke yi le ba

   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 file is removed.

   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.

   Probably the same routine will be used by finish_file() and in
   crash recovery.

   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.  When it needs a *very* temporary file for
   something in .svn (such as when local changes during an update), use
   tmp/.svn/blah$PID.tmp.  Since no .svn/ file ever has a .blah
   extension, if something ends in .*, then it must be a tmp file.

   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.

`prop-base/'

   Pristine repos properties for those files, in hashdump format.
   todo: may also store dirent props here, lots of good formats for
   mixing those two, would pick one when we implement the dirent
   props.  Or may store them some other way; think this will be best
   answered after having the rest of the library working.

`props/'

   The non-pristine (working copy) of each file's properties.  These
   are where local modifications to properties live.

   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 will work
   sufficiently, but shouldn't be abused.  They'll work fine for
   storing information like ACLs, permissions, ownership, and notes;
   but users shouldn't be trying to store 30 meg PNG files.  :)

'wcprops/' and 'dir-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.  Nor do we
   paranoid-ly move them through .svn/tmp/ when changing them.  These
   sorts of behaviors are meant for preserving sacred user data,
   especially local modifications.  wcprops, on the other hand, are
   just internal tracking data used by the system, like the 'entries'
   file.

------------------------
todo: some loose ends

   1. filename escaping in .svn/entries
   2. 



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.