perldoc > SVN::Ra

man perldoc info pydoc3 ri search

📛 NAME

SVN::Ra - Subversion remote access functions

🚀 Quick Reference

Use Case	Command	Description
Open a session to a repository	SVN::Ra->new('url')	Create an RA object with the given URL, using default auth and config.
Get the latest revision number	$ra->get_latest_revnum	Return HEAD revision number of the repository.
Get log history for a path	$ra->get_log($paths, $start, $end, $limit, $discover, $strict, \&callback)	Invoke callback for each revision in range, with change info.
Retrieve file contents	$ra->get_file($path, $revnum, $fh)	Write file contents to filehandle, return properties.
Get directory listing	$ra->get_dir($path, $revnum)	Return hash of directory entries, properties, and fetched revision.
Commit changes	$ra->get_commit_editor($logmsg, $callback, $baton, $lock_tokens, $keep_locks)	Return an editor object for committing a new revision.
Update working copy	$ra->do_update($revnum, $target, $recurse, $editor)	Return a Reporter to describe WC, then Subversion drives editor.
Check path type	$ra->check_path($path, $revnum)	Return node kind constant (none, file, dir, unknown).
Get repository root	$ra->get_repos_root	Return root URL of the repository.
Get repository UUID	$ra->get_uuid	Return UUID string of the repository.

📋 SYNOPSIS

use SVN::Core;
use SVN::Ra;

my $ra = SVN::Ra->new('file:///tmp/svntest');
print $ra->get_latest_revnum;

📖 DESCRIPTION

SVN::Ra wraps the object-oriented "svn_ra_plugin_t" functions, providing access to a Subversion repository through a URL, using whichever repository access module is appropriate.

🔧 SVN::Ra->new(...)

The constructor creates an RA object and calls "open" for it. Its parameters are either a hash of options or a single value containing the URL of the repository. Valid options are:

• url — The URL of the repository.
• auth — An "auth_baton" could be given to the SVN::RA object. Defaults to an "auth_provider" with a "username_provider". See SVN::Client for how to create "auth_baton".
• pool — The pool for the RA session to use. Member functions will also be called with this pool. Defaults to a newly created root pool.
• config — The config hash that could be obtained by calling SVN::Core::config_get_config(undef).
• callback — The "ra_callback" namespace to use. Defaults to SVN::Ra::Callbacks.

The following examples will both do the same thing, with all the optional arguments taking their defaults:

my $ra = SVN::Ra->new('file:///tmp/repos');
my $ra = SVN::Ra->new(url => 'file:///tmp/repos');

🛠️ METHODS

Please consult the svn_ra.h section in the Subversion API. Member functions of "svn_ra_plugin_t" can be called as methods of SVN::Ra objects, with the "session_baton" and "pool" arguments omitted.

• $ra->change_rev_prop($revnum, $name, $value) — Sets the revision (unversioned) property $name to $value on revision $revnum, or removes the property if $value is undef.

  $ra->change_rev_prop(123, 'svn:log', 'New log message.');

  Of course this will only work if there is a "pre-revprop-change" hook available.
• $ra->check_path($path, $revnum) — Kind of node at $path in revision $revnum. A number which matches one of these constants: $SVN::Node::none, $SVN::Node::file, $SVN::Node::dir, $SVN::Node::unknown.
• $ra->do_diff($revision, $target, $recurse, $ignore_ancestry, $versus_url, $editor) and $ra->do_diff2($revision, $target, $recurse, $ignore_ancestry, $text_deltas, $versus_url, $editor) — Both return a SVN::Ra::Reporter with which you can describe a working copy. It will then call methods on $editor to indicate the differences between the repository and the working copy. The "do_diff2" method added in Subversion 1.4 adds the $text_deltas option, which if false disables text deltas.

  my $reporter = $ra->do_diff(1, '', 1, 0, $repos_url,
                              MyEditor->new);
  $reporter->set_path(...);
  $reporter->finish_report;

