Working copy status.

We have two functions for getting working copy status: one function for getting the status of exactly one thing, and another for getting the statuses of (potentially) multiple things. More...

Data Structures
struct	svn_wc_status2_t
	Structure for holding the "status" of a working copy item. More...
struct	svn_wc_status_t
	Same as svn_wc_status2_t, but without the svn_lock_t 'repos_lock' field. More...
Typedefs
typedef struct svn_wc_status2_t	svn_wc_status2_t
	Structure for holding the "status" of a working copy item.
typedef struct svn_wc_status_t	svn_wc_status_t
	Same as svn_wc_status2_t, but without the svn_lock_t 'repos_lock' field.
typedef svn_error_t *(*	svn_wc_status_func3_t )(void *baton, const char *path, svn_wc_status2_t *status, apr_pool_t *pool)
	A callback for reporting a status about path.
typedef void(*	svn_wc_status_func2_t )(void *baton, const char *path, svn_wc_status2_t *status)
	Same as svn_wc_status_func3_t(), but without a provided pool or the ability to propagate errors.
typedef void(*	svn_wc_status_func_t )(void *baton, const char *path, svn_wc_status_t *status)
	Same as svn_wc_status_func2_t(), but for older svn_wc_status_t structures.
Enumerations
enum	svn_wc_status_kind {   svn_wc_status_none = 1,   svn_wc_status_unversioned,   svn_wc_status_normal,   svn_wc_status_added,   svn_wc_status_missing,   svn_wc_status_deleted,   svn_wc_status_replaced,   svn_wc_status_modified,   svn_wc_status_merged,   svn_wc_status_conflicted,   svn_wc_status_ignored,   svn_wc_status_obstructed,   svn_wc_status_external,   svn_wc_status_incomplete }
	The type of status for the working copy. More...
Functions
svn_wc_status2_t *	svn_wc_dup_status2 (const svn_wc_status2_t *orig_stat, apr_pool_t *pool)
	Return a deep copy of the orig_stat status structure, allocated in pool.
svn_wc_status_t *	svn_wc_dup_status (const svn_wc_status_t *orig_stat, apr_pool_t *pool)
	Same as svn_wc_dup_status2(), but for older svn_wc_status_t structures.
svn_error_t *	svn_wc_status2 (svn_wc_status2_t **status, const char *path, svn_wc_adm_access_t *adm_access, apr_pool_t *pool)
	Fill *status for path, allocating in pool.
svn_error_t *	svn_wc_status (svn_wc_status_t **status, const char *path, svn_wc_adm_access_t *adm_access, apr_pool_t *pool)
	Same as svn_wc_status2(), but for older svn_wc_status_t structures.
svn_error_t *	svn_wc_get_status_editor4 (const svn_delta_editor_t **editor, void **edit_baton, void **set_locks_baton, svn_revnum_t *edit_revision, svn_wc_adm_access_t *anchor, const char *target, svn_depth_t depth, svn_boolean_t get_all, svn_boolean_t no_ignore, const apr_array_header_t *ignore_patterns, svn_wc_status_func3_t status_func, void *status_baton, svn_cancel_func_t cancel_func, void *cancel_baton, svn_wc_traversal_info_t *traversal_info, apr_pool_t *pool)
	Set *editor and *edit_baton to an editor that generates svn_wc_status2_t structures and sends them through status_func / status_baton.
svn_error_t *	svn_wc_get_status_editor3 (const svn_delta_editor_t **editor, void **edit_baton, void **set_locks_baton, svn_revnum_t *edit_revision, svn_wc_adm_access_t *anchor, const char *target, svn_depth_t depth, svn_boolean_t get_all, svn_boolean_t no_ignore, apr_array_header_t *ignore_patterns, svn_wc_status_func2_t status_func, void *status_baton, svn_cancel_func_t cancel_func, void *cancel_baton, svn_wc_traversal_info_t *traversal_info, apr_pool_t *pool)
	Same as svn_wc_get_status_editor4(), but using svn_wc_status_func2_t instead of svn_wc_status_func3_t.
