[svnbook] r4313 committed - Document the new svn:global-ignores property....
svnbook at googlecode.com
svnbook at googlecode.com
Mon Jan 14 12:26:33 CST 2013
Revision: 4313
Author: ptburba
Date: Mon Jan 14 10:25:22 2013
Log: Document the new svn:global-ignores property.
* en/book/ch03-advanced-topics.xml
(svn.advanced.props.inheritable): New section stub.
(svn.advanced.props.special.ignore): Add explanation and
example of svn:global-ignores property.
http://code.google.com/p/svnbook/source/detail?r=4313
Modified:
/trunk/en/book/ch03-advanced-topics.xml
=======================================
--- /trunk/en/book/ch03-advanced-topics.xml Thu Sep 6 17:42:53 2012
+++ /trunk/en/book/ch03-advanced-topics.xml Mon Jan 14 10:25:22 2013
@@ -1303,6 +1303,16 @@
/>.</para>
</note>
+ </sect2>
+
+ <!-- ===============================================================
-->
+ <sect2 id="svn.advanced.props.inheritable">
+ <title>Inheritable Properties</title>
+
+ <para>TODO: Document Inheritable Properties -- This is a temporary
+ stub so other sections referencing this new topic have somewhere
+ to point. </para>
+
</sect2>
<!-- ===============================================================
-->
@@ -1755,17 +1765,17 @@
directories—its output can get quite noisy where many of
these things exist.</para>
- <para>So Subversion provides two ways for telling it which files
+ <para>So Subversion provides several ways for telling it which files
you would prefer that it simply disregard. One of the ways
involves the use of Subversion's runtime configuration system
(see <xref linkend="svn.advanced.confarea" />), and therefore
applies to all the Subversion operations that make use of that
runtime configuration—generally those performed on a particular
- computer or by a particular user of a computer. The other way
- makes use of Subversion's directory property support and is more
+ computer or by a particular user of a computer. Two other methods
+ make use of Subversion's directory property support and are more
tightly bound to the versioned tree itself, and therefore
- affects everyone who has a working copy of that tree. Both of
- the mechanisms use <firstterm>file patterns</firstterm> (strings
+ affects everyone who has a working copy of that tree. All of
+ these mechanisms use <firstterm>file patterns</firstterm> (strings
of literal and special wildcard characters used to match against
filenames) to decide which files to ignore.</para>
@@ -1868,7 +1878,8 @@
<para>When found on a versioned directory, the
<literal>svn:ignore</literal> property is expected to contain a
list of newline-delimited file patterns that Subversion should
- use to determine ignorable objects in that same directory.
+ use to determine ignorable objects in that
+ <emphasis>same</emphasis> directory.
These patterns do not override those found in the
<literal>global-ignores</literal> runtime configuration option,
but are instead appended to that list. And it's worth noting
@@ -1884,6 +1895,30 @@
result of a conversion of some source DocBook XML files to a
more legible output format.</para>
+ <para>Subversion 1.8 provides a more powerful version of the
+ <literal>svn:ignore</literal> property, the
+ <literal>svn:global-ignores</literal> property. Like the
+ <literal>svn:ignore</literal> property,
+ <literal>svn:global-ignores</literal> can only be set
+ on a directory and contains file patterns Subversion uses to
+ determine ignorable objects.<footnote><para>The ignore patterns
+ in the <literal>svn:global-ignores</literal> property may be
+ delimited with any whitespace (similar to the
+ <literal>global-ignores</literal> runtime configuration option),
+ not just newlines (as with the <literal>svn:ignore</literal>
+ property).</para></footnote> These ignore patterns are also
+ appended to any patterns defined in the
+ <literal>global-ignores</literal> runtime configuration option
+ together with any <literal>svn:ignore</literal> defined patterns.
+ Unlike <literal>svn:ignore</literal> however, the
+ <literal>svn:global-ignores</literal> property is inheritable
+ <footnote><para>Of course only a 1.8 or newer Subversion client
+ will recognize the inheritability and special meaning of the
+ <literal>svn:global-ignores</literal> property!</para></footnote>
+ and applies to <emphasis>all</emphasis> paths under the directory on
+ which the property is set, not just the immediate children of the
+ directory.</para>
+
<note>
<para>Subversion's support for ignorable file patterns extends
only to the one-time process of adding unversioned
@@ -1925,11 +1960,19 @@
</sidebar>
- <para>The global list of ignore patterns tends to be more a
- matter of personal taste and ties more closely to a user's
- particular tool chain than to the details of any particular
- working copy's needs. So, the rest of this section will focus
- on the <literal>svn:ignore</literal> property and its
+ <para>The ignore patterns in the <literal>global-ignores</literal>
+ runtime configuration option tend to be more a
+ matter of personal taste<footnote><para>Despite being a matter
+ of personal taste, if you don't explicitly set the
+ <literal>global-ignores</literal> runtime configuration,
+ Subversion uses a default value. See the
+ <literal>global-ignores</literal> entry in
+ <xref linkend="svn.advanced.confarea.opts.config"/></para>
+ </footnote> and ties more closely to a user's particular tool
+ chain than to the details of any particular working copy's needs.
+ So, the rest of this section will focus
+ on the <literal>svn:ignore</literal> and
+ <literal>svn:global-ignores</literal> properies and their
uses.</para>
<para>Say you have the following output from <command>svn
@@ -2016,8 +2059,37 @@
I calc/debug_log.1
I calc/debug_log.2.gz
I calc/debug_log.3.gz
+I calc/wip.1.diff
</screen>
</informalexample>
+
+ <para>All of your previously hidden unversioned paths are once
+ again shown, but now with the <literal>'I' Ignored</literal>
+ status. But wait, what about <filename>wip.1.diff</filename>?
+ The <literal>svn:ignore</literal> property on
+ <filename>calc</filename> doesn't include any pattern that
+ matches that filename, so why is it ignored?<footnote><para>
+ Let's assume that you don't have a matching pattern anywhere
+ in your <literal>global-ignores</literal> runtime configuration.
+ </para></footnote> The answer lies in the third method by which
+ Subversion can disregard unversioned paths, the inheritable
+ <literal>svn:global-ignores</literal> property. Using the
+ <command>svn propget</command> subcommand with the
+ <option>--show-inherited-props</option> option, you see that
+ the <literal>svn:global-ignores</literal> property is set on the
+ root of your working copy, and sure enough, it defines a
+ matching ignore pattern:</para>
+
+ <informalexample>
+ <screen>
+$ svn pg svn:global-ignores calc -v --show-inherited-props
+Inherited properties on 'calc',
+from '.':
+ svn:global-ignores
+ *.diff
+ *.patch
+</screen>
+ </informalexample>
<para>As mentioned earlier, the list of file patterns to ignore is
also used by <command>svn add</command> and <command>svn
@@ -2025,7 +2097,7 @@
Subversion to begin managing some set of files and directories.
Rather than force the user to pick and choose which files in a
tree she wishes to start versioning, Subversion uses the ignore
- patterns—both the global and the per-directory
+ patterns—the global, per-directory, and inherited
lists—to determine which files should not be swept into
the version control system as part of a larger recursive
addition or import operation. And here again, you can use the
@@ -2034,7 +2106,8 @@
present.</para>
<tip>
- <para>Even if <literal>svn:ignore</literal> is set, you may run
+ <para>Even if <literal>svn:ignore</literal> or
+ <literal>svn:global-ignores</literal> is set, you may run
into problems if you use shell wildcards in a command. Shell
wildcards are expanded into an explicit list of targets before
Subversion operates on them, so running <userinput>svn
@@ -2050,7 +2123,8 @@
version control, and the <option>--force</option> option will
cause Subversion to crawl through that directory, adding
unversioned files while still honoring the
- <literal>svn:ignore</literal> property and
+ <literal>svn:ignore</literal> and
+ <literal>svn:global-ignores</literal> properties and the
<literal>global-ignores</literal> runtime configuration
variable. Be sure to also provide the <option>--depth
files</option> option to the <command>svn add</command>
More information about the svnbook-dev
mailing list