Ruby bindings for the Subversion client library: Documentation

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


- 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, 

- 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::Error::ENTRY_NOT_FOUND, Svn::Error::FS_NOT_FOUND, 

In order to implement our 15 new Ruby API functions, we also will need to implement the following Ruby API classes:

To implement the above classes, we will need to create the following C/SWIG functions.

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

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

  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,

  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
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

  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

  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

  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
  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
  Returns the value of the revision to which the working copy was actually

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.