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.apache.org/repos/asf/subversion/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
41 documentation 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
174 create 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
214 targets 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
283 typically transmitted to the editor as a deletion of one thing and
284 the addition of another, but if this flag is true, unrelated items
285 will 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->diff_summarize($target1, $revision1, $target2, $revision2,
298 $recursive, $ignore_ancestry, \&summarize_func, $pool);
299 Produce a diff summary which lists the changed items between
300 $target1 at $revision1 and $target2 at $revision2 without creating
301 text deltas. $target1 and $target2 can be either working-copy
302 paths or URLs.
303 The function may report false positives if $ignore_ancestry is
305 false, since a file might have been modified between two revisions,
306 but still have the same contents.
307 Calls \&summarize_func with with a svn_client_diff_summarize_t
309 structure describing the difference.
310 See diff() for a description of the other parameters.
312 Has no return.
314 $ctx->export($from, $to, $revision, $force, $pool);
316 Export the contents of either a subversion repository or a
317 subversion working copy into a 'clean' directory (meaning a
318 directory with no administrative directories).
319 $from is either the path to the working copy on disk, or a URL to
321 the repository you wish to export.
322 $to is the path to the directory where you wish to create the
324 exported tree.
325 $revision is the revision that should be exported, which is only
327 used when exporting from a repository. It may be undef otherwise.
328 The notify callback will be called for the items exported.
330 Returns the value of the revision actually exported or
332 $SVN::Core::INVALID_REVNUM for local exports.
333 $ctx->import($path, $url, $nonrecursive, $pool);
335 Import file or directory $path into repository directory $url at
336 head.
337 If some components of $url do not exist then create parent
339 directories as necessary.
340 If $path is a directory, the contents of that directory are
342 imported directly into the directory identified by $url. Note that
343 the directory $path itself is not imported; that is, the basename
344 of $path is not part of the import.
345 If $path is a file, then the dirname of $url is the directory
347 receiving the import. The basename of $url is the filename in the
348 repository. In this case if $url already exists, raise an error.
349 The notify callback (if defined) will be called as the import
351 progresses, with any of the following actions:
352 $SVN::Wc::Notify::Action::commit_added,
353 $SVN::Wc::Notify::Action::commit_postfix_txdelta.
354 Use $nonrecursive to indicate that imported directories should not
356 recurse into any subdirectories they may have.
357 Uses the log_msg callback to determine the log message for the
359 commit when one is needed.
360 Returns a svn_client_commit_info_t object.
362 $ctx->log($targets, $start, $end, $discover_changed_paths,
364 $strict_node_history, \&log_receiver, $pool);
365 Invoke the log_receiver subroutine on each log_message from $start
366 to $end in turn, inclusive (but will never invoke receiver on a
367 given log message more than once).
368 $targets is a reference to an array containing all the paths or
370 URLs for which the log messages are desired. The log_receiver is
371 only invoked on messages whose revisions involved a change to some
372 path in $targets.
373 If $discover_changed_paths is set, then the changed_paths argument
375 to the log_receiver routine will be passed on each invocation.
376 If $strict_node_history is set, copy history (if any exists) will
378 not be traversed while harvesting revision logs for each target.
379 If $start or $end is undef the arp_err code will be set to:
381 $SVN::Error::CLIENT_BAD_REVISION.
382 Special case for repositories at revision 0:
384 If $start is 'HEAD' and $end is 1, then handle an empty (no
386 revisions) repository specially: instead of erroring because
387 requested revision 1 when the highest revision is 0, just invoke
388 $log_receiver on revision 0, passing undef to changed paths and
389 empty strings for the author and date. This is because that
390 particular combination of $start and $end usually indicates the
391 common case of log invocation; the user wants to see all log
392 messages from youngest to oldest, where the oldest commit is
393 revision 1. That works fine, except there are no commits in the
394 repository, hence this special case.
395 Calls the notify subroutine with a $SVN::Wc::Notify::Action::skip
397 signal on any unversioned targets.
398 The log_receiver takes the following arguments: $changed_paths,
400 $revision, $author, $date, $message, $pool
401 It is called once for each log $message from the $revision on $date
403 by $author. $author, $date or $message may be undef.
404 If $changed_paths is defined it references a hash with the keys
406 every path committed in $revision; the values are
407 svn_log_changed_path_t objects.
408 $ctx->ls($target, $revision, $recursive, $pool);
410 Returns a hash of svn_dirent_t objects for $target at $revision.
411 If $target is a directory, returns entries for all of the
413 directories' contents. If $recursive is true, it will recurse
414 subdirectories in $target.
415 If $target is a file only return an entry for the file.
417 If $target is non-existent, raises the $SVN::Error::FS_NOT_FOUND
419 error.
420 $ctx->merge($src1, $rev1, $src2, $rev2, $target_wcpath, $recursive,
422 $ignore_ancestry, $force, $dry_run, $pool);
423 Merge changes from $src1/$rev1 to $src2/$rev2 into the working-copy
424 path $target_wcpath.
425 $src1 and $src2 are either URLs that refer to entries in the
427 repository, or paths to entries in the working copy.
428 By 'merging', we mean: apply file differences and schedule
430 additions & deletions when appropriate.
431 $src1 and $src2 must both represent the same node kind; that is, if
433 $src1 is a directory, $src2 must also be, and if $src1 is a file,
434 $src2 must also be.
435 If either $rev1 or $rev2 is undef raises the
437 $SVN::Error::CLIENT_BAD_REVISION error.
438 If $recursive is true (and the URLs are directories), apply changes
440 recursively; otherwise, only apply changes in the current
441 directory.
442 Use $ignore_ancestry to control whether or not items being diffed
444 will be checked for relatedness first. Unrelated items are
445 typically transmitted to the editor as a deletion of one thing and
446 the addition of another, but if this flag is true, unrelated items
447 will be diffed as if they were related.
448 If $force is not set and the merge involves deleting locally
450 modified or unversioned items the operation will raise an error.
451 If $force is set such items will be deleted.
452 Calls the notify callback once for each merged target, passing the
454 targets local path.
455 If $dry_run is true the merge is carried out, and the full
457 notification feedback is provided, but the working copy is not
458 modified.
459 Has no return.
461 $ctx->mkdir($targets, $pool);
463 Create a directory, either in a repository or a working copy.
464 If $targets contains URLs, immediately attempts to commit the
466 creation of the directories in $targets in the repository. Returns
467 a svn_client_commit_info_t object.
468 Else, create the directories on disk, and attempt to schedule them
470 for addition. In this case returns undef.
471 Calls the notify callback when the directory has been created
473 (successfully) in the working copy, with the path of the new
474 directory. Note this is only called for items added to the working
475 copy.
476 $ctx->move($src_path, $src_revision, $dst_path, $force, $pool);
478 Move $src_path to $dst_path.
479 $src_path must be a file or directory under version control, or the
481 URL of a versioned item in the repository.
482 If $src_path is a repository URL:
484 * $dst_path must also be a repository URL (existent or not).
486 * $src_revision is used to choose the revision from which to copy
488 the $src_path.
489 * The log_msg callback will be called for the commit log message.
491 * The move operation will be immediately committed. If the commit
493 succeeds, returns a svn_client_commit_info_t object.
494 If $src_path is a working copy path
496 * $dst_path must also be a working copy path (existent or not).
498 * $src_revision is ignored and may be undef. The log_msg callback
500 will not be called.
501 * This is a scheduling operation. No changes will happen to the
503 repository until a commit occurs. This scheduling can be removed
504 with $ctx->revert(). If $src_path is a file it is removed from the
505 working copy immediately. If $src_path is a directory it will
506 remain in the working copy but all files, and unversioned items, it
507 contains will be removed.
508 * If $src_path contains locally modified and/or unversioned items
510 and $force is not set, the copy will raise an error. If $force is
511 set such items will be removed.
512 The notify callback will be called twice for each item moved, once
514 to indicate the deletion of the moved node, and once to indicate
515 the addition of the new location of the node.
516 $ctx->propget($propname, $target, $revision, $recursive, $pool);
518 Returns a reference to a hash containing paths or URLs, prefixed by
519 $target (a working copy or URL), of items for which the property
520 $propname is set, and whose values represent the property value for
521 $propname at that path.
522 $ctx->proplist($target, $revision, $recursive, $pool);
524 Returns a reference to an array of svn_client_proplist_item_t
525 objects.
526 For each item the node_name member of the proplist_item object
528 contains the name relative to the same base as $target.
529 If $revision is undef, then get properties from the working copy,
531 if $target is a working copy, or from the repository head if
532 $target is a URL. Else get the properties as of $revision.
533 If $recursive is false, or $target is a file, the returned array
535 will only contain a single element. Otherwise, it will contain one
536 entry for each versioned entry below (and including) $target.
537 If $target is not found, raises the $SVN::Error::ENTRY_NOT_FOUND
539 error.
540 $ctx->propset($propname, $propval, $target, $recursive, $pool);
542 Set $propname to $propval on $target (a working copy or URL path).
543 If $recursive is true, then $propname will be set recursively on
545 $target and all children. If $recursive is false, and $target is a
546 directory, $propname will be set on only $target.
547 A $propval of undef will delete the property.
549 If $propname is an svn-controlled property (i.e. prefixed with
551 svn:), then the caller is responsible for ensuring that $propval is
552 UTF8-encoded and uses LF line-endings.
553 $ctx->relocate($dir, $from, $to, $recursive, $pool);
555 Modify a working copy directory $dir, changing any repository URLs
556 that begin with $from to begin with $to instead, recursing into
557 subdirectories if $recursive is true.
558 Has no return.
560 $ctx->resolved($path, $recursive, $pool);
562 Removed the 'conflicted' state on a working copy path.
563 This will not semantically resolve conflicts; it just allows $path
565 to be committed in the future. The implementation details are
566 opaque. If $recursive is set, recurse below $path, looking for
567 conflicts to resolve.
568 If $path is not in a state of conflict to begin with, do nothing.
570 If $path's conflict state is removed, call the notify callback with
572 the $path.
573 $ctx->revert($paths, $recursive, $pool);
575 Restore the pristine version of a working copy $paths, effectively
576 undoing any local mods.
577 For each path in $paths, if it is a directory and $recursive is
579 true, this will be a recursive operation.
580 $ctx->revprop_get($propname, $url, $revision, $pool);
582 Returns two values, the first of which is the value of $propname on
583 revision $revision in the repository represented by $url. The
584 second value is the actual revision queried.
585 Note that unlike its cousin $ctx->propget(), this routine doesn't
587 affect working copy at all; it's a pure network operation that
588 queries an unversioned property attached to a revision. This can
589 be used to query log messages, dates, authors, and the like.
590 $ctx->revprop_list($url, $revision, $pool);
592 Returns two values, the first of which is a reference to a hash
593 containing the properties attached to $revision in the repository
594 represented by $url. The second value is the actual revision
595 queried.
596 Note that unlike its cousin $ctx->proplist(), this routine doesn't
598 read a working copy at all; it's a pure network operation that
599 reads unversioned properties attached to a revision.
600 $ctx->revprop_set($propname, $propval, $url, $revision, $force, $pool);
602 Set $propname to $propval on revision $revision in the repository
603 represented by $url.
604 Returns the actual revision affected. A $propval of undef will
606 delete the property.
607 If $force is true, allow newlines in the author property.
609 If $propname is an svn-controlled property (i.e. prefixed with
611 svn:), then the caller is responsible for ensuring that the value
612 is UTF8-encoded and uses LF line-endings.
613 Note that unlike its cousin $ctx->propset(), this routine doesn't
615 affect the working copy at all; it's a pure network operation that
616 changes an unversioned property attached to a revision. This can
617 be used to tweak log messages, dates, authors, and the like. Be
618 careful: it's a lossy operation, meaning that any existing value is
619 replaced with the new value, with no way to retrieve the prior
620 value.
621 Also note that unless the administrator creates a pre-revprop-
623 change hook in the repository, this feature will fail.
624 $ctx->status($path, $revision, \&status_func, $recursive, $get_all,
626 $update, $no_ignore, $pool);
627 Given $path to a working copy directory (or single file), call
628 status_func() with a set of svn_wc_status_t objects which describe
629 the status of $path and its children.
630 If $recursive is true, recurse fully, else do only immediate
632 children.
633 If $get_all is set, retrieve all entries; otherwise, retrieve only
635 'interesting' entries (local mods and/or out-of-date).
636 If $update is set, contact the repository and augment the status
638 objects with information about out-of-dateness (with respect to
639 $revision). Also, will return the value of the actual revision
640 against with the working copy was compared. (The return will be
641 undef if $update is not set).
642 The function recurses into externals definitions ('svn:externals')
644 after handling the main target, if any exist. The function calls
645 the notify callback with $SVN::Wc::Notify::Action::status_external
646 action before handling each externals definition, and with
647 $SVN::Wc::Notify::Action::status_completed after each.
648 The status_func subroutine takes the following parameters: $path,
650 $status
651 $path is the pathname of the file or directory which status is
653 being reported. $status is a svn_wc_status_t object.
654 The return of the status_func subroutine is ignored.
656 $ctx->info($path_or_url, $peg_revision, $revision, \&receiver,
658 $recurse);
659 Invokes \&receiver passing it information about $path_or_url for
660 $revision. The information returned is system-generated metadata,
661 not the sort of "property" metadata created by users. For methods
662 available on the object passed to \&receiver, see svn_info_t.
663 If both revision arguments are either svn_opt_revision_unspecified
665 or NULL, then information will be pulled solely from the working
666 copy; no network connections will be made.
667 Otherwise, information will be pulled from a repository. The
669 actual node revision selected is determined by the $path_or_url as
670 it exists in $peg_revision. If $peg_revision is undef, then it
671 defaults to HEAD for URLs or WORKING for WC targets.
672 If $path_or_url is not a local path, then if $revision is PREV (or
674 some other kind that requires a local path), an error will be
675 returned, because the desired revision cannot be determined.
676 Uses the authentication baton cached in ctx to authenticate against
678 the repository.
679 If $recurse is true (and $path_or_url is a directory) this will be
681 a recursive operation, invoking $receiver on each child.
682 my $receiver = sub {
684 my( $path, $info, $pool ) = @_;
685 print "Current revision of $path is ", $info->rev, "\n";
686 };
687 $ctx->info( 'foo/bar.c', undef, 'WORKING', $receiver, 0 );
688 $ctx->switch($path, $url, $revision, $recursive, $pool);
690 Switch working tree $path to $url at $revision.
691 $revision must be a number, 'HEAD', or a date, otherwise it raises
693 the $SVN::Error::CLIENT_BAD_REVISION error.
694 Calls the notify callback on paths affected by the switch. Also
696 invokes the callback for files that may be restored from the text-
697 base because they were removed from the working copy.
698 Summary of purpose: This is normally used to switch a working
700 directory over to another line of development, such as a branch or
701 a tag. Switching an existing working directory is more efficient
702 than checking out $url from scratch.
703 Returns the value of the revision to which the working copy was
705 actually switched.
706 $ctx->update($path, $revision, $recursive, $pool)
708 Update a working copy $path to $revision.
709 $revision must be a revision number, 'HEAD', or a date or this
711 method will raise the $SVN::Error::CLIENT_BAD_REVISION error.
712 Calls the notify callback for each item handled by the update, and
714 also for files restored from the text-base.
715 Returns the revision to which the working copy was actually
717 updated.
718 $ctx->url_from_path($target, $pool); or
720 SVN::Client::url_from_path($target, $pool);
721 Returns the URL for $target.
722 If $target is already a URL it returns $target.
724 If $target is a versioned item, it returns $target's entry URL.
726 If $target is unversioned (has no entry), returns undef.
728 $ctx->uuid_from_path($path, $adm_access, $pool);
730 Return the repository uuid for working-copy $path, allocated in
731 $pool.
732 Use $adm_access to retrieve the uuid from $path's entry; if not
734 present in the entry, then call $ctx->uuid_from_url() to retrieve,
735 using the entry's URL.
736 Note: The only reason this function falls back on
738 $ctx->uuid_from_url is for compatibility purposes. Old working
739 copies may not have uuids in the entries files.
740 Note: This method probably doesn't work right now without a lot of
742 pain, because SVN::Wc is incomplete and it requires an adm_access
743 object from it.
744 $ctx->uuid_from_url($url, $pool);
746 Return repository uuid for url.
747
749 The following attribute methods are provided that allow you to set
750 various configuration or retrieve it. They all take value(s) to set
751 the attribute and return the new value of the attribute or no
752 parameters which returns the current value.
753 $ctx->auth(SVN::Client::get_username_provider());
755 Provides access to the auth_baton in the svn_client_ctx_t attached
756 to the SVN::Client object.
757 This method will accept an array or array ref of values returned
759 from the authentication provider functions see "AUTHENTICATION
760 PROVIDERS", which it will convert to an auth_baton for you. This
761 is the preferred method of setting the auth_baton.
762 It will also accept a scalar that references a _p_svn_auth_baton_t
764 such as those returned from SVN::Core::auth_open and
765 SVN::Core::auth_open_helper.
766 $ctx->notify(\¬ify);
768 Sets the notify callback for the client context to a code reference
769 that you pass. It always returns the current codereference set.
770 The subroutine pointed to by this reference will be called when a
772 change is made to the working copy. The return value of this
773 function is ignored. It's only purpose is to notify you of the
774 change.
775 The subroutine will receive 6 parameters. The first parameter will
777 be the path of the changed file (absolute or relative to the cwd).
778 The second is an integer specifying the type of action taken. See
779 SVN::Wc for a list of the possible actions values and what they
780 mean. The 3rd is an integer specifying the kind of node the path
781 is, which can be: $SVN::Node::none, $SVN::Node::file,
782 $SVN::Node::dir, $SVN::Node::unknown. The fourth parameter is the
783 mime-type of the file or undef if the mime-type is unknown (it will
784 always be undef for directories). The 5th parameter is the state
785 of the file, again see SVN::Wc for a list of the possible states.
786 The 6th and final parameter is the numeric revision number of the
787 changed file. The revision number will be -1 except when the
788 action is $SVN::Wc::Notify::Action::update_completed.
789 $ctx->log_msg(\&log_msg)
791 Sets the log_msg callback for the client context to a code
792 reference that you pass. It always returns the current
793 codereference set.
794 The subroutine pointed to by this coderef will be called to get the
796 log message for any operation that will commit a revision to the
797 repo.
798 It receives 4 parameters. The first parameter is a reference to a
800 scalar value in which the callback should place the log_msg. If
801 you wish to cancel the commit you can set this scalar to undef.
802 The 2nd value is a path to a temporary file which might be holding
803 that log message, or undef if no such field exists (though, if
804 log_msg is undef, this value is undefined). The log message MUST
805 be a UTF8 string with LF line separators. The 3rd parameter is a
806 reference to an array of svn_client_commit_item3_t objects, which
807 may be fully or only partially filled-in, depending on the type of
808 commit operation. The 4th and last parameter will be a pool.
809 If the function wishes to return an error it should return a
811 svn_error_t object made with SVN::Error::create. Any other return
812 value will be interpreted as SVN_NO_ERROR.
813 $ctx->cancel(\&cancel)
815 Sets the log_msg callback for the client context to a code
816 reference that you pass. It always returns the current
817 codereference set.
818 The subroutine pointed to by this value will be called to see if
820 the operation should be canceled. If the operation should be
821 canceled, the function may return one of the following values:
822 An svn_error_t object made with SVN::Error::create.
824 Any true value, in which case the bindings will generate an
826 svn_error_t object for you with the error code of SVN_ERR_CANCELLED
827 and the string set to "By cancel callback".
828 A string, in which case the bindings will generate an svn_error_t
830 object for you with the error code of SVN_ERR_CANCELLED and the
831 string set to the string you returned.
832 Any other value will be interpreted as wanting to continue the
834 operation. Generally, it's best to return 0 to continue the
835 operation.
836 $ctx->pool(new SVN::Pool);
838 Method that sets or gets the default pool that is passed to method
839 calls requiring a pool, but which were not explicitly passed one.
840 See SVN::Core for more information about how pools are managed in
842 this interface.
843 $ctx->config(SVN::Core::config_get_config(undef));
845 Method that allows access to the config member of the
846 svn_client_ctx_t. Accepts a Perl hash to set, which is what
847 functions like SVN::Core:config_get_config() will return.
848 It will return a _p_arp_hash_t scalar. This is a temporary
850 situation. The return value is not particular useful. In the
851 future, this value will be tied to the actual hash used by the C
852 API.
853
855 The following functions get authentication providers for you. They
856 come in two forms. Standard or File versions, which look for
857 authentication information in the subversion configuration directory
858 that was previously cached, or Prompt versions which call a subroutine
859 to allow you to prompt the user for the information.
860 The functions that return the svn_auth_provider_object_t for prompt
862 style providers take a reference to a Perl subroutine to use for the
863 callback. The first parameter each of these subroutines receive is a
864 credential object. The subroutines return the response by setting
865 members of that object. Members may be set like so:
866 $cred->username("breser"); These functions and credential objects
867 always have a may_save member which specifies if the authentication
868 data will be cached.
869 The providers are as follows:
871 NAME WHAT IT HANDLES
873 ---------------- ----------------------------------------
874 simple username and password pairs
875 username username only
877 ssl_server_trust server certificates and failures
879 authenticating them
880 ssl_client_cert client side certificate files
882 ssl_client_cert_pw password for a client side certificate file.
884 SVN::Client::get_simple_provider
886 Returns a simple provider that returns information from previously
887 cached sessions. Takes no parameters or one pool parameter.
888 SVN::Client::get_simple_prompt_provider
890 Returns a simple provider that prompts the user via a callback.
891 Takes two or three parameters, the first is the callback
892 subroutine, the 2nd is the number of retries to allow, the 3rd is
893 optionally a pool. The subroutine gets called with the following
894 parameters: a svn_auth_cred_simple_t object, a realm string, a
895 default username, may_save, and a pool. The svn_auth_cred_simple
896 has the following members: username, password, and may_save.
897 SVN::Client::get_username_provider
899 Returns a username provider that returns information from a
900 previously cached sessions. Takes no parameters or one pool
901 parameter.
902 SVN::Client::get_username_prompt_provider
904 Returns a username provider that prompts the user via a callback.
905 Takes two or three parameters, the first is the callback
906 subroutine, the 2nd is the number of retries to allow, the 3rd is
907 optionally a pool. The subroutine gets called with the following
908 parameters: a svn_auth_cred_username_t object, a realm string, a
909 default username, may_save, and a pool. The svn_auth_cred_username
910 has the following members: username and may_save.
911 SVN::Client::get_ssl_server_trust_file_provider
913 Returns a server trust provider that returns information from
914 previously cached sessions. Takes no parameters or optionally a
915 pool parameter.
916 SVN::Client::get_ssl_server_trust_prompt_provider
918 Returns a server trust provider that prompts the user via a
919 callback. Takes one or two parameters the callback subroutine and
920 optionally a pool parameter. The subroutine gets called with the
921 following parameters. A svn_auth_cred_ssl_server_trust_t object, a
922 realm string, an integer specifying how the certificate failed
923 authentication, a svn_auth_ssl_server_cert_info_t object, may_save,
924 and a pool. The svn_auth_cred_ssl_server_trust_t object has the
925 following members: may_save and accepted_failures. The
926 svn_auth_ssl_server_cert_info_t object has the following members
927 (and behaves just like cred objects though you can't modify it):
928 hostname, fingerprint, valid_from, valid_until, issuer_dname,
929 ascii_cert.
930 The masks used for determining the failures are in SVN::Auth::SSL
932 and are named:
933 $SVN::Auth::SSL::NOTYETVALID $SVN::Auth::SSL::EXPIRED
935 $SVN::Auth::SSL::CNMISMATCH $SVN::Auth::SSL::UNKNOWNCA
936 $SVN::Auth::SSL::OTHER
937 You reply by setting the accepted_failures of the cred object with
939 an integer of the values for what you want to accept bitwise AND'd
940 together.
941 SVN::Client::get_ssl_client_cert_file_provider
943 Returns a client certificate provider that returns information from
944 previously cached sessions. Takes no parameters or optionally a
945 pool parameter.
946 SVN::Client::get_ssl_client_cert_prompt_provider
948 Returns a client certificate provider that prompts the user via a
949 callback. Takes two or three parameters: the first is the callback
950 subroutine, the 2nd is the number of retries to allow, the 3rd is
951 optionally a pool parameter. The subroutine gets called with the
952 following parameters. A svn_auth_cred_ssl_client_cert object, a
953 realm string, may_save, and a pool. The
954 svn_auth_cred_ssl_client_cert the following members: cert_file and
955 may_save.
956 SVN::Client::get_ssl_client_cert_pw_file_provider
958 Returns a client certificate password provider that returns
959 information from previously cached sessions. Takes no parameters
960 or optionally a pool parameter.
961 SVN::Client::get_ssl_client_cert_pw_prompt_provider
963 Returns a client certificate password provider that prompts the
964 user via a callback. Takes two or three parameters, the first is
965 the callback subroutine, the 2nd is the number of retries to allow,
966 the 3rd is optionally a pool parameter. The subroutine gets called
967 with the following parameters. A svn_auth_cred_ssl_client_cert_pw
968 object, a realm string, may_save, and a pool. The
969 svn_auth_cred_ssl_client_cert_pw has the following members:
970 password and may_save.
971
973 These are some of the object types that are returned from the methods
974 and functions. Others are documented in SVN::Core and SVN::Wc. If an
975 object is not documented, it is more than likely opaque and not
976 something you can do anything with, except pass to other functions that
977 require such objects.
978 svn_info_t
980 $info->URL()
981 Where the item lives in the repository.
982 $info->rev()
984 The revision of the object. If path_or_url is a working-copy
985 path, then this is its current working revnum. If path_or_url
986 is a URL, then this is the repos revision that path_or_url
987 lives in.
988 $info->kind()
990 The node's kind.
991 $info->repos_root_URL()
993 The root URL of the repository.
994 $info->repos_UUID()
996 The repository's UUID.
997 $info->last_changed_rev()
999 The last revision in which this object changed.
1000 $info->last_changed_date()
1002 The date of the last_changed_rev.
1003 $info->last_changed_author()
1005 The author of the last_changed_rev.
1006 $info->lock()
1008 An exclusive lock, if present. Could be either local or
1009 remote.
1010 See SVN::Wc::svn_wc_entry_t for the rest of these. svn_client.h
1012 indicates that these were copied from that struct and mean the same
1013 things. They are also only useful when working with a WC.
1014 $info->has_wc_info()
1016 $info->schedule()
1017 $info->copyfrom_url()
1018 $info->copyfrom_rev()
1019 $info->text_time()
1020 $info->prop_time()
1021 $info->checksum()
1022 $info->conflict_old()
1023 $info->conflict_new()
1024 $info->conflict_wrk()
1025 $info->prejfile()
1026 svn_client_commit_item3_t
1028 $citem->path()
1029 Absolute working-copy path of item.
1030 $citem->kind()
1032 An integer representing the type of node it is (file/dir). Can
1033 be one of the following constants: $SVN::Node::none
1034 $SVN::Node::file $SVN::Node::dir $SVN::Node::unknown
1035 $citem->url()
1037 Commit URL for this item.
1038 $citem->revision()
1040 Revision (copyfrom_rev if state_flags has IS_COPY set).
1041 $citem->copyform_url();
1043 CopyFrom URL
1044 $citem->state_flags();
1046 One of several state flags: $SVN::Client::COMMIT_ITEM_ADD
1047 $SVN::Client::COMMIT_ITEM_DELETE
1048 $SVN::Client::COMMIT_ITEM_TEXT_MODS
1049 $SVN::Client::COMMIT_ITEM_PROP_MODS
1050 $SVN::Client::COMMIT_ITEM_IS_COPY
1051 $citem>incoming_prop_changes()
1053 A reference to an array of svn_prop_t objects representing
1054 changes to WC properties.
1055 $citem>outgoing_prop_changes()
1057 A reference to an array of svn_prop_t objects representing
1058 extra changes to properties in the repository (which are not
1059 necessarily reflected by the WC).
1060 svn_client_commit_info_t
1062 $cinfo->revision()
1063 Just committed revision.
1064 $cinfo->date()
1066 Server-Side date of the commit as a string.
1067 $cinfo->author()
1069 Author of the commit.
1070 svn_client_proplist_item_t
1072 $proplist->node_name()
1073 The name of the node on which these properties are set.
1074 $proplist->prop_hash()
1076 A reference to a hash of property names and values.
1077 svn_client_diff_summarize_kind_t - SVN::Summarize
1079 An enum of the following constants:
1080 $SVN::Client::Summarize::normal, $SVN::Client::Summarize::added,
1082 $SVN::Client::Summarize::modified, $SVN::Client::Summarize::deleted.
1083 svn_client_diff_summarize_t
1085 $diff_summarize->path()
1086 Path relative to the target. If the target is a file, path is
1087 the empty string.
1088 $diff_summarize->summarize_kind()
1090 Change kind.
1091 $diff_summarize->prop_changed()
1093 Properties changed?
1094 $diff_summarize->node_kind()
1096 File or dir?
1097
1099 * Better support for the config.
1100 * Unit tests for cleanup, diff, export, merge, move, relocate, resolved
1102 and switch. This may reveal problems for using these methods as I
1103 haven't tested them yet that require deeper fixes.
1104
1106 Chia-liang Kao <clkao@clkao.org>
1107 Ben Reser <ben@reser.org>
1109
1111 Copyright (c) 2003 CollabNet. All rights reserved.
1112 This software is licensed as described in the file COPYING, which you
1114 should have received as part of this distribution. The terms are also
1115 available at http://subversion.tigris.org/license-1.html. If newer
1116 versions of this license are posted there, you may use a newer version
1117 instead, at your option.
1118 This software consists of voluntary contributions made by many
1120 individuals. For exact contribution history, see the revision history
1121 and logs, available at http://subversion.tigris.org/.
1122
1124 Hey! The above document had some coding errors, which are explained
1125 below:
1126 Around line 1451:
1128 =back without =over
1129perl v5.12.3 2010-03-16 native::Client(3)