svn_fs.h

linux subdivision ying gai ke yi le ba

/** Change descriptor. */
typedef struct svn_fs_path_change_t
{
  /** node revision id of changed path */
  const svn_fs_id_t *node_rev_id;

  /** kind of change (see above) */
  svn_fs_path_change_kind_t change_kind;

  /** were there text mods? */
  svn_boolean_t text_mod;

  /** were there property mods? */
  svn_boolean_t prop_mod;

} svn_fs_path_change_t;


/** Determine what has changed under a @a root.
 *
 * Allocate and return a hash @a *changed_paths_p containing descriptions
 * of the paths changed under @a root.  The hash is keyed with 
 * <tt>const char *</tt> paths, and has @c svn_fs_path_change_t * values.  
 * Use @c pool for all allocations, including the hash and its values.
 */
svn_error_t *svn_fs_paths_changed (apr_hash_t **changed_paths_p,
                                   svn_fs_root_t *root,
                                   apr_pool_t *pool);

/** @} */


/* Operations appropriate to all kinds of nodes.  */

/** Set @a *kind_p to the type of node present at @a path under @a
 * root.  If @a path does not exist under @a root, set @a *kind to @c
 * svn_node_none.  Use @a pool for temporary allocation.
 */
svn_error_t *svn_fs_check_path (svn_node_kind_t *kind_p,
                                svn_fs_root_t *root,
                                const char *path,
                                apr_pool_t *pool);


/** An opaque node history object. */
typedef struct svn_fs_history_t svn_fs_history_t;


/** Set @a *history_p to an opaque node history object which
 * represents @a path under @a root.  @a root must be a revision root.
 * Use @a pool for all allocations.
 */
svn_error_t *svn_fs_node_history (svn_fs_history_t **history_p,
                                  svn_fs_root_t *root,
                                  const char *path,
                                  apr_pool_t *pool);


/** Set @a *prev_history_t to an opaque node history object which
 * represents the previous (or "next oldest") interesting history
 * location for the filesystem node represented by @a history, or @c
 * NULL if no such previous history exists.  If @a cross_copies is @c
 * FALSE, also return @c NULL if stepping backwards in history to @a
 * prev_history_t would cross a filesystem copy operation.  
 *
 * NOTE: If this is the first call to svn_fs_history_prev() for the @a
 * history object, it could return a history object whose location is
 * the same as the original.  This will happen if the original
 * location was an interested one (where the node was modified, or
 * took place in a copy event).  This behavior allows looping callers
 * to avoid the calling svn_fs_history_location() on the object
 * returned by svn_fs_node_history(), and instead go ahead and begin
 * calling svn_fs_history_prev().
 *
 * NOTE: This function uses node-id ancestry alone to determine
 * modifiedness, and therefore does NOT claim that in any of the
 * returned revisions file contents changed, properties changed,
 * directory entries lists changed, etc.  
 *
 * ALSO NOTE: The revisions returned for @a path will be older than or
 * the same age as the revision of that path in @a root.  That is, if
 * @a root is a revision root based on revision X, and @a path was
 * modified in some revision(s) younger than X, those revisions
 * younger than X will not be included for @a path.  */
svn_error_t *svn_fs_history_prev (svn_fs_history_t **prev_history_p,
                                  svn_fs_history_t *history,
                                  svn_boolean_t cross_copies,
                                  apr_pool_t *pool);


/** Set @a *path and @a *revision to the path and revision,
 * respectively, of the @a history object.  Use @a pool for all
 * allocations. 
 */
svn_error_t *svn_fs_history_location (const char **path,
                                      svn_revnum_t *revision,
                                      svn_fs_history_t *history,
                                      apr_pool_t *pool);
                                      

/** Set @a *is_dir to @c TRUE iff @a path in @a root is a directory.
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *svn_fs_is_dir (svn_boolean_t *is_dir,
                            svn_fs_root_t *root,
                            const char *path,
                            apr_pool_t *pool);


/** Set @a *is_file to @c TRUE iff @a path in @a root is a file.
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *svn_fs_is_file (svn_boolean_t *is_file,
                             svn_fs_root_t *root,
                             const char *path,
                             apr_pool_t *pool);


/** Get the id of a node.
 *
 * Set @a *id_p to the node revision ID of @a path in @a root, allocated in 
 * @a pool.
 *
 * If @a root is the root of a transaction, keep in mind that other
 * changes to the transaction can change which node @a path refers to,
 * and even whether the path exists at all.
 */