svn_error_t *	svn_wc_get_status_editor2 (const svn_delta_editor_t **editor, void **edit_baton, void **set_locks_baton, svn_revnum_t *edit_revision, svn_wc_adm_access_t *anchor, const char *target, apr_hash_t *config, svn_boolean_t recurse, svn_boolean_t get_all, svn_boolean_t no_ignore, svn_wc_status_func2_t status_func, void *status_baton, svn_cancel_func_t cancel_func, void *cancel_baton, svn_wc_traversal_info_t *traversal_info, apr_pool_t *pool)
	Like svn_wc_get_status_editor3(), but with ignore_patterns provided from the corresponding value in config, and recurse instead of depth.
svn_error_t *	svn_wc_get_status_editor (const svn_delta_editor_t **editor, void **edit_baton, svn_revnum_t *edit_revision, svn_wc_adm_access_t *anchor, const char *target, apr_hash_t *config, svn_boolean_t recurse, svn_boolean_t get_all, svn_boolean_t no_ignore, svn_wc_status_func_t status_func, void *status_baton, svn_cancel_func_t cancel_func, void *cancel_baton, svn_wc_traversal_info_t *traversal_info, apr_pool_t *pool)
	Same as svn_wc_get_status_editor2(), but with set_locks_baton set to NULL, and taking a deprecated svn_wc_status_func_t argument.
svn_error_t *	svn_wc_status_set_repos_locks (void *set_locks_baton, apr_hash_t *locks, const char *repos_root, apr_pool_t *pool)
	Associate locks, a hash table mapping const char* absolute repository paths to svn_lock_t objects, with a set_locks_baton returned by an earlier call to svn_wc_get_status_editor3().

---

Detailed Description

We have two functions for getting working copy status: one function for getting the status of exactly one thing, and another for getting the statuses of (potentially) multiple things.

The concept of depth, as explained in the documentation for svn_depth_t, may be useful in understanding this. Suppose we're getting the status of directory D:

