svn_props.h revision 251881
1255040Sgibbs/**
2255040Sgibbs * @copyright
3255040Sgibbs * ====================================================================
4255040Sgibbs *    Licensed to the Apache Software Foundation (ASF) under one
5255040Sgibbs *    or more contributor license agreements.  See the NOTICE file
6255040Sgibbs *    distributed with this work for additional information
7255040Sgibbs *    regarding copyright ownership.  The ASF licenses this file
8255040Sgibbs *    to you under the Apache License, Version 2.0 (the
9255040Sgibbs *    "License"); you may not use this file except in compliance
10255040Sgibbs *    with the License.  You may obtain a copy of the License at
11255040Sgibbs *
12255040Sgibbs *      http://www.apache.org/licenses/LICENSE-2.0
13255040Sgibbs *
14255040Sgibbs *    Unless required by applicable law or agreed to in writing,
15255040Sgibbs *    software distributed under the License is distributed on an
16255040Sgibbs *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17255040Sgibbs *    KIND, either express or implied.  See the License for the
18255040Sgibbs *    specific language governing permissions and limitations
19255040Sgibbs *    under the License.
20255040Sgibbs * ====================================================================
21255040Sgibbs * @endcopyright
22255040Sgibbs *
23255040Sgibbs * @file svn_props.h
24255040Sgibbs * @brief Subversion properties
25255040Sgibbs */
26255040Sgibbs
27255040Sgibbs/* ==================================================================== */
28255040Sgibbs
29255040Sgibbs#ifndef SVN_PROPS_H
30255040Sgibbs#define SVN_PROPS_H
31255040Sgibbs
32255040Sgibbs#include <apr_pools.h>   /* for apr_pool_t */
33255040Sgibbs#include <apr_tables.h>  /* for apr_array_header_t */
34255040Sgibbs#include <apr_hash.h>    /* for apr_hash_t */
35255040Sgibbs
36255040Sgibbs#include "svn_types.h"   /* for svn_boolean_t, svn_error_t */
37255040Sgibbs#include "svn_string.h"  /* for svn_string_t */
38255040Sgibbs
39255040Sgibbs#ifdef __cplusplus
40255040Sgibbsextern "C" {
41255040Sgibbs#endif /* __cplusplus */
42255040Sgibbs
43255040Sgibbs/**
44255040Sgibbs * @defgroup svn_props_support Properties management utilities
45255040Sgibbs * @{
46255040Sgibbs */
47255040Sgibbs
48255040Sgibbs
49255040Sgibbs
50255040Sgibbs/** A general in-memory representation of a single property.  Most of
51255040Sgibbs * the time, property lists will be stored completely in hashes.  But
52255040Sgibbs * sometimes it's useful to have an "ordered" collection of
53255040Sgibbs * properties, in which case we use an array of these structures.
54255040Sgibbs *
55255040Sgibbs * Also: sometimes we want a list that represents a set of property
56255040Sgibbs * *changes*, and in this case, an @c apr_hash_t won't work -- there's no
57255040Sgibbs * way to represent a property deletion, because we can't store a @c NULL
58255040Sgibbs * value in a hash.  So instead, we use these structures.
59255040Sgibbs */
60255040Sgibbstypedef struct svn_prop_t
61255040Sgibbs{
62255040Sgibbs  const char *name;           /**< Property name */
63255040Sgibbs  const svn_string_t *value;  /**< Property value */
64255040Sgibbs} svn_prop_t;
65255040Sgibbs
66255040Sgibbs
67255040Sgibbs/**
68255040Sgibbs * Return a duplicate of @a prop, allocated in @a pool. No part of the new
69255040Sgibbs * structure will be shared with @a prop.
70255040Sgibbs *
71255040Sgibbs * @since New in 1.3.
72255040Sgibbs */
73255040Sgibbssvn_prop_t *
74255040Sgibbssvn_prop_dup(const svn_prop_t *prop,
75255040Sgibbs             apr_pool_t *pool);
76255040Sgibbs
77255040Sgibbs
78255040Sgibbs/**
79255040Sgibbs * Duplicate an @a array of svn_prop_t items using @a pool.
80255040Sgibbs *
81255040Sgibbs * @since New in 1.3.
82255040Sgibbs */
83255040Sgibbsapr_array_header_t *
84255040Sgibbssvn_prop_array_dup(const apr_array_header_t *array,
85255040Sgibbs                   apr_pool_t *pool);
86255040Sgibbs
87255040Sgibbs
88255040Sgibbs/** A structure to represent inherited properties.
89255040Sgibbs *
90255040Sgibbs * @since New in 1.8.
91255040Sgibbs */
92255040Sgibbstypedef struct svn_prop_inherited_item_t
93255040Sgibbs{
94255040Sgibbs  /** The absolute working copy path, relative filesystem path, or URL
95255040Sgibbs   * from which the properties in @a prop_hash are inherited.  (For
96255040Sgibbs   * details about which path specification format is in use for a
97255040Sgibbs   * particular instance of this structure, consult the documentation
98255040Sgibbs   * for the API which produced it.) */
99255040Sgibbs  const char *path_or_url;
100255040Sgibbs
101255040Sgibbs  /** A hash of (<tt>const char *</tt>) inherited property names, and
102255040Sgibbs   * (<tt>svn_string_t *</tt>) property values. */
103255040Sgibbs  apr_hash_t *prop_hash;
104255040Sgibbs
105255040Sgibbs} svn_prop_inherited_item_t;
106255040Sgibbs
107255040Sgibbs
108255040Sgibbs/**
109255040Sgibbs * Given a hash (keys <tt>const char *</tt> and values <tt>const
110255040Sgibbs * svn_string_t</tt>) of properties, returns an array of svn_prop_t
111255040Sgibbs * items using @a pool.
112255040Sgibbs *
113255040Sgibbs * @since New in 1.5.
114255040Sgibbs */
115255040Sgibbsapr_array_header_t *
116255040Sgibbssvn_prop_hash_to_array(const apr_hash_t *hash,
117255040Sgibbs                       apr_pool_t *pool);
118255040Sgibbs
119255040Sgibbs/**
120255040Sgibbs * Given an array of svn_prop_t items, return a hash mapping const char *
121255040Sgibbs * property names to const svn_string_t * values.
122255040Sgibbs *
123255726Sgibbs * @warning The behaviour on #svn_prop_t objects with a @c NULL @c
124255040Sgibbs * svn_prop_t.value member is undefined.
125255040Sgibbs *
126255040Sgibbs * @since New in 1.7.
127255040Sgibbs */
128255040Sgibbsapr_hash_t *
129255040Sgibbssvn_prop_array_to_hash(const apr_array_header_t *properties,
130255040Sgibbs                       apr_pool_t *result);
131255040Sgibbs
132255040Sgibbs/**
133255040Sgibbs * Creates a deep copy of @a hash (keys <tt>const char *</tt> and
134255040Sgibbs * values <tt>const svn_string_t *</tt>) in @a pool.
135255040Sgibbs *
136255040Sgibbs * @since New in 1.6.
137255040Sgibbs */
138255040Sgibbsapr_hash_t *
139255040Sgibbssvn_prop_hash_dup(const apr_hash_t *hash,
140255040Sgibbs                  apr_pool_t *pool);
141255040Sgibbs
142255040Sgibbs/**
143255040Sgibbs * Return the value of property @a prop_name as it is in @a properties,
144255040Sgibbs * with values <tt>const svn_string_t</tt>. If @a prop_name is not
145255040Sgibbs * in @a properties or @a properties is NULL, return NULL.
146255040Sgibbs *
147255040Sgibbs * @since New in 1.7.
148255040Sgibbs */
149255040Sgibbsconst char *
150255040Sgibbssvn_prop_get_value(const apr_hash_t *properties,
151255040Sgibbs                   const char *prop_name);
152255040Sgibbs
153255040Sgibbs/**
154255040Sgibbs * Subversion distinguishes among several kinds of properties,
155255040Sgibbs * particularly on the client-side.  There is no "unknown" kind; if
156255040Sgibbs * there's nothing special about a property name, the default category
157255040Sgibbs * is @c svn_prop_regular_kind.
158255040Sgibbs */
159255040Sgibbstypedef enum svn_prop_kind
160255040Sgibbs{
161255040Sgibbs  /** In .svn/entries, i.e., author, date, etc. */
162255040Sgibbs  svn_prop_entry_kind,
163255040Sgibbs
164255040Sgibbs  /** Client-side only, stored by specific RA layer. */
165255040Sgibbs  svn_prop_wc_kind,
166255040Sgibbs
167255040Sgibbs  /** Seen if user does "svn proplist"; note that this includes some "svn:"
168255040Sgibbs   * props and all user props, i.e. ones stored in the repository fs.
169255040Sgibbs   */
170255040Sgibbs  svn_prop_regular_kind
171255040Sgibbs} svn_prop_kind_t;
172255040Sgibbs
173255040Sgibbs/** Return the property kind of a property named @a prop_name.
174255040Sgibbs *
175255040Sgibbs * @since New in 1.8.
176255040Sgibbs */
177255040Sgibbssvn_prop_kind_t
178255040Sgibbssvn_property_kind2(const char *prop_name);
179255040Sgibbs
180255040Sgibbs/** Return the prop kind of a property named @a prop_name, and
181255040Sgibbs * (if @a prefix_len is non-@c NULL) set @a *prefix_len to the length of
182255040Sgibbs * the prefix of @a prop_name that was sufficient to distinguish its kind.
183255040Sgibbs *
184255040Sgibbs * @deprecated Provided for backward compatibility with the 1.7 API.
185255040Sgibbs */
186255040SgibbsSVN_DEPRECATED
187255040Sgibbssvn_prop_kind_t
188255040Sgibbssvn_property_kind(int *prefix_len,
189255040Sgibbs                  const char *prop_name);
190255040Sgibbs
191255040Sgibbs
192255040Sgibbs/** Return @c TRUE iff @a prop_name represents the name of a Subversion
193255040Sgibbs * property.  That is, any property name in Subversion's name space for
194255040Sgibbs * versioned or unversioned properties, regardless whether the particular
195255040Sgibbs * property name is recognized.
196255040Sgibbs */
197255040Sgibbssvn_boolean_t
198255040Sgibbssvn_prop_is_svn_prop(const char *prop_name);
199255040Sgibbs
200255040Sgibbs
201255040Sgibbs/** Return @c TRUE iff @a props has at least one property whose name
202255040Sgibbs * represents the name of a Subversion property, in the sense of
203255040Sgibbs * svn_prop_is_svn_prop().
204255040Sgibbs *
205255040Sgibbs * @since New in 1.5.
206255040Sgibbs */
207255040Sgibbssvn_boolean_t
208255040Sgibbssvn_prop_has_svn_prop(const apr_hash_t *props,
209255040Sgibbs                      apr_pool_t *pool);
210255040Sgibbs
211255040Sgibbs/** Return @c TRUE iff @a prop_name is a Subversion property whose
212255040Sgibbs * value is interpreted as a boolean.
213255040Sgibbs *
214255040Sgibbs * @since New in 1.5.
215255040Sgibbs */
216255040Sgibbssvn_boolean_t
217255040Sgibbssvn_prop_is_boolean(const char *prop_name);
218255040Sgibbs
219255040Sgibbs/** Return @c TRUE iff @a prop_name is in the "svn:" name space and is a
220255040Sgibbs * known revision property ("svn:log" or "svn:date", e.g.).
221255040Sgibbs *
222255040Sgibbs * This will return @c FALSE for any property name that is not known by this
223255040Sgibbs * version of the library, even though the name may be known to other (for
224255040Sgibbs * example, later) Subversion software.
225255040Sgibbs *
226255040Sgibbs * @since New in 1.8.
227255040Sgibbs */
228255040Sgibbssvn_boolean_t
229255040Sgibbssvn_prop_is_known_svn_rev_prop(const char *prop_name);
230255040Sgibbs
231255040Sgibbs/** Return @c TRUE iff @a prop_name is in the "svn:" name space and is a
232255040Sgibbs * known versioned property that is allowed on a file and/or on a
233255040Sgibbs * directory ("svn:eol-style", "svn:ignore", or "svn:mergeinfo", e.g.).
234255040Sgibbs *
235255040Sgibbs * This will return @c FALSE for any property name that is not known
236255040Sgibbs * by this version of the library, even though the name may be known
237255040Sgibbs * to other (for example, later) Subversion software.
238255040Sgibbs *
239255040Sgibbs * @since New in 1.8.
240255040Sgibbs */
241255040Sgibbssvn_boolean_t
242255040Sgibbssvn_prop_is_known_svn_node_prop(const char *prop_name);
243255040Sgibbs
244255040Sgibbs/** Return @c TRUE iff @a prop_name is in the "svn:" name space and is
245255040Sgibbs * a known versioned property that is allowed on a file
246255040Sgibbs * ("svn:eol-style" or "svn:mergeinfo", e.g.).
247255040Sgibbs *
248255040Sgibbs * This will return @c FALSE for any property name that is not known
249255040Sgibbs * by this version of the library, even though the name may be known
250255040Sgibbs * to other (for example, later) Subversion software.
251255040Sgibbs *
252255040Sgibbs * @since New in 1.8.
253255040Sgibbs */
254255040Sgibbssvn_boolean_t
255255040Sgibbssvn_prop_is_known_svn_file_prop(const char *prop_name);
256255040Sgibbs
257255040Sgibbs/** Return @c TRUE iff @a prop_name is in the "svn:" name space and is
258255040Sgibbs * a known versioned property that is allowed on a directory
259255040Sgibbs * ("svn:ignore" or "svn:mergeinfo", e.g.).
260255040Sgibbs *
261255040Sgibbs * This will return @c FALSE for any property name that is not known
262255040Sgibbs * by this version of the library, even though the name may be known
263255040Sgibbs * to other (for example, later) Subversion software.
264255040Sgibbs *
265255040Sgibbs * @since New in 1.8.
266255040Sgibbs */
267255040Sgibbssvn_boolean_t
268255040Sgibbssvn_prop_is_known_svn_dir_prop(const char *prop_name);
269255040Sgibbs
270255040Sgibbs/** If @a prop_name requires that its value be stored as UTF8/LF in the
271255040Sgibbs * repository, then return @c TRUE.  Else return @c FALSE.  This is for
272255040Sgibbs * users of libsvn_client or libsvn_fs, since it their responsibility
273255040Sgibbs * to do this translation in both directions.  (See
274255040Sgibbs * svn_subst_translate_string()/svn_subst_detranslate_string() for
275255040Sgibbs * help with this task.)
276255040Sgibbs */
277255040Sgibbssvn_boolean_t
278255040Sgibbssvn_prop_needs_translation(const char *prop_name);
279255040Sgibbs
280255040Sgibbs
281255040Sgibbs/** Given a @a proplist array of @c svn_prop_t structures, allocate
282255040Sgibbs * three new arrays in @a pool.  Categorize each property and then
283255040Sgibbs * create new @c svn_prop_t structures in the proper lists.  Each new
284255040Sgibbs * @c svn_prop_t structure's fields will point to the same data within
285255040Sgibbs * @a proplist's structures.
286255040Sgibbs *
287255040Sgibbs * Callers may pass NULL for each of the property lists in which they
288255040Sgibbs * are uninterested.  If no props exist in a certain category, and the
289255040Sgibbs * property list argument for that category is non-NULL, then that
290255040Sgibbs * array will come back with <tt>->nelts == 0</tt>.
291255040Sgibbs */
292255040Sgibbssvn_error_t *
293255040Sgibbssvn_categorize_props(const apr_array_header_t *proplist,
294255040Sgibbs                     apr_array_header_t **entry_props,
295255040Sgibbs                     apr_array_header_t **wc_props,
296255040Sgibbs                     apr_array_header_t **regular_props,
297255040Sgibbs                     apr_pool_t *pool);
298255040Sgibbs
299255040Sgibbs
300255040Sgibbs/** Given two property hashes (<tt>const char *name</tt> -> <tt>const
301255040Sgibbs * svn_string_t *value</tt>), deduce the differences between them (from
302255040Sgibbs * @a source_props -> @c target_props).  Set @a propdiffs to a new array of
303255040Sgibbs * @c svn_prop_t structures, with one entry for each property that differs,
304255040Sgibbs * including properties that exist in @a source_props or @a target_props but
305255040Sgibbs * not both. The @c value field of each entry is that property's value from
306255040Sgibbs * @a target_props or NULL if that property only exists in @a source_props.
307255040Sgibbs *
308255040Sgibbs * Allocate the array from @a pool. Allocate the contents of the array from
309255040Sgibbs * @a pool or by reference to the storage of the input hashes or both.
310255040Sgibbs *
311255040Sgibbs * For note, here's a quick little table describing the logic of this
312255040Sgibbs * routine:
313255040Sgibbs *
314255040Sgibbs * @verbatim
315255040Sgibbs   source_props    target_props      event
316255040Sgibbs   ------------    ------------      -----
317255040Sgibbs   value = foo     value = NULL      Deletion occurred.
318255040Sgibbs   value = foo     value = bar       Set occurred (modification)
319255040Sgibbs   value = NULL    value = baz       Set occurred (creation) @endverbatim
320255040Sgibbs */
321255040Sgibbssvn_error_t *
322255040Sgibbssvn_prop_diffs(apr_array_header_t **propdiffs,
323255040Sgibbs               const apr_hash_t *target_props,
324255040Sgibbs               const apr_hash_t *source_props,
325255040Sgibbs               apr_pool_t *pool);
326255040Sgibbs
327255040Sgibbs
328255040Sgibbs/**
329255040Sgibbs * Return @c TRUE iff @a prop_name is a valid property name.
330255040Sgibbs *
331255040Sgibbs * For now, "valid" means the ASCII subset of an XML "Name".
332255040Sgibbs * XML "Name" is defined at http://www.w3.org/TR/REC-xml#sec-common-syn
333255040Sgibbs *
334255040Sgibbs * @since New in 1.5.
335255040Sgibbs */
336255040Sgibbssvn_boolean_t
337255726Sgibbssvn_prop_name_is_valid(const char *prop_name);
338255040Sgibbs
339255040Sgibbs
340255040Sgibbs
341255040Sgibbs/* Defines for reserved ("svn:") property names.  */
342255040Sgibbs
343255040Sgibbs/** All Subversion property names start with this. */
344255040Sgibbs#define SVN_PROP_PREFIX "svn:"
345255040Sgibbs
346255040Sgibbs
347255040Sgibbs/** Visible properties
348255040Sgibbs *
349255040Sgibbs * These are regular properties that are attached to ordinary files
350255040Sgibbs * and dirs, and are visible (and tweakable) by svn client programs
351255040Sgibbs * and users.  Adding these properties causes specific effects.
352255040Sgibbs *
353255040Sgibbs * @note the values of these properties are always UTF8-encoded with
354255040Sgibbs * LF line-endings.  It is the burden of svn library users to enforce
355255040Sgibbs * this.  Use svn_prop_needs_translation() to discover if a
356255040Sgibbs * certain property needs translation, and you can use
357255040Sgibbs * svn_subst_translate_string()/svn_subst_detranslate_string()
358255040Sgibbs * to do the translation.
359255040Sgibbs *
360255040Sgibbs * @defgroup svn_prop_visible_props Visible properties
361255040Sgibbs * @{
362255040Sgibbs */
363255040Sgibbs
364255040Sgibbs/** Properties whose values are interpreted as booleans (such as
365255040Sgibbs * svn:executable, svn:needs_lock, and svn:special) always fold their
366255040Sgibbs * value to this.
367255040Sgibbs *
368255040Sgibbs * @since New in 1.5.
369255040Sgibbs */
370255040Sgibbs#define SVN_PROP_BOOLEAN_TRUE "*"
371255040Sgibbs
372255040Sgibbs/** The mime-type of a given file. */
373255040Sgibbs#define SVN_PROP_MIME_TYPE  SVN_PROP_PREFIX "mime-type"
374255040Sgibbs
375255040Sgibbs/** The ignore patterns for a given directory. */
376255040Sgibbs#define SVN_PROP_IGNORE  SVN_PROP_PREFIX "ignore"
377255040Sgibbs
378255040Sgibbs/** The line ending style for a given file. */
379255040Sgibbs#define SVN_PROP_EOL_STYLE  SVN_PROP_PREFIX "eol-style"
380255040Sgibbs
381255040Sgibbs/** The "activated" keywords (for keyword substitution) for a given file. */
382255040Sgibbs#define SVN_PROP_KEYWORDS  SVN_PROP_PREFIX "keywords"
383255040Sgibbs
384255040Sgibbs/** Set to either TRUE or FALSE if we want a file to be executable or not. */
385255040Sgibbs#define SVN_PROP_EXECUTABLE  SVN_PROP_PREFIX "executable"
386255040Sgibbs
387255040Sgibbs/** The value to force the executable property to when set.
388255040Sgibbs *
389255040Sgibbs * @deprecated Provided for backward compatibility with the 1.4 API.
390255040Sgibbs * Use @c SVN_PROP_BOOLEAN_TRUE instead.
391255040Sgibbs */
392255040Sgibbs#define SVN_PROP_EXECUTABLE_VALUE SVN_PROP_BOOLEAN_TRUE
393255040Sgibbs
394255040Sgibbs/** Set to TRUE ('*') if we want a file to be set to read-only when
395255040Sgibbs * not locked.  FALSE is indicated by deleting the property. */
396255040Sgibbs#define SVN_PROP_NEEDS_LOCK  SVN_PROP_PREFIX "needs-lock"
397255040Sgibbs
398255040Sgibbs/** The value to force the needs-lock property to when set.
399255040Sgibbs *
400255040Sgibbs * @deprecated Provided for backward compatibility with the 1.4 API.
401255040Sgibbs * Use @c SVN_PROP_BOOLEAN_TRUE instead.
402255040Sgibbs */
403255040Sgibbs#define SVN_PROP_NEEDS_LOCK_VALUE SVN_PROP_BOOLEAN_TRUE
404255040Sgibbs
405255040Sgibbs/** Set if the file should be treated as a special file. */
406255040Sgibbs#define SVN_PROP_SPECIAL  SVN_PROP_PREFIX "special"
407255040Sgibbs
408255040Sgibbs/** The value to force the special property to when set.
409255040Sgibbs *
410255040Sgibbs * @deprecated Provided for backward compatibility with the 1.4 API.
411255726Sgibbs * Use @c SVN_PROP_BOOLEAN_TRUE instead.
412255040Sgibbs */
413255040Sgibbs#define SVN_PROP_SPECIAL_VALUE SVN_PROP_BOOLEAN_TRUE
414255040Sgibbs
415255040Sgibbs/** Describes external items to check out into this directory.
416255040Sgibbs *
417255040Sgibbs * The format is a series of lines, each in the following format:
418255040Sgibbs *   [-r REV] URL[@PEG] LOCALPATH
419255040Sgibbs * LOCALPATH is relative to the directory having this property.
420255040Sgibbs * REV pins the external to revision REV.
421255040Sgibbs * URL may be a full URL or a relative URL starting with one of:
422255040Sgibbs *   ../  to the parent directory of the extracted external
423255040Sgibbs *   ^/   to the repository root
424255040Sgibbs *   /    to the server root
425255040Sgibbs *   //   to the URL scheme
426255040Sgibbs * The following format is supported for interoperability with
427255040Sgibbs * Subversion 1.4 and earlier clients:
428255040Sgibbs *   LOCALPATH [-r PEG] URL
429255040Sgibbs * The ambiguous format 'relative_path relative_path' is taken as
430255040Sgibbs * 'relative_url relative_path' with peg revision support.
431255040Sgibbs * Lines starting with a '#' character are ignored.
432255040Sgibbs */
433255040Sgibbs#define SVN_PROP_EXTERNALS  SVN_PROP_PREFIX "externals"
434255040Sgibbs
435255040Sgibbs/** Merge info property used to record a resource's merge history.
436255040Sgibbs *
437255040Sgibbs * The format is a series of lines containing merge paths and revision
438255040Sgibbs * ranges, such as:
439255040Sgibbs *
440255040Sgibbs * @verbatim
441255040Sgibbs     /trunk: 1-6,9,37-38
442255040Sgibbs     /trunk/foo: 10 @endverbatim
443255040Sgibbs */
444255040Sgibbs#define SVN_PROP_MERGEINFO SVN_PROP_PREFIX "mergeinfo"
445255040Sgibbs
446255040Sgibbs/** Property used to record inheritable configuration auto-props. */
447255040Sgibbs#define SVN_PROP_INHERITABLE_AUTO_PROPS SVN_PROP_PREFIX "auto-props"
448255040Sgibbs
449255040Sgibbs/** Property used to record inheritable configuration ignores. */
450255040Sgibbs#define SVN_PROP_INHERITABLE_IGNORES SVN_PROP_PREFIX "global-ignores"
451255040Sgibbs
452255040Sgibbs/** Meta-data properties.
453255040Sgibbs *
454255040Sgibbs * The following properties are used for storing meta-data about
455255040Sgibbs * individual entries in the meta-data branches of subversion,
456255040Sgibbs * see issue #1256 or browseable at
457255040Sgibbs * http://svn.apache.org/viewvc/subversion/branches/meta-data-versioning/ .
458255040Sgibbs * Furthermore @c svntar (http://svn.borg.ch/svntar/) and @c FSVS
459255040Sgibbs * (http://fsvs.tigris.org/) use these, too.
460255040Sgibbs *
461255040Sgibbs * Please note that these formats are very UNIX-centric currently;
462255040Sgibbs * a bit of discussion about Windows can be read at
463255040Sgibbs * http://article.gmane.org/gmane.comp.version-control.subversion.devel/103991
464255040Sgibbs *
465255040Sgibbs * @defgroup svn_prop_meta_data Meta-data properties
466255040Sgibbs * @{ */
467255040Sgibbs
468255040Sgibbs/** The files' last modification time.
469255040Sgibbs * This is stored as string in the form @c "2008-08-07T07:38:51.008782Z", to
470255040Sgibbs * be converted by the functions @c svn_time_to_cstring() and
471255040Sgibbs * @c svn_time_from_cstring(). */
472255040Sgibbs#define SVN_PROP_TEXT_TIME  SVN_PROP_PREFIX "text-time"
473255040Sgibbs
474255040Sgibbs/** The files' owner.
475255040Sgibbs * Stored as numeric ID, optionally followed by whitespace and the string:
476255040Sgibbs * @c "1000 pmarek". Parsers @b should accept any number of whitespace,
477255040Sgibbs * and writers @b should put exactly a single space. */
478255040Sgibbs#define SVN_PROP_OWNER SVN_PROP_PREFIX "owner"
479255040Sgibbs
480255040Sgibbs/** The files' group.
481255040Sgibbs * The same format as for @c SVN_PROP_OWNER, the owner-property. */
482255040Sgibbs#define SVN_PROP_GROUP  SVN_PROP_PREFIX "group"
483255040Sgibbs
484255040Sgibbs/** The files' unix-mode.
485255040Sgibbs * Stored in octal, with a leading @c 0; may have 5 digits if any of @c setuid,
486255040Sgibbs * @c setgid or @c sticky are set; an example is @c "0644". */
487255040Sgibbs#define SVN_PROP_UNIX_MODE  SVN_PROP_PREFIX "unix-mode"
488255040Sgibbs
489255040Sgibbs/** @} */ /* Meta-data properties */
490255040Sgibbs
491255040Sgibbs/**
492255040Sgibbs * This is a list of all user-visible and -settable versioned node
493255040Sgibbs * properties.
494255040Sgibbs *
495255040Sgibbs * @since New in 1.8.
496255040Sgibbs */
497255040Sgibbs#define SVN_PROP_NODE_ALL_PROPS SVN_PROP_MIME_TYPE, \
498255040Sgibbs                                SVN_PROP_IGNORE, \
499255040Sgibbs                                SVN_PROP_EOL_STYLE, \
500255040Sgibbs                                SVN_PROP_KEYWORDS, \
501255040Sgibbs                                SVN_PROP_EXECUTABLE, \
502255040Sgibbs                                SVN_PROP_NEEDS_LOCK, \
503255040Sgibbs                                SVN_PROP_SPECIAL, \
504255040Sgibbs                                SVN_PROP_EXTERNALS, \
505255040Sgibbs                                SVN_PROP_MERGEINFO, \
506255040Sgibbs                                SVN_PROP_INHERITABLE_AUTO_PROPS, \
507255040Sgibbs                                SVN_PROP_INHERITABLE_IGNORES, \
508255040Sgibbs                                \
509255040Sgibbs                                SVN_PROP_TEXT_TIME, \
510255040Sgibbs                                SVN_PROP_OWNER, \
511255040Sgibbs                                SVN_PROP_GROUP, \
512255040Sgibbs                                SVN_PROP_UNIX_MODE,
513255040Sgibbs
514255040Sgibbs/** @} */
515255040Sgibbs
516255040Sgibbs/** WC props are props that are invisible to users:  they're generated
517255040Sgibbs * by an RA layer, and stored in secret parts of .svn/.
518255040Sgibbs *
519255040Sgibbs * @defgroup svn_prop_invisible_props Invisible properties
520255040Sgibbs * @{
521255040Sgibbs */
522255040Sgibbs
523255040Sgibbs/** The property name *prefix* that makes a property a "WC property".
524255040Sgibbs *
525255040Sgibbs * For example, WebDAV RA implementations might store a versioned-resource
526255040Sgibbs * url as a WC prop like this:
527255040Sgibbs *
528255040Sgibbs * <pre reason="Should use 'verbatim' instead, but Doxygen v1.6.1 & v1.7.1
529255040Sgibbs *              then doesn't recognize the #define; presumably a bug.">
530255040Sgibbs      name = svn:wc:dav_url
531255040Sgibbs      val  = http://www.example.com/repos/452348/e.289 </pre>
532255040Sgibbs *
533255040Sgibbs * The client will try to protect WC props by warning users against
534255040Sgibbs * changing them.  The client will also send them back to the RA layer
535255040Sgibbs * when committing.
536255040Sgibbs */
537255040Sgibbs#define SVN_PROP_WC_PREFIX     SVN_PROP_PREFIX "wc:"
538255040Sgibbs
539255040Sgibbs/** Another type of non-user-visible property.  "Entry properties" are
540255040Sgibbs * stored as fields with the administrative 'entries' file.
541255040Sgibbs */
542255040Sgibbs#define SVN_PROP_ENTRY_PREFIX  SVN_PROP_PREFIX "entry:"
543255040Sgibbs
544255040Sgibbs/** The revision this entry was last committed to on. */
545255040Sgibbs#define SVN_PROP_ENTRY_COMMITTED_REV     SVN_PROP_ENTRY_PREFIX "committed-rev"
546255040Sgibbs
547255040Sgibbs/** The date this entry was last committed to on. */
548255040Sgibbs#define SVN_PROP_ENTRY_COMMITTED_DATE    SVN_PROP_ENTRY_PREFIX "committed-date"
549255040Sgibbs
550255040Sgibbs/** The author who last committed to this entry. */
551255040Sgibbs#define SVN_PROP_ENTRY_LAST_AUTHOR       SVN_PROP_ENTRY_PREFIX "last-author"
552255040Sgibbs
553255040Sgibbs/** The UUID of this entry's repository. */
554255040Sgibbs#define SVN_PROP_ENTRY_UUID       SVN_PROP_ENTRY_PREFIX "uuid"
555255040Sgibbs
556255040Sgibbs/** The lock token for this entry.
557255040Sgibbs * @since New in 1.2. */
558255040Sgibbs#define SVN_PROP_ENTRY_LOCK_TOKEN SVN_PROP_ENTRY_PREFIX "lock-token"
559255040Sgibbs
560255040Sgibbs/** When custom, user-defined properties are passed over the wire, they will
561255040Sgibbs * have this prefix added to their name.
562255040Sgibbs */
563255040Sgibbs#define SVN_PROP_CUSTOM_PREFIX SVN_PROP_PREFIX "custom:"
564255040Sgibbs
565255040Sgibbs/** @} */
566255040Sgibbs
567255040Sgibbs/**
568255040Sgibbs * These are reserved properties attached to a "revision" object in
569255040Sgibbs * the repository filesystem.  They can be queried by using
570255040Sgibbs * svn_fs_revision_prop().
571255040Sgibbs *
572255040Sgibbs * @defgroup svn_props_revision_props Revision properties
573255040Sgibbs * @{
574255040Sgibbs */
575255726Sgibbs
576255726Sgibbs/** The fs revision property that stores a commit's author. */
577255726Sgibbs#define SVN_PROP_REVISION_AUTHOR  SVN_PROP_PREFIX "author"
578255040Sgibbs
579255040Sgibbs/** The fs revision property that stores a commit's log message. */
580255040Sgibbs#define SVN_PROP_REVISION_LOG  SVN_PROP_PREFIX "log"
581255040Sgibbs
582255040Sgibbs/** The fs revision property that stores a commit's date. */
583255040Sgibbs#define SVN_PROP_REVISION_DATE  SVN_PROP_PREFIX "date"
584255040Sgibbs
585255040Sgibbs/** The fs revision property that stores a commit's "original" date.
586255040Sgibbs *
587255040Sgibbs * The svn:date property must be monotonically increasing, along with
588255040Sgibbs * the revision number. In certain scenarios, this may pose a problem
589255040Sgibbs * when the revision represents a commit that occurred at a time which
590255040Sgibbs * does not fit within the sequencing required for svn:date. This can
591255040Sgibbs * happen, for instance, when the revision represents a commit to a
592255040Sgibbs * foreign version control system, or possibly when two Subversion
593255040Sgibbs * repositories are combined. This property can be used to record the
594255040Sgibbs * TRUE, original date of the commit.
595255040Sgibbs */
596255040Sgibbs#define SVN_PROP_REVISION_ORIG_DATE  SVN_PROP_PREFIX "original-date"
597255040Sgibbs
598255040Sgibbs/** The presence of this fs revision property indicates that the
599255040Sgibbs * revision was automatically generated by the mod_dav_svn
600255040Sgibbs * autoversioning feature.  The value is irrelevant.
601255040Sgibbs */
602255040Sgibbs#define SVN_PROP_REVISION_AUTOVERSIONED  SVN_PROP_PREFIX "autoversioned"
603255040Sgibbs
604255040Sgibbs
605255040Sgibbs/* More reserved revision props in the 'svn:' namespace, used by the
606255040Sgibbs   svnsync tool:   */
607255040Sgibbs
608255040Sgibbs/** Prefix for all svnsync custom properties.
609255726Sgibbs * @since New in 1.4.
610255726Sgibbs */
611255726Sgibbs#define SVNSYNC_PROP_PREFIX             SVN_PROP_PREFIX "sync-"
612255726Sgibbs
613255726Sgibbs/* The following revision properties are set on revision 0 of
614256073Sgibbs * destination repositories by svnsync:
615255726Sgibbs */
616256073Sgibbs
617255726Sgibbs/** Used to enforce mutually exclusive destination repository access.
618255726Sgibbs * @since New in 1.4.
619255726Sgibbs */
620255726Sgibbs#define SVNSYNC_PROP_LOCK               SVNSYNC_PROP_PREFIX "lock"
621255726Sgibbs
622255726Sgibbs/** Identifies the repository's source URL.
623255726Sgibbs * @since New in 1.4.
624255726Sgibbs */
625255726Sgibbs#define SVNSYNC_PROP_FROM_URL           SVNSYNC_PROP_PREFIX "from-url"
626255726Sgibbs/** Identifies the repository's source UUID.
627255726Sgibbs * @since New in 1.4.
628255726Sgibbs */
629255726Sgibbs#define SVNSYNC_PROP_FROM_UUID          SVNSYNC_PROP_PREFIX "from-uuid"
630255726Sgibbs
631255726Sgibbs/** Identifies the last completely mirrored revision.
632255726Sgibbs * @since New in 1.4.
633255726Sgibbs */
634255726Sgibbs#define SVNSYNC_PROP_LAST_MERGED_REV    SVNSYNC_PROP_PREFIX "last-merged-rev"
635255726Sgibbs
636255726Sgibbs/** Identifies the revision currently being copied.
637255726Sgibbs * @since New in 1.4.
638255726Sgibbs */
639255726Sgibbs#define SVNSYNC_PROP_CURRENTLY_COPYING  SVNSYNC_PROP_PREFIX "currently-copying"
640255726Sgibbs
641255726Sgibbs
642255726Sgibbs/**
643256073Sgibbs * This is a list of all revision properties.
644255726Sgibbs */
645255726Sgibbs#define SVN_PROP_REVISION_ALL_PROPS SVN_PROP_REVISION_AUTHOR, \
646256073Sgibbs                                    SVN_PROP_REVISION_LOG, \
647255726Sgibbs                                    SVN_PROP_REVISION_DATE, \
648255726Sgibbs                                    SVN_PROP_REVISION_AUTOVERSIONED, \
649255726Sgibbs                                    SVN_PROP_REVISION_ORIG_DATE, \
650255726Sgibbs                                    SVNSYNC_PROP_LOCK, \
651255726Sgibbs                                    SVNSYNC_PROP_FROM_URL, \
652255726Sgibbs                                    SVNSYNC_PROP_FROM_UUID, \
653255726Sgibbs                                    SVNSYNC_PROP_LAST_MERGED_REV, \
654255726Sgibbs                                    SVNSYNC_PROP_CURRENTLY_COPYING,
655255726Sgibbs
656255726Sgibbs/** @} */
657255726Sgibbs
658255726Sgibbs/**
659255726Sgibbs * These are reserved properties attached to a "transaction" object in
660255726Sgibbs * the repository filesystem in advance of the pre-commit hook script
661255726Sgibbs * running on the server, but then automatically removed from the
662255726Sgibbs * transaction before its promotion to a new revision.
663255726Sgibbs *
664255726Sgibbs * @defgroup svn_props_ephemeral_txnprops Ephemeral transaction properties
665255726Sgibbs * @{
666255726Sgibbs */
667255726Sgibbs
668255040Sgibbs/** The prefix used for all (ephemeral) transaction properties.
669255040Sgibbs *
670255040Sgibbs * @since New in 1.8.
671255040Sgibbs */
672255726Sgibbs#define SVN_PROP_TXN_PREFIX  SVN_PROP_PREFIX "txn-"
673255040Sgibbs
674255726Sgibbs/** Identifies the client version compability level.  For clients
675255726Sgibbs * compiled against Subversion libraries, this is @c SVN_VER_NUMBER.
676255726Sgibbs * Third-party implementations are advised to use similar formatting
677255726Sgibbs * for values of this property.
678255040Sgibbs *
679255726Sgibbs * @since New in 1.8.
680255726Sgibbs */
681255726Sgibbs#define SVN_PROP_TXN_CLIENT_COMPAT_VERSION \
682255726Sgibbs            SVN_PROP_TXN_PREFIX "client-compat-version"
683255726Sgibbs
684255726Sgibbs/** Identifies the client's user agent string, if any.
685255726Sgibbs *
686255726Sgibbs * @since New in 1.8.
687255726Sgibbs */
688255726Sgibbs#define SVN_PROP_TXN_USER_AGENT \
689255726Sgibbs            SVN_PROP_TXN_PREFIX "user-agent"
690255726Sgibbs
691255726Sgibbs/** The prefix reserved for copies of (ephemeral) transaction
692255726Sgibbs * properties designed to outlive the transaction.  Administrators may
693255726Sgibbs * choose to, in their pre-commit hook scripts, copy the values of one
694255726Sgibbs * or more properties named @c SVN_PROP_TXN_PREFIX + "something"
695255726Sgibbs * to new properties named @c SVN_PROP_REVISION_PREFIX + "something",
696255726Sgibbs * allowing that information to survive the commit-time removal of
697255726Sgibbs * ephemeral transaction properties.
698255726Sgibbs *
699255726Sgibbs * @since New in 1.8.
700255726Sgibbs */
701255726Sgibbs#define SVN_PROP_REVISION_PREFIX  SVN_PROP_PREFIX "revision-"
702255726Sgibbs
703255726Sgibbs
704255726Sgibbs/** @} */
705255726Sgibbs
706255726Sgibbs/** @} */
707255726Sgibbs
708255726Sgibbs
709255726Sgibbs
710255726Sgibbs#ifdef __cplusplus
711255726Sgibbs}
712255726Sgibbs#endif /* __cplusplus */
713255726Sgibbs
714255726Sgibbs#endif /* SVN_PROPS_H */
715255726Sgibbs