svn_error_t *svn_fs_node_id (const svn_fs_id_t **id_p,
                             svn_fs_root_t *root,
                             const char *path,
                             apr_pool_t *pool);

/** Set @a *revision to the revision in which @a path under @a root was 
 * created.  Use @a pool for any temporary allocations.  @a *revision will 
 * be set to @c SVN_INVALID_REVNUM for uncommitted nodes (i.e. modified nodes 
 * under a transaction root).
 */
svn_error_t *svn_fs_node_created_rev (svn_revnum_t *revision,
                                      svn_fs_root_t *root,
                                      const char *path,
                                      apr_pool_t *pool);

/** Set @a *created_path to the path at which @a path under @a root was
 * created.  Use @a pool for all allocations.  Callers may use this
 * function in conjunction with svn_fs_node_created_rev() perform a
 * reverse lookup of the mapping of (path, revision) -> node-id that
 * svn_fs_node_id() performs.
 */
svn_error_t *svn_fs_node_created_path (const char **created_path,
                                       svn_fs_root_t *root,
                                       const char *path,
                                       apr_pool_t *pool);


/** Set @a *value_p to the value of the property named @a propname of 
 * @a path in @a root.  If the node has no property by that name, set 
 * @a *value_p to zero.  Allocate the result in @a pool.
 */
svn_error_t *svn_fs_node_prop (svn_string_t **value_p,
                               svn_fs_root_t *root,
                               const char *path,
                               const char *propname,
                               apr_pool_t *pool);
   

/** Set @a *table_p to the entire property list of @a path in @a root, 
 * 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_node_proplist (apr_hash_t **table_p,
                                   svn_fs_root_t *root,
                                   const char *path,
                                   apr_pool_t *pool);


/** Change a node's property's value, or add/delete a property.
 *
 * - @a root and @a path indicate the node whose property should change.
 *   @a root must be the root of a transaction, not the root of a revision.
 * - @a name is the name of the property to change.
 * - @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_node_prop (svn_fs_root_t *root,
                                      const char *path,
                                      const char *name,
                                      const svn_string_t *value,
                                      apr_pool_t *pool);


/** Determine if the properties of two path/root combinations are different.
 *
 * Set @a *changed_p to 1 if the properties at @a path1 under @a root1 differ
 * from those at @a path2 under @a root2, or set it to 0 if they are the
 * same.  Both paths must exist under their respective roots, and both
 * roots must be in the same filesystem.
 */
svn_error_t *svn_fs_props_changed (svn_boolean_t *changed_p,
                                   svn_fs_root_t *root1,
                                   const char *path1,
                                   svn_fs_root_t *root2,
                                   const char *path2,
                                   apr_pool_t *pool);