To offer all three levels, we could have one unified function, taking a `depth' parameter. Unfortunately, because this function would have to handle multiple return values as well as the single return value case, getting the status of just one entity would become cumbersome: you'd have to roll through a hash to find one lone status.

So we have svn_wc_status() for depth-empty (just D itself), and svn_wc_get_status_editor() for depth-immediates and depth-infinity, since the latter two involve multiple return values.

Note:

The status structures may contain a NULL ->entry field. This indicates an item that is not versioned in the working copy.

---

Typedef Documentation

typedef struct svn_wc_status2_t svn_wc_status2_t

Structure for holding the "status" of a working copy item.

The item's entry data is in entry, augmented and possibly shadowed by the other fields. entry is NULL if this item is not under version control.

Note:

Fields may be added to the end of this structure in future versions. Therefore, to preserve binary compatibility, users should not directly allocate structures of this type.

Since:

New in 1.2.

typedef void(* svn_wc_status_func2_t)(void *baton, const char *path, svn_wc_status2_t *status)

Same as svn_wc_status_func3_t(), but without a provided pool or the ability to propagate errors.

Since:

New in 1.2.

Deprecated:

Provided for backward compatibility with the 1.5 API.

Definition at line 2956 of file svn_wc.h.

typedef svn_error_t*(* svn_wc_status_func3_t)(void *baton, const char *path, svn_wc_status2_t *status, apr_pool_t *pool)

A callback for reporting a status about path.

baton is a closure object; it should be provided by the implementation, and passed by the caller.

pool will be cleared between invocations to the callback.

Since:

New in 1.6.

Definition at line 2944 of file svn_wc.h.

typedef void(* svn_wc_status_func_t)(void *baton, const char *path, svn_wc_status_t *status)

Same as svn_wc_status_func2_t(), but for older svn_wc_status_t structures.

Deprecated:

Provided for backward compatibility with the 1.1 API.

Definition at line 2965 of file svn_wc.h.

typedef struct svn_wc_status_t svn_wc_status_t

Same as svn_wc_status2_t, but without the svn_lock_t 'repos_lock' field.

Deprecated:

Provided for backward compatibility with the 1.1 API.

---

Enumeration Type Documentation

enum svn_wc_status_kind

The type of status for the working copy.

Enumerator:

svn_wc_status_none	does not exist
svn_wc_status_unversioned	is not a versioned thing in this wc
svn_wc_status_normal	exists, but uninteresting
svn_wc_status_added	is scheduled for addition
svn_wc_status_missing	under v.c., but is missing
svn_wc_status_deleted	scheduled for deletion
svn_wc_status_replaced	was deleted and then re-added
svn_wc_status_modified	text or props have been modified
svn_wc_status_merged	local mods received repos mods
svn_wc_status_conflicted	local mods received conflicting repos mods
svn_wc_status_ignored	is unversioned but configured to be ignored
svn_wc_status_obstructed	an unversioned resource is in the way of the versioned resource
svn_wc_status_external	an unversioned directory path populated by an svn:externals property; this status is not used for file externals
svn_wc_status_incomplete	a directory doesn't contain a complete entries list

Definition at line 2655 of file svn_wc.h.

---

Function Documentation

svn_wc_status_t* svn_wc_dup_status	(	const svn_wc_status_t *	orig_stat,
		apr_pool_t *	pool
	)

Same as svn_wc_dup_status2(), but for older svn_wc_status_t structures.

Deprecated:

Provided for backward compatibility with the 1.1 API.

svn_wc_status2_t* svn_wc_dup_status2	(	const svn_wc_status2_t *	orig_stat,
		apr_pool_t *	pool
	)

Return a deep copy of the orig_stat status structure, allocated in pool.

Since:

New in 1.2.

svn_error_t* svn_wc_get_status_editor	(	const svn_delta_editor_t **	editor,
		void **	edit_baton,
		svn_revnum_t *	edit_revision,
		svn_wc_adm_access_t *	anchor,
		const char *	target,
		apr_hash_t *	config,
		svn_boolean_t	recurse,
		svn_boolean_t	get_all,
		svn_boolean_t	no_ignore,
		svn_wc_status_func_t	status_func,
		void *	status_baton,
		svn_cancel_func_t	cancel_func,
		void *	cancel_baton,
		svn_wc_traversal_info_t *	traversal_info,
		apr_pool_t *	pool
	)

Same as svn_wc_get_status_editor2(), but with set_locks_baton set to NULL, and taking a deprecated svn_wc_status_func_t argument.

Deprecated:

Provided for backward compatibility with the 1.1 API.

svn_error_t* svn_wc_get_status_editor2	(	const svn_delta_editor_t **	editor,
		void **	edit_baton,
		void **	set_locks_baton,
		svn_revnum_t *	edit_revision,
		svn_wc_adm_access_t *	anchor,
		const char *	target,
		apr_hash_t *	config,
		svn_boolean_t	recurse,
		svn_boolean_t	get_all,
		svn_boolean_t	no_ignore,
		svn_wc_status_func2_t	status_func,
		void *	status_baton,
		svn_cancel_func_t	cancel_func,
		void *	cancel_baton,
		svn_wc_traversal_info_t *	traversal_info,
		apr_pool_t *	pool
	)

Like svn_wc_get_status_editor3(), but with ignore_patterns provided from the corresponding value in config, and recurse instead of depth.

If recurse is TRUE, behave as if for svn_depth_infinity; else if recurse is FALSE, behave as if for svn_depth_immediates.

Since:

New in 1.2.

Deprecated:

Provided for backward compatibility with the 1.4 API.

svn_error_t* svn_wc_get_status_editor3	(	const svn_delta_editor_t **	editor,
		void **	edit_baton,
		void **	set_locks_baton,
		svn_revnum_t *	edit_revision,
		svn_wc_adm_access_t *	anchor,
		const char *	target,
		svn_depth_t	depth,
		svn_boolean_t	get_all,
		svn_boolean_t	no_ignore,
		apr_array_header_t *	ignore_patterns,
		svn_wc_status_func2_t	status_func,
		void *	status_baton,
		svn_cancel_func_t	cancel_func,
		void *	cancel_baton,
		svn_wc_traversal_info_t *	traversal_info,
		apr_pool_t *	pool
	)

Same as svn_wc_get_status_editor4(), but using svn_wc_status_func2_t instead of svn_wc_status_func3_t.

Since:

New in 1.5.

Deprecated:

Provided for backward compatibility with the 1.4 API.

svn_error_t* svn_wc_get_status_editor4	(	const svn_delta_editor_t **	editor,
		void **	edit_baton,
		void **	set_locks_baton,
		svn_revnum_t *	edit_revision,
		svn_wc_adm_access_t *	anchor,
		const char *	target,
		svn_depth_t	depth,
		svn_boolean_t	get_all,
		svn_boolean_t	no_ignore,
		const apr_array_header_t *	ignore_patterns,
		svn_wc_status_func3_t	status_func,
		void *	status_baton,
		svn_cancel_func_t	cancel_func,
		void *	cancel_baton,
		svn_wc_traversal_info_t *	traversal_info,
		apr_pool_t *	pool
	)

Set *editor and *edit_baton to an editor that generates svn_wc_status2_t structures and sends them through status_func / status_baton.

anchor is an access baton, with a tree lock, for the local path to the working copy which will be used as the root of our editor. If target is not empty, it represents an entry in the anchor path which is the subject of the editor drive (otherwise, the anchor is the subject).

If set_locks_baton is non-NULL, it will be set to a baton that can be used in a call to the svn_wc_status_set_repos_locks() function.

Callers drive this editor to describe working copy out-of-dateness with respect to the repository. If this information is not available or not desired, callers should simply call the close_edit() function of the editor vtable.

If the editor driver calls editor's set_target_revision() vtable function, then when the edit drive is completed, *edit_revision will contain the revision delivered via that interface.

Assuming the target is a directory, then:

• If get_all is FALSE, then only locally-modified entries will be returned. If TRUE, then all entries will be returned.

• If depth is svn_depth_empty, a status structure will be returned for the target only; if svn_depth_files, for the target and its immediate file children; if svn_depth_immediates, for the target and its immediate children; if svn_depth_infinity, for the target and everything underneath it, fully recursively.

If depth is svn_depth_unknown, take depths from the working copy and behave as above in each directory's case.

If the given depth is incompatible with the depth found in a working copy directory, the found depth always governs.

If no_ignore is set, statuses that would typically be ignored will instead be reported.

ignore_patterns is an array of file patterns matching unversioned files to ignore for the purposes of status reporting, or NULL if the default set of ignorable file patterns should be used.

If cancel_func is non-NULL, call it with cancel_baton while building the statushash to determine if the client has cancelled the operation.

If traversal_info is non-NULL, then record pre-update traversal state in it. (Caller should obtain traversal_info from svn_wc_init_traversal_info().)

Allocate the editor itself in pool, but the editor does temporary allocations in a subpool of pool.

Since:

New in 1.6.

svn_error_t* svn_wc_status	(	svn_wc_status_t **	status,
		const char *	path,
		svn_wc_adm_access_t *	adm_access,
		apr_pool_t *	pool
	)

Same as svn_wc_status2(), but for older svn_wc_status_t structures.

Deprecated:

Provided for backward compatibility with the 1.1 API.

svn_error_t* svn_wc_status2	(	svn_wc_status2_t **	status,
		const char *	path,
		svn_wc_adm_access_t *	adm_access,
		apr_pool_t *	pool
	)

Fill *status for path, allocating in pool.

adm_access must be an access baton for path.

Here are some things to note about the returned structure. A quick examination of the status->text_status after a successful return of this function can reveal the following things:

• svn_wc_status_none : path is not versioned, and is either not present on disk, or is ignored by svn's default ignore regular expressions or the svn:ignore property setting for path's parent directory.

• svn_wc_status_missing : path is versioned, but is missing from the working copy.

• svn_wc_status_unversioned : path is not versioned, but is present on disk and not being ignored (see above).

The other available results for the text_status field are more straightforward in their meanings. See the comments on the svn_wc_status_kind structure for some hints.

Since:

New in 1.2.

svn_error_t* svn_wc_status_set_repos_locks	(	void *	set_locks_baton,
		apr_hash_t *	locks,
		const char *	repos_root,
		apr_pool_t *	pool
	)

Associate locks, a hash table mapping const char* absolute repository paths to svn_lock_t objects, with a set_locks_baton returned by an earlier call to svn_wc_get_status_editor3().

repos_root is the repository root URL. Perform all allocations in pool.

Note:

locks will not be copied, so it must be valid throughout the edit. pool must also not be destroyed or cleared before the edit is finished.

Since:

New in 1.2.