Introduction

This page introduces new API. The central part of the API is an abstraction of a generic tree of (usually) versioned nodes -- where each node is a file or directory, with properties.

We already have a generic tree-editing API (svn_delta_editor_t, svn_editor_t). It will be beneficial to have a generic tree-access API as well. The idea is that code can use the same interface to examine the WC base, the WC working state, revision X in a repository, or any other concrete or virtual tree that we may decide to implement. Use of a common API can reduce code duplication, improving consistency of behaviour, simplifying maintenance and reducing bugs. It should be possible to write operations that combine generic trees, such as traversing two trees in parallel, diffing and patching trees. Then we could, for example, extend 'svn diff' to be able to compare any two arbitrary trees, related or not, such as the unversioned tree '/tmp/saved-tests' against the WC tree 'wc/subversion/tests'. Instead of doing this by writing several more variants of the current three subroutines (WC/WC, WC/repos, repos/repos), in principle we would need just one diff subroutine that takes two Tree objects as input. Another goal here is to facilitate writing a three-way merge that fully supports moves and renames.

Key ideas:

Source Code

http://svn.apache.org/repos/asf/subversion/branches/tree-read-api/

Core:

subversion/include/svn_tree.h

subversion/include/private/svn_tree_impl.h

subversion/libsvn_subr/tree.c

Implementations of RA trees, WC trees, disk trees:

subversion/libsvn_ra/ra_trees.c

subversion/libsvn_wc/wc_trees.c

subversion/libsvn_subr/disk_trees.c

Push vs Pull

This is a "pull" interface -- the flow of control pulls data from a tree (when reading, that is), in contrast to using svn_editor_t to read a tree, the data is pushed and therefor the producer is in control of the order of traversal etc.

Push not suitable for diffing etc... ### ...

Tree Classes

tree-impl-classes.png

svn_tree_t

Abstract representation of a tree of svn_tree_node_t.

This object presents an interface for referring to, accessing and traversing a tree, usually a versioned tree, of the kind of nodes that Subversion versions.

A tree always has a root node: a completely empty tree is not allowed.

An implementation of this interface could represent, among other trees:

Methods:

svn_tree_node_t

Abstract representation of a tree node.

Attributes:

Methods:

Operations On Trees

Tree Walking

Let's use the style of Python's os.walk(dir_path). That is:

The Python style is that the walker acts as a "generator" of (dir_path, subdirs[], files[]) tuples. Implementing in C for Subversion, we'll use a callback "visitor" function instead, receiving those things as arguments, and also receiving a baton for closure.

Benefits of a per-dir walk:

Open-dir / close-dir:

Traversal order:

TreeApi (last edited 2012-11-09 17:01:49 by JulianFoad)