/** Discover a node's copy ancestry, if any.
 *
 * If the node at @a path in @a root was copied from some other node, set
 * @a *rev_p and @a *path_p to the revision and path of the other node,
 * allocating @a *path_p in @a pool.
 *
 * Else if there is no copy ancestry for the node, set @a *rev_p to
 * @c SVN_INVALID_REVNUM and @a *path_p to null.
 *
 * If an error is returned, the values of @a *rev_p and @a *path_p are
 * undefined, but otherwise, if one of them is set as described above,
 * you may assume the other is set correspondingly.
 *
 * @a root may be a revision root or a transaction root.
 *
 * Notes:
 *    - Copy ancestry does not descend.  After copying directory D to
 *      E, E will have copy ancestry referring to D, but E's children
 *      may not.  See also @c svn_fs_copy().
 *
 *    - Copy ancestry *under* a copy is preserved.  That is, if you
 *      copy /A/D/G/pi to /A/D/G/pi2, and then copy /A/D/G to /G, then
 *      /G/pi2 will still have copy ancestry pointing to /A/D/G/pi.
 *      We don't know if this is a feature or a bug yet; if it turns
 *      out to be a bug, then the fix is to make @c svn_fs_copied_from()
 *      observe the following logic, which currently callers may
 *      choose to follow themselves: if node X has copy history, but
 *      its ancestor A also has copy history, then you may ignore X's
 *      history if X's revision-of-origin is earlier than A's --
 *      because that would mean that X's copy history was preserved in
 *      a copy-under-a-copy scenario.  If X's revision-of-origin is
 *      the same as A's, then it was copied under A during the same
 *      transaction that created A.  (X's revision-of-origin cannot be
 *      greater than A's, if X has copy history.)  ### todo: See how
 *      people like this, it can always be hidden behind the curtain
 *      if necessary.
 *
 *    - Copy ancestry is not stored as a regular subversion property
 *      because it is not inherited.  Copying foo to bar results in a
 *      revision of bar with copy ancestry; but committing a text
 *      change to bar right after that results in a new revision of
 *      bar without copy ancestry.
 */
svn_error_t *svn_fs_copied_from (svn_revnum_t *rev_p,
                                 const char **path_p,
                                 svn_fs_root_t *root,
                                 const char *path,
                                 apr_pool_t *pool);


/** Merge changes between two nodes into a third node.
 *
 * Given nodes @a source and @a target, and a common ancestor @a ancestor,
 * modify @a target to contain all the changes made between @a ancestor and
 * @a source, as well as the changes made between @a ancestor and @a target.
 * @a target_root must be the root of a transaction, not a revision.
 *
 * @a source, @a target, and @a ancestor are generally directories; this
 * function recursively merges the directories' contents.  If they are
 * files, this function simply returns an error whenever @a source,
 * @a target, and @a ancestor are all distinct node revisions.
 *
 * If there are differences between @a ancestor and @a source that conflict
 * with changes between @a ancestor and @a target, this function returns an
 * @c SVN_ERR_FS_CONFLICT error.
 *
 * If the merge is successful, @a target is left in the merged state, and
 * the base root of @a target's txn is set to the root node of @a source.
 * If an error is returned (whether for conflict or otherwise), @a target
 * is left unaffected.
 *
 * If @a conflict_p is non-null, then: a conflict error sets @a *conflict_p
 * to the name of the node in @a target which couldn't be merged,
 * otherwise, success sets @a *conflict_p to null.
 *
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *svn_fs_merge (const char **conflict_p,
                           svn_fs_root_t *source_root,
                           const char *source_path,
                           svn_fs_root_t *target_root,
                           const char *target_path,
                           svn_fs_root_t *ancestor_root,
                           const char *ancestor_path,
                           apr_pool_t *pool);



/* Directories.  */


/** The type of a Subversion directory entry.  */
typedef struct svn_fs_dirent_t
{

  /** The name of this directory entry.  */
  const char *name;

  /** The node revision ID it names.  */
  const svn_fs_id_t *id;

  /** The node kind. */
  svn_node_kind_t kind;

} svn_fs_dirent_t;


/** Set @a *entries_p to a newly allocated APR hash table containing the
 * entries of the directory at @a path in @a root.  The keys of the table
 * are entry names, as byte strings, excluding the final null
 * character; the table's values are pointers to @c svn_fs_dirent_t
 * structures.  Allocate the table and its contents in @a pool.
 */
svn_error_t *svn_fs_dir_entries (apr_hash_t **entries_p,
                                 svn_fs_root_t *root,
                                 const char *path,
                                 apr_pool_t *pool);


/** Create a new directory named @a path in @a root.  The new directory has
 * no entries, and no properties.  @a root must be the root of a transaction, 
 * not a revision.
 *
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *svn_fs_make_dir (svn_fs_root_t *root,
                              const char *path,
                              apr_pool_t *pool);
                              

/** Delete the node named @a path in @a root.  If the node being deleted is
 * a directory, its contents will be deleted recursively.  @a root must be
 * the root of a transaction, not of a revision.  Use @a pool for
 * temporary allocation.
 *