Eric S. Raymond wrote on 2020-12-22:
> As promised, I have updated notes/dump-load-format.txt with the
> information in the ewplies to my recent query.
Thanks.
[...]
> === Unresolved questions ===
>
> 1. In interpreting a Node record which has both a copyfrom source and
> a property section, it is possible that the copy source node itself
> has a property section. How are they to be combined?
They are combined analogous to how the text section is combined. That is, start
with the copy source's properties section (which may be empty), and then
according to the current record's properties section (if present), either
replace it (if a non-delta) or modify it (if a delta).
One could probably describe this principle well by changing "text section" to
"text section and/or properties section" wherever applicable, e.g., in section
"The kinds of operations", in sentences like "Node records can carry content
... from a text section or from a copy source".
> 2. The section on the semantics of kinds of operations documents a
> minor bug at r39883 in the behavior of "add". Has this been fixed?
I don't know, and can't find a relevant issue filed.
> It'd be nice if we could dispose of these.
In case you are interested in reviewing some other tweaks to the document, I
attach a diff I made a long time ago which attempts mostly minor
clarifications, with a few small substantive changes and a few questions among
them. Changes that we both agree on could go in.
--
- Julian
Index: notes/dump-load-format.txt
===================================================================
--- notes/dump-load-format.txt (revision 1852475)
+++ notes/dump-load-format.txt (working copy)
@@ -127,9 +127,15 @@
A Node record describes an action on a path relative to the repository
root, and always begins with the Node-path specification.
+The Node-path line gives the path of the node, relative to the root of
+the repository. Writers should write a canonical relpath; readers should
+accept a non-canonical path (but without any '..' segments).
+
The Node-kind line indicates whether the path is a file or directory.
The header value will be one of the strings "file" or "dir".
This header may be (and usually is) absent if the node action is a delete.
+If the node action is a replace, this header describes the kind of the new
+node, and the kind of the old node is not described.
The Node-action line is always present and specifies the type of
operation for this node. The header value is one of the strings
@@ -139,7 +145,7 @@
Either both the Node-copyfrom-rev and Node-copyfrom-path lines will be
present, or neither will be. They pair to describe a copy source for
the node. Copy-source semantics will be described in detail later in
-this document.
+this document. The path format rules are as for the 'Node-path' line.
The Text-content-{md5,sha1} and Text-copy-source-{md5,sha1} lines are
hash integrity checks and will be present only if Text-content-length
@@ -148,9 +154,12 @@
corrupted.
Text-content-length will be present only when there is a text section.
-Zero is a legal value for this length, indicating an empty file.
+Zero is a legal value for this length, at least in non-delta dumps when
+it indicates an empty file.
Prop-content-length will be present only when there is a properties section.
+Zero is a legal value for this length, at least in non-delta dumps when
+it indicates an empty set of properties.
Content-length will be present if there is either a text or a
properties section. This is not always the case. In particular,
@@ -203,8 +212,8 @@
properties, content, and flows. The distinctions among content,
paths, and flows matter for understanding some operations.
-A path is a filesystem location (a file or directory). There are two
-kinds of paths in a dumpfile; node paths and copy sources.
+A path is the location of a file or directory in a filesystem. Paths
+appear in two places in a dumpfile: node paths and copy sources.
Properties are key-value pairs associated with revisions or paths.
Subversion interprets and reserves some properties, those beginning
@@ -227,8 +236,9 @@
A Node record describes a change in properties, the addition or deletion
of a flow, or a change in content. It must do at least one of these things,
otherwise it would be a no-op and omitted.
+### A no-op change is possible, at least in Subversion 1.8.
-When no copyfrom is present, and the action isn't an add or copy, then
+When no copyfrom is present, and the action isn't an add or replace[?], then
the kind of the thing identified by (PATH, REVISION) must agree with
the kind of the thing identified by (PATH, -1+REVISION).
@@ -272,32 +282,34 @@
section or from a copy source (that is, a copy-path and copy-revision
pair).
-Giving a copy source appends the node to the flow of which that source
+Giving a copy source attaches the node to the flow of which that source
is part; when you 'add' or 'replace' with a copy source, the content
-at the path becomes a copy of the source (but see below for a
+and properties at the path are copied from the source (but see below for a
qualification about directories).
-
-Giving a text section also changes the content of the flow. In the
-(unusual) case that a node has both a copy source and a text section,
-the correct semantics is to attach the path to the source flow and
-then change the content.
+ ### Above, we said something that sounds different: "A copy operation
+ creates a new flow connected to the flow from which it was copied."
+ ### What qualification?
+
+If a node has a text section and/or a property section as well as a copy
+source, the correct semantics is to attach the path to the source flow and
+then change the content and/or properties.
An add operation creates a new flow for a file or directory. See the
-table above for possible operand combinations.
+table above for possible operand combinations. When an add has a copy
+source, it produces a new flow with history extending back through the
+copy source.
A delete operation deletes a flow and its content. If the path is a
file, the file is deleted. If the path is a directory, the directory
and all its children are deleted. A subsequent add at the same path
will create a new and different flow with its own history.
-A change operation changes properties on a file or directory path. See the
+A change operation changes the content of a file, and changes the
+properties on a file or directory path. See the
table above for possible operand combinations.
A replace operation behaves exactly like a delete followed by an add
-(destroying an old flow, producing a new one) when it has no copy
-source. When a replace has a copy source, it produces a new flow
-with history extending back through the copy source. A Node record
-representing a replace operation may have a property section.
+(destroying an old flow, producing a new one).
The main reason "replace" exists is because it helps sequential
processors of the dump stream avoid possibly notifying about multiple
@@ -349,17 +361,18 @@
=== Properties and persistence ===
-The properties section of a Revision record consists of some (possibly
-empty) subset of the three reserved revision properties: svn:author,
-svn:date, and svn:log, along with any other revision properties.
-
-The revision properties do not persist to later revisions. Each revision
-has exactly the revision properties specified in its revision record, or
-no revision properties if there is no property section.
+The properties section of a Revision record holds the per-commit properties
+for that revision, known as the revision properties. This consists of some
+(possibly empty) subset of the three reserved revision properties:
+svn:author, svn:date, and svn:log, along with any other revision properties.
+
+The revision properties do not persist to later revisions. Each revision has
+exactly the revision properties specified in its revision record, or no
+revision properties if there are none specified in its revision record.
The key thing to know about Node properties is that they are
persistent, once set, until modified by a future property
-section on the same path.
+section on the same path and flow.
Normally, a dumpfile re-lists the entire property set for a directory
or file in every Node record that changes any part of it. (But see
