[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: [PATCH] Tweak description of BASE_NODE table

From: Julian Foad <julian.foad_at_wandisco.com>
Date: Mon, 16 Aug 2010 13:42:32 +0100

On Thu, 2010-08-12, Greg Stein wrote:
> Looks good!

Committed. Now I'm trying to understand and document BASE_NODE (first)
in more detail. Then I/we can tackle the other tables, and especially
it should give me (and anyone else who may be struggling to follow) a
starting point for understanding the NODE_DATA change.

I want to help write a top-down description that new developers can
understand, and at the same time I'm aiming for something we can use as
a *definitive* specification when it comes to deciding what's a bug,
writing unit tests, etc., so it must not gloss over any important
details.

My starting point is trying to describe what I think it means now. I
haven't tested each statement against current behaviour. If we find any
unnecessary quirks and exceptions, I want to first document them as
such, and then we can decide whether and when to eliminate them.

Are any parts of this inaccurate?

[[[
Index: subversion/libsvn_wc/wc-metadata.sql
===================================================================
/home/julianfoad/bin/svn-external-diff: warning: files are different types: text/x-c; charset=us-ascii text/x-lisp; charset=us-ascii
--- subversion/libsvn_wc/wc-metadata.sql (revision 985836)
+++ subversion/libsvn_wc/wc-metadata.sql (working copy)
@@ -73,21 +73,111 @@ CREATE TABLE WCROOT (
 
 CREATE UNIQUE INDEX I_LOCAL_ABSPATH ON WCROOT (local_abspath);
 
 
 /* ------------------------------------------------------------------------- */
 
+/*
+The BASE_NODE table:
+
+ BASE is what we get from the server. It is the *absolute* pristine copy.
+ You need to use checkout, update, switch, or commit to alter your view of
+ the repository.
+
+ In the BASE tree, each node corresponds to a particular node-rev in the
+ repository. It can be a mixed-revision tree. Each node holds either a
+ copy of the node-rev as it exists in the repository (if presence ==
+ 'normal'), or a place-holder (if presence == 'absent' or 'excluded' or
+ 'not-present').
+ [Quoted from wc_db.h]
+
+Overview of BASE_NODE columns:
+
+ Indexing columns: (wc_id, local_relpath, parent_relpath)
+
+ (presence)
+ - One of the following values:
+
+ 'presence' Meaning Node-Rev? Content? Last-Change?
+ ---------- ----------- ----------- -------- ------------
+ normal => Present Existing Yes Yes
+ absent => Unauthz Existing No No
+ excluded => Unwanted Existing No No
+ not-pres => Nonexistent Nonexistent No No
+ incomplete => ### undefined
+
+ Node-Rev columns: (repos_id, repos_relpath, revnum)
+ - Always points to the corresponding repository node-rev.
+ - Points to an existing node-rev, unless presence==not-present in which
+ case it points to a nonexistent node-rev.
+ - ### A comment on 'repos_id' and 'repos_relpath' says they may be null;
+ is this true and wanted?
+ - ### A comment on 'revnum' says, "this could be NULL for non-present
+ nodes -- no info"; is this true and wanted?
+
+ Content columns: (kind, properties, depth, target, checksum)
+ - One of: ---- ---------- ----- ------ --------
+ 'dir' Yes Yes null null
+ 'symlink' Yes null Yes null
+ 'file' Yes null null Yes
+ 'unknown' null null null null
+ - Content is present iff presence==normal, otherwise kind=unknown and
+ the other columns are null.
+ - If kind==dir: the children are represented by the existence of other
+ BASE_NODE rows. For each immediate child of 'repos_relpath'@'revnum'
+ that is included by 'depth', a BASE_NODE row exists with its
+ 'local_relpath' being this node's 'local_relpath' plus the child's
+ basename. (Rows may also exist for additional children which are
+ outside the scope of 'depth' or do not exist as children of this
+ node-rev in the repository, including 'externals' and paths updated to
+ a revision in which they do exist.) There is no distinction between
+ depth=immediates and depth=infinity here.
+ - If kind==symlink: the target path is contained in 'target'.
+ - If kind==file: the content is contained in the Pristine Store,
+ referenced by its SHA-1 checksum 'checksum'.
+
+ Last-Change columns: (changed_rev, changed_date, changed_author)
+ - Last-Change info is present iff presence==normal, otherwise null.
+ - Specifies the revision in which the content was last changed before
+ Node-Rev, following copies and not counting the copy operation itself
+ as a change.
+ - Does not specify the revision in which this node first appeared at
+ the repository path 'repos_relpath', which could be more recent than
+ the last change of this node's content.
+ - Includes a copy of the corresponding date and author rev-props.
+
+ Working file status: (translated_size, last_mod_time)
+ - Present iff kind==file and node has no WORKING_NODE row, otherwise
+ null. (If kind==file and node has a WORKING_NODE row, the info is
+ recorded in that row). ### True?
+ - Records the status of the working file on disk, for the purpose of
+ detecting quickly whether that file has been modified.
+ - Logically belongs to the ACTUAL_NODE table but is recorded in the
+ BASE_NODE and WORKING_NODE tables instead to avoid the overhead of
+ storing an ACTUAL_NODE row for each unmodified file.
+ - Records the actual size and mod-time of the disk file at the time when
+ its content was last determined to be logically unmodified relative to
+ its base, taking account of keywords and EOL style.
+
+ (dav_cache)
+
+ (incomplete_children)
+ - Obsolete, unused.
+
+ (file_external)
+*/
+
 CREATE TABLE BASE_NODE (
   /* specifies the location of this node in the local filesystem. wc_id
      implies an absolute path, and local_relpath is relative to that
      location (meaning it will be "" for the wcroot). */
   wc_id INTEGER NOT NULL REFERENCES WCROOT (id),
   local_relpath TEXT NOT NULL,
 
- /* the repository this node is part of, and the relative path [to its
- root] within revision "revnum" of that repository. These may be NULL,
+ /* The repository this node is part of, and the relative path (from its
+ root) within revision "revnum" of that repository. These may be NULL,
      implying they should be derived from the parent and local_relpath.
      Non-NULL typically indicates a switched node.
 
      Note: they must both be NULL, or both non-NULL. */
   repos_id INTEGER REFERENCES REPOSITORY (id),
   repos_relpath TEXT,
@@ -109,20 +199,18 @@ CREATE TABLE BASE_NODE (
      this could be NULL for non-present nodes -- no info. */
   revnum INTEGER,
 
   /* If this node is a file, then the SHA-1 checksum of the pristine text. */
   checksum TEXT,
 
- /* The size in bytes of the working file when it had no local text
- modifications. This means the size of the text when translated from
- repository-normal format to working copy format with EOL style
- translated and keywords expanded according to the properties in the
- "properties" column of this row.
+ /* The size in bytes of the working file when it was last determined to be
+ logically unmodified relative to its base, taking account of keywords
+ and EOL style.
 
- NULL if this node is not a file or if the size has not (yet) been
- computed. */
+ NULL if this node is not a file or if this info has not yet been
+ determined. */
   translated_size INTEGER,
 
   /* Information about the last change to this node. changed_rev must be
      not-null if this node has presence=="normal". changed_date and
      changed_author may be null if the corresponding revprops are missing.
 
@@ -134,18 +222,25 @@ CREATE TABLE BASE_NODE (
   /* NULL depth means "default" (typically svn_depth_infinity) */
   depth TEXT,
 
   /* for kind==symlink, this specifies the target. */
   symlink_target TEXT,
 
+ /* The mod-time of the working file when it was last determined to be
+ logically unmodified relative to its base, taking account of keywords
+ and EOL style.
+
+ NULL if this node is not a file or if this info has not yet been
+ determined.
+ */
   /* ### Do we need this? We've currently got various mod time APIs
      ### internal to libsvn_wc, but those might be used in answering some
      ### question which is better answered some other way. */
   last_mod_time INTEGER, /* an APR date/time (usec since 1970) */
 
- /* serialized skel of this node's properties. could be NULL if we
+ /* serialized skel of this node's properties. NULL if we
      have no information about the properties (a non-present node). */
   properties BLOB,
 
   /* serialized skel of this node's dav-cache. could be NULL if the
      node does not have any dav-cache. */
   dav_cache BLOB,

]]]

wc-metadata.sql looks like a good home for this documentation for the
time being. Perhaps it will eventually live separately.

- Julian
Received on 2010-08-16 14:43:20 CEST

This is an archived mail posted to the Subversion Dev mailing list.