1native::Client(3) User Contributed Perl Documentation native::Client(3)
2
6 SVN::Client - Subversion client functions
7
9 use SVN::Client;
10 my $ctx = new SVN::Client(
11 auth => [SVN::Client::get_simple_provider(),
12 SVN::Client::get_simple_prompt_provider(\&simple_prompt,2),
13 SVN::Client::get_username_provider()]
14 );
15 $ctx->cat (\*STDOUT, 'http://svn.collab.net/repos/svn/trunk/README',
17 'HEAD');
18 sub simple_prompt {
20 my $cred = shift;
21 my $realm = shift;
22 my $default_username = shift;
23 my $may_save = shift;
24 my $pool = shift;
25 print "Enter authentication info for realm: $realm\n";
27 print "Username: ";
28 my $username = <>;
29 chomp($username);
30 $cred->username($username);
31 print "Password: ";
32 my $password = <>;
33 chomp($password);
34 $cred->password($password);
35 }
36
38 SVN::Client wraps the highest level of functions provided by subversion
39 to accomplish specific tasks in an object oriented API. Methods are
40 similar to the functions provided by the C API and as such the documen‐
41 tation for it may be helpful in understanding this interface.
42 There are a few notable differences from the C API. Most C function
44 calls take a svn_client_ctx_t pointer as the next to last parameter.
45 The Perl method calls take a SVN::Client object as the first parameter.
46 This allows method call invocation of the methods to be possible. For
47 example, the following are equivalent:
48 SVN::Client::add($ctx,$path, $recursive, $pool);
50 $ctx->add($path, $recursive, $pool);
51 Many of the C API calls also take a apr_pool_t pointer as their last
53 argument. The Perl bindings generally deal with this for you and you
54 do not need to pass a pool parameter. However, you may still pass a
55 pool parameter as the last parameter to override the automatic handling
56 of this for you.
57 Users of this interface should not directly manipulate the underlying
59 hash values but should use the respective attribute methods. Many of
60 these attribute methods do other things, especially when setting an
61 attribute, besides simply manipulating the value in the hash.
62
64 The client methods described below take a variety of parameters. Many
65 of them are similar. Methods accepting parameters named below will
66 follow the rules below or will be noted otherwise in the method
67 description.
68 $ctx
70 An SVN::Client object that you get from the constructor.
71 $url
73 This is a URL to a subversion repository.
74 $path
76 This is a path to a file or directory on the local file system.
77 $paths
79 This argument can either be a single path to a file or directory on
80 the local file system, or it can be a reference to an array of
81 files or directories on the local file system.
82 $target
84 This is a path to a file or directory in a working copy or a URL to
85 a file or directory in a subversion repository.
86 $targets
88 This argument can either be a single $target (as defined above) or
89 a reference to an array of them.
90 $revision
92 This specifies a revision in the subversion repository. You can
93 specify a revision in several ways. The easiest and most obvious
94 is to directly provide the revision number. You may also use the
95 strings (aka revision keywords) 'HEAD', 'BASE', 'COMMITTED', and
96 'PREV' which have the same meanings as in the command line client.
97 When referencing a working copy you can use the string 'WORKING" to
98 reference the BASE plus any local modifications. undef may be used
99 to specify an unspecified revision. Finally you may pass a date by
100 specifying the date inside curly braces '{}'. The date formats
101 accepted are the same as the command line client accepts.
102 $recursive $nonrecursive.
104 A boolean parameter that specifies if the action should follow
105 directories. It should only be 1 or 0. $recursive means, 1 means
106 to descend into directories, 0 means not to. $nonrecursive has the
107 inverse meaning.
108 $pool
110 Pool is always an option parameter. If you wish to pass a pool
111 parameter it should be a SVN::Pool or an apr_pool_t object.
112
114 The following methods are available:
115 $ctx = SVN::Client->new( %options );
117 This class method constructs a new "SVN::Client" object and returns
118 a reference to it.
119 Key/value pair arguments may be provided to set up the initial
121 state of the user agent. The following methods correspond to
122 attribute methods described below:
123 KEY DEFAULT
125 ---------- ----------------------------------------
126 auth auth_baton initiated with providers that
127 read cached authentication options from
128 the subversion config only.
129 cancel undef
131 config Hash containing the config from the
133 default subversion config file location.
134 log_msg undef
136 notify undef
138 pool A new pool is created for the context.
140 $ctx->add($path, $recursive, $pool);
142 Schedule a working copy $path for addition to the repository.
143 $path's parent must be under revision control already, but $path is
145 not. If $recursive is set, then assuming $path is a directory, all
146 of its contents will be scheduled for addition as well.
147 Calls the notify callback for each added item.
149 Important: this is a scheduling operation. No changes will happen
151 to the repository until a commit occurs. This scheduling can be
152 removed with $ctx->revert().
153 No return.
155 $ctx->blame($target, $start, $end, \&receiver, $pool);
157 Invoke \&receiver subroutine on each line-blame item associated
158 with revision $end of $target, using $start as the default source
159 of all blame.
160 An Error will be raised if either $start or $end is undef.
162 No return.
164 The blame receiver subroutine receives the following arguments:
166 $line_no, $revision, $author, $date, $line, $pool
167 $line_no is the line number of the file (starting with 0). The
169 line was last changed in revision number $revision by $author on
170 $date and the contents were $line.
171 The blame receiver subroutine can return an svn_error_t object to
173 return an error. All other returns will be ignored. You can cre‐
174 ate an svn_error_t object with SVN::Error::create().
175 $ctx->cat(\*FILEHANDLE, $target, $revision, $pool);
177 Outputs the content of the file identified by $target and $revision
178 to the FILEHANDLE. FILEHANDLE is a reference to a filehandle.
179 If $target is not a local path and if $revision is 'PREV' (or some
181 other kind that requires a local path), then an error will be
182 raised, because the desired revision can not be determined.
183 $ctx->checkout($url, $path, $revision, $recursive, $pool);
185 Checkout a working copy of $url at $revision using $path as the
186 root directory of the newly checked out working copy.
187 $revision must be a number, 'HEAD', or a date. If $revision does
189 not meet these requirements the $SVN::Error::CLIENT_BAD_REVISION is
190 raised.
191 Returns the value of the revision actually checked out of the
193 repository.
194 $ctx->cleanup($dir, $pool);
196 Recursively cleanup a working copy directory, $dir, finishing any
197 incomplete operations, removing lockfiles, etc.
198 $ctx->commit($targets, $nonrecursive, $pool);
200 Commit files or directories referenced by target. Will use the
201 log_msg callback to obtain the log message for the commit.
202 If $targets contains no paths (zero elements), then does nothing
204 and immediately returns without error.
205 Calls the notify callback as the commit progresses with any of the
207 following actions: $SVN::Wc::Notify::Action::commit_modified,
208 $SVN::Wc::Notify::Action::commit_added,
209 $SVN::Wc::Notify::Action::commit_deleted,
210 $SVN::Wc::Notify::Action::commit_replaced,
211 $SVN::Wc::Notify::Action::commit_postfix_txdelta.
212 Use $nonrecursive to indicate that subdirectories of directory tar‐
214 gets should be ignored.
215 Returns a svn_client_commit_info_t object. If the revision member
217 of the commit information object is $SVN::Core::INVALID_REVNUM and
218 no error was raised, then the commit was a no-op; nothing needed to
219 be committed.
220 $ctx->copy($src_target, $src_revision, $dst_target, $pool);
222 Copies $src_target to $dst_target.
223 $src_target must be a file or directory under version control, or
225 the URL of a versioned item in the repository. If $src_target is a
226 URL, $src_revision is used to choose the revision from which to
227 copy the $src_target. $dst_path must be a file or directory under
228 version control, or a repository URL, existing or not.
229 If $dst_target is a URL, immediately attempt to commit the copy
231 action to the repository. The log_msg callback will be called to
232 query for a commit log message. If the commit succeeds, return a
233 svn_client_commit_info_t object.
234 If $dst_target is not a URL, then this is just a variant of
236 $ctx->add(), where the $dst_path items are scheduled for addition
237 as copies. No changes will happen to the repository until a commit
238 occurs. This scheduling can be removed with $ctx->revert(). undef
239 will be returned in this case.
240 Calls the notify callback for each item added at the new location,
242 passing the new, relative path of the added item.
243 $ctx->delete($targets, $force, $pool);
245 Delete items from a repository or working copy.
246 If the paths in $targets are URLs, immediately attempt to commit a
248 deletion of the URLs from the repository. The log_msg callback
249 will be called to query for a commit log message. If the commit
250 succeeds, return a svn_client_commit_info_t object. Every path
251 must belong to the same repository.
252 Else, schedule the working copy paths in $targets for removal from
254 the repository. Each path's parent must be under revision control.
255 This is just a scheduling operation. No changes will happen to the
256 repository until a commit occurs. This scheduling can be removed
257 with $ctx->revert(). If a path is a file it is immediately removed
258 from the working copy. If the path is a directory it will remain
259 in the working copy but all the files, and all unversioned items it
260 contains will be removed. If $force is not set then this operation
261 will fail if any path contains locally modified and/or unversioned
262 items. If $force is set such items will be deleted.
263 The notify callback is called for each item deleted with the path
265 of the deleted item.
266 Has no return.
268 $ctx->diff($diff_options, $target1, $revision1, $target2, $revision2,
270 $recursive, $ignore_ancestry, $no_diff_deleted, $outfile, $errfile,
271 $pool);
272 Produces diff output which describes the delta between $target1 at
273 $revision1 and $target2 at $revision2. They both must represent
274 the same node type (i.e. they most both be directories or files).
275 The revisions must not be undef.
276 Prints the output of the diff to the filename or filehandle passed
278 as $outfile, and any errors to the filename or filehandle passed as
279 $errfile.
280 Use $ignore_ancestry to control whether or not items being diffed
282 will be checked for relatedness first. Unrelated items are typi‐
283 cally transmitted to the editor as a deletion of one thing and the
284 addition of another, but if this flag is true, unrelated items will
285 be diffed as if they were related.
286 If $no_diff_deleted is true, then no diff output will be generated
288 on deleted files.
289 $diff_options is a reference to an array of additional arguments to
291 pass to diff process invoked to compare files. You'll usually just
292 want to use [] to pass an empty array to return a unified context
293 diff (like `diff -u`).
294 Has no return.
296 $ctx->export($from, $to, $revision, $force, $pool);
298 Export the contents of either a subversion repository or a subver‐
299 sion working copy into a 'clean' directory (meaning a directory
300 with no administrative directories).
301 $from is either the path to the working copy on disk, or a URL to
303 the repository you wish to export.
304 $to is the path to the directory where you wish to create the
306 exported tree.
307 $revision is the revision that should be exported, which is only
309 used when exporting from a repository. It may be undef otherwise.
310 The notify callback will be called for the items exported.
312 Returns the value of the revision actually exported or
314 $SVN::Core::INVALID_REVNUM for local exports.
315 $ctx->import($path, $url, $nonrecursive, $pool);
317 Import file or directory $path into repository directory $url at
318 head.
319 If some components of $url do not exist then create parent directo‐
321 ries as necessary.
322 If $path is a directory, the contents of that directory are
324 imported directly into the directory identified by $url. Note that
325 the directory $path itself is not imported; that is, the basename
326 of $path is not part of the import.
327 If $path is a file, then the dirname of $url is the directory
329 receiving the import. The basename of $url is the filename in the
330 repository. In this case if $url already exists, raise an error.
331 The notify callback (if defined) will be called as the import pro‐
333 gresses, with any of the following actions:
334 $SVN::Wc::Notify::Action::commit_added,
335 $SVN::Wc::Notify::Action::commit_postfix_txdelta.
336 Use $nonrecursive to indicate that imported directories should not
338 recurse into any subdirectories they may have.
339 Uses the log_msg callback to determine the log message for the com‐
341 mit when one is needed.
342 Returns a svn_client_commit_info_t object.
344 $ctx->log($targets, $start, $end, $discover_changed_paths,
346 $strict_node_history, \&log_receiver, $pool);
347 Invoke the log_receiver subroutine on each log_message from $start
348 to $end in turn, inclusive (but will never invoke receiver on a
349 given log message more than once).
350 $targets is a reference to an array containing all the paths or
352 URLs for which the log messages are desired. The log_receiver is
353 only invoked on messages whose revisions involved a change to some
354 path in $targets.
355 If $discover_changed_paths is set, then the changed_paths argument
357 to the log_receiver routine will be passed on each invocation.
358 If $strict_node_history is set, copy history (if any exists) will
360 not be traversed while harvesting revision logs for each target.
361 If $start or $end is undef the arp_err code will be set to:
363 $SVN::Error::CLIENT_BAD_REVISION.
364 Special case for repositories at revision 0:
366 If $start is 'HEAD' and $end is 1, then handle an empty (no revi‐
368 sions) repository specially: instead of erroring because requested
369 revision 1 when the highest revision is 0, just invoke
370 $log_receiver on revision 0, passing undef to changed paths and
371 empty strings for the author and date. This is because that par‐
372 ticular combination of $start and $end usually indicates the common
373 case of log invocation; the user wants to see all log messages from
374 youngest to oldest, where the oldest commit is revision 1. That
375 works fine, except there are no commits in the repository, hence
376 this special case.
377 Calls the notify subroutine with a $SVN::Wc::Notify::Action::skip
379 signal on any unversioned targets.
380 The log_receiver takes the following arguments: $changed_paths,
382 $revision, $author, $date, $message, $pool
383 It is called once for each log $message from the $revision on $date
385 by $author. $author, $date or $message may be undef.
386 If $changed_paths is defined it references a hash with the keys
388 every path committed in $revision; the values are
389 svn_log_changed_path_t objects.
390 $ctx->ls($target, $revision, $recursive, $pool);
392 Returns a hash of svn_dirent_t objects for $target at $revision.
393 If $target is a directory, returns entries for all of the directo‐
395 ries' contents. If $recursive is true, it will recurse subdirecto‐
396 ries in $target.
397 If $target is a file only return an entry for the file.
399 If $target is non-existent, raises the $SVN::Error::FS_NOT_FOUND
401 error.
402 $ctx->merge($src1, $rev1, $src2, $rev2, $target_wcpath, $recursive,
404 $ignore_ancestry, $force, $dry_run, $pool);
405 Merge changes from $src1/$rev1 to $src2/$rev2 into the working-copy
406 path $target_wcpath.
407 $src1 and $src2 are either URLs that refer to entries in the repos‐
409 itory, or paths to entries in the working copy.
410 By 'merging', we mean: apply file differences and schedule addi‐
412 tions & deletions when appropriate.
413 $src1 and $src2 must both represent the same node kind; that is, if
415 $src1 is a directory, $src2 must also be, and if $src1 is a file,
416 $src2 must also be.
417 If either $rev1 or $rev2 is undef raises the
419 $SVN::Error::CLIENT_BAD_REVISION error.
420 If $recursive is true (and the URLs are directories), apply changes
422 recursively; otherwise, only apply changes in the current direc‐
423 tory.
424 Use $ignore_ancestry to control whether or not items being diffed
426 will be checked for relatedness first. Unrelated items are typi‐
427 cally transmitted to the editor as a deletion of one thing and the
428 addition of another, but if this flag is true, unrelated items will
429 be diffed as if they were related.
430 If $force is not set and the merge involves deleting locally modi‐
432 fied or unversioned items the operation will raise an error. If
433 $force is set such items will be deleted.
434 Calls the notify callback once for each merged target, passing the
436 targets local path.
437 If $dry_run is true the merge is carried out, and the full notifi‐
439 cation feedback is provided, but the working copy is not modified.
440 Has no return.
442 $ctx->mkdir($targets, $pool);
444 Create a directory, either in a repository or a working copy.
445 If $targets contains URLs, immediately attempts to commit the cre‐
447 ation of the directories in $targets in the repository. Returns a
448 svn_client_commit_info_t object.
449 Else, create the directories on disk, and attempt to schedule them
451 for addition. In this case returns undef.
452 Calls the notify callback when the directory has been created (suc‐
454 cessfully) in the working copy, with the path of the new directory.
455 Note this is only called for items added to the working copy.
456 $ctx->move($src_path, $src_revision, $dst_path, $force, $pool);
458 Move $src_path to $dst_path.
459 $src_path must be a file or directory under version control, or the
461 URL of a versioned item in the repository.
462 If $src_path is a repository URL:
464 * $dst_path must also be a repository URL (existent or not).
466 * $src_revision is used to choose the revision from which to copy
468 the $src_path.
469 * The log_msg callback will be called for the commit log message.
471 * The move operation will be immediately committed. If the commit
473 succeeds, returns a svn_client_commit_info_t object.
474 If $src_path is a working copy path
476 * $dst_path must also be a working copy path (existent or not).
478 * $src_revision is ignored and may be undef. The log_msg callback
480 will not be called.
481 * This is a scheduling operation. No changes will happen to the
483 repository until a commit occurs. This scheduling can be removed
484 with $ctx->revert(). If $src_path is a file it is removed from the
485 working copy immediately. If $src_path is a directory it will
486 remain in the working copy but all files, and unversioned items, it
487 contains will be removed.
488 * If $src_path contains locally modified and/or unversioned items
490 and $force is not set, the copy will raise an error. If $force is
491 set such items will be removed.
492 The notify callback will be called twice for each item moved, once
494 to indicate the deletion of the moved node, and once to indicate
495 the addition of the new location of the node.
496 $ctx->propget($propname, $target, $revision, $recursive, $pool);
498 Returns a reference to a hash containing paths or URLs, prefixed by
499 $target (a working copy or URL), of items for which the property
500 $propname is set, and whose values represent the property value for
501 $propname at that path.
502 $ctx->proplist($target, $revision, $recursive, $pool);
504 Returns a reference to an array of svn_client_proplist_item_t
505 objects.
506 For each item the node_name member of the proplist_item object con‐
508 tains the name relative to the same base as $target.
509 If $revision is undef, then get properties from the working copy,
511 if $target is a working copy, or from the repository head if $tar‐
512 get is a URL. Else get the properties as of $revision.
513 If $recursive is false, or $target is a file, the returned array
515 will only contain a single element. Otherwise, it will contain one
516 entry for each versioned entry below (and including) $target.
517 If $target is not found, raises the $SVN::Error::ENTRY_NOT_FOUND
519 error.
520 $ctx->propset($propname, $propval, $target, $recursive, $pool);
522 Set $propname to $propval on $target (a working copy or URL path).
523 If $recursive is true, then $propname will be set recursively on
525 $target and all children. If $recursive is false, and $target is a
526 directory, $propname will be set on only $target.
527 A $propval of undef will delete the property.
529 If $propname is an svn-controlled property (i.e. prefixed with
531 svn:), then the caller is responsible for ensuring that $propval is
532 UTF8-encoded and uses LF line-endings.
533 $ctx->relocate($dir, $from, $to, $recursive, $pool);
535 Modify a working copy directory $dir, changing any repository URLs
536 that begin with $from to begin with $to instead, recursing into
537 subdirectories if $recursive is true.
538 Has no return.
540 $ctx->resolved($path, $recursive, $pool);
542 Removed the 'conflicted' state on a working copy path.
543 This will not semantically resolve conflicts; it just allows $path
545 to be committed in the future. The implementation details are
546 opaque. If $recursive is set, recurse below $path, looking for
547 conflicts to resolve.
548 If $path is not in a state of conflict to begin with, do nothing.
550 If $path's conflict state is removed, call the notify callback with
552 the $path.
553 $ctx->revert($paths, $recursive, $pool);
555 Restore the pristine version of a working copy $paths, effectively
556 undoing any local mods.
557 For each path in $paths, if it is a directory and $recursive is
559 true, this will be a recursive operation.
560 $ctx->revprop_get($propname, $url, $revision, $pool);
562 Returns two values, the first of which is the value of $propname on
563 revision $revision in the repository represented by $url. The sec‐
564 ond value is the actual revision queried.
565 Note that unlike its cousin $ctx->propget(), this routine doesn't
567 affect working copy at all; it's a pure network operation that
568 queries an unversioned property attached to a revision. This can
569 be used to query log messages, dates, authors, and the like.
570 $ctx->revprop_list($url, $revision, $pool);
572 Returns two values, the first of which is a reference to a hash
573 containing the properties attached to $revision in the repository
574 represented by $url. The second value is the actual revision
575 queried.
576 Note that unlike its cousin $ctx->proplist(), this routine doesn't
578 read a working copy at all; it's a pure network operation that
579 reads unversioned properties attached to a revision.
580 $ctx->revprop_set($propname, $propval, $url, $revision, $force, $pool);
582 Set $propname to $propval on revision $revision in the repository
583 represented by $url.
584 Returns the actual revision affected. A $propval of undef will
586 delete the property.
587 If $force is true, allow newlines in the author property.
589 If $propname is an svn-controlled property (i.e. prefixed with
591 svn:), then the caller is responsible for ensuring that the value
592 is UTF8-encoded and uses LF line-endings.
593 Note that unlike its cousin $ctx->propset(), this routine doesn't
595 affect the working copy at all; it's a pure network operation that
596 changes an unversioned property attached to a revision. This can
597 be used to tweak log messages, dates, authors, and the like. Be
598 careful: it's a lossy operation, meaning that any existing value is
599 replaced with the new value, with no way to retrieve the prior
600 value.
601 Also note that unless the administrator creates a pre-revprop-
603 change hook in the repository, this feature will fail.
604 $ctx->status($path, $revision, \&status_func, $recursive, $get_all,
606 $update, $no_ignore, $pool);
607 Given $path to a working copy directory (or single file), call sta‐
608 tus_func() with a set of svn_wc_status_t objects which describe the
609 status of $path and its children.
610 If $recursive is true, recurse fully, else do only immediate chil‐
612 dren.
613 If $get_all is set, retrieve all entries; otherwise, retrieve only
615 'interesting' entries (local mods and/or out-of-date).
616 If $update is set, contact the repository and augment the status
618 objects with information about out-of-dateness (with respect to
619 $revision). Also, will return the value of the actual revision
620 against with the working copy was compared. (The return will be
621 undef if $update is not set).
622 The function recurses into externals definitions ('svn:externals')
624 after handling the main target, if any exist. The function calls
625 the notify callback with $SVN::Wc::Notify::Action::status_external
626 action before handling each externals definition, and with
627 $SVN::Wc::Notify::Action::status_completed after each.
628 The status_func subroutine takes the following parameters: $path,
630 $status
631 $path is the pathname of the file or directory which status is
633 being reported. $status is a svn_wc_status_t object.
634 The return of the status_func subroutine is ignored.
636 $ctx->info($path_or_url, $peg_revision, $revision, \&receiver,
638 $recurse);
639 Invokes \&receiver passing it information about $path_or_url for
640 $revision. The information returned is system-generated metadata,
641 not the sort of "property" metadata created by users. For methods
642 available on the object passed to \&receiver, see svn_info_t.
643 If both revision arguments are either svn_opt_revision_unspecified
645 or NULL, then information will be pulled solely from the working
646 copy; no network connections will be made.
647 Otherwise, information will be pulled from a repository. The
649 actual node revision selected is determined by the $path_or_url as
650 it exists in $peg_revision. If $peg_revision is undef, then it
651 defaults to HEAD for URLs or WORKING for WC targets.
652 If $path_or_url is not a local path, then if $revision is PREV (or
654 some other kind that requires a local path), an error will be
655 returned, because the desired revision cannot be determined.
656 Uses the authentication baton cached in ctx to authenticate against
658 the repository.
659 If $recurse is true (and $path_or_url is a directory) this will be
661 a recursive operation, invoking $receiver on each child.
662 my $receiver = sub {
664 my( $path, $info, $pool ) = @_;
665 print "Current revision of $path is ", $info->rev, "\n";
666 };
667 $ctx->info( 'foo/bar.c', undef, 'WORKING', $receiver, 0 );
668 $ctx->switch($path, $url, $revision, $recursive, $pool);
670 Switch working tree $path to $url at $revision.
671 $revision must be a number, 'HEAD', or a date, otherwise it raises
673 the $SVN::Error::CLIENT_BAD_REVISION error.
674 Calls the notify callback on paths affected by the switch. Also
676 invokes the callback for files that may be restored from the text-
677 base because they were removed from the working copy.
678 Summary of purpose: This is normally used to switch a working
680 directory over to another line of development, such as a branch or
681 a tag. Switching an existing working directory is more efficient
682 than checking out $url from scratch.
683 Returns the value of the revision to which the working copy was
685 actually switched.
686 $ctx->update($path, $revision, $recursive, $pool)
688 Update a working copy $path to $revision.
689 $revision must be a revision number, 'HEAD', or a date or this
691 method will raise the $SVN::Error::CLIENT_BAD_REVISION error.
692 Calls the notify callback for each item handled by the update, and
694 also for files restored from the text-base.
695 Returns the revision to which the working copy was actually
697 updated.
698 $ctx->url_from_path($target, $pool); or
700 SVN::Client::url_from_path($target, $pool);
701 Returns the URL for $target.
702 If $target is already a URL it returns $target.
704 If $target is a versioned item, it returns $target's entry URL.
706 If $target is unversioned (has no entry), returns undef.
708 $ctx->uuid_from_path($path, $adm_access, $pool);
710 Return the repository uuid for working-copy $path, allocated in
711 $pool.
712 Use $adm_access to retrieve the uuid from $path's entry; if not
714 present in the entry, then call $ctx->uuid_from_url() to retrieve,
715 using the entry's URL.
716 Note: The only reason this function falls back on
718 $ctx->uuid_from_url is for compatibility purposes. Old working
719 copies may not have uuids in the entries files.
720 Note: This method probably doesn't work right now without a lot of
722 pain, because SVN::Wc is incomplete and it requires an adm_access
723 object from it.
724 $ctx->uuid_from_url($url, $pool);
726 Return repository uuid for url.
727
729 The following attribute methods are provided that allow you to set var‐
730 ious configuration or retrieve it. They all take value(s) to set the
731 attribute and return the new value of the attribute or no parameters
732 which returns the current value.
733 $ctx->auth(SVN::Client::get_username_provider());
735 Provides access to the auth_baton in the svn_client_ctx_t attached
736 to the SVN::Client object.
737 This method will accept an array or array ref of values returned
739 from the authentication provider functions see "AUTHENTICATION
740 PROVIDERS", which it will convert to an auth_baton for you. This
741 is the preferred method of setting the auth_baton.
742 It will also accept a scalar that references a _p_svn_auth_baton_t
744 such as those returned from SVN::Core::auth_open and
745 SVN::Core::auth_open_helper.
746 $ctx->notify(\¬ify);
748 Sets the notify callback for the client context to a code reference
749 that you pass. It always returns the current codereference set.
750 The subroutine pointed to by this reference will be called when a
752 change is made to the working copy. The return value of this func‐
753 tion is ignored. It's only purpose is to notify you of the change.
754 The subroutine will receive 6 parameters. The first parameter will
756 be the path of the changed file (absolute or relative to the cwd).
757 The second is an integer specifying the type of action taken. See
758 SVN::Wc for a list of the possible actions values and what they
759 mean. The 3rd is an integer specifying the kind of node the path
760 is, which can be: $SVN::Node::none, $SVN::Node::file,
761 $SVN::Node::dir, $SVN::Node::unknown. The fourth parameter is the
762 mime-type of the file or undef if the mime-type is unknown (it will
763 always be undef for directories). The 5th parameter is the state
764 of the file, again see SVN::Wc for a list of the possible states.
765 The 6th and final parameter is the numeric revision number of the
766 changed file. The revision number will be -1 except when the
767 action is $SVN::Wc::Notify::Action::update_completed.
768 $ctx->log_msg(\&log_msg)
770 Sets the log_msg callback for the client context to a code refer‐
771 ence that you pass. It always returns the current codereference
772 set.
773 The subroutine pointed to by this coderef will be called to get the
775 log message for any operation that will commit a revision to the
776 repo.
777 It receives 4 parameters. The first parameter is a reference to a
779 scalar value in which the callback should place the log_msg. If
780 you wish to cancel the commit you can set this scalar to undef.
781 The 2nd value is a path to a temporary file which might be holding
782 that log message, or undef if no such field exists (though, if
783 log_msg is undef, this value is undefined). The log message MUST
784 be a UTF8 string with LF line separators. The 3rd parameter is a
785 reference to an array of svn_client_commit_item_t objects, which
786 may be fully or only partially filled-in, depending on the type of
787 commit operation. The 4th and last parameter will be a pool.
788 If the function wishes to return an error it should return a
790 svn_error_t object made with SVN::Error::create. Any other return
791 value will be interpreted as SVN_NO_ERROR.
792 $ctx->cancel(\&cancel)
794 Sets the log_msg callback for the client context to a code refer‐
795 ence that you pass. It always returns the current codereference
796 set.
797 The subroutine pointed to by this value will be called to see if
799 the operation should be canceled. If the operation should be can‐
800 celed, the function may return one of the following values:
801 An svn_error_t object made with SVN::Error::create.
803 Any true value, in which case the bindings will generate an
805 svn_error_t object for you with the error code of SVN_ERR_CANCELLED
806 and the string set to "By cancel callback".
807 A string, in which case the bindings will generate an svn_error_t
809 object for you with the error code of SVN_ERR_CANCELLED and the
810 string set to the string you returned.
811 Any other value will be interpreted as wanting to continue the
813 operation. Generally, it's best to return 0 to continue the opera‐
814 tion.
815 $ctx->pool(new SVN::Pool);
817 Method that sets or gets the default pool that is passed to method
818 calls requiring a pool, but which were not explicitly passed one.
819 See SVN::Core for more information about how pools are managed in
821 this interface.
822
824 The following functions get authentication providers for you. They
825 come in two forms. Standard or File versions, which look for authenti‐
826 cation information in the subversion configuration directory that was
827 previously cached, or Prompt versions which call a subroutine to allow
828 you to prompt the user for the information.
829 The functions that return the svn_auth_provider_object_t for prompt
831 style providers take a reference to a Perl subroutine to use for the
832 callback. The first parameter each of these subroutines receive is a
833 credential object. The subroutines return the response by setting mem‐
834 bers of that object. Members may be set like so: $cred->user‐
835 name("breser"); These functions and credential objects always have a
836 may_save member which specifies if the authentication data will be
837 cached.
838 The providers are as follows:
840 NAME WHAT IT HANDLES
842 ---------------- ----------------------------------------
843 simple username and password pairs
844 username username only
846 ssl_server_trust server certificates and failures
848 authenticating them
849 ssl_client_cert client side certificate files
851 ssl_client_cert_pw password for a client side certificate file.
853 SVN::Client::get_simple_provider
855 Returns a simple provider that returns information from previously
856 cached sessions. Takes no parameters or one pool parameter.
857 SVN::Client::get_simple_prompt_provider
859 Returns a simple provider that prompts the user via a callback.
860 Takes two or three parameters, the first is the callback subrou‐
861 tine, the 2nd is the number of retries to allow, the 3rd is option‐
862 ally a pool. The subroutine gets called with the following parame‐
863 ters: a svn_auth_cred_simple_t object, a realm string, a default
864 username, may_save, and a pool. The svn_auth_cred_simple has the
865 following members: username, password, and may_save.
866 SVN::Client::get_username_provider
868 Returns a username provider that returns information from a previ‐
869 ously cached sessions. Takes no parameters or one pool parameter.
870 SVN::Client::get_username_prompt_provider
872 Returns a username provider that prompts the user via a callback.
873 Takes two or three parameters, the first is the callback subrou‐
874 tine, the 2nd is the number of retries to allow, the 3rd is option‐
875 ally a pool. The subroutine gets called with the following parame‐
876 ters: a svn_auth_cred_username_t object, a realm string, a default
877 username, may_save, and a pool. The svn_auth_cred_username has the
878 following members: username and may_save.
879 SVN::Client::get_ssl_server_trust_file_provider
881 Returns a server trust provider that returns information from pre‐
882 viously cached sessions. Takes no parameters or optionally a pool
883 parameter.
884 SVN::Client::get_ssl_server_trust_prompt_provider
886 Returns a server trust provider that prompts the user via a call‐
887 back. Takes one or two parameters the callback subroutine and
888 optionally a pool parameter. The subroutine gets called with the
889 following parameters. A svn_auth_cred_ssl_server_trust_t object, a
890 realm string, an integer specifying how the certificate failed
891 authentication, a svn_auth_ssl_server_cert_info_t object, may_save,
892 and a pool. The svn_auth_cred_ssl_server_trust_t object has the
893 following members: may_save and accepted_failures. The
894 svn_auth_ssl_server_cert_info_t object has the following members
895 (and behaves just like cred objects though you can't modify it):
896 hostname, fingerprint, valid_from, valid_until, issuer_dname,
897 ascii_cert.
898 The masks used for determining the failures are in SVN::Auth::SSL
900 and are named:
901 $SVN::Auth::SSL::NOTYETVALID $SVN::Auth::SSL::EXPIRED
903 $SVN::Auth::SSL::CNMISMATCH $SVN::Auth::SSL::UNKNOWNCA
904 $SVN::Auth::SSL::OTHER
905 You reply by setting the accepted_failures of the cred object with
907 an integer of the values for what you want to accept bitwise AND'd
908 together.
909 SVN::Client::get_ssl_cert_file_provider
911 Returns a client certificate provider that returns information from
912 previously cached sessions. Takes no parameters or optionally a
913 pool parameter.
914 SVN::Client::get_ssl_cert_prompt_provider
916 Returns a client certificate provider that prompts the user via a
917 callback. Takes two or three parameters: the first is the callback
918 subroutine, the 2nd is the number of retries to allow, the 3rd is
919 optionally a pool parameter. The subroutine gets called with the
920 following parameters. A svn_auth_cred_ssl_client_cert object, a
921 realm string, may_save, and a pool. The
922 svn_auth_cred_ssl_client_cert the following members: cert_file and
923 may_save.
924 SVN::Client::get_ssl_cert_pw_file_provider
926 Returns a client certificate password provider that returns infor‐
927 mation from previously cached sessions. Takes no parameters or
928 optionally a pool parameter.
929 SVN::Client::get_ssl_cert_pw_prompt_provider
931 Returns a client certificate password provider that prompts the
932 user via a callback. Takes two or three parameters, the first is
933 the callback subroutine, the 2nd is the number of retries to allow,
934 the 3rd is optionally a pool parameter. The subroutine gets called
935 with the following parameters. A svn_auth_cred_ssl_client_cert_pw
936 object, a realm string, may_save, and a pool. The
937 svn_auth_cred_ssl_client_cert_pw has the following members: pass‐
938 word and may_save.
939
941 These are some of the object types that are returned from the methods
942 and functions. Others are documented in SVN::Core and SVN::Wc. If an
943 object is not documented, it is more than likely opaque and not some‐
944 thing you can do anything with, except pass to other functions that
945 require such objects.
946 svn_info_t
948 $info->URL()
950 Where the item lives in the repository.
951 $info->rev()
953 The revision of the object. If path_or_url is a working-copy
954 path, then this is its current working revnum. If path_or_url
955 is a URL, then this is the repos revision that path_or_url
956 lives in.
957 $info->kind()
959 The node's kind.
960 $info->repos_root_URL()
962 The root URL of the repository.
963 $info->repos_UUID()
965 The repository's UUID.
966 $info->last_changed_rev()
968 The last revision in which this object changed.
969 $info->last_changed_date()
971 The date of the last_changed_rev.
972 $info->last_changed_author()
974 The author of the last_changed_rev.
975 $info->lock()
977 An exclusive lock, if present. Could be either local or
978 remote.
979 See SVN::Wc::svn_wc_entry_t for the rest of these. svn_client.h indi‐
981 cates that these were copied from that struct and mean the same things.
982 They are also only useful when working with a WC.
983 $info->has_wc_info()
985 $info->schedule()
986 $info->copyfrom_url()
987 $info->copyfrom_rev()
988 $info->text_time()
989 $info->prop_time()
990 $info->checksum()
991 $info->conflict_old()
992 $info->conflict_new()
993 $info->conflict_wrk()
994 $info->prejfile()
995 svn_client_commit_item_t
997 $citem->path()
999 Absolute working-copy path of item.
1000 $citem->kind()
1002 An integer representing the type of node it is
1003 (file/dir). Can be one of the following constants:
1004 $SVN::Node::none $SVN::Node::file $SVN::Node::dir
1005 $SVN::Node::unknown
1006 $citem->url()
1008 Commit URL for this item.
1009 $citem->revision()
1011 Revision (copyfrom_rev if state_flags has IS_COPY set).
1012 $citem->copyform_url();
1014 CopyFrom URL
1015 $citem->state_flags();
1017 One of several state flags: $SVN::Client::COM‐
1018 MIT_ITEM_ADD $SVN::Client::COMMIT_ITEM_DELETE
1019 $SVN::Client::COMMIT_ITEM_TEXT_MODS $SVN::Client::COM‐
1020 MIT_ITEM_PROP_MODS $SVN::Client::COMMIT_ITEM_IS_COPY
1021 $citem>wcprop_changes()
1023 A reference to an array of svn_prop_t objects represent
1024 changes to wc properties.
1025 svn_client_commit_info_t
1027 $cinfo->revision()
1029 Just committed revision.
1030 $cinfo->date()
1032 Server-Side date of the commit as a string.
1033 $cinfo->author()
1035 Author of the commit.
1036 svn_client_proplist_item_t
1038 $proplist->node_name()
1040 The name of the node on which these properties are set.
1041 $proplist->prop_hash()
1043 A reference to a hash of property names and values.
1044
1046 * Better support for the config.
1047 * Unit tests for cleanup, diff, export, merge, move, relocate, resolved
1049 and switch. This may reveal problems for using these methods as I
1050 haven't tested them yet that require deeper fixes.
1051
1053 Chia-liang Kao <clkao@clkao.org>
1054 Ben Reser <ben@reser.org>
1056
1058 Copyright (c) 2003 CollabNet. All rights reserved.
1059 This software is licensed as described in the file COPYING, which you
1061 should have received as part of this distribution. The terms are also
1062 available at http://subversion.tigris.org/license-1.html. If newer
1063 versions of this license are posted there, you may use a newer version
1064 instead, at your option.
1065 This software consists of voluntary contributions made by many individ‐
1067 uals. For exact contribution history, see the revision history and
1068 logs, available at http://subversion.tigris.org/.
1069perl v5.8.8 2005-06-17 native::Client(3)