# 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_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.
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.
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_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_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.
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_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_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.
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.
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.
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 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

typedef struct svn_wc_status2_t svn_wc_status2_t

### 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.

typedef struct svn_wc_status3_t svn_wc_status3_t

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.

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 (### 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_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 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:

- svn_wc_status_none : local_abspath is not versioned, and is not present on disk

- svn_wc_status_missing : local_abspath is versioned, but is missing from the working copy.

- svn_wc_status_unversioned : local_abspath 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.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_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 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