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

Re: Problems with the documentation of Subversion dump format

From: Eric S. Raymond <esr_at_thyrsus.com>
Date: Tue, 13 Dec 2011 09:44:59 -0500

Philip Martin <philip.martin_at_wandisco.com>:
> esr_at_thyrsus.com (Eric S. Raymond) writes:
> > # The "replace" action [?is only issued with directory copies, and?]
> > # signifies that the existing contents of the directory should be
> > # removed before the copy.
> Replace applies to files as well.

Does a file replace differ in any way from a delete plus add of the new text?

Can a replace include a property section?

Does a replace always have text associated with it, or can it have a
copyfrom source?

If a file replace can have a copyfrom source, how does replace with a
copyfrom source differ from add with a copyfrom source?

How does a "change" differ from a "replace"? My guess is that
"change" is issued for nodes that are pure property changes with no
file content changes; is this correct?

For each of the actions, it needs to be clear

* whether it can have a text section
* whether it can have a copyfrom source
* whether it can have a property section
* whether it can be a file operation, a directory operation, or both.

The yes-or-no answers to those questions alone imply 36 different
possible semantic cases. There are probably simplifying rules like
"anything that can have a text section can have a file copyfrom
source" or "any file operation except a delete can have a proerty
section", but the existing notes don't really make any of these clear.

To understand this, I'm reduced to groveling through megabytes of
dumpfiles, trying to figure out all the corner cases by eyeball. This
means the documentation isn't good enough; the syntax of dumpfiles is
beautifully designed but the semantics is pretty murky.
> > # Interpreting copyfrom_path for file copies is straightforward; the
> > # target pathname gets the contents of the source pathname.
> > #
> > # Directory copies (the primitive beneath branching and tagging) are
> > # tricky. For each source path under the source directory, a new path
> > # is generated by removing the head segment of the pathname that is
> > # the source directory. That new path under the target directory gets
> > # the content of the source path.
> Not sure what this means. This copies A/B/C to X/Y/Z:
> Node-path: X/Y/Z
> Node-kind: dir
> Node-action: add
> Node-copyfrom-rev: 10
> Node-copyfrom-path: A/B/C

I meant that, given this:

> Node-path: x/y/z
> Node-kind: dir
> Node-action: add
> Node-copyfrom-rev: 10
> Node-copyfrom-path: a/b/c

a file a/b/c/d will be copied to x/y/z/d. The "a/b/c" is what I was calling
the "head segment".

If that's not the way it's supposed to work, how is it supposed to worl?

> > # A single revision may include multiple copyfrom nodes, even multiple
> > # copyfroms to the same directory, even mixed directory and file copies
> > # to the same directory; [?Subversion client tools never generate such
> > # mixed copies, but?] I have seen the results of cvs2svn doing it.
> Not sure what "mixed directory and file copies to the same directory"
> means or why Subversion clients would be restricted. Given directories
> D1 and D2 and a file F it's trivial to copy D1 to D2/Dnew and F to
> D2/Fnew.

Yes, but in a single copy command? My experience is that every one copy
operation done from the CLI triggers a commit.

		Eric S. Raymond
Received on 2011-12-13 15:46:08 CET

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