Using delta editor to read and write WC local mods

== Towards using a Delta Editor to get changes into and out of WC ==

I wanted to find out about the options for using a standard interface to transfer local modifications from the WC to a shelf and from a shelf to the WC. Therefore I studied the svn_delta_editor_t, as this is known to be functionally complete. (Earlier I looked at the svn_diff_tree_processor_t, and this seems not to be ready for such a task.)

svn_delta_editor_t is used widely throughout Subversion but not consistently. In particular, handling of copy source ('copyfrom') is inconsistent.

=== Copy-from in a commit ===

A WC working state is a place for preparing a commit -- a single new revision. The new revision will be built from the changes specified by the WC, through a delta editor. One of the possible changes is 'add with history', with copyfrom revision and path parameters to specify the backward-pointing line of history for that node. When the commit is finalized, it will be based on a repository revision that is newer than (or equal to) the copy source revision of any added-with-history subtree. It is the repository's job (I assume) to enforce a valid copy source, where a node of the right kind already existed.

The WC commit editor driver therefore sends copyfrom info, and the repository commit editor receives copyfrom info, in order for the repository to link a copied node to its line of history.

=== Copy-from sent to the client ===

In the other direction, we have several editor implementations for sending changes from repository to client:

  * do_diff / diff editor
  * do_status / status editor
    - using 'reporter'; no copyfrom info

  * do_update / update editor
  * do_switch / switch editor
    - using 'reporter'; optional weak copyfrom info (see below)

  * replay (one revision at a time)
    - sends full copyfrom info (see below)

The 'do_diff' functionality can be used to diff any pair of locations in the repository. (Actually, using the reporter to describe the left-hand side, it can compare any mixed tree on the left-hand side with any single tree on the right-hand side.) The change that it describes does not necessarily represent the construction of one revision from the previous revision. Information about the line of history of each node in the right-hand-side tree is rather incidental. For example, it is not fundamentally more interesting than the history of the left-hand-side tree, and knowing the backward history connections is not fundamentally more interesting than knowing the forward connections. In contrast, 'commit' fundamentally can only create backward connections from the new nodes.

'do_status' is meant to provide a cheap preview of 'do_update' and/or 'do_switch', AFAIK; I am not considering it further here.

'do_update' and 'do_switch' are not concerned with history connections. They only need to provide a new base layer for the WC, containing a snapshot of content but not history connections. Bear in mind that update and switch can go backward in time as well as forward.

=== Why do update and switch have optional weak copyfrom? ===

Was this added in an attempt to transmit 'move' information to the update editor?

There is a big difference between a (backward pointing) history connection in the repository and a "move" modification. A "move" modification has to be understood in the context of the modification being studied -- the left and right sides of a diff.

=== Other editors that send/receive copyfrom ===

'copy' command
svnmucc
svnrdump load
svnsync
  - these send copyfrom (as a full URL) to commit editor

ra_serf/update.c
  - uses copyfrom to select a base file version for delta
  - passes any copyfrom through to the update editor
  - the update editor asserts that no copyfrom shall ever arrive
    (svn_wc__get_update_editor/svn_wc__get_switch_editor)

svnrdump dump
  - calls svn_ra_do_update3(send_copy_from_args=False) for
    the initial full revision (if not 'incremental')
  - then expects to receive copyfrom info (files and dirs)
    so it can write out a complete dump record
  - ### it won't receive any copyfrom so will write a broken
    initial full revision record :-(

=== Sending 'copyfrom' to svn_delta_editor_t ===

I found the following sending of 'copyfrom' arguments:

Client commit editor (do_item_commit()):
  - sends copyfrom for both dirs and files,
  - fully with nesting (as is required for a commit).

svn_repos_begin_report3(send_copy_from_args=True):
  - sends copyfrom to editor->add_file(),
  - for files only (in "add_file_smartly()"),
  - only when the file itself was the copy root.

RA-local/serf/svn driving svn_repos_begin_report3():
  - do_diff, do_status: send_copy_from_args=False;
  - do_update, do_switch: send_copy_from_args is optional.

Callers of svn_ra_do_update|switch():
  - none request send_copyfrom_args.

svn_repos_replay2():
  - sends copyfrom for both dirs and files,
  - fully with nesting (as is required for 'svnsync')

svn_repos_dir_delta2():
  - doesn't send any copyfrom;
  - this function is almost obsolete anyway.

== Conclusions and Actions ==

To get a copyfrom-delta out of WC, use the "commit" code:
  -> decouple the delta-sending part from the repository-aware part
     of client "commit"
  -> write features that perform a "commit" from WC to other existing
     delta editors (useful for testing, at least; maybe for users too):
     - "commit to dumpfile"

To get a copyfrom-delta into a WC as working modifications:
  -> write a WC modifications editor (receiver)
  -> write features that push modifications into a WC:
     - copy the mods from one WC into another
     - pull a single rev from a repo into the WC
  -> write round-trip testing using these facilities

No current caller of svn_ra_do_update|switch requests sending copyfrom. If any third-party code does, it only gets copyfrom in very limited cases. So,
  -> can the 'send_copy_from_args' option be deprecated, server-side?
  -> this API option should be deprecated, client-side;
  -> the ra_serf update code using copyfrom should be removed
     (following r998193 which removed its last use)

Test and fix svnrdump dump (initial full revision):
  -> test whether it works -- presumably not
  -> write more thorough tests, e.g. run it alongside 'svnadmin dump'
     'everywhere' and compare their outputs
  -> fix it

-- 
- Julian