Subversion
Data Structures | Typedefs | Enumerations | Functions
Working copy status.
Working copy management

We have three functions for getting working copy status: one function for getting the status of exactly one thing, another for getting the statuses of (potentially) multiple things and a third for getting the working copy out-of-dateness with respect to the repository. More...

Data Structures

struct  svn_wc_status3_t
 Structure for holding the "status" of a working copy item. More...
struct  svn_wc_status2_t
 ### All diffs are not yet known. 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_status3_t svn_wc_status3_t
 Structure for holding the "status" of a working copy item.
typedef struct svn_wc_status2_t svn_wc_status2_t
 ### All diffs are not yet known.
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_func4_t )(void *baton, const char *local_abspath, const svn_wc_status3_t *status, apr_pool_t *scratch_pool)
 A callback for reporting a status about local_abspath.
typedef svn_error_t *(* svn_wc_status_func3_t )(void *baton, const char *path, svn_wc_status2_t *status, apr_pool_t *pool)
 Same as svn_wc_status_func4_t, but with a non-const status and a relative 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_status3_tsvn_wc_dup_status3 (const svn_wc_status3_t *orig_stat, apr_pool_t *pool)
 Return a deep copy of the orig_stat status structure, allocated in pool.
svn_wc_status2_tsvn_wc_dup_status2 (const svn_wc_status2_t *orig_stat, apr_pool_t *pool)
 Same as svn_wc_dup_status3(), but for older svn_wc_status_t structures.
svn_wc_status_tsvn_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_tsvn_wc_status3 (svn_wc_status3_t **status, svn_wc_context_t *wc_ctx, const char *local_abspath, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
 Fill *status for local_abspath, allocating in result_pool.
svn_error_tsvn_wc_status2 (svn_wc_status2_t **status, const char *path, svn_wc_adm_access_t *adm_access, apr_pool_t *pool)
 Similar to svn_wc_status3(), but with a adm_access baton and absolute path.
svn_error_tsvn_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_tsvn_wc_walk_status (svn_wc_context_t *wc_ctx, const char *local_abspath, svn_depth_t depth, svn_boolean_t get_all, svn_boolean_t no_ignore, svn_boolean_t ignore_text_mods, const apr_array_header_t *ignore_patterns, svn_wc_status_func4_t status_func, void *status_baton, svn_cancel_func_t cancel_func, void *cancel_baton, apr_pool_t *scratch_pool)
 Walk the working copy status of local_abspath using wc_ctx, by creating svn_wc_status3_t structures and sending these through status_func / status_baton.
svn_error_tsvn_wc_get_status_editor5 (const svn_delta_editor_t **editor, void **edit_baton, void **set_locks_baton, svn_revnum_t *edit_revision, svn_wc_context_t *wc_ctx, const char *anchor_abspath, const char *target_basename, svn_depth_t depth, svn_boolean_t get_all, svn_boolean_t no_ignore, svn_boolean_t depth_as_sticky, svn_boolean_t server_performs_filtering, const apr_array_header_t *ignore_patterns, svn_wc_status_func4_t status_func, void *status_baton, svn_cancel_func_t cancel_func, void *cancel_baton, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
 Set *editor and *edit_baton to an editor that generates svn_wc_status3_t structures and sends them through status_func / status_baton.
svn_error_tsvn_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)
 Same as svn_wc_get_status_editor5, but using svn_wc_status_func3_t instead of svn_wc_status_func4_t.
svn_error_tsvn_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, const 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_tsvn_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_tsvn_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_tsvn_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 three functions for getting working copy status: one function for getting the status of exactly one thing, another for getting the statuses of (potentially) multiple things and a third for getting the working copy out-of-dateness with respect to the repository.

Why do we have two different functions for getting working copy status? 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_status3() for depth-empty (just D itself), and svn_wc_walk_status() for depth-immediates and depth-infinity, since the latter two involve multiple return values. And for out-of-dateness information we have svn_wc_get_status_editor5().


Typedef Documentation

### All diffs are not yet known.

Same as svn_wc_status3_t, but without the svn_boolean_t 'versioned' field. Instead an item that is not versioned has the 'entry' field set to NULL.

Since:
New in 1.2.
Deprecated:
Provided for backward compatibility with the 1.6 API.

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

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.7.
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 3906 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)

Same as svn_wc_status_func4_t, but with a non-const status and a relative path.

Since:
New in 1.6.
Deprecated:
Provided for backward compatibility with the 1.6 API.

