callers of client__get_revision_number() / added nodes returning revision of 0

as promised, all callers of svn_client__get_revision_number() and what they
want. This is interesting because this function returns -1 for
svn_opt_revision_unspecified, which would clash with added nodes returning
-1 as well. There are comment markings in this "patch", coded according to
this legend:

  invocation type (randomly chosen single character labels)...
  out-parameter revision:
  0 _unspecified -> SVN_INVALID_REVNUM
  1 _number -> revision->value.number

  a _head -> _ra_latest_revnum(ra_session)
  b _date -> _ra_get_dated_revision(ra_session, revision->value.date)
  x _head & youngest_rev -> youngest_rev
  y _date & youngest_rev -> min( ra_get_dated_revision(...), youngest_rev)

  i (_working | _base) & local_abspath -> entry->revision
  j _committed & local_abspath -> entry->cmt_rev
  k _previous & local_abspath -> entry->cmt_rev - 1

  out-parameter youngest_rev only useful with x, y

(the diff is both inline and attached)

[[[
* subversion/libsvn_client/blame.c
  (svn_client_blame5):

* subversion/libsvn_client/copy.c
  (repos_to_repos_copy):
  (repos_to_wc_copy):

* subversion/libsvn_client/diff.c
  (diff_prepare_repos_repos):
  (diff_wc_wc):
  (diff_repos_wc):

* subversion/libsvn_client/log.c
  (svn_client_log5):

* subversion/libsvn_client/merge.c
  (normalize_merge_sources):
  (merge_locked):
  (merge_reintegrate_locked):

* subversion/libsvn_client/mergeinfo.c
  (get_mergeinfo):

* subversion/libsvn_client/prop_commands.c
  (svn_client_revprop_set2):
  (svn_client_propget3):
  (svn_client_revprop_get):
  (svn_client_revprop_list):

* subversion/libsvn_client/ra.c
  (svn_client__ra_session_from_path):
  (svn_client__repos_locations):

* subversion/libsvn_client/revisions.c

* subversion/libsvn_client/status.c
  (svn_client_status5):

* subversion/libsvn_client/update.c
  (update_internal):

* subversion/libsvn_client/url.c
  (svn_client__derive_location):

--This line, and those below, will be ignored--
Index: subversion/libsvn_client/blame.c
===================================================================
--- subversion/libsvn_client/blame.c (revision 953988)
+++ subversion/libsvn_client/blame.c (working copy)
@@ -622,6 +622,7 @@ svn_client_blame5(const char *target,
                                            peg_revision, end,
                                            ctx, pool));

+/* X blame, start_revnum: 01 ab ijk -> static file_rev_baton */
   SVN_ERR(svn_client__get_revision_number(&start_revnum, NULL, ctx->wc_ctx,
                                           target_abspath_or_url, ra_session,
                                           start, pool));
Index: subversion/libsvn_client/copy.c
===================================================================
--- subversion/libsvn_client/copy.c (revision 953988)
+++ subversion/libsvn_client/copy.c (working copy)
@@ -783,6 +783,7 @@ repos_to_repos_copy(svn_commit_info_t **
       /* Resolve revision keywords and such into real revision number,
          passing NULL for the path (to ensure error if trying to get a
          revision based on the working copy). */
+/* X repos-repos copy, source URL: 01 abxy */
       SVN_ERR(svn_client__get_revision_number(&pair->src_revnum, &youngest,
                                               ctx->wc_ctx, NULL,
                                               ra_session,
@@ -1785,6 +1786,7 @@ repos_to_wc_copy(const apr_array_header_
       svn_client__copy_pair_t *pair = APR_ARRAY_IDX(copy_pairs, i,
                                                     svn_client__copy_pair_t *);

+/* X repos-wc copy, source URL: 01 ab */
       SVN_ERR(svn_client__get_revision_number(&pair->src_revnum, NULL,
                                               ctx->wc_ctx, NULL, ra_session,
                                               &pair->src_op_revision, pool));
Index: subversion/libsvn_client/diff.c
===================================================================
--- subversion/libsvn_client/diff.c (revision 953988)
+++ subversion/libsvn_client/diff.c (working copy)
@@ -1242,6 +1242,7 @@ diff_prepare_repos_repos(const struct di
     }

   /* Resolve revision and get path kind for the second target. */
+/* X repos-repos diff, right side: 01 ab ijk */
   SVN_ERR(svn_client__get_revision_number(&drr->rev2, NULL, ctx->wc_ctx,
            (params->path2 == drr->url2) ? NULL : params_path2_abspath,
            ra_session, params->revision2, pool));
@@ -1254,6 +1255,7 @@ diff_prepare_repos_repos(const struct di

   /* Do the same for the first target. */
   SVN_ERR(svn_ra_reparent(ra_session, drr->url1, pool));
+/* X repos-repos diff, left side: 01 ab ijk */
   SVN_ERR(svn_client__get_revision_number(&drr->rev1, NULL, ctx->wc_ctx,
            (params->path1 == drr->url1) ? NULL : params_path1_abspath,
            ra_session, params->revision1, pool));
@@ -1365,6 +1367,7 @@ diff_wc_wc(const char *path1,
           "and its working files are supported at this time")));

   /* Resolve named revisions to real numbers. */
+/* X wc-wc diff, get commit-base revision: i */
   err = svn_client__get_revision_number(&callback_baton->revnum1, NULL,
                                         ctx->wc_ctx, abspath1, NULL,
                                         revision1, pool);
@@ -1577,6 +1580,7 @@ diff_repos_wc(const char *path1,
                                   pool, pool));

   /* Tell the RA layer we want a delta to change our txn to URL1 */
+/* X repos-wc diff, left side: 01 ab ijk */
   SVN_ERR(svn_client__get_revision_number(&rev, NULL, ctx->wc_ctx,
                                           (path1 == url1) ? NULL : abspath1,
                                           ra_session, revision1, pool));
Index: subversion/libsvn_client/log.c
===================================================================
--- subversion/libsvn_client/log.c (revision 953988)
+++ subversion/libsvn_client/log.c (working copy)
@@ -588,10 +588,12 @@ svn_client_log5(const apr_array_header_t

       range = APR_ARRAY_IDX(revision_ranges, i, svn_opt_revision_range_t *);

+/* X log, range start: 01 abxy ijk */
       SVN_ERR(svn_client__get_revision_number(&start_revnum, &youngest_rev,
                                               ctx->wc_ctx,
local_abspath_or_url,
                                               ra_session, &range->start,
                                               iterpool));
+/* X log, range end: 01 abxy ijk */
       SVN_ERR(svn_client__get_revision_number(&end_revnum, &youngest_rev,
                                               ctx->wc_ctx,
local_abspath_or_url,
                                               ra_session, &range->end,
Index: subversion/libsvn_client/merge.c
===================================================================
--- subversion/libsvn_client/merge.c (revision 953988)
+++ subversion/libsvn_client/merge.c (working copy)
@@ -6074,6 +6074,7 @@ normalize_merge_sources(apr_array_header
   *merge_sources_p = apr_array_make(pool, 1, sizeof(merge_source_t *));

   /* Resolve our PEG_REVISION to a real number. */
+/* X merge source, peg rev: 01 abxy ijk */
   SVN_ERR(svn_client__get_revision_number(&peg_revnum, &youngest_rev,
                                           ctx->wc_ctx,
                                           source_abspath_or_url,
@@ -6104,11 +6105,13 @@ normalize_merge_sources(apr_array_header
         return svn_error_create(SVN_ERR_CLIENT_BAD_REVISION, NULL,
                                 _("Not all required revisions are specified"));

+/* X merge source, range start: 01 abxy ijk */
       SVN_ERR(svn_client__get_revision_number(&range_start_rev, &youngest_rev,
                                               ctx->wc_ctx,
                                               source_abspath_or_url,
                                               ra_session, range_start,
                                               subpool));
+/* X merge source, range end: 01 abxy ijk */
       SVN_ERR(svn_client__get_revision_number(&range_end_rev, &youngest_rev,
                                               ctx->wc_ctx,
                                               source_abspath_or_url,
@@ -8621,9 +8624,11 @@ merge_locked(const char *source1,
                                                FALSE, TRUE, ctx, sesspool));

   /* Resolve revisions to real numbers. */
+/* X merge, range start: 01 abxy */
   SVN_ERR(svn_client__get_revision_number(&rev1, &youngest_rev, ctx->wc_ctx,
                                           NULL, ra_session1, revision1,
                                           sesspool));
+/* X merge, range end: 01 abxy */
   SVN_ERR(svn_client__get_revision_number(&rev2, &youngest_rev, ctx->wc_ctx,
                                           NULL, ra_session2, revision2,
                                           sesspool));
@@ -9910,6 +9915,7 @@ merge_reintegrate_locked(const char *sou
                                                FALSE, FALSE, ctx,
                                                scratch_pool));

+/* X reintegrate merge, peg rev: 01 ab */
   SVN_ERR(svn_client__get_revision_number(&rev2, NULL, ctx->wc_ctx,
                                           "",
                                           source_ra_session, peg_revision,
Index: subversion/libsvn_client/mergeinfo.c
===================================================================
--- subversion/libsvn_client/mergeinfo.c (revision 953988)
+++ subversion/libsvn_client/mergeinfo.c (working copy)
@@ -1034,6 +1034,7 @@ get_mergeinfo(svn_mergeinfo_catalog_t *m
       SVN_ERR(svn_client__open_ra_session_internal(&ra_session, path_or_url,
                                                    NULL, NULL, FALSE,
                                                    TRUE, ctx, scratch_pool));
+/* X mergeinfo, peg rev: 01 ab ijk */
       SVN_ERR(svn_client__get_revision_number(&rev, NULL, ctx->wc_ctx,
                                               local_abspath, ra_session,
                                               &peg_rev, scratch_pool));
Index: subversion/libsvn_client/prop_commands.c
===================================================================
--- subversion/libsvn_client/prop_commands.c (revision 953988)
+++ subversion/libsvn_client/prop_commands.c (working copy)
@@ -443,6 +443,7 @@ svn_client_revprop_set2(const char *prop

   /* Resolve the revision into something real, and return that to the
      caller as well. */
+/* X set revprop: 1 ab */
   SVN_ERR(svn_client__get_revision_number(set_rev, NULL, ctx->wc_ctx, NULL,
                                           ra_session, revision, pool));

@@ -867,6 +868,8 @@ svn_client_propget3(apr_hash_t **props,
         {
           /* svn uses SVN_ERR_UNVERSIONED_RESOURCE as warning only
              for this function. */
+ /* ### it most certainly doesn't! SVN_ERR_UNVERSIONED_RESOURCE is
+ used in numerous other places. */
           return svn_error_createf(SVN_ERR_UNVERSIONED_RESOURCE, err,
                                    _("'%s' is not under version control"),
                                    svn_dirent_local_style(local_abspath,
@@ -882,11 +885,13 @@ svn_client_propget3(apr_hash_t **props,
       if (added)
         revnum = 0;
       else
+/* X get prop: 01 ijk */
         SVN_ERR(svn_client__get_revision_number(&revnum, NULL, ctx->wc_ctx,
                                                 local_abspath, NULL, revision,
                                                 pool));

       /* If FALSE, we must want the working revision. */
+ /* XXX what about _revision_prev? this sucks. */
       pristine = (revision->kind == svn_opt_revision_committed
                   || revision->kind == svn_opt_revision_base);

@@ -935,6 +940,7 @@ svn_client_revprop_get(const char *propn

   /* Resolve the revision into something real, and return that to the
      caller as well. */
+/* X get revprop: 1 ab */
   SVN_ERR(svn_client__get_revision_number(set_rev, NULL, ctx->wc_ctx, NULL,
                                           ra_session, revision, pool));

@@ -1279,6 +1285,7 @@ svn_client_revprop_list(apr_hash_t **pro

   /* Resolve the revision into something real, and return that to the
      caller as well. */
+/* X list revprops: 1 ab */
   SVN_ERR(svn_client__get_revision_number(set_rev, NULL, ctx->wc_ctx, NULL,
                                           ra_session, revision, pool));

Index: subversion/libsvn_client/ra.c
===================================================================
--- subversion/libsvn_client/ra.c (revision 953988)
+++ subversion/libsvn_client/ra.c (working copy)
@@ -455,6 +455,7 @@ svn_client__ra_session_from_path(svn_ra_
   /* Resolve good_rev into a real revnum. */
   if (good_rev->kind == svn_opt_revision_unspecified)
     good_rev->kind = svn_opt_revision_head;
+/* X ra_session_from_path: 1 ab */
   SVN_ERR(svn_client__get_revision_number(&rev, NULL, ctx->wc_ctx, url,
                                           ra_session, good_rev, pool));

@@ -631,16 +632,19 @@ svn_client__repos_locations(const char *

   /* Resolve the opt_revision_ts. */
   if (peg_revnum == SVN_INVALID_REVNUM)
+/* X _repos_locations, revision: 01 abxy ijk */
     SVN_ERR(svn_client__get_revision_number(&peg_revnum, &youngest_rev,
                                             ctx->wc_ctx, local_abspath_or_url,
                                             ra_session, revision, pool));

+/* X _repos_locations, start: 01 abxy ijk */
   SVN_ERR(svn_client__get_revision_number(&start_revnum, &youngest_rev,
                                           ctx->wc_ctx, local_abspath_or_url,
                                           ra_session, start, pool));
   if (end->kind == svn_opt_revision_unspecified)
     end_revnum = start_revnum;
   else
+/* X _repos_locations, end: 01 abxy ijk */
     SVN_ERR(svn_client__get_revision_number(&end_revnum, &youngest_rev,
                                             ctx->wc_ctx, local_abspath_or_url,
                                             ra_session, end, pool));
Index: subversion/libsvn_client/revisions.c
===================================================================
--- subversion/libsvn_client/revisions.c (revision 953988)
+++ subversion/libsvn_client/revisions.c (working copy)
@@ -38,6 +38,23 @@

 svn_error_t *
+/* X
+ * invocation types...
+ * out-parameter revision:
+ * 0 _unspecified -> SVN_INVALID_REVNUM
+ * 1 _number -> revision->value.number
+ *
+ * a _head -> _ra_latest_revnum(ra_session)
+ * b _date -> _ra_get_dated_revision(ra_session, revision->value.date)
+ * x _head & youngest_rev -> youngest_rev
+ * y _date & youngest_rev -> min( ra_get_dated_revision(...), youngest_rev)
+ *
+ * i (_working | _base) & local_abspath -> entry->revision
+ * j _committed & local_abspath -> entry->cmt_rev
+ * k _previous & local_abspath -> entry->cmt_rev - 1
+ *
+ * out-parameter youngest_rev only useful with x, y
+ */
 svn_client__get_revision_number(svn_revnum_t *revnum,
                                 svn_revnum_t *youngest_rev,
                                 svn_wc_context_t *wc_ctx,
Index: subversion/libsvn_client/status.c
===================================================================
--- subversion/libsvn_client/status.c (revision 953988)
+++ subversion/libsvn_client/status.c (working copy)
@@ -432,6 +432,7 @@ svn_client_status5(svn_revnum_t *result_
           else
             {
               /* Get a revision number for our status operation. */
+/* X status: 01 b ijk */
               SVN_ERR(svn_client__get_revision_number(&revnum, NULL,
                                                       ctx->wc_ctx,
                                                       target_abspath,
Index: subversion/libsvn_client/update.c
===================================================================
--- subversion/libsvn_client/update.c (revision 953988)
+++ subversion/libsvn_client/update.c (working copy)
@@ -197,6 +197,10 @@ update_internal(svn_revnum_t *result_rev

   /* ### todo: shouldn't svn_client__get_revision_number be able
      to take a URL as easily as a local path? */
+ /* ### No. The local_abspath is needed to look up a node's WC revision.
+ Keywords that make sense on URLs (HEAD, <DATE>) only need the
+ ra_session, not the actual URL. */
+/* X update: 01 ab ijk */
   SVN_ERR(svn_client__get_revision_number(&revnum, NULL, ctx->wc_ctx,
                                           local_abspath, ra_session, revision,
                                           pool));
Index: subversion/libsvn_client/url.c
===================================================================
--- subversion/libsvn_client/url.c (revision 953988)
+++ subversion/libsvn_client/url.c (working copy)
@@ -120,6 +120,7 @@ svn_client__derive_location(const char *
                                                        NULL, FALSE, TRUE, ctx,
                                                        scratch_pool));
         }
+/* X _derive_location, peg rev: 01 ab */
       SVN_ERR(svn_client__get_revision_number(peg_revnum, NULL, ctx->wc_ctx,
                                               NULL, ra_session, peg_revision,
                                               scratch_pool));
]]]