svn_fs.h

linux subdivision ying gai ke yi le ba

 *
 * To make a change to a Subversion filesystem:
 * - Create a transaction object, using @c svn_fs_begin_txn.
 * - Call @c svn_fs_txn_root, to get the transaction's root directory.
 * - Make whatever changes you like in that tree.
 * - Commit the transaction, using @c svn_fs_commit_txn.
 *
 * The filesystem implementation guarantees that your commit will
 * either:
 * - succeed completely, so that all of the changes are committed to
 *   create a new revision of the filesystem, or
 * - fail completely, leaving the filesystem unchanged.
 *
 * Until you commit the transaction, any changes you make are
 * invisible.  Only when your commit succeeds do they become visible
 * to the outside world, as a new revision of the filesystem.
 *
 * If you begin a transaction, and then decide you don't want to make
 * the change after all (say, because your net connection with the
 * client disappeared before the change was complete), you can call
 * @c svn_fs_abort_txn, to cancel the entire transaction; this
 * leaves the filesystem unchanged.
 *
 * The only way to change the contents of files or directories, or
 * their properties, is by making a transaction and creating a new
 * revision, as described above.  Once a revision has been committed, it
 * never changes again; the filesystem interface provides no means to
 * go back and edit the contents of an old revision.  Once history has
 * been recorded, it is set in stone.  Clients depend on this property
 * to do updates and commits reliably; proxies depend on this property
 * to cache changes accurately; and so on.
 *
 * There are two kinds of nodes in the filesystem: mutable, and
 * immutable.  Revisions in the filesystem consist entirely of
 * immutable nodes, whose contents never change.  A transaction in
 * progress, which the user is still constructing, uses mutable nodes
 * for those nodes which have been changed so far, and refers to
 * immutable nodes from existing revisions for portions of the tree
 * which haven't been changed yet in that transaction.
 *
 * Immutable nodes, as part of revisions, never refer to mutable
 * nodes, which are part of uncommitted transactions.  Mutable nodes
 * may refer to immutable nodes, or other mutable nodes.
 *
 * Note that the terms "immutable" and "mutable" describe whether or
 * not the nodes have been changed as part of a transaction --- not
 * the permissions on the nodes they refer to.  Even if you aren't
 * authorized to modify the filesystem's root directory, you might be
 * authorized to change some descendant of the root; doing so would
 * create a new mutable copy of the root directory.  Mutability refers
 * to the role of the node: part of an existing revision, or part of a
 * new one.  This is independent of your authorization to make changes
 * to a given node.
 *
 * Transactions are actually persistent objects, stored in the
 * database.  You can open a filesystem, begin a transaction, and
 * close the filesystem, and then a separate process could open the
 * filesystem, pick up the same transaction, and continue work on it.
 * When a transaction is successfully committed, it is removed from
 * the database.
 *
 * Every transaction is assigned a name.  You can open a transaction
 * by name, and resume work on it, or find out the name of a
 * transaction you already have open.  You can also list all the
 * transactions currently present in the database.
 *
 * Transaction names are guaranteed to contain only letters (upper-
 * and lower-case), digits, `-', and `.', from the ASCII character
 * set.
 *
 * @defgroup svn_fs_txns filesystem transactions
 * @{
 */

/** The type of a Subversion transaction object.  */
typedef struct svn_fs_txn_t svn_fs_txn_t;


/** Begin a new transaction on the filesystem @a fs, based on existing
 * revision @a rev.  Set @a *txn_p to a pointer to the new transaction.
 * When committed, this transaction will create a new revision.
 *
 * Allocate the new transaction in @a pool; when @a pool is freed, the new
 * transaction will be closed (neither committed nor aborted).
 *
 *<pre>   >> Note: if you're building a txn for committing, you probably <<
 *   >> don't want to call this directly.  Instead, call            <<
 *   >> @c svn_repos_fs_begin_txn_for_commit(), which honors the       <<
 *   >> repository's hook configurations.                           <<</pre>
 */
svn_error_t *svn_fs_begin_txn (svn_fs_txn_t **txn_p,
                               svn_fs_t *fs,
                               svn_revnum_t rev,
                               apr_pool_t *pool);


/** Commit @a txn.
 *
 *<pre>   >> Note: you usually don't want to call this directly.        <<
 *   >> Instead, call @c svn_repos_fs_commit_txn(), which honors the  <<
 *   >> repository's hook configurations.                          <<</pre>
 *
 * If the transaction conflicts with other changes committed to the
 * repository, return an @c SVN_ERR_FS_CONFLICT error.  Otherwise, create
 * a new filesystem revision containing the changes made in @a txn,
 * storing that new revision number in @a *new_rev, and return zero.
 *
 * If @a conflict_p is non-zero, use it to provide details on any
 * conflicts encountered merging @a txn with the most recent committed
 * revisions.  If a conflict occurs, set @a *conflict_p to the path of
 * the conflict in @a txn, with the same lifetime as @a txn;
 * otherwise, set @a *conflict_p to null.
 *
 * If the commit succeeds, @a txn is invalid.
 *
 * If the commit fails, @a txn is still valid; you can make more
 * operations to resolve the conflict, or call @c svn_fs_abort_txn to
 * abort the transaction.
 *
 * NOTE:  Success or failure of the commit of @a txn is determined by
 * examining the value of @a *new_rev upon this function's return.  If
 * the value is a valid revision number, the commit was successful,
 * even though a non-@c NULL function return value may indicate that
 * something else went wrong.
 */
svn_error_t *svn_fs_commit_txn (const char **conflict_p,
                                svn_revnum_t *new_rev,
                                svn_fs_txn_t *txn,
                                apr_pool_t *pool);


/** Abort the transaction @a txn.  Any changes made in @a txn are
 * discarded, and the filesystem is left unchanged.  Use @a pool for
 * any necessary allocations.
 *
 * Use @a pool for any necessary allocations.
 *
 * NOTE: This function first sets the state of the transaction to
 * "dead", and then attempts to the purge the txn and any related data
 * from the filesystem.  If some part of the cleanup process fails,
 * the transaction and some portion of its data may remain in the
 * database after this function returns.  Use @c svn_fs_purge_txn() to
 * retry the transaction cleanup.
 */
svn_error_t *svn_fs_abort_txn (svn_fs_txn_t *txn,
                               apr_pool_t *pool);


/** Cleanup the dead transaction in @a fs whose ID is @a txn_id.  Use
 * @a pool for all allocations.  If the transaction is not yet dead,
 * the error @c SVN_ERR_FS_TRANSACTION_NOT_DEAD is returned.  (The
 * caller probably forgot to abort the transaction, or the cleanup
 * step of that abort failed for some reason.)
 */
svn_error_t *svn_fs_purge_txn (svn_fs_t *fs,
                               const char *txn_id,
                               apr_pool_t *pool);


/** Set @a *name_p to the name of the transaction @a txn, as a
 * null-terminated string.  Allocate the name in @a pool.
 */
svn_error_t *svn_fs_txn_name (const char **name_p,
                              svn_fs_txn_t *txn,
                              apr_pool_t *pool);


/** Return @a txn's base revision.  If @a txn's base root id is an mutable
 * node, return 0.
 */
svn_revnum_t svn_fs_txn_base_revision (svn_fs_txn_t *txn);



/** Open the transaction named @a name in the filesystem @a fs.  Set @a *txn 
 * to the transaction.
 *
 * If there is no such transaction, @c SVN_ERR_FS_NO_SUCH_TRANSACTION is
 * the error returned.
 *
 * Allocate the new transaction in @a pool; when @a pool is freed, the new
 * transaction will be closed (neither committed nor aborted).
 */
svn_error_t *svn_fs_open_txn (svn_fs_txn_t **txn,
                              svn_fs_t *fs,
                              const char *name,
                              apr_pool_t *pool);


/** Set @a *names_p to an array of <tt>const char *</tt> @a ids which are the 
 * names of all the currently active transactions in the filesystem @a fs.
 * Allocate the array in @a pool.
 */
svn_error_t *svn_fs_list_transactions (apr_array_header_t **names_p,
                                       svn_fs_t *fs,
                                       apr_pool_t *pool);

/* Transaction properties */

/** Set @a *value_p to the value of the property named @a propname on
 * transaction @a txn.  If @a txn has no property by that name, set 
 * @a *value_p to zero.  Allocate the result in @a pool.
 */
svn_error_t *svn_fs_txn_prop (svn_string_t **value_p,
                              svn_fs_txn_t *txn,
                              const char *propname,
                              apr_pool_t *pool);


/** Set @a *table_p to the entire property list of transaction @a txn in
 * filesystem @a fs, as an APR hash table allocated in @a pool.  The
 * resulting table maps property names to pointers to @c svn_string_t
 * objects containing the property value.
 */
svn_error_t *svn_fs_txn_proplist (apr_hash_t **table_p,
                                  svn_fs_txn_t *txn,
                                  apr_pool_t *pool);


/** Change a transactions @a txn's property's value, or add/delete a
 * property.  @a name is the name of the property to change, and @a value 
 * is the new value of the property, or zero if the property should be
 * removed altogether.  Do any necessary temporary allocation in @a pool.
 */
svn_error_t *svn_fs_change_txn_prop (svn_fs_txn_t *txn,
                                     const char *name,
                                     const svn_string_t *value,
                                     apr_pool_t *pool);

/** @} */


/** Roots.
 *
 * An @c svn_fs_root_t object represents the root directory of some
 * revision or transaction in a filesystem.  To refer to particular
 * node, you provide a root, and a directory path relative that root.
 *
 * @defgroup svn_fs_roots filesystem roots
 * @{
 */

/** The Filesystem Root object. */
typedef struct svn_fs_root_t svn_fs_root_t;


/** Set @a *root_p to the root directory of revision @a rev in filesystem 
 * @a fs.  Allocate @a *root_p in @a pool.
 */
svn_error_t *svn_fs_revision_root (svn_fs_root_t **root_p,
                                   svn_fs_t *fs,
                                   svn_revnum_t rev,
                                   apr_pool_t *pool);


/** Set @a *root_p to the root directory of @a txn.  Allocate @a *root_p in 
 * @a pool.
 */
svn_error_t *svn_fs_txn_root (svn_fs_root_t **root_p,
                              svn_fs_txn_t *txn,
                              apr_pool_t *pool);


/** Free the root directory @a root.  Simply clearing or destroying the
 * pool @a root was allocated in will have the same effect as calling
 * this function.
 */
void svn_fs_close_root (svn_fs_root_t *root);


/** Return the filesystem to which @a root belongs.  */
svn_fs_t *svn_fs_root_fs (svn_fs_root_t *root);


/** Return @c TRUE iff @a root is a transaction root.  */
svn_boolean_t svn_fs_is_txn_root (svn_fs_root_t *root);

/** Return @c TRUE iff @a root is a revision root.  */
svn_boolean_t svn_fs_is_revision_root (svn_fs_root_t *root);


/** If @a root is the root of a transaction, return the name of the
 * transaction, allocated in @a pool; otherwise, return null.
 */
const char *svn_fs_txn_root_name (svn_fs_root_t *root,
                                  apr_pool_t *pool);


/** If @a root is the root of a revision, return the revision number.
 * Otherwise, return @c SVN_INVALID_REVNUM.
 */
svn_revnum_t svn_fs_revision_root_revision (svn_fs_root_t *root);

/** @} */


/** Directory entry names and directory paths.
 *
 * Here are the rules for directory entry names, and directory paths:
 *
 * A directory entry name is a Unicode string encoded in UTF-8, and
 * may not contain the null character (U+0000).  The name should be in
 * Unicode canonical decomposition and ordering.  No directory entry
 * may be named '.', '..', or the empty string.  Given a directory
 * entry name which fails to meet these requirements, a filesystem
 * function returns an SVN_ERR_FS_PATH_SYNTAX error.
 *
 * A directory path is a sequence of zero or more directory entry
 * names, separated by slash characters (U+002f), and possibly ending
 * with slash characters.  Sequences of two or more consecutive slash
 * characters are treated as if they were a single slash.  If a path
 * ends with a slash, it refers to the same node it would without the
 * slash, but that node must be a directory, or else the function
 * returns an SVN_ERR_FS_NOT_DIRECTORY error.
 *
 * A path consisting of the empty string, or a string containing only
 * slashes, refers to the root directory.
 *
 * @defgroup svn_fs_directories filesystem directories
 * @{
 */



/** The kind of change that occurred on the path. */
typedef enum
{
  /** default value */
  svn_fs_path_change_modify = 0,

  /** path added in txn */
  svn_fs_path_change_add,

  /** path removed in txn */
  svn_fs_path_change_delete,

  /** path removed and re-added in txn */
  svn_fs_path_change_replace,

  /** ignore all previous change items for path (internal-use only) */
  svn_fs_path_change_reset

} svn_fs_path_change_kind_t;