• $ra->do_status($target, $revision, $recurse, $editor) — Returns a SVN::Ra::Reporter to which you can describe the status of a working copy. It will then call methods on $editor to describe the current status of the working copy compared to the repository.
• $ra->do_switch($revnum, $target, $recurse, $repos_url, $editor) — Returns a SVN::Ra::Reporter with which you can describe a working copy. It will then call methods on $editor to indicate how to adjust the working copy to switch it to revision $revnum of $repos_url.
• $ra->do_update($revision_to_update_to, $target, $recurse, $editor) — Returns a SVN::Ra::Reporter object. Call methods on the reporter to describe the current state of your working copy. After calling finish_report(), Subversion will generate calls to your $editor to describe the differences between what you already have and the state of the repository in $revision_to_update_to. To update to the latest revision, pass $SVN::Core::INVALID_REVNUM for the first argument. $target should be the path to the part of the repository you are interested in. If $recurse is true and the target is a directory, update recursively. All paths are relative to the URL used to open $ra. The caller may not perform any RA operations using $ra before finishing the report. This example shows the simplest update:

  my $reporter = $ra->do_update($revnum, '', 1, MyEditor->new);
  $reporter->set_path('', 0, 1, undef);
  $reporter->finish_report;

• $ra->get_commit_editor($logmsg, $callback, $callback_baton, $lock_tokens, $keep_locks) and $ra->get_commit_editor2($logmsg, $callback, $callback_baton, $lock_tokens, $keep_locks) — Return an opaque editor object for committing a new revision. The return values should be passed to the SVN::Delta::Editor constructor. For example:

  my $editor = SVN::Delta::Editor->new(
      $ra->get_commit_editor(
          "I'm going to commit some changes from within my Perl code.",
          \&commit_callback, undef, {}, 0));

  The $callback function will be called during $ed->close_edit() after the commit succeeds. "get_commit_editor2" passes the callback a single value (object or hash ref) containing all information, including the error message from the post-commit hook. The callback for the original version receives three arguments: new revision number, date/time, and author name. $logmsg is a string stored in "svn:log". $lock_tokens is a hash ref mapping paths to lock tokens. If $keep_locks is true, locks on committed files are not released. The method returns a list of two items: the actual editor and the editor baton.
• $ra->get_dated_revision($time) — TODO: doesn't seem to work in Subversion 1.3.
• $ra->get_dir($path, $revnum) and $ra->get_dir2($path, $revnum, $dirent_fields) — Fetch directory entries and properties of the directory at $path in revision $revnum. Returns a list of three values: a reference to a hash of directory entries (keys are filenames, values are _p_svn_dirent_t objects), a number (valid only if $revnum is $SVN::Core::INVALID_REVNUM), and a reference to a hash of all properties on the directory. Examples:

  my ($dirents, undef, $props) = $ra->get_dir('trunk/dir', 123);
  my ($dirents, $fetched_revnum, $props) = $ra->get_dir(
      'trunk/dir', $SVN::Core::INVALID_REVNUM);

• $ra->get_file($path, $revnum, $fh) — Fetch contents and properties of the file at $path in revision $revnum. $fh should be a Perl filehandle to write contents to, or undef. Returns a list of two values: a number (valid only if $revnum is $SVN::Core::INVALID_REVNUM) and a reference to a hash of properties. Examples:

  my (undef, $props) = $ra->get_file(
      'trunk/foo', 123, undef);
  
  open my $fh, '>', 'tmp_out'
      or die "error opening file: $!";
  my (undef, $props) = $ra->get_file(
      'trunk/foo', 123, $fh);
  
  my ($fetched_revnum, $props) = $ra->get_file(
      'trunk/foo', $SVN::Core::INVALID_REVNUM, $fh);

