contrib/subversion/subversion/include/private/svn_client_shelf2.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_client_shelf2.h
  24  * @brief Subversion's client library: experimental shelving v2
  25  */
  26
  27 #ifndef SVN_CLIENT_SHELF2_H
  28 #define SVN_CLIENT_SHELF2_H
  29
  30 #include <apr.h>
  31 #include <apr_pools.h>
  32 #include <apr_hash.h>
  33 #include <apr_time.h>
  34
  35 #include "svn_client.h"
  36 #include "svn_types.h"
  37 #include "svn_string.h"
  38 #include "svn_wc.h"
  39 #include "svn_diff.h"
  40 #include "private/svn_diff_tree.h"
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif /* __cplusplus */
  45
  46
  47 \f
  48 /** Shelving v2, with checkpoints
  49  *
  50  * @defgroup svn_client_shelves_checkpoints Shelves and checkpoints
  51  * @{
  52  */
  53
  54 /** A shelf.
  55  *
  56  * @warning EXPERIMENTAL.
  57  */
  58 typedef struct svn_client__shelf2_t
  59 {
  60     /* Public fields (read-only for public use) */
  61     const char *name;
  62     int max_version;  /** @deprecated */
  63
  64     /* Private fields */
  65     const char *wc_root_abspath;
  66     const char *shelves_dir;
  67     apr_hash_t *revprops;  /* non-null; allocated in POOL */
  68     svn_client_ctx_t *ctx;
  69     apr_pool_t *pool;
  70 } svn_client__shelf2_t;
  71
  72 /** One version of a shelved change-set.
  73  *
  74  * @warning EXPERIMENTAL.
  75  */
  76 typedef struct svn_client__shelf2_version_t
  77 {
  78   /* Public fields (read-only for public use) */
  79   svn_client__shelf2_t *shelf;
  80   apr_time_t mtime;  /** time-stamp of this version */
  81
  82   /* Private fields */
  83   const char *files_dir_abspath;  /** abspath of the storage area */
  84   int version_number;  /** version number starting from 1 */
  85 } svn_client__shelf2_version_t;
  86
  87 /** Open an existing shelf or create a new shelf.
  88  *
  89  * Create a new shelf (containing no versions) if a shelf named @a name
  90  * is not found.
  91  *
  92  * The shelf should be closed after use by calling svn_client_shelf_close().
  93  *
  94  * @a local_abspath is any path in the WC and is used to find the WC root.
  95  *
  96  * @warning EXPERIMENTAL.
  97  */
  98 SVN_EXPERIMENTAL
  99 svn_error_t *
 100 svn_client__shelf2_open_or_create(svn_client__shelf2_t **shelf_p,
 101                                   const char *name,
 102                                   const char *local_abspath,
 103                                   svn_client_ctx_t *ctx,
 104                                   apr_pool_t *result_pool);
 105
 106 /** Open an existing shelf named @a name, or error if it doesn't exist.
 107  *
 108  * The shelf should be closed after use by calling svn_client_shelf_close().
 109  *
 110  * @a local_abspath is any path in the WC and is used to find the WC root.
 111  *
 112  * @warning EXPERIMENTAL.
 113  */
 114 SVN_EXPERIMENTAL
 115 svn_error_t *
 116 svn_client__shelf2_open_existing(svn_client__shelf2_t **shelf_p,
 117                                  const char *name,
 118                                  const char *local_abspath,
 119                                  svn_client_ctx_t *ctx,
 120                                  apr_pool_t *result_pool);
 121
 122 /** Close @a shelf.
 123  *
 124  * If @a shelf is NULL, do nothing; otherwise @a shelf must be an open shelf.
 125  *
 126  * @warning EXPERIMENTAL.
 127  */
 128 SVN_EXPERIMENTAL
 129 svn_error_t *
 130 svn_client__shelf2_close(svn_client__shelf2_t *shelf,
 131                          apr_pool_t *scratch_pool);
 132
 133 /** Delete the shelf named @a name, or error if it doesn't exist.
 134  *
 135  * @a local_abspath is any path in the WC and is used to find the WC root.
 136  *
 137  * @warning EXPERIMENTAL.
 138  */
 139 SVN_EXPERIMENTAL
 140 svn_error_t *
 141 svn_client__shelf2_delete(const char *name,
 142                           const char *local_abspath,
 143                           svn_boolean_t dry_run,
 144                           svn_client_ctx_t *ctx,
 145                           apr_pool_t *scratch_pool);
 146
 147 /** Save the local modifications found by @a paths, @a depth,
 148  * @a changelists as a new version of @a shelf.
 149  *
 150  * If any paths are shelved, create a new shelf-version and return the new
 151  * shelf-version in @a *new_version_p, else set @a *new_version_p to null.
 152  * @a new_version_p may be null if that output is not wanted; a new shelf-
 153  * version is still saved and may be found through @a shelf.
 154  *
 155  * @a paths are relative to the CWD, or absolute.
 156  *
 157  * For each successfully shelved path: call @a shelved_func (if not null)
 158  * with @a shelved_baton.
 159  *
 160  * If any paths cannot be shelved: if @a not_shelved_func is given, call
 161  * it with @a not_shelved_baton for each such path, and still create a new
 162  * shelf-version if any paths are shelved.
 163  *
 164  * This function does not revert the changes from the WC; use
 165  * svn_client_shelf_unapply() for that.
 166  *
 167  * @warning EXPERIMENTAL.
 168  */
 169 SVN_EXPERIMENTAL
 170 svn_error_t *
 171 svn_client__shelf2_save_new_version3(svn_client__shelf2_version_t **new_version_p,
 172                                      svn_client__shelf2_t *shelf,
 173                                      const apr_array_header_t *paths,
 174                                      svn_depth_t depth,
 175                                      const apr_array_header_t *changelists,
 176                                      svn_client_status_func_t shelved_func,
 177                                      void *shelved_baton,
 178                                      svn_client_status_func_t not_shelved_func,
 179                                      void *not_shelved_baton,
 180                                      apr_pool_t *scratch_pool);
 181
 182 /** Delete all newer versions of @a shelf newer than @a shelf_version.
 183  *
 184  * If @a shelf_version is null, delete all versions of @a shelf. (The
 185  * shelf will still exist, with any log message and other revprops, but
 186  * with no versions in it.)
 187  *
 188  * Leave the shelf's log message and other revprops unchanged.
 189  *
 190  * Any #svn_client_shelf_version_t object that refers to a deleted version
 191  * will become invalid: attempting to use it will give undefined behaviour.
 192  * The given @a shelf_version will remain valid.
 193  *
 194  * @warning EXPERIMENTAL.
 195  */
 196 SVN_EXPERIMENTAL
 197 svn_error_t *
 198 svn_client__shelf2_delete_newer_versions(svn_client__shelf2_t *shelf,
 199                                          svn_client__shelf2_version_t *shelf_version,
 200                                          apr_pool_t *scratch_pool);
 201
 202 /** Return in @a shelf_version an existing version of @a shelf, given its
 203  * @a version_number. Error if that version doesn't exist.
 204  *
 205  * There is no need to "close" it after use.
 206  *
 207  * @warning EXPERIMENTAL.
 208  */
 209 SVN_EXPERIMENTAL
 210 svn_error_t *
 211 svn_client__shelf2_version_open(svn_client__shelf2_version_t **shelf_version_p,
 212                                 svn_client__shelf2_t *shelf,
 213                                 int version_number,
 214                                 apr_pool_t *result_pool,
 215                                 apr_pool_t *scratch_pool);
 216
 217 /** Return in @a shelf_version the newest version of @a shelf.
 218  *
 219  * Set @a shelf_version to null if no versions exist.
 220  *
 221  * @warning EXPERIMENTAL.
 222  */
 223 SVN_EXPERIMENTAL
 224 svn_error_t *
 225 svn_client__shelf2_get_newest_version(svn_client__shelf2_version_t **shelf_version_p,
 226                                       svn_client__shelf2_t *shelf,
 227                                       apr_pool_t *result_pool,
 228                                       apr_pool_t *scratch_pool);
 229
 230 /** Return in @a versions_p an array of (#svn_client_shelf_version_t *)
 231  * containing all versions of @a shelf.
 232  *
 233  * The versions will be in chronological order, oldest to newest.
 234  *
 235  * @warning EXPERIMENTAL.
 236  */
 237 SVN_EXPERIMENTAL
 238 svn_error_t *
 239 svn_client__shelf2_get_all_versions(apr_array_header_t **versions_p,
 240                                     svn_client__shelf2_t *shelf,
 241                                     apr_pool_t *result_pool,
 242                                     apr_pool_t *scratch_pool);
 243
 244 /** Apply @a shelf_version to the WC.
 245  *
 246  * If @a dry_run is true, try applying the shelf-version to the WC and
 247  * report the full set of notifications about successes and conflicts,
 248  * but leave the WC untouched.
 249  *
 250  * @warning EXPERIMENTAL.
 251  */
 252 SVN_EXPERIMENTAL
 253 svn_error_t *
 254 svn_client__shelf2_apply(svn_client__shelf2_version_t *shelf_version,
 255                          svn_boolean_t dry_run,
 256                          apr_pool_t *scratch_pool);
 257
 258 /** Test whether we can successfully apply the changes for @a file_relpath
 259  * in @a shelf_version to the WC.
 260  *
 261  * Set @a *conflict_p to true if the changes conflict with the WC state,
 262  * else to false.
 263  *
 264  * If @a file_relpath is not found in @a shelf_version, set @a *conflict_p
 265  * to FALSE.
 266  *
 267  * @a file_relpath is relative to the WC root.
 268  *
 269  * A conflict means the shelf cannot be applied successfully to the WC
 270  * because the change to be applied is not compatible with the current
 271  * working state of the WC file. Examples are a text conflict, or the
 272  * file does not exist or is a directory, or the shelf is trying to add
 273  * the file but it already exists, or trying to delete it but it does not
 274  * exist.
 275  *
 276  * Return an error only if something is broken, e.g. unable to read data
 277  * from the specified shelf-version.
 278  *
 279  * Leave the WC untouched.
 280  *
 281  * @warning EXPERIMENTAL.
 282  */
 283 SVN_EXPERIMENTAL
 284 svn_error_t *
 285 svn_client__shelf2_test_apply_file(svn_boolean_t *conflict_p,
 286                                    svn_client__shelf2_version_t *shelf_version,
 287                                    const char *file_relpath,
 288                                    apr_pool_t *scratch_pool);
 289
 290 /** Reverse-apply @a shelf_version to the WC.
 291  *
 292  * @warning EXPERIMENTAL.
 293  */
 294 SVN_EXPERIMENTAL
 295 svn_error_t *
 296 svn_client__shelf2_unapply(svn_client__shelf2_version_t *shelf_version,
 297                            svn_boolean_t dry_run,
 298                            apr_pool_t *scratch_pool);
 299
 300 /** Set @a *affected_paths to a hash with one entry for each path affected
 301  * by the @a shelf_version.
 302  *
 303  * The hash key is the path of the affected file, relative to the WC root.
 304  *
 305  * (Future possibility: When moves and copies are supported, the hash key
 306  * is the old path and value is the new path.)
 307  *
 308  * @warning EXPERIMENTAL.
 309  */
 310 SVN_EXPERIMENTAL
 311 svn_error_t *
 312 svn_client__shelf2_paths_changed(apr_hash_t **affected_paths,
 313                                  svn_client__shelf2_version_t *shelf_version,
 314                                  apr_pool_t *result_pool,
 315                                  apr_pool_t *scratch_pool);
 316
 317 /** Set @a shelf's revprop @a prop_name to @a prop_val.
 318  *
 319  * This can be used to set or change the shelf's log message
 320  * (property name "svn:log" or #SVN_PROP_REVISION_LOG).
 321  *
 322  * If @a prop_val is NULL, delete the property (if present).
 323  *
 324  * @warning EXPERIMENTAL.
 325  */
 326 SVN_EXPERIMENTAL
 327 svn_error_t *
 328 svn_client__shelf2_revprop_set(svn_client__shelf2_t *shelf,
 329                                const char *prop_name,
 330                                const svn_string_t *prop_val,
 331                                apr_pool_t *scratch_pool);
 332
 333 /** Set @a shelf's revprops to @a revprop_table.
 334  *
 335  * This deletes all previous revprops.
 336  *
 337  * @warning EXPERIMENTAL.
 338  */
 339 SVN_EXPERIMENTAL
 340 svn_error_t *
 341 svn_client__shelf2_revprop_set_all(svn_client__shelf2_t *shelf,
 342                                    apr_hash_t *revprop_table,
 343                                    apr_pool_t *scratch_pool);
 344
 345 /** Get @a shelf's revprop @a prop_name into @a *prop_val.
 346  *
 347  * If the property is not present, set @a *prop_val to NULL.
 348  *
 349  * This can be used to get the shelf's log message
 350  * (property name "svn:log" or #SVN_PROP_REVISION_LOG).
 351  *
 352  * The lifetime of the result is limited to that of @a shelf and/or
 353  * of @a result_pool.
 354  *
 355  * @warning EXPERIMENTAL.
 356  */
 357 SVN_EXPERIMENTAL
 358 svn_error_t *
 359 svn_client__shelf2_revprop_get(svn_string_t **prop_val,
 360                                svn_client__shelf2_t *shelf,
 361                                const char *prop_name,
 362                                apr_pool_t *result_pool);
 363
 364 /** Get @a shelf's revprops into @a props.
 365  *
 366  * The lifetime of the result is limited to that of @a shelf and/or
 367  * of @a result_pool.
 368  *
 369  * @warning EXPERIMENTAL.
 370  */
 371 SVN_EXPERIMENTAL
 372 svn_error_t *
 373 svn_client__shelf2_revprop_list(apr_hash_t **props,
 374                                 svn_client__shelf2_t *shelf,
 375                                 apr_pool_t *result_pool);
 376
 377 /** Set the log message in @a shelf to @a log_message.
 378  *
 379  * If @a log_message is null, delete the log message.
 380  *
 381  * Similar to svn_client_shelf_revprop_set(... SVN_PROP_REVISION_LOG ...).
 382  *
 383  * @warning EXPERIMENTAL.
 384  */
 385 SVN_EXPERIMENTAL
 386 svn_error_t *
 387 svn_client__shelf2_set_log_message(svn_client__shelf2_t *shelf,
 388                                    const char *log_message,
 389                                    apr_pool_t *scratch_pool);
 390
 391 /** Get the log message in @a shelf into @a *log_message.
 392  *
 393  * Set @a *log_message to NULL if there is no log message.
 394  *
 395  * Similar to svn_client_shelf_revprop_get(... SVN_PROP_REVISION_LOG ...).
 396  *
 397  * The result is allocated in @a result_pool.
 398  *
 399  * @warning EXPERIMENTAL.
 400  */
 401 SVN_EXPERIMENTAL
 402 svn_error_t *
 403 svn_client__shelf2_get_log_message(char **log_message,
 404                                    svn_client__shelf2_t *shelf,
 405                                    apr_pool_t *result_pool);
 406
 407 /** Information about a shelf.
 408  *
 409  * @warning EXPERIMENTAL.
 410  */
 411 typedef struct svn_client__shelf2_info_t
 412 {
 413   apr_time_t mtime;  /* mtime of the latest change */
 414 } svn_client__shelf2_info_t;
 415
 416 /** Set @a *shelf_infos to a hash, keyed by shelf name, of pointers to
 417  * @c svn_client_shelf_info_t structures, one for each shelf in the
 418  * given WC.
 419  *
 420  * @a local_abspath is any path in the WC and is used to find the WC root.
 421  *
 422  * @warning EXPERIMENTAL.
 423  */
 424 SVN_EXPERIMENTAL
 425 svn_error_t *
 426 svn_client__shelf2_list(apr_hash_t **shelf_infos,
 427                         const char *local_abspath,
 428                         svn_client_ctx_t *ctx,
 429                         apr_pool_t *result_pool,
 430                         apr_pool_t *scratch_pool);
 431
 432 /* Report the shelved status of all the shelved paths in SHELF_VERSION
 433  * via WALK_FUNC(WALK_BATON, ...).
 434  *
 435  * @warning EXPERIMENTAL.
 436  */
 437 SVN_EXPERIMENTAL
 438 svn_error_t *
 439 svn_client__shelf2_version_status_walk(svn_client__shelf2_version_t *shelf_version,
 440                                        const char *wc_relpath,
 441                                        svn_wc_status_func4_t walk_func,
 442                                        void *walk_baton,
 443                                        apr_pool_t *scratch_pool);
 444
 445 /** Output the subtree of @a shelf_version rooted at @a shelf_relpath
 446  * as a diff to @a diff_processor.
 447  *
 448  * ### depth and ignore_ancestry are currently ignored.
 449  *
 450  * @warning EXPERIMENTAL.
 451  */
 452 SVN_EXPERIMENTAL
 453 svn_error_t *
 454 svn_client__shelf2_diff(svn_client__shelf2_version_t *shelf_version,
 455                         const char *shelf_relpath,
 456                         svn_depth_t depth,
 457                         svn_boolean_t ignore_ancestry,
 458                         const svn_diff_tree_processor_t *diff_processor,
 459                         apr_pool_t *scratch_pool);
 460
 461 /** @} */
 462
 463 #ifdef __cplusplus
 464 }
 465 #endif /* __cplusplus */
 466
 467 #endif  /* SVN_CLIENT_SHELF2_H */