Documenting WORKING.presence = 'incomplete'...
I understand 'incomplete' means the same as 'normal' except that the
node's children are not (known to be) all present and complete.
Bert responded, "Yes on the incomplete part. (But it also applies to the
properties on the directory). At least for editor v1. gstein has some
slightly other ideas about incomplete, but this is how we handle it
now."
I'm not going to consider the "slightly other ideas" in this email. But
what about incomplete properties?
Should we be able to create a WORKING directory node before we know its
properties? (Yes, I believe we do want to be able to do this.) If so,
should we represent it with
presence = incomplete, or
properties = NULL, or
presence = incomplete and properties = NULL
?
Also, should 'incomplete' be allowed to describe a file? A symlink?
My take on this is that we should keep the meanings of the columns
orthogonal as much as possible. At the DB schema level, there's no
reason why files, dirs and sym-links should not all have props and
should not all be able to be incomplete in the sense of not having their
props yet. The higher level code might want to avoid ever having
incomplete file, or props on a symlink, but that's doesn't reduce the
benefit of keeping the schema meanings orthogonal. And there's no reason
to have more than one way of representing 'props are unknown'.
So let's specify:
* presence = 'incomplete' just refers to children when this is a
directory. (It does not mean anything about properties.)
* 'properties' is NULL if the properties of this node are not (yet)
known. ('properties' is an empty skel if there are no properties.)
Good?
Patch (I would strip out the '###' lines):
[[[
* subversion/libsvn_wc/wc-metadata.sql
(WORKING_NODE): Clarify doc strings on 'presence' and 'properties'
with respect to representing a node incompletely.
Index: subversion/libsvn_wc/wc-metadata.sql
===================================================================
--- subversion/libsvn_wc/wc-metadata.sql (revision 912547)
+++ subversion/libsvn_wc/wc-metadata.sql (working copy)
@@ -249,6 +249,16 @@
Scan upwards from here looking for copyfrom or moved_here values
to detect the type of operation constructing this node.
+ incomplete: the same as 'normal', but this is a directory and the rows
+ describing its children are not (yet) known to be all present and
+ complete. This enables the result of an interrupted copy, for
+ instance, to be represented without needing to have 'dangling
+ children' hanging around in the database without their parents.
+ ### If 'properties' not yet filled in, do we use 'incomplete' or
+ ### 'properties = NULL' or both? If the meaning involves properties,
+ ### is it applicable just to a dir or also to a file? a symlink?
+ ### I suggest making it orthogonal: don't involve properties here.
+
not-present: the node (or parent) was originally copied or moved-here.
A subtree of that source has since been deleted. There may be
underlying BASE node to replace. For a move-here or copy-here, the
@@ -259,9 +269,6 @@
nodes were plain adds, those nodes would be shifted to that target
for addition.
- incomplete: nodes are being added into the WORKING tree, and the full
- information about this node is not (yet) present.
-
base-deleted: the underlying BASE node has been marked for deletion due
to a delete or a move-away (see the moved_to column to determine
which), and has not been replaced. */
@@ -333,8 +340,9 @@
### 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. NULL if we
- have no information about the properties (a non-present node). */
+ /* A serialized skel of this node's properties. An empty skel if there are
+ no properties. NULL if we have no information (yet) about the
+ properties or if it is a non-present node. */
properties BLOB,
/* should the node on disk be kept after a schedule delete?
]]]
- Julian
