NAME
SVN::Client - Subversion client functions
SYNOPSIS
use SVN::Client;
my $ctx = new SVN::Client(
auth => [SVN::Client::getsimpleprovider(),
SVN::Client::getsimplepromptprovider(\&simpleprompt,2),
SVN::Client::getusernameprovider()]
);
$ctx->cat (\*STDOUT, 'http://svn.collab.net/repos/svn/trunk/README',
'HEAD');
sub simpleprompt {
my $cred = shift;
my $realm = shift;
my $defaultusername = shift;
my $maysave = shift;
my $pool = shift;
print "Enter authentication info for realm: $realm\n";
print "Username: ";
my $username = <>;
chomp($username);
$cred->username($username);
print "Password: ";
my $password = <>;
chomp($password);
$cred->password($password);
}
DESCRIPTION
SVN::Client wraps the highest level of functions provided by subversion
to accomplish specific tasks in an object oriented API. Methods are
similar to the functions provided by the C API and as such the
documentation for it may be helpful in understanding this interface.
There are a few notable differences from the C API. Most C function
calls take a svnclientctxt pointer as the next to last parameter.
The Perl method calls take a SVN::Client object as the first parameter.
This allows method call invocation of the methods to be possible. For
example, the following are equivalent:
SVN::Client::add($ctx,$path, $recursive, $pool);
$ctx->add($path, $recursive, $pool);
Many of the C API calls also take a aprpoolt pointer as their last
argument. The Perl bindings generally deal with this for you and you
do not need to pass a pool parameter. However, you may still pass a
pool parameter as the last parameter to override the automatic handling
of this for you.
Users of this interface should not directly manipulate the underlying
hash values but should use the respective attribute methods. Many of
these attribute methods do other things, especially when setting an
attribute, besides simply manipulating the value in the hash.
PPAARRAAMMEETTEERR NNOOTTEESS
The client methods described below take a variety of parameters. Many
of them are similar. Methods accepting parameters named below will
follow the rules below or will be noted otherwise in the method
description.
$ctx
An SVN::Client object that you get from the constructor.
$url
This is a URL to a subversion repository.
$path
This is a path to a file or directory on the local file system.
$paths
This argument can either be a single path to a file or directory on
the local file system, or it can be a reference to an array of
files or directories on the local file system.
$target
This is a path to a file or directory in a working copy or a URL to
a file or directory in a subversion repository.
$targets
This argument can either be a single $target (as defined above) or
a reference to an array of them.
$revision
This specifies a revision in the subversion repository. You can
specify a revision in several ways. The easiest and most obvious
is to directly provide the revision number. You may also use the
strings (aka revision keywords) 'HEAD', 'BASE', 'COMMITTED', and
'PREV' which have the same meanings as in the command line client.
When referencing a working copy you can use the string 'WORKING" to
reference the BASE plus any local modifications. undef may be used
to specify an unspecified revision. Finally you may pass a date by
specifying the date inside curly braces '{}'. The date formats
accepted are the same as the command line client accepts.
$recursive $nonrecursive.
A boolean parameter that specifies if the action should follow
directories. It should only be 1 or 0. $recursive means, 1 means
to descend into directories, 0 means not to. $nonrecursive has the
inverse meaning.
$pool
Pool is always an option parameter. If you wish to pass a pool
parameter it should be a SVN::Pool or an aprpoolt object.
MMEETTHHOODDSS
The following methods are available:
$ctx = SVN::Client->new( %options );
This class method constructs a new "SVN::Client" object and returns
a reference to it.
Key/value pair arguments may be provided to set up the initial
state of the user agent. The following methods correspond to
attribute methods described below:
KEY DEFAULT
----- --------------------
auth authbaton initiated with providers that
read cached authentication options from
the subversion config only.
cancel undef
config Hash containing the config from the
default subversion config file location.
logmsg undef
notify undef
pool A new pool is created for the context.
$ctx->add($path, $recursive, $pool);
Schedule a working copy $path for addition to the repository.
$path's parent must be under revision control already, but $path is
not. If $recursive is set, then assuming $path is a directory, all
of its contents will be scheduled for addition as well.
Calls the notify callback for each added item.
Important: this is a sscchheedduulliinngg operation. No changes will happen
to the repository until a commit occurs. This scheduling can be
removed with $ctx->revert().
No return.
$ctx->blame($target, $start, $end, \&receiver, $pool);
Invoke \&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 undef.
No return.
The blame receiver subroutine receives the following arguments:
$lineno, $revision, $author, $date, $line, $pool
$lineno 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 svnerrort object to
return an error. All other returns will be ignored. You can
create an svnerrort object with SVN::Error::create().
$ctx->cat(\*FILEHANDLE, $target, $revision, $pool);
Outputs the content of the file identified by $target and $revision
to the FILEHANDLE. FILEHANDLE is a reference to a filehandle.
If $target is not a local path and if $revision is 'PREV' (or some
other kind that requires a local path), then an error will be
raised, because the desired revision can not be determined.
$ctx->checkout($url, $path, $revision, $recursive, $pool);
Checkout a working copy of $url at $revision using $path as the
root directory of the newly checked out working copy.
$revision must be a number, 'HEAD', or a date. If $revision does
not meet these requirements the $SVN::Error::CLIENTBADREVISION is
raised.
Returns the value of the revision actually checked out of the
repository.
$ctx->cleanup($dir, $pool);
Recursively cleanup a working copy directory, $dir, finishing any
incomplete operations, removing lockfiles, etc.
$ctx->commit($targets, $nonrecursive, $pool);
Commit files or directories referenced by target. Will use the
logmsg callback to obtain the log message for the commit.
If $targets contains no paths (zero elements), then does nothing
and immediately returns without error.
Calls the notify callback as the commit progresses with any of the
following actions: $SVN::Wc::Notify::Action::commitmodified,
$SVN::Wc::Notify::Action::commitadded,
$SVN::Wc::Notify::Action::commitdeleted,
$SVN::Wc::Notify::Action::commitreplaced,
$SVN::Wc::Notify::Action::commitpostfixtxdelta.
Use $nonrecursive to indicate that subdirectories of directory
targets should be ignored.
Returns a svnclientcommitinfot object. If the revision member
of the commit information object is $SVN::Core::INVALIDREVNUM and
no error was raised, then the commit was a no-op; nothing needed to
be committed.
$ctx->copy($srctarget, $srcrevision, $dsttarget, $pool);
Copies $srctarget to $dsttarget.
$srctarget must be a file or directory under version control, or
the URL of a versioned item in the repository. If $srctarget is a
URL, $srcrevision is used to choose the revision from which to
copy the $srctarget. $dstpath must be a file or directory under
version control, or a repository URL, existing or not.
If $dsttarget is a URL, immediately attempt to commit the copy
action to the repository. The logmsg callback will be called to
query for a commit log message. If the commit succeeds, return a
svnclientcommitinfot object.
If $dsttarget is not a URL, then this is just a variant of
$ctx->add(), where the $dstpath items are scheduled for addition
as copies. No changes will happen to the repository until a commit
occurs. This scheduling can be removed with $ctx->revert(). undef
will be returned in this case.
Calls the notify callback for each item added at the new location,
passing the new, relative path of the added item.
$ctx->delete($targets, $force, $pool);
Delete items from a repository or working copy.
If the paths in $targets are URLs, immediately attempt to commit a
deletion of the URLs from the repository. The logmsg callback
will be called to query for a commit log message. If the commit
succeeds, return a svnclientcommitinfot object. Every path
must belong to the same repository.
Else, schedule the working copy paths in $targets for removal from
the repository. Each path's parent must be under revision control.
This is just a sscchheedduulliinngg operation. No changes will happen to the
repository until a commit occurs. This scheduling can be removed
with $ctx->revert(). If a path is a file it is immediately removed
from the working copy. If the path is a directory it will remain
in the working copy but all the files, and all unversioned items it
contains will be removed. If $force is not set then this operation
will fail if any path contains locally modified and/or unversioned
items. If $force is set such items will be deleted.
The notify callback is called for each item deleted with the path
of the deleted item.
Has no return.
$ctx->diff($diffoptions, $target1, $revision1, $target2, $revision2,
$recursive, $ignoreancestry, $nodiffdeleted, $outfile, $errfile,
$pool);
Produces diff output which describes the delta between $target1 at
$revision1 and $target2 at $revision2. They both must represent
the same node type (i.e. they most both be directories or files).
The revisions must not be undef.
Prints the output of the diff to the filename or filehandle passed
as $outfile, and any errors to the filename or filehandle passed as
$errfile.
Use $ignoreancestry 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 $nodiffdeleted is true, then no diff output will be generated
on deleted files.
$diffoptions is a reference to an array of additional arguments to
pass to diff process invoked to compare files. You'll usually just
want to use [] to pass an empty array to return a unified context
diff (like `diff -u`).
Has no return.
$ctx->export($from, $to, $revision, $force, $pool);
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 undef otherwise.
The notify callback will be called for the items exported.
Returns the value of the revision actually exported or
$SVN::Core::INVALIDREVNUM for local exports.
$ctx->import($path, $url, $nonrecursive, $pool);
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::commitadded,
$SVN::Wc::Notify::Action::commitpostfixtxdelta.
Use $nonrecursive to indicate that imported directories should not
recurse into any subdirectories they may have.
Uses the logmsg callback to determine the log message for the
commit when one is needed.
Returns a svnclientcommitinfot object.
$ctx->log($targets, $start, $end, $discoverchangedpaths,
$strictnodehistory, \&logreceiver, $pool);
Invoke the logreceiver subroutine on each logmessage from $start
to $end in turn, inclusive (but will never invoke receiver on a
given log message more than once).
$targets is a reference to an array containing all the paths or
URLs for which the log messages are desired. The logreceiver is
only invoked on messages whose revisions involved a change to some
path in $targets.
If $discoverchangedpaths is set, then the changedpaths argument
to the logreceiver routine will be passed on each invocation.
If $strictnodehistory is set, copy history (if any exists) will
not be traversed while harvesting revision logs for each target.
If $start or $end is undef the arperr code will be set to:
$SVN::Error::CLIENTBADREVISION.
Special case for repositories at revision 0:
If $start is 'HEAD' and $end is 1, then handle an empty (no
revisions) repository specially: instead of erroring because
requested revision 1 when the highest revision is 0, just invoke
$logreceiver on revision 0, passing undef to changed paths and
empty strings for the author and date. This is because that
particular combination of $start and $end usually indicates the
common case of log invocation; the user wants to see all log
messages from youngest to oldest, where the oldest commit is
revision 1. That works fine, except there are no commits in the
repository, hence this special case.
Calls the notify subroutine with a $SVN::Wc::Notify::Action::skip
signal on any unversioned targets.
The logreceiver takes the following arguments: $changedpaths,
$revision, $author, $date, $message, $pool
It is called once for each log $message from the $revision on $date
by $author. $author, $date or $message may be undef.
If $changedpaths is defined it references a hash with the keys
every path committed in $revision; the values are
svnlogchangedpatht objects.
$ctx->ls($target, $revision, $recursive, $pool);
Returns a hash of svndirentt 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::FSNOTFOUND
error.
$ctx->merge($src1, $rev1, $src2, $rev2, $targetwcpath, $recursive,
$ignoreancestry, $force, $dryrun, $pool);
Merge changes from $src1/$rev1 to $src2/$rev2 into the working-copy
path $targetwcpath.
$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 undef raises the
$SVN::Error::CLIENTBADREVISION error.
If $recursive is true (and the URLs are directories), apply changes
recursively; otherwise, only apply changes in the current
directory.
Use $ignoreancestry 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 $dryrun is true the merge is carried out, and the full
notification feedback is provided, but the working copy is not
modified.
Has no return.
$ctx->mkdir($targets, $pool);
Create a directory, either in a repository or a working copy.
If $targets contains URLs, immediately attempts to commit the
creation of the directories in $targets in the repository. Returns
a svnclientcommitinfot object.
Else, create the directories on disk, and attempt to schedule them
for addition. In this case returns undef.
Calls the notify callback when the directory has been created
(successfully) in the working copy, with the path of the new
directory. Note this is only called for items added to the working
copy.
$ctx->move($srcpath, $srcrevision, $dstpath, $force, $pool);
Move $srcpath to $dstpath.
$srcpath must be a file or directory under version control, or the
URL of a versioned item in the repository.
If $srcpath is a repository URL:
* $dstpath must also be a repository URL (existent or not).
* $srcrevision is used to choose the revision from which to copy
the $srcpath.
* The logmsg callback will be called for the commit log message.
* The move operation will be immediately committed. If the commit
succeeds, returns a svnclientcommitinfot object.
If $srcpath is a working copy path
* $dstpath must also be a working copy path (existent or not).
* $srcrevision is ignored and may be undef. The logmsg callback
will not be called.
* This is a scheduling operation. No changes will happen to the
repository until a commit occurs. This scheduling can be removed
with $ctx->revert(). If $srcpath is a file it is removed from the
working copy immediately. If $srcpath is a directory it will
remain in the working copy but all files, and unversioned items, it
contains will be removed.
* If $srcpath contains locally modified and/or unversioned items
and $force is not set, the copy will raise an error. If $force is
set such items will be removed.
The notify callback will be called twice for each item moved, once
to indicate the deletion of the moved node, and once to indicate
the addition of the new location of the node.
$ctx->propget($propname, $target, $revision, $recursive, $pool);
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.
$ctx->proplist($target, $revision, $recursive, $pool);
Returns a reference to an array of svnclientproplistitemt
objects.
For each item the nodename member of the proplistitem object
contains the name relative to the same base as $target.
If $revision is undef, 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::ENTRYNOTFOUND
error.
$ctx->propset($propname, $propval, $target, $recursive, $pool);
Set $propname to $propval on $target (a working copy or URL path).
If $recursive is true, then $propname will be set recursively on
$target and all children. If $recursive is false, and $target is a
directory, $propname will be set on oonnllyy $target.
A $propval of undef will delete the property.
If $propname is an svn-controlled property (i.e. prefixed with
svn:), then the caller is responsible for ensuring that $propval is
UTF8-encoded and uses LF line-endings.
$ctx->relocate($dir, $from, $to, $recursive, $pool);
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.
$ctx->resolved($path, $recursive, $pool);
Removed 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 $path's conflict state is removed, call the notify callback with
the $path.
$ctx->revert($paths, $recursive, $pool);
Restore the pristine version of a working copy $paths, effectively
undoing any local mods.
For each path in $paths, if it is a directory and $recursive is
true, this will be a recursive operation.
$ctx->revpropget($propname, $url, $revision, $pool);
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 $ctx->propget(), this routine doesn't
affect working copy at all; it's a pure network operation that
queries an uunnvveerrssiioonneedd property attached to a revision. This can
be used to query log messages, dates, authors, and the like.
$ctx->revproplist($url, $revision, $pool);
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 $ctx->proplist(), this routine doesn't
read a working copy at all; it's a pure network operation that
reads uunnvveerrssiioonneedd properties attached to a revision.
$ctx->revpropset($propname, $propval, $url, $revision, $force, $pool);
Set $propname to $propval on revision $revision in the repository
represented by $url.
Returns the actual revision affected. A $propval of undef 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 $ctx->propset(), this routine doesn't
affect the working copy at all; it's a pure network operation that
changes an uunnvveerrssiioonneedd 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.
$ctx->status($path, $revision, \&statusfunc, $recursive, $getall,
$update, $noignore, $pool);
Given $path to a working copy directory (or single file), call
statusfunc() with a set of svnwcstatust objects which describe
the status of $path and its children.
If $recursive is true, recurse fully, else do only immediate
children.
If $getall 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
undef 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::statusexternal
action before handling each externals definition, and with
$SVN::Wc::Notify::Action::statuscompleted after each.
The statusfunc subroutine takes the following parameters: $path,
$status
$path is the pathname of the file or directory which status is
being reported. $status is a svnwcstatust object.
The return of the statusfunc subroutine is ignored.
$ctx->info($pathorurl, $pegrevision, $revision, \&receiver,
$recurse);
Invokes \&receiver passing it information about $pathorurl for
$revision. The information returned is system-generated metadata,
not the sort of "property" metadata created by users. For methods
available on the object passed to \&receiver, sseeee ssvvnniinnffoott.
If both revision arguments are either svnoptrevisionunspecified
or NULL, then information will be pulled solely from the working
copy; no network connections will be made.
Otherwise, information will be pulled from a repository. The
actual node revision selected is determined by the $pathorurl as
it exists in $pegrevision. If $pegrevision is undef, then it
defaults to HEAD for URLs or WORKING for WC targets.
If $pathorurl is not a local path, then if $revision is PREV (or
some other kind that requires a local path), an error will be
returned, because the desired revision cannot be determined.
Uses the authentication baton cached in ctx to authenticate against
the repository.
If $recurse is true (and $pathorurl is a directory) this will be
a recursive operation, invoking $receiver on each child.
my $receiver = sub {
my( $path, $info, $pool ) = @;
print "Current revision of $path is ", $info->rev, "\n";
};
$ctx->info( 'foo/bar.c', undef, 'WORKING', $receiver, 0 );
$ctx->switch($path, $url, $revision, $recursive, $pool);
Switch working tree $path to $url at $revision.
$revision must be a number, 'HEAD', or a date, otherwise it raises
the $SVN::Error::CLIENTBADREVISION 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.
$ctx->update($path, $revision, $recursive, $pool)
Update a working copy $path to $revision.
$revision must be a revision number, 'HEAD', or a date or this
method will raise the $SVN::Error::CLIENTBADREVISION error.
Calls the notify callback for each item handled by the update, and
also for files restored from the text-base.
Returns the revision to which the working copy was actually
updated.
$ctx->urlfrompath($target, $pool); or
SVN::Client::urlfrompath($target, $pool);
Returns the URL for $target.
If $target is already a URL it returns $target.
If $target is a versioned item, it returns $target's entry URL.
If $target is unversioned (has no entry), returns undef.
$ctx->uuidfrompath($path, $admaccess, $pool);
Return the repository uuid for working-copy $path, allocated in
$pool.
Use $admaccess to retrieve the uuid from $path's entry; if not
present in the entry, then call $ctx->uuidfromurl() to retrieve,
using the entry's URL.
Note: The only reason this function falls back on
$ctx->uuidfromurl is for compatibility purposes. Old working
copies may not have uuids in the entries files.
Note: This method probably doesn't work right now without a lot of
pain, because SVN::Wc is incomplete and it requires an admaccess
object from it.
$ctx->uuidfromurl($url, $pool);
Return repository uuid for url.
AATTTTRRIIBBUUTTEE MMEETTHHOODDSS
The following attribute methods are provided that allow you to set
various configuration or retrieve it. They all take value(s) to set
the attribute and return the new value of the attribute or no
parameters which returns the current value.
$ctx->auth(SVN::Client::getusernameprovider());
Provides access to the authbaton in the svnclientctxt attached
to the SVN::Client object.
This method will accept an array or array ref of values returned
from the authentication provider functions see "AUTHENTICATION
PROVIDERS", which it will convert to an authbaton for you. This
is the preferred method of setting the authbaton.
It will also accept a scalar that references a psvnauthbatont
such as those returned from SVN::Core::authopen and
SVN::Core::authopenhelper.
$ctx->notify(\¬ify);
Sets the notify callback for the client context to a code reference
that you pass. It always returns the current codereference set.
The subroutine pointed to by this reference will be called when a
change is made to the working copy. The return value of this
function is ignored. It's only purpose is to notify you of the
change.
The subroutine will receive 6 parameters. The first parameter will
be the path of the changed file (absolute or relative to the cwd).
The second is an integer specifying the type of action taken. See
SVN::Wc for a list of the possible actions values and what they
mean. The 3rd is an integer specifying the kind of node the path
is, which can be: $SVN::Node::none, $SVN::Node::file,
$SVN::Node::dir, $SVN::Node::unknown. The fourth parameter is the
mime-type of the file or undef if the mime-type is unknown (it will
always be undef for directories). The 5th parameter is the state
of the file, again see SVN::Wc for a list of the possible states.
The 6th and final parameter is the numeric revision number of the
changed file. The revision number will be -1 except when the
action is $SVN::Wc::Notify::Action::updatecompleted.
$ctx->logmsg(\&logmsg)
Sets the logmsg callback for the client context to a code
reference that you pass. It always returns the current
codereference set.
The subroutine pointed to by this coderef will be called to get the
log message for any operation that will commit a revision to the
repo.
It receives 4 parameters. The first parameter is a reference to a
scalar value in which the callback should place the logmsg. If
you wish to cancel the commit you can set this scalar to undef.
The 2nd value is a path to a temporary file which might be holding
that log message, or undef if no such field exists (though, if
logmsg is undef, this value is undefined). The log message MMUUSSTT
be a UTF8 string with LF line separators. The 3rd parameter is a
reference to an array of svnclientcommititemt objects, which
may be fully or only partially filled-in, depending on the type of
commit operation. The 4th and last parameter will be a pool.
If the function wishes to return an error it should return a
svnerrort object made with SVN::Error::create. Any other return
value will be interpreted as SVNNOERROR.
$ctx->cancel(\&cancel)
Sets the logmsg callback for the client context to a code
reference that you pass. It always returns the current
codereference set.
The subroutine pointed to by this value will be called to see if
the operation should be canceled. If the operation should be
canceled, the function may return one of the following values:
An svnerrort object made with SVN::Error::create.
Any true value, in which case the bindings will generate an
svnerrort object for you with the error code of SVNERRCANCELLED
and the string set to "By cancel callback".
A string, in which case the bindings will generate an svnerrort
object for you with the error code of SVNERRCANCELLED and the
string set to the string you returned.
Any other value will be interpreted as wanting to continue the
operation. Generally, it's best to return 0 to continue the
operation.
$ctx->pool(new SVN::Pool);
Method that sets or gets the default pool that is passed to method
calls requiring a pool, but which were not explicitly passed one.
See SVN::Core for more information about how pools are managed in
this interface.
$ctx->config(SVN::Core::configgetconfig(undef));
Method that allows access to the config member of the
svnclientctxt. Accepts a Perl hash to set, which is what
functions like SVN::Core:configgetconfig() will return.
It will return a parphasht scalar. This is a temporary
situation. The return value is not particular useful. In the
future, this value will be tied to the actual hash used by the C
API.
AAUUTTHHEENNTTIICCAATTIIOONN PPRROOVVIIDDEERRSS
The following functions get authentication providers for you. They
come in two forms. Standard or File versions, which look for
authentication information in the subversion configuration directory
that was previously cached, or Prompt versions which call a subroutine
to allow you to prompt the user for the information.
The functions that return the svnauthproviderobjectt for prompt
style providers take a reference to a Perl subroutine to use for the
callback. The first parameter each of these subroutines receive is a
credential object. The subroutines return the response by setting
members of that object. Members may be set like so:
$cred->username("breser"); These functions and credential objects
always have a maysave member which specifies if the authentication
data will be cached.
The providers are as follows:
NAME WHAT IT HANDLES
-------- --------------------
simple username and password pairs
username username only
sslservertrust server certificates and failures
authenticating them
sslclientcert client side certificate files
sslclientcertpw password for a client side certificate file.
SVN::Client::getsimpleprovider
Returns a simple provider that returns information from previously
cached sessions. Takes no parameters or one pool parameter.
SVN::Client::getsimplepromptprovider
Returns a simple provider that prompts the user via a callback.
Takes two or three parameters, the first is the callback
subroutine, the 2nd is the number of retries to allow, the 3rd is
optionally a pool. The subroutine gets called with the following
parameters: a svnauthcredsimplet object, a realm string, a
default username, maysave, and a pool. The svnauthcredsimple
has the following members: username, password, and maysave.
SVN::Client::getusernameprovider
Returns a username provider that returns information from a
previously cached sessions. Takes no parameters or one pool
parameter.
SVN::Client::getusernamepromptprovider
Returns a username provider that prompts the user via a callback.
Takes two or three parameters, the first is the callback
subroutine, the 2nd is the number of retries to allow, the 3rd is
optionally a pool. The subroutine gets called with the following
parameters: a svnauthcredusernamet object, a realm string, a
default username, maysave, and a pool. The svnauthcredusername
has the following members: username and maysave.
SVN::Client::getsslservertrustfileprovider
Returns a server trust provider that returns information from
previously cached sessions. Takes no parameters or optionally a
pool parameter.
SVN::Client::getsslservertrustpromptprovider
Returns a server trust provider that prompts the user via a
callback. Takes one or two parameters the callback subroutine and
optionally a pool parameter. The subroutine gets called with the
following parameters. A svnauthcredsslservertrustt object, a
realm string, an integer specifying how the certificate failed
authentication, a svnauthsslservercertinfot object, maysave,
and a pool. The svnauthcredsslservertrustt object has the
following members: maysave and acceptedfailures. The
svnauthsslservercertinfot object has the following members
(and behaves just like cred objects though you can't modify it):
hostname, fingerprint, validfrom, validuntil, issuerdname,
asciicert.
The masks used for determining the failures are in SVN::Auth::SSL
and are named:
$SVN::Auth::SSL::NOTYETVALID $SVN::Auth::SSL::EXPIRED
$SVN::Auth::SSL::CNMISMATCH $SVN::Auth::SSL::UNKNOWNCA
$SVN::Auth::SSL::OTHER
You reply by setting the acceptedfailures of the cred object with
an integer of the values for what you want to accept bitwise AND'd
together.
SVN::Client::getsslcertfileprovider
Returns a client certificate provider that returns information from
previously cached sessions. Takes no parameters or optionally a
pool parameter.
SVN::Client::getsslcertpromptprovider
Returns a client certificate provider that prompts the user via a
callback. Takes two or three parameters: the first is the callback
subroutine, the 2nd is the number of retries to allow, the 3rd is
optionally a pool parameter. The subroutine gets called with the
following parameters. A svnauthcredsslclientcert object, a
realm string, maysave, and a pool. The
svnauthcredsslclientcert the following members: certfile and
maysave.
SVN::Client::getsslcertpwfileprovider
Returns a client certificate password provider that returns
information from previously cached sessions. Takes no parameters
or optionally a pool parameter.
SVN::Client::getsslcertpwpromptprovider
Returns a client certificate password provider that prompts the
user via a callback. Takes two or three parameters, the first is
the callback subroutine, the 2nd is the number of retries to allow,
the 3rd is optionally a pool parameter. The subroutine gets called
with the following parameters. A svnauthcredsslclientcertpw
object, a realm string, maysave, and a pool. The
svnauthcredsslclientcertpw has the following members:
password and maysave.
OOBBJJEECCTTSS
These are some of the object types that are returned from the methods
and functions. Others are documented in SVN::Core and SVN::Wc. If an
object is not documented, it is more than likely opaque and not
something you can do anything with, except pass to other functions that
require such objects.
ssvvnniinnffoott
$info->URL()
Where the item lives in the repository.
$info->rev()
The revision of the object. If pathorurl is a working-copy
path, then this is its current working revnum. If pathorurl
is a URL, then this is the repos revision that pathorurl
lives in.
$info->kind()
The node's kind.
$info->reposrootURL()
The root URL of the repository.
$info->reposUUID()
The repository's UUID.
$info->lastchangedrev()
The last revision in which this object changed.
$info->lastchangeddate()
The date of the lastchangedrev.
$info->lastchangedauthor()
The author of the lastchangedrev.
$info->lock()
An exclusive lock, if present. Could be either local or
remote.
See SVN::Wc::svnwcentryt for the rest of these. svnclient.h
indicates that these were copied from that struct and mean the same
things. They are also only useful when working with a WC.
$info->haswcinfo()
$info->schedule()
$info->copyfromurl()
$info->copyfromrev()
$info->texttime()
$info->proptime()
$info->checksum()
$info->conflictold()
$info->conflictnew()
$info->conflictwrk()
$info->prejfile()
ssvvnncclliieennttccoommmmiittiitteemmtt
$citem->path()
Absolute working-copy path of item.
$citem->kind()
An integer representing the type of node it is (file/dir). Can
be one of the following constants: $SVN::Node::none
$SVN::Node::file $SVN::Node::dir $SVN::Node::unknown
$citem->url()
Commit URL for this item.
$citem->revision()
Revision (copyfromrev if stateflags has ISCOPY set).
$citem->copyformurl();
CopyFrom URL
$citem->stateflags();
One of several state flags: $SVN::Client::COMMITITEMADD
$SVN::Client::COMMITITEMDELETE
$SVN::Client::COMMITITEMTEXTMODS
$SVN::Client::COMMITITEMPROPMODS
$SVN::Client::COMMITITEMISCOPY
$citem>wcpropchanges()
A reference to an array of svnpropt objects represent changes
to wc properties.
ssvvnncclliieennttccoommmmiittiinnffoott
$cinfo->revision()
Just committed revision.
$cinfo->date()
Server-Side date of the commit as a string.
$cinfo->author()
Author of the commit.
ssvvnncclliieennttpprroopplliissttiitteemmtt
$proplist->nodename()
The name of the node on which these properties are set.
$proplist->prophash()
A reference to a hash of property names and values.
TTOODDOO
* Better support for the config.
* Unit tests for cleanup, diff, export, merge, move, relocate, resolved
and switch. This may reveal problems for using these methods as I
haven't tested them yet that require deeper fixes.
AUTHORS Chia-liang Kao
Ben Reser
COPYRIGHT Copyright (c) 2003 CollabNet. All rights reserved.
This software is licensed as described in the file COPYING, which you
should have received as part of this distribution. The terms are also
available at http://subversion.tigris.org/license-1.html. If newer
versions of this license are posted there, you may use a newer version
instead, at your option.
This software consists of voluntary contributions made by many
individuals. For exact contribution history, see the revision history
and logs, available at http://subversion.tigris.org/.
PPOODD EERRRROORRSS
e! The above document had some coding errors, which are explained bbeellooww::
Around line 1309:
You forgot a '=back' before '=head2'
perl v5.8.8 2006-03-07 native::Client(3)