subversion/include/svn_mergeinfo.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  * Copyright (c) 2006-2008 CollabNet.  All rights reserved.
   5  *
   6  * This software is licensed as described in the file COPYING, which
   7  * you should have received as part of this distribution.  The terms
   8  * are also available at http://subversion.tigris.org/license-1.html.
   9  * If newer versions of this license are posted there, you may use a
  10  * newer version instead, at your option.
  11  *
  12  * This software consists of voluntary contributions made by many
  13  * individuals.  For exact contribution history, see the revision
  14  * history and logs, available at http://subversion.tigris.org/.
  15  * ====================================================================
  16  * @endcopyright
  17  *
  18  * @file svn_mergeinfo.h
  19  * @brief mergeinfo handling and processing
  20  */
  21
  22
  23 #ifndef SVN_MERGEINFO_H
  24 #define SVN_MERGEINFO_H
  25
  26 #include <apr_pools.h>
  27 #include <apr_tables.h>         /* for apr_array_header_t */
  28 #include <apr_hash.h>
  29
  30 #include "svn_error.h"
  31
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif /* __cplusplus */
  36
  37 /** Overview of the @c SVN_PROP_MERGEINFO property.
  38  *
  39  * Merge history is stored in the @c SVN_PROP_MERGEINFO property of files
  40  * and directories.  The @c SVN_PROP_MERGEINFO property on a path stores the
  41  * complete list of changes merged to that path, either directly or via the
  42  * path's parent, grand-parent, etc..
  43  *
  44  * Every path in a tree may have @c SVN_PROP_MERGEINFO set, but if the
  45  * @c SVN_PROP_MERGEINFO for a path is equivalent to the
  46  * @c SVN_PROP_MERGEINFO for its parent, then the @c SVN_PROP_MERGEINFO on
  47  * the path will 'elide' (be removed) from the path as a post step to any
  48  * merge.  If a path's parent does not have any @c SVN_PROP_MERGEINFO set,
  49  * the path's mergeinfo can elide to its nearest grand-parent,
  50  * great-grand-parent, etc. that has equivalent @c SVN_PROP_MERGEINFO set
  51  * on it.
  52  *
  53  * If a path has no @c SVN_PROP_MERGEINFO of its own, it inherits mergeinfo
  54  * from its nearest parent that has @c SVN_PROP_MERGEINFO set.  The
  55  * exception to this is @c SVN_PROP_MERGEINFO with non-ineritable revision
  56  * ranges.  These non-inheritable ranges apply only to the path which they
  57  * are set on.
  58  *
  59  * Due to Subversion's allowance for mixed revision working copies, both
  60  * elision and inheritance within the working copy presume the path
  61  * between a path and its nearest parent with mergeinfo is at the same
  62  * working revision.  If this is not the case then neither inheritance nor
  63  * elision can occur.
  64  *
  65  * The value of the @c SVN_PROP_MERGEINFO property is a string consisting of
  66  * a path, a colon, and comma separated revision list, containing one or more
  67  * revision or revision ranges. Revision range start and end points are
  68  * separated by "-".  Revisions and revision ranges may have the optional
  69  * @c SVN_MERGEINFO_NONINHERITABLE_STR suffix to signify a non-inheritable
  70  * revision/revision range.
  71  *
  72  * @c SVN_PROP_MERGEINFO Value Grammar:
  73  *
  74  *   Token             Definition
  75  *   -----             ----------
  76  *   revisionrange     REVISION1 "-" REVISION2
  77  *   revisioneelement  (revisionrange | REVISION)"*"?
  78  *   rangelist         revisioneelement (COMMA revisioneelement)*
  79  *   revisionline      PATHNAME COLON rangelist
  80  *   top               revisionline (NEWLINE revisionline)*
  81  *
  82  * The PATHNAME is the source of a merge and the rangelist the revision(s)
  83  * merged to the path @c SVN_PROP_MERGEINFO is set on directly or indirectly
  84  * via inheritance.  PATHNAME must always exist at the specified rangelist
  85  * and thus a single merge may result in multiple revisionlines if the source
  86  * was renamed.
  87  *
  88  * Rangelists must be sorted from lowest to highest revision and cannot
  89  * contain overlapping revisionlistelements.  REVISION1 must be less than
  90  * REVISION2.  Consecutive single revisions that can be represented by a
  91  * revisionrange are allowed however (e.g. '5,6,7,8,9-12' or '5-12' are
  92  * both acceptable).
  93  */
  94
  95 /* Suffix for SVN_PROP_MERGEINFO revision ranges indicating a given
  96    range is non-inheritable. */
  97 #define SVN_MERGEINFO_NONINHERITABLE_STR "*"
  98
  99 /** Terminology for data structures that contain mergeinfo.
 100  *
 101  * Subversion commonly uses several data structures to represent
 102  * mergeinfo in RAM:
 103  *
 104  * (a) Strings (@c svn_string_t *) containing "unparsed mergeinfo".
 105  *
 106  * (b) Hashes mapping merge source paths (@c const char *, starting
 107  *     with slashes) to non-empty arrays (@c apr_array_header_t *) of
 108  *     merge ranges (@c svn_merge_range_t *), ordered from smallest
 109  *     revision range to largest.  These hashes are called "mergeinfo"
 110  *     and are represented by @c svn_mergeinfo_t.  The sorted arrays
 111  *     are called "rangelists".
 112  *
 113  * (c) Hashes mapping paths (@c const char *, starting with slashes)
 114  *     to @c svn_mergeinfo_t.  These hashes are called "mergeinfo
 115  *     catalogs" and are represented by @c svn_mergeinfo_catalog_t.
 116  *
 117  * Both @c svn_mergeinfo_t and @c svn_mergeinfo_catalog_t are just
 118  * typedefs for @c apr_hash_t *; there is no static type-checking, and
 119  * you still use standard @c apr_hash_t functions to interact with
 120  * them.
 121  *
 122  * Note that while the keys of mergeinfos are always relative to the
 123  * repository root, the keys of a catalog may be relative to something
 124  * else, such as an RA session root.
 125  */
 126
 127 typedef apr_hash_t *svn_mergeinfo_t;
 128 typedef apr_hash_t *svn_mergeinfo_catalog_t;
 129
 130 /** Parse the mergeinfo from @a input into @a *mergeinfo.  If no
 131  * mergeinfo is available, return an empty mergeinfo (never @c NULL).
 132  * Perform temporary allocations in @a pool.
 133  *
 134  * If @a input is not a grammatically correct @c SVN_PROP_MERGEINFO
 135  * property, contains overlapping or unordered revision ranges, or revision
 136  * ranges with a start revision greater than or equal to its end revision,
 137  * or contains paths mapped to empty revision ranges, then return
 138  * @c SVN_ERR_MERGEINFO_PARSE_ERROR.
 139  * @since New in 1.5.
 140  */
 141 svn_error_t *
 142 svn_mergeinfo_parse(svn_mergeinfo_t *mergeinfo, const char *input,
 143                     apr_pool_t *pool);
 144
 145 /** Calculate the delta between two mergeinfos, @a mergefrom and @a mergeto
 146  * (which may be @c NULL), and place the result in @a *deleted and @a
 147  * *added (neither output argument may be @c NULL).
 148  *
 149  * @a consider_inheritance determines how the rangelists in the two
 150  * hashes are compared for equality.  If @a consider_inheritance is FALSE,
 151  * then the start and end revisions of the @c svn_merge_range_t's being
 152  * compared are the only factors considered when determining equality.
 153  *
 154  *  e.g. '/trunk: 1,3-4*,5' == '/trunk: 1,3-5'
 155  *
 156  * If @a consider_inheritance is TRUE, then the inheritability of the
 157  * @c svn_merge_range_t's is also considered and must be the same for two
 158  * otherwise identical ranges to be judged equal.
 159  *
 160  *  e.g. '/trunk: 1,3-4*,5' != '/trunk: 1,3-5'
 161  *       '/trunk: 1,3-4*,5' == '/trunk: 1,3-4*,5'
 162  *       '/trunk: 1,3-4,5'  == '/trunk: 1,3-4,5'
 163  *
 164  * @since New in 1.5.
 165  */
 166 svn_error_t *
 167 svn_mergeinfo_diff(svn_mergeinfo_t *deleted, svn_mergeinfo_t *added,
 168                    svn_mergeinfo_t mergefrom, svn_mergeinfo_t mergeto,
 169                    svn_boolean_t consider_inheritance,
 170                    apr_pool_t *pool);
 171
 172 /** Merge one mergeinfo, @a changes, into another mergeinfo @a
 173  * mergeinfo.
 174  *
 175  * When intersecting rangelists for a path are merged, the inheritability of
 176  * the resulting svn_merge_range_t depends on the inheritability of the
 177  * operands.  If two non-inheritable ranges are merged the result is always
 178  * non-inheritable, in all other cases the resulting range is inheritable.
 179  *
 180  *  e.g. '/A: 1,3-4'  merged with '/A: 1,3,4*,5' --> '/A: 1,3-5'
 181  *       '/A: 1,3-4*' merged with '/A: 1,3,4*,5' --> '/A: 1,3,4*,5'
 182  *
 183  * @since New in 1.5.
 184  */
 185 svn_error_t *
 186 svn_mergeinfo_merge(svn_mergeinfo_t mergeinfo, svn_mergeinfo_t changes,
 187                     apr_pool_t *pool);
 188
 189 /** Removes @a eraser (the subtrahend) from @a whiteboard (the
 190  * minuend), and places the resulting difference in @a *mergeinfo.
 191  *
 192  * @since New in 1.5.
 193  */
 194 svn_error_t *
 195 svn_mergeinfo_remove(svn_mergeinfo_t *mergeinfo, svn_mergeinfo_t eraser,
 196                      svn_mergeinfo_t whiteboard, apr_pool_t *pool);
 197
 198 /** Calculate the delta between two rangelists consisting of @c
 199  * svn_merge_range_t * elements (sorted in ascending order), @a from
 200  * and @a to, and place the result in @a *deleted and @a *added
 201  * (neither output argument will ever be @c NULL).
 202  *
 203  * @a consider_inheritance determines how to account for the inheritability
 204  * of the two rangelist's ranges when calculating the diff,
 205  * @see svn_mergeinfo_diff().
 206  *
 207  * @since New in 1.5.
 208  */
 209 svn_error_t *
 210 svn_rangelist_diff(apr_array_header_t **deleted, apr_array_header_t **added,
 211                    apr_array_header_t *from, apr_array_header_t *to,
 212                    svn_boolean_t consider_inheritance,
 213                    apr_pool_t *pool);
 214
 215 /** Merge two rangelists consisting of @c svn_merge_range_t *
 216  * elements, @a *rangelist and @a changes, placing the results in
 217  * @a *rangelist.  Either rangelist may be empty.
 218  *
 219  * When intersecting rangelists are merged, the inheritability of
 220  * the resulting svn_merge_range_t depends on the inheritability of the
 221  * operands, @see svn_mergeinfo_merge().
 222  *
 223  * Note: @a *rangelist and @a changes must be sorted as said by @c
 224  * svn_sort_compare_ranges().  @a *rangelist is guaranteed to remain
 225  * in sorted order and be compacted to the minimal number of ranges
 226  * needed to represent the merged result.
 227  *
 228  * @since New in 1.5.
 229  */
 230 svn_error_t *
 231 svn_rangelist_merge(apr_array_header_t **rangelist,
 232                     apr_array_header_t *changes,
 233                     apr_pool_t *pool);
 234
 235 /** Removes @a eraser (the subtrahend) from @a whiteboard (the
 236  * minuend), and places the resulting difference in @a output.
 237  *
 238  * Note: @a eraser and @a whiteboard must be sorted as said by @c
 239  * svn_sort_compare_ranges().  @a output is guaranteed to be in sorted
 240  * order.
 241  *
 242  * @a consider_inheritance determines how to account for the
 243  * @c svn_merge_range_t inheritable field when comparing @a whiteboard's
 244  * and @a *eraser's rangelists for equality.  @See svn_mergeinfo_diff().
 245  *
 246  * @since New in 1.5.
 247  */
 248 svn_error_t *
 249 svn_rangelist_remove(apr_array_header_t **output, apr_array_header_t *eraser,
 250                      apr_array_header_t *whiteboard,
 251                      svn_boolean_t consider_inheritance,
 252                      apr_pool_t *pool);
 253
 254 /** Find the intersection of two mergeinfos, @a mergeinfo1 and @a
 255  * mergeinfo2, and place the result in @a *mergeinfo, which is (deeply)
 256  * allocated in @a pool.
 257  *
 258  * @since New in 1.5.
 259  */
 260 svn_error_t *
 261 svn_mergeinfo_intersect(svn_mergeinfo_t *mergeinfo,
 262                         svn_mergeinfo_t mergeinfo1,
 263                         svn_mergeinfo_t mergeinfo2,
 264                         apr_pool_t *pool);
 265
 266 /** Find the intersection of two rangelists consisting of @c
 267  * svn_merge_range_t * elements, @a rangelist1 and @a rangelist2, and
 268  * place the result in @a *rangelist (which is never @c NULL).
 269  *
 270  * Note: @a rangelist1 and @a rangelist2 must be sorted as said by @c
 271  * svn_sort_compare_ranges(). @a *rangelist is guaranteed to be in sorted
 272  * order.
 273  * @since New in 1.5.
 274  */
 275 svn_error_t *
 276 svn_rangelist_intersect(apr_array_header_t **rangelist,
 277                         apr_array_header_t *rangelist1,
 278                         apr_array_header_t *rangelist2,
 279                         apr_pool_t *pool);
 280
 281 /** Reverse @a rangelist, and the @c start and @c end fields of each
 282  * range in @a rangelist, in place.
 283  *
 284  * TODO(miapi): Is this really a valid function?  Rangelists that
 285  * aren't sorted, or rangelists containing reverse ranges, are
 286  * generally not valid in mergeinfo code.  Can we rewrite the two
 287  * places where this is used?
 288  *
 289  * @since New in 1.5.
 290  */
 291 svn_error_t *
 292 svn_rangelist_reverse(apr_array_header_t *rangelist, apr_pool_t *pool);
 293
 294 /** Take an array of svn_merge_range_t *'s in @a rangelist, and convert it
 295  * back to a text format rangelist in @a output.  If @a rangelist contains
 296  * no elements, sets @a output to the empty string.
 297  *
 298  * @since New in 1.5.
 299  */
 300 svn_error_t *
 301 svn_rangelist_to_string(svn_string_t **output,
 302                         const apr_array_header_t *rangelist,
 303                         apr_pool_t *pool);
 304
 305 /** Return a deep copy of @c svn_merge_range_t *'s in @a rangelist excluding
 306  * all non-inheritable @c svn_merge_range_t.  If @a start and @a end are valid
 307  * revisions and @a start is less than or equal to @a end, then exclude only the
 308  * non-inheritable revision ranges that intersect inclusively with the range
 309  * defined by @a start and @a end.  If @a rangelist contains no elements, return
 310  * an empty array.  Allocate the copy in @a pool.
 311  *
 312  * @since New in 1.5.
 313  */
 314 svn_error_t *
 315 svn_rangelist_inheritable(apr_array_header_t **inheritable_rangelist,
 316                           apr_array_header_t *rangelist,
 317                           svn_revnum_t start,
 318                           svn_revnum_t end,
 319                           apr_pool_t *pool);
 320
 321 /** Return a deep copy of @a mergeinfo, excluding all non-inheritable
 322  * @c svn_merge_range_t.  If @a start and @a end are valid revisions
 323  * and @a start is less than or equal to @a end, then exclude only the
 324  * non-inheritable revisions that intersect inclusively with the range
 325  * defined by @a start and @a end.  If @a path is not NULL remove
 326  * non-inheritable ranges only for @a path.  Allocate the copy in @a
 327  * pool.
 328  *
 329  * @since New in 1.5.
 330  */
 331 svn_error_t *
 332 svn_mergeinfo_inheritable(svn_mergeinfo_t *inheritable_mergeinfo,
 333                           svn_mergeinfo_t mergeinfo,
 334                           const char *path,
 335                           svn_revnum_t start,
 336                           svn_revnum_t end,
 337                           apr_pool_t *pool);
 338
 339 /** Take a mergeinfo in MERGEINPUT, and convert it back to unparsed
 340  *  mergeinfo in *OUTPUT.  If INPUT contains no elements, return the
 341  *  empty string.
 342  *
 343  * @since New in 1.5.
 344 */
 345 svn_error_t *
 346 svn_mergeinfo_to_string(svn_string_t **output,
 347                         svn_mergeinfo_t mergeinput,
 348                         apr_pool_t *pool);
 349
 350 /** Take a hash of mergeinfo in @a mergeinfo, and sort the rangelists
 351  * associated with each key (in place).
 352  *
 353  * TODO(miapi): mergeinfos should *always* be sorted.  This should be
 354  * a private function.
 355  *
 356  * @since New in 1.5
 357  */
 358 svn_error_t *
 359 svn_mergeinfo_sort(svn_mergeinfo_t mergeinfo, apr_pool_t *pool);
 360
 361 /** Return a deep copy of @a mergeinfo, allocated in @a pool.
 362  *
 363  * @since New in 1.5.
 364  */
 365 svn_mergeinfo_t
 366 svn_mergeinfo_dup(svn_mergeinfo_t mergeinfo, apr_pool_t *pool);
 367
 368 /** Return a deep copy of @a rangelist, allocated in @a pool.
 369  *
 370  * @since New in 1.5.
 371  */
 372 apr_array_header_t *
 373 svn_rangelist_dup(apr_array_header_t *rangelist, apr_pool_t *pool);
 374
 375
 376 /**
 377  * The three ways to request mergeinfo affecting a given path.
 378  *
 379  * @since New in 1.5.
 380  */
 381 typedef enum
 382 {
 383   /** Explicit mergeinfo only. */
 384   svn_mergeinfo_explicit,
 385
 386   /** Explicit mergeinfo, or if that doesn't exist, the inherited
 387       mergeinfo from a target's nearest (path-wise, not history-wise)
 388       ancestor. */
 389   svn_mergeinfo_inherited,
 390
 391   /** Mergeinfo on target's nearest (path-wise, not history-wise)
 392       ancestor, regardless of whether target has explict mergeinfo. */
 393   svn_mergeinfo_nearest_ancestor
 394 } svn_mergeinfo_inheritance_t;
 395
 396 /** Return a constant string expressing @a inherit as an English word,
 397  * i.e., "explicit" (default), "inherited", or "nearest_ancestor".
 398  * The string is not localized, as it may be used for client<->server
 399  * communications.
 400  *
 401  * @since New in 1.5.
 402  */
 403 const char *
 404 svn_inheritance_to_word(svn_mergeinfo_inheritance_t inherit);
 405
 406
 407 /** Return the appropriate @c svn_mergeinfo_inheritance_t for @a word.
 408  * @a word is as returned from svn_inheritance_to_word().  Defaults to
 409  * @c svn_mergeinfo_explicit.
 410  *
 411  * @since New in 1.5.
 412  */
 413 svn_mergeinfo_inheritance_t
 414 svn_inheritance_from_word(const char *word);
 415
 416
 417 #ifdef __cplusplus
 418 }
 419 #endif /* __cplusplus */
 420
 421 #endif /* SVN_MERGEINFO_H */