You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@subversion.apache.org by st...@apache.org on 2015/08/14 14:26:40 UTC
svn commit: r1695878 -
/subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h
Author: stefan2
Date: Fri Aug 14 12:26:40 2015
New Revision: 1695878
URL: http://svn.apache.org/r1695878
Log:
On the svn-mergeinfo-normalizer:
Document the internal API. No functional change.
* tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h
(): Add docstrings to everything.
Modified:
subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h
Modified: subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h
URL: http://svn.apache.org/viewvc/subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h?rev=1695878&r1=1695877&r2=1695878&view=diff
==============================================================================
--- subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h (original)
+++ subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h Fri Aug 14 12:26:40 2015
@@ -42,8 +42,6 @@ extern "C" {
/*** Command dispatch. ***/
-typedef struct svn_min__branch_lookup_t svn_min__branch_lookup_t;
-
/* Hold results of option processing that are shared by multiple
commands. */
typedef struct svn_min__opt_state_t
@@ -81,16 +79,31 @@ typedef struct svn_min__opt_state_t
svn_boolean_t non_interactive;
} svn_min__opt_state_t;
+/* Opaque structure allowing to check efficiently whether a given path
+ * exists in the repository @HEAD. */
+typedef struct svn_min__branch_lookup_t svn_min__branch_lookup_t;
+/* Type of the baton passed to any of our sub-commands. */
typedef struct svn_min__cmd_baton_t
{
+ /* Preprocessed line options. */
svn_min__opt_state_t *opt_state;
+
+ /* Client context. */
svn_client_ctx_t *ctx;
+ /* Base path of the directory tree currently being processed. */
const char *local_abspath;
+
+ /* Working copy root path of LOCAL_ABSPATH. */
const char *wc_root;
+
+ /* Root of the corresponding working copy. */
const char *repo_root;
+ /* If the sub-command, e.g. the local lookup only 'remove-branches',
+ * needs a specific repository lookup data structure, set it here.
+ * If this is NULL, the sub-command will use remove lookup to REPO_ROOT. */
svn_min__branch_lookup_t *lookup;
} svn_min__cmd_baton_t;
@@ -117,29 +130,56 @@ svn_error_t *
svn_min__check_cancel(void *baton);
-/*** Command-line output functions -- printing to the user. ***/
+/*** Internal API linking the various modules. ***/
+/* Set the path and url members in BATON to handle the IDX-th target
+ * specified at the command line. Allocate the paths in RESULT_POOL and
+ * use SCRATCH_POOL for temporaries. */
svn_error_t *
svn_min__add_wc_info(svn_min__cmd_baton_t* baton,
int idx,
apr_pool_t* result_pool,
apr_pool_t* scratch_pool);
+/* Scan the working copy sub-tree specified in BATON for mergeinfo and
+ * return them in *RESULT, allocated in RESULT_POOL. The element type is
+ * opaque. Use SCRATCH_POOL for temporary allocations. */
svn_error_t *
svn_min__read_mergeinfo(apr_array_header_t **result,
svn_min__cmd_baton_t *baton,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
+/* For the MERGEINFO as returned by svn_min__read_mergeinfo() return the
+ * FS path that is parent to the working copy and all branches mentioned
+ * in the mergeinfo. Allocate the return value in RESULT_POOL and use
+ * SCRATCH_POOL for temporaries. */
const char *
svn_min__common_parent(apr_array_header_t *mergeinfo,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
+/* Return the mergeinfo at index IDX in MERGEINFO.
+ * IDX must be 0 .. MERGEINFO->NELTS-1. */
svn_mergeinfo_t
svn_min__get_mergeinfo(apr_array_header_t *mergeinfo,
int idx);
+/* Return the full info on the mergeinfo at IDX in MERGEINFO. Set *FS_PATH
+ * to the FS path of the respective working copy node, *SUBTREE_RELPATH to
+ * its local absolute path and *PARENT_PATH to the local absolute path of
+ * the working copy node that carries the closest parent mergeinfo.
+ * return the working. Set *SUBTREE_MERGEINFO to the parsed mergeinfo at
+ * *SUBTREE_RELPATH and *PARENT_MERGEINFO to the parsed mergeinfo at
+ * *PARENT_PATH.
+ *
+ * If there is no parent mergeinfo, *PARENT_PATH will be "" and
+ * *PARENT_MERGEINFO will be NULL. If IDX is not a valid array index,
+ * "" will be returned for all paths and all mergeinfo will be NULL.
+ *
+ * Note that the returned data is shared with MERGEINFO and has the same
+ * lifetime. It is perfectly legal to modify the svn_mergeinfo_t hashes
+ * and store the result using svn_min__write_mergeinfo. */
void
svn_min__get_mergeinfo_pair(const char **fs_path,
const char **parent_path,
@@ -149,29 +189,46 @@ svn_min__get_mergeinfo_pair(const char *
apr_array_header_t *mergeinfo,
int idx);
+/* Store the MERGEINFO in the working copy specified by BATON. Delete
+ * the mergeinfo on those nodes where it is empty but keep the empty data
+ * in MERGEINFO. Use SCRATCH_POOL for temporary allocations. */
svn_error_t *
svn_min__write_mergeinfo(svn_min__cmd_baton_t *baton,
apr_array_header_t *mergeinfo,
apr_pool_t *scratch_pool);
+/* Remove entries with empty mergeinfo from MERGEINFO. */
svn_error_t *
svn_min__remove_empty_mergeinfo(apr_array_header_t *mergeinfo);
+/* Print statistics for WC_MERGEINFO to console. Use SCRATCH_POOL for
+ * temporaries. */
svn_error_t *
svn_min__print_mergeinfo_stats(apr_array_header_t *wc_mergeinfo,
apr_pool_t *scratch_pool);
+/* Opaque data structure containing the log / history downloaded from the
+ * repository. */
typedef struct svn_min__log_t svn_min__log_t;
+/* Data structure describing a copy operation as part of svn_min__log_t. */
typedef struct svn_min__copy_t
{
+ /* Copy target FS path. */
const char *path;
+
+ /* Copy target revision. */
svn_revnum_t revision;
+ /* Copy source FS path. */
const char *copyfrom_path;
+
+ /* Copy source revision. */
svn_revnum_t copyfrom_revision;
} svn_min__copy_t;
+/* Fetch the full *LOG for the given URL using the context in BATON.
+ * Allocate *LOG in RESULT_POOL and use SCRATCH_POOL for temporaries. */
svn_error_t *
svn_min__log(svn_min__log_t **log,
const char *url,
@@ -179,12 +236,18 @@ svn_min__log(svn_min__log_t **log,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
+/* Scan LOG and determine what revisions in RANGES actually operate on PATH
+ * or its sub-nodes. Return those revisions, allocated in RESULT_POOL.
+ * Note that parent path changes don't count as operative within PATH. */
svn_rangelist_t *
svn_min__operative(svn_min__log_t *log,
const char *path,
svn_rangelist_t *ranges,
apr_pool_t *result_pool);
+/* Scan LOG and determine what revisions in RANGES are operative on PATH
+ * but outside SUBTREE (possibly but not exclusively modifying paths within
+ * SUBTREE). Return those revisions, allocated in RESULT_POOL. */
svn_rangelist_t *
svn_min__operative_outside_subtree(svn_min__log_t *log,
const char *path,
@@ -192,6 +255,10 @@ svn_min__operative_outside_subtree(svn_m
svn_rangelist_t *ranges,
apr_pool_t *result_pool);
+/* Scan LOG from START_REV down to END_REV and find the latest deletion of
+ * PATH or a parent thereof and return the revision that contains the
+ * deletion. Return SVN_INVALID_REVNUM if no such deletion could be found.
+ * Use SCRATCH_POOL for temporaries. */
svn_revnum_t
svn_min__find_deletion(svn_min__log_t *log,
const char *path,
@@ -199,12 +266,18 @@ svn_min__find_deletion(svn_min__log_t *l
svn_revnum_t end_rev,
apr_pool_t *scratch_pool);
+/* Scan LOG for deletions of PATH or any of its parents. Return an array,
+ * allocated in RESULT_POOL, containing all svn_revnum_t that contain such
+ * deletions in ascending order. Use SCRATCH_POOL for temporaries. */
apr_array_header_t *
svn_min__find_deletions(svn_min__log_t *log,
const char *path,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
+/* Scan LOG for the latest copy of PATH or any of its parents no later than
+ * START_REV and no earlier than END_REV. Return SVN_INVALID_REVNUM if no
+ * such revision exists. Use SCRATCH_POOL for temporaries. */
svn_revnum_t
svn_min__find_copy(svn_min__log_t *log,
const char *path,
@@ -212,6 +285,11 @@ svn_min__find_copy(svn_min__log_t *log,
svn_revnum_t end_rev,
apr_pool_t *scratch_pool);
+/* Scan LOG for copies of PATH, any of its parents or sub-nodes made from
+ * revisions no later than START_REV and no earlier than END_REV. Return
+ * those copies as svn_min__copy_t* in an array allocated in RESULT_POOL.
+ * The copy objects themselves are shared with LOG. Use SCRATCH_POOL
+ * for temporary allocations. */
apr_array_header_t *
svn_min__get_copies(svn_min__log_t *log,
const char *path,
@@ -220,6 +298,15 @@ svn_min__get_copies(svn_min__log_t *log,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
+/* Return the opaque history object for PATH, starting at START_REV and
+ * going back to its initial creation or END_REV - whichever is latest.
+ *
+ * The history is a sequence of segments, each describing that the node
+ * existed at a given path for a given range of revisions. Between two
+ * segments, there must have been a copy operation.
+ *
+ * Allocate the result in RESULT_POOL and use SCRATCH_POOL for temporaries.
+ */
apr_array_header_t *
svn_min__get_history(svn_min__log_t *log,
const char *path,
@@ -228,15 +315,22 @@ svn_min__get_history(svn_min__log_t *log
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
+/* Return the (potentially empty) parts of LHS and RHS where their history
+ * overlaps, i.e. those (partial) history segments where they have the same
+ * path for in the same revisions. Allocate the result in RESULT_POOL. */
apr_array_header_t *
svn_min__intersect_history(apr_array_header_t *lhs,
apr_array_header_t *rhs,
apr_pool_t *result_pool);
+/* Return the revision ranges that are covered by the segments in HISTORY.
+ * Allocate the result in RESULT_POOL. */
svn_rangelist_t *
svn_min__history_ranges(apr_array_header_t *history,
apr_pool_t *result_pool);
+/* Allocate a new path lookup object in RESULT_POOL and make it use SESSION
+ * for any future repository lookups. */
svn_min__branch_lookup_t *
svn_min__branch_lookup_create(svn_ra_session_t *session,
apr_pool_t *result_pool);