0.2 draft of dumpfile documentation

["Eric S. Raymond" <es...@thyrsus.com>]

Please review the enclosed carefully.  It incorporates all of
sussman's original notes, everything I've been able to learn or deduce, 
and the email conversations.  There is a list of open questions
near the top.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: 0.2 draft of dumpfile documentation

["roderich.schupp@googlemail.com" <ro...@googlemail.com>]

On Dec 15, 10:33 am, "roderich.sch...@googlemail.com"
<ro...@googlemail.com> wrote:

>> 4. What are the detailed semantics of "change" with copyfrom?  I
> It's an "add-with-history" immediately followed by a modification (of
> contents and/or properties) of the added path.

Sorry, I was wrong. "change" with copyfrom is illegal.
If you want "add-with-history" and modify contents/properties
"at the same time" just include those parts in the record (of Node-
action
"add" or "replace").

Cheers, Roderich

Re: 0.2 draft of dumpfile documentation

[Roderich Schupp <ro...@googlemail.com>]

On Thu, Dec 15, 2011 at 11:44 AM, Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> Roderich Schupp wrote on Thu, Dec 15, 2011 at 11:32:40 +0100:
>> I think the latter. The code is in subversion/libsvn_repos/dump.c starting
>> around line 318. Some people might call that an ugly hack :)
>
> Yeah.  I wonder why that code doesn't render a replace-with-history as
> a single "Node-action: replace" "Copyfrom-*: .../" node.

Simple code ab^H^Hreuse. The ...-with-history case needs some additional
consideration and instead of factoring that code out (and leave it to
the caller whether to emit an "add" or "replace") the current implementation
calls itself (i.e. dump_node()) recursively, then fiddles with
must_dump_{text,props}
to cover its tracks.

Cheers, Roderich

Re: 0.2 draft of dumpfile documentation

[Daniel Shahaf <d....@daniel.shahaf.name>]

Roderich Schupp wrote on Thu, Dec 15, 2011 at 11:32:40 +0100:
> On Thu, Dec 15, 2011 at 11:14 AM, Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> > Is this by design or by accident of implementation?
> 
> I think the latter. The code is in subversion/libsvn_repos/dump.c starting
> around line 318. Some people might call that an ugly hack :)
> 

Yeah.  I wonder why that code doesn't render a replace-with-history as
a single "Node-action: replace" "Copyfrom-*: .../" node.

> > svn_delta_editor_t has no concept of 'replace' and must do delete+add
> > instead, but that does not mean that dumpfiles are allowed to do
> > delete+add too!
> 
> Then the situation wrt add+delete vs replace is even more weird than I thought.
> 
> Cheers, Roderich

Re: 0.2 draft of dumpfile documentation

[Roderich Schupp <ro...@googlemail.com>]

On Thu, Dec 15, 2011 at 11:14 AM, Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> Is this by design or by accident of implementation?

I think the latter. The code is in subversion/libsvn_repos/dump.c starting
around line 318. Some people might call that an ugly hack :)

> svn_delta_editor_t has no concept of 'replace' and must do delete+add
> instead, but that does not mean that dumpfiles are allowed to do
> delete+add too!

Then the situation wrt add+delete vs replace is even more weird than I thought.

Cheers, Roderich

Re: 0.2 draft of dumpfile documentation

[Daniel Shahaf <d....@daniel.shahaf.name>]

roderich.schupp@googlemail.com wrote on Thu, Dec 15, 2011 at 01:33:22 -0800:
> Thus a dump consumer can simply store the node records (in one
> revision) as a hash (associative array) with Node-path as the key. The
> only excption is that it must be prepared to "upgrade" a "delete" to
> a "replace" if it encounters an "add" for the same Node-path. Any
> other combination of actions on the same Node-path is a malformed
> dump.

Is this by design or by accident of implementation?

svn_delta_editor_t has no concept of 'replace' and must do delete+add
instead, but that does not mean that dumpfiles are allowed to do
delete+add too!

Re: 0.2 draft of dumpfile documentation

["roderich.schupp@googlemail.com" <ro...@googlemail.com>]

On Dec 14, 1:37 pm, "Eric S. Raymond" <e....@thyrsus.com> wrote:

> 1. Is delete on a directory with children expected to succeed or fail?

Succeed. A delete on a directory actually deletes the whole subtree
below it.

> 3. Is add on an existing path expected to fail?

Yes.

> 4. What are the detailed semantics of "change" with copyfrom?  I
understand the no-copyfrom case - on a file it's an ordnary text
modification, on a directory a pure property change.

It's an "add-with-history" immediately followed by a modification (of
contents and/or properties)
of the added path.

> Dump decoders should be prepared for the optional lines after
> Node-action to be in any order, except that Content-length is
> always last if it present.
>
> A Node record describes an action on a path relative to the repository
> root, and always begins with the Node-path specification.

No ordering of header lines whatsoever is expected (what the current
implementation
of e.g. "svnadmin dump" does is irrelvant).

> The main reason "replace exists" is because it helps sequential
> processors of the dump stream avoid possibly notifying about multiple
> actions on the same path.

You quote that from Pilato's mail, but in this context it gives the
false impression
that "replace" is an ad-hoc invention for dump files. It's actually
the other way around:

- internally Subversion has only the primitives add, delete, change
and replace
  (and any revision consists of at most one primitive operation for
any path involved)
- the dump file may represent an internal "replace" with either one
"replace" node or
  two nodes: a "delete" followed by a "add"

Note: I just checked Subversion trunk (subversion/libsvn_repos/
dump.c): the code still
does both (delete+add ist used if the add has history, replace
otherwise), but there's
no reason for that except programmer's convenience. Also note that
"svnadmin load"
will correctly load dumps that contain "replace" in this situation.

I think the point of Pilato's remark was this (and this should really
find its way into
the documentation):

For all node records in one revision the Node-paths are unqiue. The
only exception
is a "delete" followed by an "add" on the same Node-path.

Thus a dump consumer can simply store the node records (in one
revision)
as a hash (associative array) with Node-path as the key. The only
excption
is that it must be prepared to "upgrade" a "delete" to a "replace" if
it encounters
an "add" for the same Node-path. Any other combination of actions on
the same
Node-path is a malformed dump.

Cheers, Roderich