• $ra->get_file_revs($path, $start, $end, \&callback) — TODO: doesn't seem to work in Subversion 1.3.
• $ra->get_latest_revnum — Return the number of the latest revision (HEAD).
• $ra->get_locations($path, $peg_revnum, \@location_revisions) — TODO: doesn't seem to work in Subversion 1.3.
• $ra->get_lock($path) — Returns a _p_svn_lock_t object containing lock information, or undef if not locked.
• $ra->get_locks($path) — TODO: doesn't seem to work in Subversion 1.3.
• $ra->get_log(\@paths, $start, $end, $limit, $discover_changed_paths, $strict_node_history, \&callback) — For $limit revisions from $start to $end, invoke the receiver callback with information about changes made in the revision. The caller may not invoke any RA operations using $ra from within the callback. The first argument can be a single string or array reference of paths. $start and $end are revision numbers; if $start is $SVN::Core::INVALID_REVNUM it defaults to latest. $limit is a maximum number of callbacks; 0 means no limit. If $discover_changed_paths is true, changed paths info is passed to callback. If $strict_node_history is true, copy history is not traversed. The callback receives: a hash ref of paths changed (or undef), revision number, author, date/time, log message, and a pool object. Example:

  $ra->get_log('', 1, $ra->get_latest_revnum, 0, 1, 0,
               \&log_callback);
  
  sub log_callback
  {
      my ($paths, $revnum, $user, $datetime, $logmsg) = @_;
      print "$datetime - $user - r$revnum\n";
  
      while (my ($path, $changes) = each %$paths) {
          print $changes->action, " $path\n";
          if ($changes->copyfrom_path) {
              print " from ", $changes->copyfrom_path,
                    " r", $changes->copyfrom_rev, "\n"
          }
      }
  
      print "\n";
  }

• $ra->get_repos_root — Returns the repository's root URL (no trailing '/'), guaranteed to be a prefix of the session's URL.
• $ra->get_uuid — Returns the repository's UUID as a string.
• $ra->lock(\%path_revs, $comment, $steal_lock, \&callback) — TODO: doesn't seem to work in Subversion 1.3.2.
• $ra->reparent($url) — Change the root URL of the session to a different path. $url must be in the same repository. New in Subversion 1.4.
• $ra->replay($revnum, $low_water_mark, $send_deltas, $editor) — Call methods on $editor to describe changes made in revisions after $low_water_mark up to $revnum. Like do_update() but without a reporter. If $send_deltas is true, file contents and property values are supplied. New in Subversion 1.4.
• $ra->rev_prop($revnum, $name) — Return the value of the unversioned property $name from revision $revnum. Returns undef if no such property.

  print $ra->rev_prop(123, 'svn:date');

• $ra->rev_proplist($revnum) — Returns a reference to a hash containing all unversioned properties of revision $revnum.

  my $props = $ra->rev_proplist(123);
  print $props->{'svn:log'};

• $ra->stat($path, $revnum) — Returns a _p_svn_dirent_t object containing information about the file at $path in revision $revnum.
• $ra->unlock(\%path_tokens, $break_lock, \&callback) — TODO: doesn't seem to work in Subversion 1.3.2.

📁 SVN::Ra::Reporter

The SVN::Ra methods do_diff, do_status, do_switch, and do_update all return a SVN::Ra::Reporter object, which can be used to describe the working copy (or other available data) which the client has. Subversion uses this to figure out what new information should be provided through a tree delta editor. Objects of this class are wrappers around underlying "svn_ra_reporter2_t" objects and their associated baton.

📌 Reporter Methods

• $reporter->set_path($path, $revision, $start_empty, $lock_token, $pool) — Describe a working copy $path as being at a particular $revision. If $start_empty is true and $path is a directory, assume the directory has no entries or properties. Overrides previous calls on parent paths. $path is relative to the URL specified in SVN::Ra->open() or SVN::Ra->new(). $lock_token is optional.
• $reporter->delete_path($path, $pool) — Describe a working copy $path as missing.
• $reporter->link_path($path, $url, $revision, $start_empty, $lock_token, $pool) — Like set_path(), but $path is a reflection of a different repository $url at $revision.
• $reporter->finish_report($pool) — Call when the state report is finished; any directories or files not explicitly 'set' are assumed to be at the baseline revision. No other reporting functions should be called after this.
• $reporter->abort_report($pool) — If an error occurs, this method should cause the filesystem transaction to be aborted and cleaned up. No other reporting methods should be called after this.

📞 SVN::Ra::Callbacks

This is the wrapper class for "svn_ra_callback_t". To supply custom callbacks to SVN::Ra, subclass this class and override the member functions.

✍️ AUTHORS

Chia-liang Kao <clkao AT clkao.org>

📄 COPYRIGHT

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

📛 NAME 🚀 Quick Reference 📋 SYNOPSIS 📖 DESCRIPTION ✍️ AUTHORS 📄 COPYRIGHT