Definition at line 3894 of file svn_wc.h.

typedef svn_error_t*(* svn_wc_status_func4_t)(void *baton, const char *local_abspath, const svn_wc_status3_t *status, apr_pool_t *scratch_pool)

A callback for reporting a status about local_abspath.

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

scratch_pool will be cleared between invocations to the callback.

### we might be revamping the status infrastructure, and this callback ### could totally disappear by the end of 1.7 development. however, we ### need to mark the STATUS parameter as "const" so that it is easier ### to reason about who/what can modify those structures.

Since:
New in 1.7.

Definition at line 3882 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 3915 of file svn_wc.h.

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

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 (### unused)

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 3445 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 
)

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

Since:
New in 1.2
Deprecated:
Provided for backward compatibility with the 1.6 API.
svn_wc_status3_t* svn_wc_dup_status3 ( const svn_wc_status3_t orig_stat,
apr_pool_t *  pool 
)

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

Since:
New in 1.7.
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,
const 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.5 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 
)

Same as svn_wc_get_status_editor5, but using svn_wc_status_func3_t instead of svn_wc_status_func4_t.

And server_performs_filtering always set to TRUE.

This also uses a single pool parameter, stating that all temporary allocations are performed in manually constructed/destroyed subpool.

Since:
New in 1.6.
Deprecated:
Provided for backward compatibility with the 1.6 API.
svn_error_t* svn_wc_get_status_editor5 ( const svn_delta_editor_t **  editor,
void **  edit_baton,
void **  set_locks_baton,
svn_revnum_t edit_revision,
svn_wc_context_t wc_ctx,
const char *  anchor_abspath,
const char *  target_basename,
svn_depth_t  depth,
svn_boolean_t  get_all,
svn_boolean_t  no_ignore,
svn_boolean_t  depth_as_sticky,
svn_boolean_t  server_performs_filtering,
const apr_array_header_t *  ignore_patterns,
svn_wc_status_func4_t  status_func,
void *  status_baton,
svn_cancel_func_t  cancel_func,
void *  cancel_baton,
apr_pool_t *  result_pool,
apr_pool_t *  scratch_pool 
)

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

anchor_abspath is a working copy directory directory which will be used as the root of our editor. If target_basename is not "", it represents a node in the anchor_abspath which is the subject of the editor drive (otherwise, the anchor_abspath 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_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 canceled the operation.

If depth_as_sticky is set handle depth like when depth_is_sticky is passed for updating. This will show excluded nodes show up as added in the repository.

If server_performs_filtering is TRUE, assume that the server handles the ambient depth filtering, so this doesn't have to be handled in the editor.

Allocate the editor itself in result_pool, and use scratch_pool for temporary allocations. The editor will do its temporary allocations in a subpool of result_pool.

Since:
New in 1.7.
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 
)

Similar to svn_wc_status3(), but with a adm_access baton and absolute path.

Since:
New in 1.2.
Deprecated:
Provided for backward compatibility with the 1.6 API.
svn_error_t* svn_wc_status3 ( svn_wc_status3_t **  status,
svn_wc_context_t wc_ctx,
const char *  local_abspath,
apr_pool_t *  result_pool,
apr_pool_t *  scratch_pool 
)

Fill *status for local_abspath, allocating in result_pool.

Use scratch_pool for temporary allocations.

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:

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.7.
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.
svn_error_t* svn_wc_walk_status ( svn_wc_context_t wc_ctx,
const char *  local_abspath,
svn_depth_t  depth,
svn_boolean_t  get_all,
svn_boolean_t  no_ignore,
svn_boolean_t  ignore_text_mods,
const apr_array_header_t *  ignore_patterns,
svn_wc_status_func4_t  status_func,
void *  status_baton,
svn_cancel_func_t  cancel_func,
void *  cancel_baton,
apr_pool_t *  scratch_pool 
)

Walk the working copy status of local_abspath using wc_ctx, by creating svn_wc_status3_t structures and sending these through status_func / status_baton.

* 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 ignore_text_mods is TRUE, then the walk will not check for modified files. Any svn_wc_status3_t structures returned for files will always have a text_status field set to svn_wc_status_normal. If ignore_text_mods is FALSE, the walk checks for text changes and returns svn_wc_status3_t structures describing any changes.

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 walking to determine if the client has canceled the operation.

This function uses scratch_pool for temporary allocations.

Since:
New in 1.7.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines