[svnbook] r4315 committed - Document the new svn:auto-props property....
svnbook at googlecode.com
svnbook at googlecode.com
Tue Jan 15 21:26:54 CST 2013
Revision: 4315
Author: ptburba
Date: Tue Jan 15 19:26:38 2013
Log: Document the new svn:auto-props property.
* en/book/ch03-advanced-topics.xml
(svn.advanced.props.auto): Document the new property and add
some examples.
http://code.google.com/p/svnbook/source/detail?r=4315
Modified:
/trunk/en/book/ch03-advanced-topics.xml
=======================================
--- /trunk/en/book/ch03-advanced-topics.xml Tue Jan 15 16:26:34 2013
+++ /trunk/en/book/ch03-advanced-topics.xml Tue Jan 15 19:26:38 2013
@@ -1330,7 +1330,7 @@
obvious error (at least compared to, say, failing to
add a file to version control). To help your properties get
applied to the places that need them, Subversion provides a
- couple of simple but useful features.</para>
+ few simple but useful features.</para>
<para>Whenever you introduce a file to version control using the
<command>svn add</command> or <command>svn import</command>
@@ -1399,29 +1399,277 @@
that match <literal>*.cpp</literal> should have
<literal>svn:eol-style</literal> set to
<literal>native</literal>, and <literal>svn:keywords</literal>
- set to <literal>Id</literal>. Automatic property support is
- perhaps the handiest property-related tool in the Subversion
- toolbox. See <xref
- linkend="svn.advanced.confarea.opts.config"/> for more about
- configuring that support.</para>
+ set to <literal>Id</literal>. For more details on automatic
+ property support in the runtime configuration see <xref
+ linkend="svn.advanced.confarea.opts.config"/>.</para>
- <note>
- <para>Subversion administrators commonly ask if it is possible
- to configure, on the server side, a set of property
- definitions which all connecting clients will automatically
- consider when operating on working copies checked out from
- that server. Unfortunately, Subversion doesn't offer this
- feature. Administrators can use hook scripts to validate
- that the properties added to and modified on files and
- directories match the administrator's preferred policies,
- rejecting commits which are non-compliant in this fashion.
- (See <xref linkend="svn.reposadmin.create.hooks" /> for more
- about hook scripts.) But there's no way to automatically
- dictate those preferences to Subversion clients
- beforehand.</para>
- </note>
- </sect2>
+ <para>While automatic property support via the runtime
+ configuration system is certainly handy, Subversion
+ administrators might prefer a set of property definitions
+ which all connecting clients automatically consider when
+ operating on working copies checked out from a given server.
+ Subversion 1.8 and newer clients support such functionality
+ through the <literal>svn:auto-props</literal> inheritable
+ property.</para>
+
+ <para>The <literal>svn:auto-props</literal> property works like
+ the runtime configuration to automatically set properties on
+ files when they are added or imported. The value of the
+ <literal>svn:auto-props</literal> property is expected to be
+ the same as the <literal>auto-props</literal> runtime
+ configuration option (i.e. Any number of key-value pairs in
+ the format FILE_PATTERN = PROPNAME=VALUE[;PROPNAME=VALUE ...])
+ Like the <literal>auto-props</literal> runtime option, the
+ <literal>svn:auto-props</literal> property can be disregarded
+ when using the <option>--no-auto-props</option> option, but unlike
+ the config option, the <literal>svn:auto-props</literal> property
+ is <emphasis>not</emphasis> disabled when the
+ <literal>enable-auto-props</literal> configuration option is set
+ to <literal>no</literal>.
+ </para>
+
+ <para>For example, say you have checked out a working copy of your
+ <filename>trunk</filename> branch and need to add a new file
+ (let's assume that automatic properties in your runtime
+ configuration are disabled):</para>
+
+ <informalexample>
+ <screen>
+$ svn st
+? calc/data.c
+
+$ svn add calc/data.c
+A calc/data.c
+
+$ svn proplist -v calc/data.c
+Properties on 'calc/data.c':
+ svn:eol-style
+ native
+</screen>
+ </informalexample>
+
+ <para>Notice that after you place the unversioned file
+ <filename>data.c</filename> under version control the
+ <literal>svn:eol-style</literal> property was automatically set
+ on it. Since we assumed that the <literal>auto-props</literal>
+ runtime configuration option is disabled, we know
+ that the <literal>svn:auto-props</literal> property must be set
+ on some parent path of <filename>data.c</filename>. Using the
+ <command>svn propget</command> subcommand with the
+ <option>--show-inherited-props</option> option we see that this
+ is indeed the case:</para>
+
+ <informalexample>
+ <screen>
+$ svn propget svn:auto-props --show-inherited-props -v calc
+Inherited properties on 'calc',
+from 'http://localhost/svn/repositories/repos':
+ svn:auto-props
+ *.py = svn:eol-style=native
+ *.c = svn:eol-style=native
+ *.h = svn:eol-style=native
+</screen>
+ </informalexample>
+
+ <para>Unlike the <literal>svn:global-ignores</literal> property and
+ its analogous runtime configuration
+ <literal>global-ignores</literal>, which are combined, the
+ <literal>svn:auto-props</literal> property
+ <emphasis>overrides</emphasis> the <literal>auto-props</literal>
+ runtime configuration if it defines an auto-prop for the
+ <emphasis>same</emphasis> pattern as the runtime configuration.
+ Automatic properties inherited<footnote><para>Remember that users
+ can only inherit properties from paths for which they have read
+ access. So if an administrator sets
+ <literal>svn:auto-props</literal> on some high-level parent
+ path (e.g. the repository root), they need to be sure all users
+ have read access to that path or the desired automatic property
+ setting won't kick in.</para></footnote> from one path can also
+ override the <emphasis>identical</emphasis> pattern inherited from
+ a different path. The hierarchy of these overrides works as
+ follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>An auto-prop, for a given pattern, defined in
+ <literal>svn:auto-props</literal> overrides the same auto-prop
+ for the identical pattern in the <literal>auto-props</literal>
+ runtime configuration.</para>
+ </listitem>
+ <listitem>
+ <para>If an auto-prop, for a given pattern, is inherited from
+ more than one parents' <literal>svn:auto-props</literal>
+ property, the nearer path-wise parent overrides the more
+ distant parents.</para>
+ </listitem>
+ <listitem>
+ <para>An auto-prop, for a given pattern, defined in a
+ <literal>svn:auto-props</literal> property explicitly set on
+ a path overrides the same auto-prop(s) for the identical
+ pattern inherited from any parents.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Let's look at an example. Suppose you have this runtime
+ configuration:</para>
+
+ <informalexample>
+ <screen>
+[miscellany]
+enable-auto-props = yes
+[auto-props]
+*.py = svn:eol-style=CR
+*.c = svn:eol-style=CR
+*.h = svn:eol-style=CR
+*.cpp = svn:eol-style=CR
+</screen>
+ </informalexample>
+
+ <para>And you want to add three files in the
<filename>calc</filename>
+ directory of your working copy:</para>
+
+ <informalexample>
+ <screen>
+$ svn st
+? calc/data-binding.cpp
+? calc/data.c
+? calc/editor.py
+</screen>
+ </informalexample>
+
+ <para>Let's check what <literal>svn:auto-props</literal> apply to
+ <filename>calc</filename>:</para>
+
+ <informalexample>
+ <screen>
+$ svn propget svn:auto-props -v --show-inherited-props calc
+Inherited properties on 'calc',
+from 'http://localhost/svn/repositories/repos':
+ svn:auto-props
+ *.py = svn:eol-style=native
+ *.c = svn:eol-style=native
+ *.h = svn:eol-style=native
+
+Inherited properties on 'calc',
+from '.':
+ svn:auto-props
+ *.py = svn:eol-style=native
+ *.c = svn:keywords=Author Date Id Rev URL
+</screen>
+ </informalexample>
+
+ <para>When we add these three files what auto-props do we expect?
+ We add the trio to version control and then check:</para>
+
+ <informalexample>
+ <screen>
+$ svn add calc --force
+A calc/data-binding.cpp
+A calc/data.c
+A calc/editor.py
+</screen>
+ </informalexample>
+
+ <para>The file <filename>data-binding.cpp</filename> has only one
+ matching pattern, <literal>*.cpp = svn:eol-style=CR</literal>
+ in the runtime configuration, so obviously the
+ <literal>svn:eol-style</literal> property is set to
+ <literal>CR</literal>:</para>
+
+ <informalexample>
+ <screen>
+$ svn proplist -v calc/data-binding.cpp
+Properties on 'calc/data-binding.cpp':
+ svn:eol-style
+ CR
+</screen>
+ </informalexample>
+
+ <para>The file <filename>editor.py</filename> matches a single
+ pattern in runtime config and both of the
+ <literal>svn:auto-props</literal> properties, but by the hierarchy
+ described above, the property explicitly set on
+ <filename>calc</filename>,
+ <literal>*.py = svn:eol-style=native</literal>, takes precedence.
+ So the <literal>svn:eol-style</literal> property is set to
+ <literal>native:</literal>:</para>
+
+ <informalexample>
+ <screen>
+$ svn proplist -v calc/editor.py
+Properties on 'calc/editor.py':
+ svn:eol-style
+ native
+</screen>
+ </informalexample>
+
+ <para>The file <filename>data.c</filename> also matches patterns
+ in the runtime config and both of the inherited
+ <literal>svn:auto-props</literal> properties. The
+ <literal>svn:keywords</literal> auto-prop is only defined once,
+ on <filename>calc</filename>, so <filename>data.c</filename>
+ automatically gets that property. The
+ <literal>svn:auto-props</literal> on <filename>calc</filename>
+ don't define a <literal>svn:eol-style</literal> value however, so
+ the nearest inherited parent,
+ <literal>http://localhost/svn/repositories/repos</literal>,
+ provides that value:</para>
+
+ <informalexample>
+ <screen>
+$ svn proplist -v calc/data.c
+Properties on 'calc/data.c':
+ svn:eol-style
+ native
+ svn:keywords
+ Author Date Id Rev URL
+</screen>
+ </informalexample>
+
+ <warning>
+ <para>Overriding auto-props only applies for
+ <emphasis>identical</emphasis> patterns. If a file to be added
+ or imported matches more than one pattern, then there is no
+ guarantee which pattern's auto-props will be applied. For
+ example, say you want to add the file
+ <filename>foo.cpp</filename> in the directory
+ <filename>bar</filename>. Further, suppose the
+ <literal>svn:auto-props</literal> property is set on
+ <filename>bar</filename> with the value:</para>
+
+ <informalexample>
+ <screen>
+*.c* = svn:eol-style=native
+*.cpp = svn:eol-style=native;svn:keywords=Author Date Id Rev URL
+</screen>
+ </informalexample>
+
+ <para>Since <filename>foo.cpp</filename> matches both patterns,
+ there is no way to know if the <literal>svn:keywords</literal>
+ property will be set on <filename>foo.cpp</filename> when it
+ is added.</para>
+ </warning>
+
+ <para>A final note on <literal>svn:auto-props</literal>. This
+ property (along with the similar
+ <literal>svn:global-ignores</literal>, see
+ <xref linkend="svn.advanced.props.special.ignore"/>)
+ only provides a <emphasis>recommendation</emphasis> to clients
+ that understand the meaning of the property. Older clients will
+ ignore these properties, the <option>--no-auto-props</option>
+ option will disregard them, a user might manually change or remove
+ automatic properties after they have been set—there are
+ numerous ways in which the recommended properties contained in
+ <literal>svn:auto-props</literal> can be by-passed. Given this,
+ administrators will still need to use hook scripts to validate
+ that the properties added to and modified on files and directories
+ match the administrator's preferred policies, rejecting commits
+ which are non-compliant in this fashion.
+ (See <xref linkend="svn.reposadmin.create.hooks"/> for more
+ about hook scripts.)</para>
+
+ </sect2>
</sect1>
<!-- =================================================================
-->
More information about the svnbook-dev
mailing list