This file documents the new functions added in my Summer of Code plan for the Ruby/SWIG bindings and their dependencies. Much of the work in this file is based on the existing Subversion documentation for the Perl bindings -- David James
----------------------------------------------------------------------
Deliverables
----------------------------------------------------------------------
Code:
- 15 new Ruby API functions for the Ruby Client Library:
* blame, cleanup, export, import, ls, merge, propget, proplist,
relocate, resolved, revprop_get, revprop_list, status, switch,
url_from_path
- 4 new Ruby API classes and associated C/SWIG constructors:
* svn_client_blame_receiver_t, svn_error_t (aka Svn::Error),
svn_wc_status_t, svn_client_proplist_item_t
- 8 new Ruby API constants:
* Svn::Core::INVALID_REVNUM, Svn::Error::CLIENT_BAD_REVISION,
Svn::Error::ENTRY_NOT_FOUND, Svn::Error::FS_NOT_FOUND,
Svn::Wc::Notify::Action::commit_added,
Svn::Wc::Notify::Action::commit_postfix_txdelta,
Svn::Wc::Notify::Action::status_completed,
Svn::Wc::Notify::Action::status_external
In order to implement our 15 new Ruby API functions, we also will need to implement the following Ruby API classes:
| implements 'blame' callback | |
| allows callbacks to cancel their parent operation | |
| implements 'status' callback | |
| a class returned from the 'proplist'
and 'propget' functions that
describes a property | |
| constructor for svn_client_blame_receiver_t | |
| a constructor for svn_error_t, that allows a callback to cancel a pending operation | |
| constructor for svn_wc_status_t | |
| constructor for svn_client_proplist_item_t | |
| constructor for svn_info_t | |
| sets up a callback to allow us to be notified when an operation is complete |
The full list of functions is below. Each of the below functions will be created as a method in the Svn::Client class
def blame(target, start, end, receiver)
Invoke the receiver subroutine on each line-blame item associated
with revision end of target, using start as the default
source of all blame.
An error will be raised if either start or end is not defined.
No return.
The blame receiver subroutine receives the following arguments:
line_no, revision, author, date, line, pool
line_no is the line number of the file (starting with 0).
The line was last changed in revision number revision
by author on date and the contents were line.
The blame receiver subroutine can return an error by raising an
exception.
def cleanup(dir)
Recursively cleanup a working copy directory, dir, finishing any
incomplete operations, removing lockfiles, etc.
def export(from, to, revision, force)
Export the contents of either a subversion repository or a Subversion
working copy into a clean directory (meaning a directory with no
administrative directories).
from is either the path to the working copy on disk, or a URL
to the repository you wish to export.
to is the path to the directory where you wish to create the exported
tree.
revision is the revision that should be exported, which is only used
when exporting from a repository. It may be undefined otherwise.
The notify callback will be called for the items exported. The notify
callback can be set using the notify API function (see below).
Returns the value of the revision actually exported or
Svn::Core::INVALID_REVNUM for local exports.
def import(path, url, nonrecursive)
Import file or directory path into repository directory url at head.
If some components of url do not exist then create parent directories
as necessary.
If path is a directory, the contents of that directory are imported
directly into the directory identified by url. Note that the directory
path itself is not imported; that is, the basename of path is not part
of the import.
If path is a file, then the dirname of url is the directory receiving the
import. The basename of url is the filename in the repository. In this case
if url already exists, raise an error.
The notify callback (if defined) will be called as the import progresses, with
any of the following actions: Svn::Wc::Notify::Action::commit_added,
Svn::Wc::Notify::Action::commit_postfix_txdelta.
Use nonrecursive to indicate that imported directories should not recurse
into any subdirectories they may have.
Uses the log_msg callback to determine the log message for the commit when
one is needed.
Returns a svn_client_commit_info_t object.
def ls(target, revision, recursive)
Returns a hash of svn_dirent_t objects for target at revision.
If target is a directory, returns entries for all of the directories'
contents. If recursive is true, it will recurse subdirectories in target.
If target is a file only return an entry for the file.
If target is non-existent, raises the Svn::Error::FS_NOT_FOUND
error.
def merge(src1, rev1, src2, rev2, target_wcpath, recursive, ignore_ancestry, force, dry_run)
Merge changes from src1/rev1 to src2/rev2 into the working-copy path
target_wcpath.
src1 and src2 are either URLs that refer to entries in the repository, or
paths to entries in the working copy.
By merging, we mean: apply file differences and schedule additions &
deletions when appropriate.
src1 and src2 must both represent the same node kind; that is, if src1
is a directory, src2 must also be, and if src1 is a file, src2 must also be.
If either rev1 or rev2 is undefined, raises the Svn::Error::CLIENT_BAD_REVISION
error.
If recursive is true (and the URLs are directories), apply changes recursively;
otherwise, only apply changes in the current directory.
Use ignore_ancestry to control whether or not items being diffed will be
checked for relatedness first. Unrelated items are typically transmitted
to the editor as a deletion of one thing and the addition of another, but
if this flag is true, unrelated items will be diffed as if they were related.
If force is not set and the merge involves deleting locally modified or
unversioned items the operation will raise an error. If force is set such
items will be deleted.
Calls the notify callback once for each merged target, passing the targets
local path.
If dry_run is true the merge is carried out, and the full notification
feedback is provided, but the working copy is not modified.
Has no return.
def propget(propname, target, revision, recursive)
Returns a reference to a hash containing paths or URLs, prefixed by target (a
working copy or URL), of items for which the property propname is set, and
whose values represent the property value for propname at that path.
def proplist(target, revision, recursive)
Returns a reference to an array of svn_client_proplist_item_t objects.
For each item the node_name member of the proplist_item object contains
the name relative to the same base as target.
If revision is undefined, then get properties from the working copy, if
target is a working copy, or from the repository head if target is a URL.
Else get the properties as of revision.
If recursive is false, or target is a file, the returned array will only
contain a single element. Otherwise, it will contain one entry for each
versioned entry below (and including) target.
If target is not found, raises the Svn::Error::ENTRY_NOT_FOUND error.
def relocate(dir, from, to, recursive)
Modify a working copy directory dir, changing any repository URLs that
begin with from to begin with to instead, recursing into subdirectories if
recursive is true.
Has no return.
def resolved(path, recursive)
Remove the conflicted state on a working copy path.
This will not semantically resolve conflicts; it just allows path to be
committed in the future. The implementation details are opaque. If
recursive is set, recurse below path, looking for conflicts to
resolve.
If path is not in a state of conflict to begin with, do nothing.
If the path conflict state is removed, call the notify callback with
the path.
def revprop_get(propname, url, revision)
Returns two values, the first of which is the value of propname on revision
revision in the repository represented by url. The second value is the
actual revision queried.
Note that unlike its cousin propget(), this routine doesn't affect
working copy at all; it's a pure network operation that queries an
unversioned property attached to a revision. This can be used to query
log messages, dates, authors, and the like.
def revprop_list(url, revision)
Returns two values, the first of which is a reference to a hash containing
the properties attached to revision in the repository represented by url.
The second value is the actual revision queried.
Note that unlike its cousin proplist(), this routine doesn't read a
working copy at all; it's a pure network operation that reads unversioned
properties attached to a revision.
def revprop_set(propname, propval, url, revision, force)
Set propname to propval on revision revision in the repository represented
by url.
Returns the actual revision affected. A propval of undefined will delete the
property.
If force is true, allow newlines in the author property.
If propname is an svn-controlled property (i.e. prefixed with svn:), then
the caller is responsible for ensuring that the value is UTF8-encoded and
uses LF line-endings.
Note that unlike its cousin propset(), this routine doesn't affect
the working copy at all; it's a pure network operation that changes an
B property attached to a revision. This can be used to tweak
log messages, dates, authors, and the like. Be careful: it's a lossy
operation, meaning that any existing value is replaced with the new value,
with no way to retrieve the prior value.
Also note that unless the administrator creates a pre-revprop-change hook
in the repository, this feature will fail.
def status(path, revision, status_func, recursive, get_all, update, no_ignore)
Given path to a working copy directory (or single file), call status_func()
with a set of svn_wc_status_t objects which describe the status of path and
its children.
If recursive is true, recurse fully, else do only immediate children.
If get_all is set, retrieve all entries; otherwise, retrieve only interesting
entries (local mods and/or out-of-date).
If update is set, contact the repository and augment the status objects with
information about out-of-dateness (with respect to revision). Also, will
return the value of the actual revision against with the working copy was
compared. (The return will be undefined if update is not set).
The function recurses into externals definitions (svn:externals) after
handling the main target, if any exist. The function calls the notify callback
with Svn::Wc::Notify::Action::status_external action before handling each
externals definition, and with Svn::Wc::Notify::Action::status_completed
after each.
The status_func subroutine takes the following parameters:
path, status
path is the pathname of the file or directory which status is being
reported. status is a svn_wc_status_t object.
The return of the status_func subroutine is ignored.
def switch(path, url, revision, recursive)
Switch working tree path to url at revision.
revision must be a number, HEAD, or a date, otherwise it raises the
Svn::Error::CLIENT_BAD_REVISION error.
Calls the notify callback on paths affected by the switch. Also invokes
the callback for files that may be restored from the text-base because they
were removed from the working copy.
Summary of purpose: This is normally used to switch a working directory
over to another line of development, such as a branch or a tag. Switching
an existing working directory is more efficient than checking out url from
scratch.
Returns the value of the revision to which the working copy was actually
switched.
def url_from_path(target)
Returns the URL for target.
If target is already a URL it returns target.
If target is a versioned item, it returns the target entry URL.
If target is unversioned (has no entry), returns undefined.