[svnbook commit] r2571 - branches/ora-2e-reorg/src/en/book
cmpilato
noreply at red-bean.com
Wed Dec 20 15:07:00 CST 2006
Author: cmpilato
Date: Wed Dec 20 15:07:00 2006
New Revision: 2571
Added:
branches/ora-2e-reorg/src/en/book/app-quickstart.xml
- copied, changed from r2570, /branches/ora-2e-reorg/src/en/book/ch-introduction.xml
branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml
- copied, changed from r2570, /branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml
Removed:
branches/ora-2e-reorg/src/en/book/ch-introduction.xml
Modified:
branches/ora-2e-reorg/src/en/book/book.xml
branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml
branches/ora-2e-reorg/src/en/book/ch-basic-concepts.xml
Log:
Branch: ora-2e-reorg
Continue the reorganization effort by splitting the Advanced Topics
chapter into two (spawning a new Customizing Your Subversion
Experience chapter), transforming what was left of the Introduction
chapter into a new Quick-Start Guide appendix, plus some other section
moves.
* src/en/book/ch-basic-concepts.xml
(svn.advanced.reposurls): Moved here ch-advanced-topics.xml.
* src/en/book/ch-advanced-topics.xml
(svn.advanced.l10n svn.advanced.l10n.understanding
svn.advanced.l10n.svnuse svn.advanced.externaldifftools
svn.advanced.externaldifftools.diff
svn.advanced.externaldifftools.diff3): Removed (these live in the
new ch-customizing-svn.xml file now).
(svn.advanced.reposurls): Moved to ch-basic-concepts.xml.
* src/en/book/ch-customizing-svn.xml
New, copied from ch-advanced-topics.xml, but with everything cored
out except svn.advanced.l10n svn.advanced.l10n.understanding
svn.advanced.l10n.svnuse svn.advanced.externaldifftools
svn.advanced.externaldifftools.diff, and
svn.advanced.externaldifftools.diff3.
* src/en/book/ch-introduction.xml
Renamed to app-quickstart.xml.
* src/en/book/app-quickstart.xml
Was ch-introduction.xml. Converted to an appendix. Reworked the
opening simplesect to better describe the scope (and use "appendix"
instead of "chapter"). Renamed the "Quick-Start Guide" section to
"High-speed Tutorial". Left a TODO about expanding the tutorial.
* src/en/book/book.xml
Re-map some entities:
ch01 --> ch-basic-concepts.xml
ch02 --> ch-guided-tour.xml
ch03 --> ch-advanced-topics.xml
ch07 --> ch-customizing-svn.xml
appa --> app-quickstart.xml
appb --> app-svn-for-cvs-users.xml
appc --> app-webdav.xml
appd --> app-third-party-tools.xml
Also, drop the &appd; entity into the mix.
Copied: branches/ora-2e-reorg/src/en/book/app-quickstart.xml (from r2570, /branches/ora-2e-reorg/src/en/book/ch-introduction.xml)
==============================================================================
--- /branches/ora-2e-reorg/src/en/book/ch-introduction.xml (original)
+++ branches/ora-2e-reorg/src/en/book/app-quickstart.xml Wed Dec 20 15:07:00 2006
@@ -1,24 +1,24 @@
-<chapter id="svn.intro">
+<appendix id="svn.intro">
- <title>Introduction</title>
+ <title>Subversion Quick-Start Guide</title>
<simplesect>
- <para>Version control is the art of managing changes to
- information. It has long been a critical tool for programmers,
- who typically spend their time making small changes to software
- and then undoing those changes the next day. But the usefulness
- of version control software extends far beyond the bounds of the
- software development world. Anywhere you can find people using
- computers to manage information that changes often, there is
- room for version control. And that's where Subversion comes
- into play.</para>
- <para>This chapter contains a high-level introduction to
- Subversion—what it is; what it does; how to get it.</para>
-
- </simplesect>
+ <para>Some people have trouble absorbing a new technology by
+ reading the sort of <quote>top down</quote> approach provided by
+ this book. This appendix contains a very short introduction to
+ Subversion, and is designed to give <quote>bottom up</quote>
+ learners a fighting chance. If you prefer to learn by
+ experimentation, the following demonstration will get you up and
+ running. Along the way, we give links to the relevant chapters
+ of this book.</para>
+ <para>If you're new to the entire concept of version control or to
+ the <quote>copy-modify-merge</quote> model used by both CVS and
+ Subversion, then you should read <xref linkend="svn.basic"/>
+ before going any further.</para>
+ </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -73,24 +73,21 @@
<!-- ================================================================= -->
<sect1 id="svn.intro.quickstart">
- <title>A Quick Start</title>
-
- <para>Some people have trouble absorbing a new technology by
- reading the sort of <quote>top down</quote> approach provided by
- this book. This section is a very short introduction to
- Subversion, and is designed to give <quote>bottom up</quote>
- learners a fighting chance. If you prefer to learn by
- experimentation, the following demonstration will get you up and
- running. Along the way, we give links to the relevant chapters
- of this book.</para>
+ <title>High-speed Tutorial</title>
- <para>If you're new to the entire concept of version control or to
- the <quote>copy-modify-merge</quote> model used by both CVS and
- Subversion, then you should read <xref linkend="svn.basic"/>
- before going any further.</para>
+ <blockquote>
+ <para><quote>Please make sure your seat backs are in their full,
+ upgright position, and that your tray tables are stored.
+ Flight attendants, prepare for take-off….</quote></para>
+ </blockquote>
+
+ <para>The following is a very high-level tutorial which will walk
+ you through some basic Subversion configuration and operation.
+ By the time you complete the tutorial, you should have a basic
+ understanding of Subversion's typical usage.</para>
<note>
- <para>The following example assumes that you have
+ <para>The examples used in this appendix assume that you have
<command>svn</command>, the Subversion command-line client,
and <command>svnadmin</command>, the administrative tool,
ready to go. It also assumes you are using Subversion 1.2 or
@@ -232,13 +229,16 @@
linkend="svn.serverconfig"/> to learn about the different sorts of
server processes available and how to configure them.</para>
+ <para>### TODO: Let's make this into a full tutorial, rather than
+ simply referring off to other sections. ###</para>
+
</sect1>
-</chapter>
+</appendix>
<!--
local variables:
-sgml-parent-document: ("book.xml" "chapter")
+sgml-parent-document: ("book.xml" "appendix")
end:
-->
Modified: branches/ora-2e-reorg/src/en/book/book.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/book.xml (original)
+++ branches/ora-2e-reorg/src/en/book/book.xml Wed Dec 20 15:07:00 2006
@@ -5,18 +5,19 @@
%vers;
<!ENTITY foreword SYSTEM "foreword.xml">
<!ENTITY ch00 SYSTEM "ch-preface.xml">
-<!ENTITY ch01 SYSTEM "ch-introduction.xml">
-<!ENTITY ch02 SYSTEM "ch-basic-concepts.xml">
-<!ENTITY ch03 SYSTEM "ch-guided-tour.xml">
+<!ENTITY ch01 SYSTEM "ch-basic-concepts.xml">
+<!ENTITY ch02 SYSTEM "ch-guided-tour.xml">
+<!ENTITY ch03 SYSTEM "ch-advanced-topics.xml">
<!ENTITY ch04 SYSTEM "ch-branching-and-merging.xml">
<!ENTITY ch05 SYSTEM "ch-repository-admin.xml">
<!ENTITY ch06 SYSTEM "ch-server-configuration.xml">
-<!ENTITY ch07 SYSTEM "ch-advanced-topics.xml">
+<!ENTITY ch07 SYSTEM "ch-customizing-svn.xml">
<!ENTITY ch08 SYSTEM "ch-developer-info.xml">
<!ENTITY ch09 SYSTEM "ch-reference.xml">
-<!ENTITY appa SYSTEM "app-svn-for-cvs-users.xml">
-<!ENTITY appb SYSTEM "app-webdav.xml">
-<!ENTITY appc SYSTEM "app-third-party-tools.xml">
+<!ENTITY appa SYSTEM "app-quickstart.xml">
+<!ENTITY appb SYSTEM "app-svn-for-cvs-users.xml">
+<!ENTITY appc SYSTEM "app-webdav.xml">
+<!ENTITY appd SYSTEM "app-third-party-tools.xml">
<!ENTITY license SYSTEM "copyright.xml">
]>
@@ -94,6 +95,7 @@
&appa;
&appb;
&appc;
+ &appd;
&license;
</book>
Modified: branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml Wed Dec 20 15:07:00 2006
@@ -3286,492 +3286,6 @@
</sect2>
</sect1>
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.advanced.l10n">
- <title>Localization</title>
-
- <para><firstterm>Localization</firstterm> is the act of making
- programs behave in a region-specific way. When a program
- formats numbers or dates in a way specific to your part of the
- world, or prints messages (or accepts input) in your native
- language, the program is said to
- be <firstterm>localized</firstterm>. This section describes
- steps Subversion has made towards localization.</para>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.l10n.understanding">
- <title>Understanding locales</title>
-
- <para>Most modern operating systems have a notion of the
- <quote>current locale</quote>—that is, the region or
- country whose localization conventions are honored. These
- conventions—typically chosen by some runtime
- configuration mechanism on the computer—affect the way
- in which programs present data to the user, as well as the way
- in which they accept user input.</para>
-
- <para>On Unix-like systems, you can check the values of the
- locale-related runtime configuration options by running the
- <command>locale</command> command:</para>
-
- <screen>
-$ locale
-LANG=
-LC_COLLATE="C"
-LC_CTYPE="C"
-LC_MESSAGES="C"
-LC_MONETARY="C"
-LC_NUMERIC="C"
-LC_TIME="C"
-LC_ALL="C"
-</screen>
-
- <para>The output is a list of locale-related environment
- variables and their current values. In this example, the
- variables are all set to the default <literal>C</literal>
- locale, but users can set these variables to specific
- country/language code combinations. For example, if one were
- to set the <literal>LC_TIME</literal> variable to
- <literal>fr_CA</literal>, then programs would know to present
- time and date information formatted according a
- French-speaking Canadian's expectations. And if one were to
- set the <literal>LC_MESSAGES</literal> variable to
- <literal>zh_TW</literal>, then programs would know to present
- human-readable messages in Traditional Chinese. Setting the
- <literal>LC_ALL</literal> variable has the effect of changing
- every locale variable to the same value. The value of
- <literal>LANG</literal> is used as a default value for any
- locale variable that is unset. To see the list of available
- locales on a Unix system, run the command <command>locale
- -a</command>.</para>
-
- <para>On Windows, locale configuration is done via the
- <quote>Regional and Language Options</quote> control panel
- item. There you can view and select the values of individual
- settings from the available locales, and even customize (at a
- sickening level of detail) several of the display formatting
- conventions.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.l10n.svnuse">
- <title>Subversion's use of locales</title>
-
- <para>The Subversion client, <command>svn</command>, honors the
- current locale configuration in two ways. First, it notices
- the value of the <literal>LC_MESSAGES</literal> variable and
- attempts to print all messages in the specified language. For
- example:</para>
-
- <screen>
-$ export LC_MESSAGES=de_DE
-$ svn help cat
-cat: Gibt den Inhalt der angegebenen Dateien oder URLs aus.
-Aufruf: cat ZIEL[@REV]...
-…
-</screen>
-
- <para>This behavior works identically on both Unix and Windows
- systems. Note, though, that while your operating system might
- have support for a certain locale, the Subversion client still
- may not be able to speak the particular language. In order to
- produce localized messages, human volunteers must provide
- translations for each language. The translations are written
- using the GNU gettext package, which results in translation
- modules that end with the <filename>.mo</filename> filename
- extension. For example, the German translation file is named
- <filename>de.mo</filename>. These translation files are
- installed somewhere on your system. On Unix, they typically
- live in <filename>/usr/share/locale/</filename>, while
- on Windows they're often found in the
- <filename>\share\locale\</filename> folder in Subversion's
- installation area. Once installed, a module is named after
- the program it provides translations for. For example, the
- <filename>de.mo</filename> file may ultimately end up
- installed as
- <filename>/usr/share/locale/de/LC_MESSAGES/subversion.mo</filename>.
- By browsing the installed <filename>.mo</filename> files, you
- can see which languages the Subversion client is able to
- speak.</para>
-
- <para>The second way in which the locale is honored involves how
- <command>svn</command> interprets your input. The repository
- stores all paths, filenames, and log messages in Unicode,
- encoded as UTF-8. In that sense, the repository is
- <firstterm>internationalized</firstterm>—that is, the
- repository is ready to accept input in any human language.
- This means, however, that the Subversion client is responsible
- for sending only UTF-8 filenames and log messages into the
- repository. In order to do this, it must convert the data
- from the native locale into UTF-8.</para>
-
- <para>For example, suppose you create a file
- named<filename>caffè.txt</filename>, and then when committing
- the file, you write the log message as <quote>Adesso il caffè
- è più forte</quote>. Both the filename and log message
- contain non-ASCII characters, but because your locale is set
- to <literal>it_IT</literal>, the Subversion client knows to
- interpret them as Italian. It uses an Italian character set
- to convert the data to UTF-8 before sending them off to the
- repository.</para>
-
- <para>Note that while the repository demands UTF-8 filenames and
- log messages, it <emphasis>does not</emphasis> pay attention
- to file contents. Subversion treats file contents as opaque
- strings of bytes, and neither client nor server makes an
- attempt to understand the character set or encoding of the
- contents.</para>
-
- <sidebar>
- <title>Character set conversion errors</title>
-
- <para>While using Subversion, you might get hit with an error
- related to character set conversions:</para>
-
- <screen>
-svn: Can't convert string from native encoding to 'UTF-8':
-…
-svn: Can't convert string from 'UTF-8' to native encoding:
-…
-</screen>
-
- <para>Errors like this typically occur when the Subversion
- client has received a UTF-8 string from the repository, but
- not all of the characters in that string can be represented
- using the encoding of the current locale. For example, if
- your locale is <literal>en_US</literal> but a collaborator
- has committed a Japanese filename, you're likely to see this
- error when you receive the file during an <command>svn
- update</command>.</para>
-
- <para>The solution is either to set your locale to something
- which <emphasis>can</emphasis> represent the incoming UTF-8
- data, or to change the filename or log message in the
- repository. (And don't forget to slap your collaborator's
- hand—projects should decide on common languages ahead of
- time, so that all participants are using the same
- locale.)</para>
- </sidebar>
-
- </sect2>
-
- </sect1>
-
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.advanced.externaldifftools">
- <title>Using External Differencing Tools</title>
-
- <para>The presence of <option>--diff-cmd</option> and
- <option>--diff3-cmd</option> options, and similarly named
- runtime configuration parameters (see <xref
- linkend="svn.advanced.confarea.opts.config"/>), can lead to a
- false notion of how easy it is to use external differencing (or
- <quote>diff</quote>) and merge tools with Subversion. While
- Subversion can use most of popular such tools available, the
- effort invested in setting this up often turns out to be
- non-trivial.</para>
-
- <para>The interface between Subversion and external diff and merge
- tools harkens back to a time when Subversion's only contextual
- differencing capabilities were built around invocations of the
- GNU diffutils toolchain, specifically the
- <command>diff</command> and <command>diff3</command> utilities.
- To get the kind of behavior Subversion needed, it called these
- utilities with more than a handful of options and parameters,
- most of which were quite specific to the utilities. Some time
- later, Subversion grew its own internal differencing library,
- and as a failover mechanism,
- <footnote>
- <para>Subversion developers are good, but even the best make
- mistakes.</para>
- </footnote>
- the <option>--diff-cmd</option> and <option>--diff3-cmd</option>
- options were added to the Subversion command-line client so
- users could more easily indicate that they preferred to use the
- GNU diff and diff3 utilities instead of the newfangled internal
- diff library. If those options were used, Subversion would
- simply ignore the internal diff library, and fall back to
- running those external programs, lengthy argument lists and all.
- And that's where things remain today.</para>
-
- <para>It didn't take long for folks to realize that having such
- easy configuration mechanisms for specifying that Subversion
- should use the external GNU diff and diff3 utilities located at
- a particular place on the system could be applied toward the use
- of other diff and merge tools, too. After all, Subversion
- didn't actually verify that the things it was being told to run
- were members of the GNU diffutils toolchain. But the only
- configurable aspect of using those external tools is their
- location on the system—not the option set, parameter
- order, etc. Subversion continues throwing all those GNU utility
- options at your external diff tool regardless of whether or not
- that program can understand those options. And that's where
- things get unintuitive for most users.</para>
-
- <para>The key to using external diff and merge tools (other than
- GNU diff and diff3, of course) with Subversion is to use wrapper
- scripts which convert the input from Subversion into something
- that your differencing tool can understand, and then to convert
- the output of your tool back into a format which Subversion
- expects—the format that the GNU tools would have used.
- The following sections cover the specifics of those
- expectations.</para>
-
- <note>
- <para>The decision on when to fire off a contextual diff or
- merge as part of a larger Subversion operation is made
- entirely by Subversion, and is affected by, among other
- things, whether or not the files being operated on are
- human-readable as determined by their
- <literal>svn:mime-type</literal> property. This means, for
- example, that even if you had the niftiest Microsoft
- Word-aware differencing or merging tool in the Universe, it
- would never be invoked by Subversion so long as your versioned
- Word documents had a configured MIME type that denoted that
- they were not human-readable (such as
- <literal>application/msword</literal>). For more about MIME
- type settings, see <xref
- linkend="svn.advanced.props.special.mime-type"/></para>
- </note>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.externaldifftools.diff">
- <title>External diff</title>
-
- <para>Subversion calls external diff programs with parameters
- suitable for the GNU diff utility, and expects only that the
- external program return with a successful error code. For
- most alternative diff program, only the sixth and seventh
- arguments, the paths of the files which represent the left and
- right sides of the diff, respectively, are of interest. Note
- that Subversion runs the diff program once per modified file
- covered by the Subversion operation, so if your program runs
- in an asynchronous fashion (or <quote>backgrounded</quote>),
- you might have several instances of it all running
- simultaneously. Finally, Subversion expects that your program
- return an errorcode of 1 if your program detected differences,
- or 0 if it did not—any other errorcode is considered a
- fatal error.
- <footnote>
- <para>The GNU diff manual page puts it this way: <quote>An
- exit status of 0 means no differences were found, 1 means some
- differences were found, and 2 means trouble.</quote></para>
- </footnote>
- </para>
-
- <para><xref linkend="svn.advanced.externaldifftools.diff.ex-1"/>
- and <xref linkend="svn.advanced.externaldifftools.diff.ex-2"/>
- are templates for external diff tool wrappers in the Bourne
- shell and Windows batch scripting languages,
- respectively.</para>
-
- <example id="svn.advanced.externaldifftools.diff.ex-1">
- <title>diffwrap.sh</title>
- <programlisting>
-#!/bin/sh
-
-# Configure your favorite diff program here.
-DIFF="/usr/local/bin/my-diff-tool"
-
-# Subversion provides the paths we need as the sixth and seventh
-# parameters.
-LEFT=${6}
-RIGHT=${7}
-
-# Call the diff command (change the following line to make sense for
-# your merge program).
-$DIFF --left $LEFT --right $RIGHT
-
-# Return an errorcode of 0 if no differences were detected, 1 if some were.
-# Any other errorcode will be treated as fatal.
-</programlisting>
- </example>
-
- <example id="svn.advanced.externaldifftools.diff.ex-2">
- <title>diffwrap.bat</title>
- <programlisting>
- at ECHO OFF
-
-REM Configure your favorite diff program here.
-SET DIFF="C:\Program Files\Funky Stuff\My Diff Tool.exe"
-
-REM Subversion provides the paths we need as the sixth and seventh
-REM parameters.
-SET LEFT=%6
-SET RIGHT=%7
-
-REM Call the diff command (change the following line to make sense for
-REM your merge program).
-%DIFF% --left %LEFT% --right %RIGHT%
-
-REM Return an errorcode of 0 if no differences were detected, 1 if some were.
-REM Any other errorcode will be treated as fatal.
-</programlisting>
- </example>
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.externaldifftools.diff3">
- <title>External diff3</title>
-
- <para>Subversion calls external merge programs with parameters
- suitable for the GNU diff3 utility, expecting that the
- external program return with a successful error code and that
- the full file contents which result from the completed merge
- operation are printed on the standard output stream (so that
- Subversion can redirect them into the appropriate version
- controlled file). For most alternative merge programs, only
- the ninth, tenth, and eleventh arguments, the paths of the
- files which represent the <quote>mine</quote>,
- <quote>older</quote>, and <quote>yours</quote> inputs,
- respectively, are of interest. Note that because Subversion
- depends on the output of your merge program, you wrapper
- script must not exit before that output has been delivered to
- Subversion. When it finally does exit, it should return an
- errorcode of 0 if the merge was successful, or 1 if unresolved
- conflicts remain in the output—any other errorcode is
- considered a fatal error.</para>
-
- <para><xref linkend="svn.advanced.externaldifftools.diff3.ex-1"/>
- and <xref linkend="svn.advanced.externaldifftools.diff3.ex-2"/> are
- templates for external merge tool wrappers in the Bourne shell
- and Windows batch scripting languages, respectively.</para>
-
- <example id="svn.advanced.externaldifftools.diff3.ex-1">
- <title>diff3wrap.sh</title>
- <programlisting>
-#!/bin/sh
-
-# Configure your favorite diff3/merge program here.
-DIFF3="/usr/local/bin/my-merge-tool"
-
-# Subversion provides the paths we need as the ninth, tenth, and eleventh
-# parameters.
-MINE=${9}
-OLDER=${10}
-YOURS=${11}
-
-# Call the merge command (change the following line to make sense for
-# your merge program).
-$DIFF3 --older $OLDER --mine $MINE --yours $YOURS
-
-# After performing the merge, this script needs to print the contents
-# of the merged file to stdout. Do that in whatever way you see fit.
-# Return an errorcode of 0 on successful merge, 1 if unresolved conflicts
-# remain in the result. Any other errorcode will be treated as fatal.
-</programlisting>
- </example>
-
- <example id="svn.advanced.externaldifftools.diff3.ex-2">
- <title>diff3wrap.bat</title>
- <programlisting>
- at ECHO OFF
-
-REM Configure your favorite diff3/merge program here.
-SET DIFF3="C:\Program Files\Funky Stuff\My Merge Tool.exe"
-
-REM Subversion provides the paths we need as the ninth, tenth, and eleventh
-REM parameters. But we only have access to nine parameters at a time, so we
-REM shift our nine-parameter window twice to let us get to what we need.
-SHIFT
-SHIFT
-SET MINE=%7
-SET OLDER=%8
-SET YOURS=%9
-
-REM Call the merge command (change the following line to make sense for
-REM your merge program).
-%DIFF3% --older %OLDER% --mine %MINE% --yours %YOURS%
-
-REM After performing the merge, this script needs to print the contents
-REM of the merged file to stdout. Do that in whatever way you see fit.
-REM Return an errorcode of 0 on successful merge, 1 if unresolved conflicts
-REM remain in the result. Any other errorcode will be treated as fatal.
-</programlisting>
- </example>
-
- </sect2>
- </sect1>
-
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.advanced.reposurls">
- <title>Subversion Repository URLs</title>
-
- <para>As illustrated throughout this book, Subversion uses URLs to
- identify versioned resources in Subversion repositories. For
- the most part, these URLs use the standard syntax, allowing for
- server names and port numbers to be specified as part of the
- URL:</para>
-
- <screen>
-$ svn checkout http://svn.example.com:9834/repos
-…
-</screen>
-
- <para>But there are some nuances in Subversion's handling of URLs
- that are notable. For example, URLs containing the
- <literal>file:</literal> access method (used for local
- repositories) must, in accordance with convention, have either a
- server name of <literal>localhost</literal> or no server name at
- all:</para>
-
- <screen>
-$ svn checkout file:///path/to/repos
-…
-$ svn checkout file://localhost/path/to/repos
-…
-</screen>
-
- <para>Also, users of the <literal>file:</literal> scheme on
- Windows platforms will need to use an unofficially
- <quote>standard</quote> syntax for accessing repositories
- that are on the same machine, but on a different drive than
- the client's current working drive. Either of the two
- following URL path syntaxes will work where
- <literal>X</literal> is the drive on which the repository
- resides:</para>
-
- <screen>
-C:\> svn checkout file:///X:/path/to/repos
-…
-C:\> svn checkout "file:///X|/path/to/repos"
-…
-</screen>
-
- <para>In the second syntax, you need to quote the URL so that the
- vertical bar character is not interpreted as a pipe. Also, note
- that a URL uses ordinary slashes even though the native
- (non-URL) form of a path on Windows uses backslashes.</para>
-
- <para>Finally, it should be noted that the Subversion client will
- automatically encode URLs as necessary, just like a web browser
- does. For example, if a URL contains a space or upper-ASCII
- character:</para>
-
- <screen>
-$ svn checkout "http://host/path with space/project/españa"
-</screen>
-
- <para>…then Subversion will escape the unsafe characters
- and behave as if you had typed:</para>
-
- <screen>
-$ svn checkout http://host/path%20with%20space/project/espa%C3%B1a
-</screen>
-
- <para>If the URL contains spaces, be sure to place it within quote
- marks, so that your shell treats the whole thing as a single
- argument to the <command>svn</command> program.</para>
-
- </sect1>
-
</chapter>
<!--
Modified: branches/ora-2e-reorg/src/en/book/ch-basic-concepts.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-basic-concepts.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-basic-concepts.xml Wed Dec 20 15:07:00 2006
@@ -294,6 +294,78 @@
used.</para>
<!-- =============================================================== -->
+ <sect2 id="svn.advanced.reposurls">
+ <title>Subversion Repository URLs</title>
+
+ <para>As illustrated throughout this book, Subversion uses URLs to
+ identify versioned resources in Subversion repositories. For
+ the most part, these URLs use the standard syntax, allowing for
+ server names and port numbers to be specified as part of the
+ URL:</para>
+
+ <screen>
+ $ svn checkout http://svn.example.com:9834/repos
+ …
+ </screen>
+
+ <para>But there are some nuances in Subversion's handling of URLs
+ that are notable. For example, URLs containing the
+ <literal>file:</literal> access method (used for local
+ repositories) must, in accordance with convention, have either a
+ server name of <literal>localhost</literal> or no server name at
+ all:</para>
+
+ <screen>
+ $ svn checkout file:///path/to/repos
+ …
+ $ svn checkout file://localhost/path/to/repos
+ …
+ </screen>
+
+ <para>Also, users of the <literal>file:</literal> scheme on
+ Windows platforms will need to use an unofficially
+ <quote>standard</quote> syntax for accessing repositories
+ that are on the same machine, but on a different drive than
+ the client's current working drive. Either of the two
+ following URL path syntaxes will work where
+ <literal>X</literal> is the drive on which the repository
+ resides:</para>
+
+ <screen>
+ C:\> svn checkout file:///X:/path/to/repos
+ …
+ C:\> svn checkout "file:///X|/path/to/repos"
+ …
+ </screen>
+
+ <para>In the second syntax, you need to quote the URL so that the
+ vertical bar character is not interpreted as a pipe. Also, note
+ that a URL uses ordinary slashes even though the native
+ (non-URL) form of a path on Windows uses backslashes.</para>
+
+ <para>Finally, it should be noted that the Subversion client will
+ automatically encode URLs as necessary, just like a web browser
+ does. For example, if a URL contains a space or upper-ASCII
+ character:</para>
+
+ <screen>
+ $ svn checkout "http://host/path with space/project/españa"
+ </screen>
+
+ <para>…then Subversion will escape the unsafe characters
+ and behave as if you had typed:</para>
+
+ <screen>
+ $ svn checkout http://host/path%20with%20space/project/espa%C3%B1a
+ </screen>
+
+ <para>If the URL contains spaces, be sure to place it within quote
+ marks, so that your shell treats the whole thing as a single
+ argument to the <command>svn</command> program.</para>
+
+ </sect2>
+
+ <!-- =============================================================== -->
<sect2 id="svn.basic.in-action.wc">
<title>Working Copies</title>
Copied: branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml (from r2570, /branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml)
==============================================================================
--- /branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml Wed Dec 20 15:07:00 2006
@@ -1,3291 +1,12 @@
-<chapter id="svn.advanced">
- <title>Advanced Topics</title>
+<chapter id="svn.customization">
+ <title>Customizing Your Subversion Experience</title>
<simplesect>
- <para>If you've been reading this book chapter by chapter, from
- start to finish, you should by now have acquired enough
- knowledge to use the Subversion client to perform the most
- common version control operations. You understand how to
- checkout a working copy from a Subversion repository. You are
- comfortable with submitting and receiving changes using the
- <command>svn commit</command> and <command>svn update</command>
- functions. You've probably even developed a reflex which causes
- you to run the <command>svn status</command> command almost
- unconsciously. For all intents and purposes, you are ready to
- use Subversion in a typical environment.</para>
-
- <para>But the Subversion feature set doesn't stop at <quote>common
- version control operations</quote>.</para>
-
- <para>This chapter highlights some of Subversion's features that
- aren't quite so regularly used. In it, we will discuss
- Subversion's property (or <quote>metadata</quote>) support, and
- how to modify Subversion's default behaviors by tweaking its
- run-time configuration area. We will describe how you can use
- externals definitions to instruct Subversion to pull data from
- multiple repositories. We'll cover in detail some of the
- additional client- and server-side tools that are part of the
- Subversion distribution.</para>
-
- <para>Before reading this chapter, you should be familiar with the
- basic file and directory versioning capabilities of Subversion.
- If you haven't already read about those, or if you need a
- refresher, we recommend that you check out <xref
- linkend="svn.basic" /> and <xref linkend="svn.tour" />. Once
- you've mastered the basics and consumed this chapter, you'll be
- a Subversion power-user!
- </para>
+ <para>### TODO ###</para>
</simplesect>
- <sect1 id="svn.advanced.confarea">
- <title>Runtime Configuration Area</title>
-
- <para>Subversion provides many optional behaviors that can be
- controlled by the user. Many of these options are of the kind
- that a user would wish to apply to all Subversion operations.
- So, rather than forcing users to remember command-line arguments
- for specifying these options, and to use them for each and every
- operation they perform, Subversion uses configuration files,
- segregated into a Subversion configuration area.</para>
-
- <para>The Subversion <firstterm>configuration area</firstterm> is
- a two-tiered hierarchy of option names and their values.
- Usually, this boils down to a special directory that contains
- <firstterm>configuration files</firstterm> (the first tier),
- which are just text files in standard INI format (with
- <quote>sections</quote> providing the second tier). These files
- can be easily edited using your favorite text editor (such as
- Emacs or vi), and contain directives read by the client to
- determine which of several optional behaviors the user
- prefers.</para>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.confarea.layout">
- <title>Configuration Area Layout</title>
-
- <para>The first time that the <command>svn</command>
- command-line client is executed, it creates a per-user
- configuration area. On Unix-like systems, this area appears
- as a directory named <filename>.subversion</filename> in the
- user's home directory. On Win32 systems, Subversion creates a
- folder named <filename>Subversion</filename>, typically inside
- the <filename>Application Data</filename> area of the user's
- profile directory (which, by the way, is usually a hidden
- directory). However, on this platform the exact location
- differs from system to system, and is dictated by the Windows
- registry.
- <footnote>
- <para>The <literal>APPDATA</literal> environment variable
- points to the <filename>Application Data</filename> area,
- so you can always refer to this folder as
- <filename>%APPDATA%\Subversion</filename>.</para>
- </footnote>
- We will refer to the per-user configuration area using its Unix
- name, <filename>.subversion</filename>.</para>
-
- <para>In addition to the per-user configuration area, Subversion
- also recognizes the existence of a system-wide configuration
- area. This gives system administrators the ability to
- establish defaults for all users on a given machine. Note
- that the system-wide configuration area does not alone dictate
- mandatory policy—the settings in the per-user
- configuration area override those in the system-wide one, and
- command-line arguments supplied to the <command>svn</command>
- program have the final word on behavior. On Unix-like
- platforms, the system-wide configuration area is
- expected to be the <filename>/etc/subversion</filename>
- directory; on Windows machines, it looks for a
- <filename>Subversion</filename> directory inside the common
- <filename>Application Data</filename> location (again, as
- specified by the Windows Registry). Unlike the per-user
- case, the <command>svn</command> program does not attempt
- to create the system-wide configuration area.</para>
-
- <para>The configuration area currently contains three
- files—two configuration files (<filename>config</filename> and
- <filename>servers</filename>), and a <filename>README.txt</filename>
- file which describes the INI format. At the time of their
- creation, the files contain default values for each of the
- supported Subversion options, mostly commented out and grouped
- with textual descriptions about how the values for the key
- affect Subversion's behavior. To change a certain behavior,
- you need only to load the appropriate configuration file into
- a text editor, and modify the desired option's value. If at
- any time you wish to have the default configuration settings
- restored, you can simply remove (or rename) your configuration
- directory and then run some innocuous <command>svn</command>
- command, such as <command>svn --version</command>. A new
- configuration directory with the default contents will be
- created.</para>
-
- <para>The per-user configuration area also contains a cache of
- authentication data. The <filename>auth</filename> directory
- holds a set of subdirectories that contain pieces of cached
- information used by Subversion's various supported
- authentication methods. This directory is created in such a
- way that only the user herself has permission to read its
- contents.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.confarea.windows-registry">
- <title>Configuration and the Windows Registry</title>
-
- <para>In addition to the usual INI-based configuration area,
- Subversion clients running on Windows platforms may also use
- the Windows registry to hold the configuration data. The
- option names and their values are the same as in the INI
- files. The <quote>file/section</quote> hierarchy is
- preserved as well, though addressed in a slightly different
- fashion—in this schema, files and sections are just
- levels in the registry key tree.</para>
-
- <para>Subversion looks for system-wide configuration values
- under the
- <literal>HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion</literal>
- key. For example, the <literal>global-ignores</literal> option,
- which is in the <literal>miscellany</literal> section of the
- <filename>config</filename> file, would be found at
- <literal>HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Config\Miscellany\global-ignores</literal>.
- Per-user configuration values should be stored under
- <literal>HKEY_CURRENT_USER\Software\Tigris.org\Subversion</literal>.
- </para>
-
- <para>Registry-based configuration options are parsed
- <emphasis>before</emphasis> their file-based counterparts,
- so are overridden by values found in the configuration
- files. In other words, configuration priority is granted in
- the following order on a Windows system:</para>
-
- <orderedlist>
- <listitem>
- <para>Command-line options</para>
- </listitem>
- <listitem>
- <para>The per-user INI files</para>
- </listitem>
- <listitem>
- <para>The per-user Registry values</para>
- </listitem>
- <listitem>
- <para>The system-wide INI files</para>
- </listitem>
- <listitem>
- <para>The system-wide Registry values</para>
- </listitem>
- </orderedlist>
-
- <para>Also, the Windows Registry doesn't really support the
- notion of something being <quote>commented out</quote>.
- However, Subversion will ignore any option key whose name
- begins with a hash (<literal>#</literal>) character. This
- allows you to effectively comment out a Subversion option
- without deleting the entire key from the Registry, obviously
- simplifying the process of restoring that option.</para>
-
- <para>The <command>svn</command> command-line client never
- attempts to write to the Windows Registry, and will not
- attempt to create a default configuration area there. You can
- create the keys you need using the <command>REGEDIT</command>
- program. Alternatively, you can create a
- <filename>.reg</filename> file, and then double-click on that
- file from the Explorer shell, which will cause the data to be
- merged into your registry.</para>
-
- <example id="svn.advanced.confarea.windows-registry.ex-1">
- <title>Sample Registration Entries (.reg) File.</title>
-
- <programlisting>
-REGEDIT4
-
-[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\groups]
-
-[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\global]
-"#http-proxy-host"=""
-"#http-proxy-port"=""
-"#http-proxy-username"=""
-"#http-proxy-password"=""
-"#http-proxy-exceptions"=""
-"#http-timeout"="0"
-"#http-compression"="yes"
-"#neon-debug-mask"=""
-"#ssl-authority-files"=""
-"#ssl-trust-default-ca"=""
-"#ssl-client-cert-file"=""
-"#ssl-client-cert-password"=""
-
-[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auth]
-"#store-auth-creds"="no"
-
-[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\helpers]
-"#editor-cmd"="notepad"
-"#diff-cmd"=""
-"#diff3-cmd"=""
-"#diff3-has-program-arg"=""
-
-[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\miscellany]
-"#global-ignores"="*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store"
-"#log-encoding"=""
-"#use-commit-times"=""
-"#template-root"=""
-"#enable-auto-props"=""
-
-[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\tunnels]
-
-[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]
-</programlisting>
- </example>
-
- <para>The previous example shows the contents of a
- <filename>.reg</filename> file which contains some of the most
- commonly used configuration options and their default values.
- Note the presence of both system-wide (for network
- proxy-related options) and per-user settings (editor programs
- and password storage, among others). Also note that all the
- options are effectively commented out. You need only to
- remove the hash (<literal>#</literal>) character from the
- beginning of the option names, and set the values as you
- desire.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.confarea.opts">
- <title>Configuration Options</title>
-
- <para>In this section, we will discuss the specific
- run-time configuration options that are currently supported
- by Subversion.</para>
-
- <sect3 id="svn.advanced.confarea.opts.servers">
- <title>Servers</title>
-
- <para>The <filename>servers</filename> file contains
- Subversion configuration options related to the network
- layers. There are two special section names in this
- file—<literal>groups</literal> and
- <literal>global</literal>. The <literal>groups</literal>
- section is essentially a cross-reference table. The keys in
- this section are the names of other sections in the file;
- their values are <firstterm>globs</firstterm>—textual
- tokens which possibly contain wildcard
- characters—that are compared against the hostnames of
- the machine to which Subversion requests are sent.</para>
-
- <programlisting>
-[groups]
-beanie-babies = *.red-bean.com
-collabnet = svn.collab.net
-
-[beanie-babies]
-…
-
-[collabnet]
-…
-</programlisting>
-
- <para>When Subversion is used over a network, it attempts to
- match the name of the server it is trying to reach with a
- group name under the <literal>groups</literal> section. If
- a match is made, Subversion then looks for a section in the
- <filename>servers</filename> file whose name is the matched
- group's name. From that section it reads the actual network
- configuration settings.</para>
-
- <para>The <literal>global</literal> section contains the
- settings that are meant for all of the servers not matched
- by one of the globs under the <literal>groups</literal>
- section. The options available in this section are
- exactly the same as those valid for the other server
- sections in the file (except, of course, the special
- <literal>groups</literal> section), and are as
- follows:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>http-proxy-host</literal></term>
- <listitem>
- <para>This specifies the hostname of the proxy computer
- through which your HTTP-based Subversion requests must
- pass. It defaults to an empty value, which means that
- Subversion will not attempt to route HTTP requests
- through a proxy computer, and will instead attempt to
- contact the destination machine directly.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-proxy-port</literal></term>
- <listitem>
- <para>This specifies the port number on the proxy host
- to use. It defaults to an empty value.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-proxy-username</literal></term>
- <listitem>
- <para>This specifies the username to supply to the proxy
- machine. It defaults to an empty value.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-proxy-password</literal></term>
- <listitem>
- <para>This specifies the password to supply to the proxy
- machine. It defaults to an empty value.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-timeout</literal></term>
- <listitem>
- <para>This specifies the amount of time, in seconds, to
- wait for a server response. If you experience
- problems with a slow network connection causing
- Subversion operations to timeout, you should increase
- the value of this option. The default value is
- <literal>0</literal>, which instructs the underlying
- HTTP library, Neon, to use its default timeout
- setting.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-compression</literal></term>
- <listitem>
- <para>This specifies whether or not Subversion should
- attempt to compress network requests made to DAV-ready
- servers. The default value is <literal>yes</literal>
- (though compression will only occur if that capability
- is compiled into the network layer). Set this to
- <literal>no</literal> to disable compression, such as
- when debugging network transmissions.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>neon-debug-mask</literal></term>
- <listitem>
- <para>This is an integer mask that the underlying HTTP
- library, Neon, uses for choosing what type of
- debugging output to yield. The default value is
- <literal>0</literal>, which will silence all debugging
- output. For more information about how Subversion
- makes use of Neon, see <xref linkend="svn.developer" />.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ssl-authority-files</literal></term>
- <listitem>
- <para>This is a semicolon-delimited list of paths to files
- containing certificates of the certificate authorities
- (or CAs) that
- are accepted by the Subversion client when accessing the
- repository over HTTPS.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ssl-trust-default-ca</literal></term>
- <listitem>
- <para>Set this variable to <literal>yes</literal> if you
- want Subversion to automatically trust the set of
- default CAs that ship with OpenSSL.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ssl-client-cert-file</literal></term>
- <listitem>
- <para>If a host (or set of hosts) requires an SSL client
- certificate, you'll normally be prompted for a path to
- your certificate. By setting this variable to that
- same path, Subversion will be able to find your client
- certificate automatically without prompting you.
- There's no standard place to store your certificate on
- disk; Subversion will grab it from any path you
- specify.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ssl-client-cert-password</literal></term>
- <listitem>
- <para>If your SSL client certificate file is encrypted
- by a passphrase, Subversion will prompt you for the
- passphrase whenever the certificate is used. If you
- find this annoying (and don't mind storing the
- password in the <filename>servers</filename> file),
- then you can set this variable to the certificate's
- passphrase. You won't be prompted anymore.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect3>
- <sect3 id="svn.advanced.confarea.opts.config">
- <title>Config</title>
-
- <para>The <filename>config</filename> file contains the rest
- of the currently available Subversion run-time options,
- those not related to networking. There are only a few
- options in use at this time, but they are again grouped into
- sections in expectation of future additions.</para>
-
- <para>The <literal>auth</literal> section contains settings
- related to Subversion's authentication and authorization
- against the repository. It contains:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>store-passwords</literal></term>
- <listitem>
- <para>This instructs Subversion to cache, or not to
- cache, passwords that are supplied by the user in
- response to server authentication challenges. The
- default value is <literal>yes</literal>. Set this to
- <literal>no</literal> to disable this on-disk password
- caching. You can override this option for a single
- instance of the <command>svn</command> command using
- the <option>--no-auth-cache</option> command-line
- parameter (for those subcommands that support it).
- For more information, see <xref
- linkend="svn.serverconfig.netmodel.credcache"/>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>store-auth-creds</literal></term>
- <listitem>
- <para>This setting is the same as
- <literal>store-passwords</literal>, except that it
- enables or disables disk-caching of
- <emphasis>all</emphasis> authentication information:
- usernames, passwords, server certificates, and any
- other types of cacheable credentials.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>The <literal>helpers</literal> section controls which
- external applications Subversion uses to accomplish its
- tasks. Valid options in this section are:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>editor-cmd</literal></term>
- <listitem>
- <para>This specifies the program Subversion will use to
- query the user for a log message during a commit
- operation, such as when using <command>svn
- commit</command> without either the
- <option>--message</option> (<option>-m</option>) or
- <option>--file</option> (<option>-F</option>) options.
- This program is also used with the <command>svn
- propedit</command> command—a temporary file is
- populated with the current value of the property the
- user wishes to edit, and the edits take place right
- in the editor program (see <xref
- linkend="svn.advanced.props" />). This option's default
- value is empty. The order of priority for determining the
- editor command is:</para>
- <orderedlist>
- <listitem>
- <para>Command-line option <literal>--editor-cmd</literal></para>
- </listitem>
- <listitem>
- <para>Environment variable <literal>SVN_EDITOR</literal></para>
- </listitem>
- <listitem>
- <para>Configuration option <literal>editor-cmd</literal></para>
- </listitem>
- <listitem>
- <para>Environment variable <literal>VISUAL</literal></para>
- </listitem>
- <listitem>
- <para>Environment variable <literal>EDITOR</literal></para>
- </listitem>
- <listitem>
- <para>Possibly, a default value built in to Subversion
- (not present in the official builds)</para>
- </listitem>
- </orderedlist>
- <para>The value of any of these options or variables is
- (unlike <literal>diff-cmd</literal>) the beginning of a
- command line to be executed by the shell. Subversion
- appends a space and the pathname of the temporary file to be
- edited. The editor should modify the temporary file and
- return a zero exit code to indicate success.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>diff-cmd</literal></term>
- <listitem>
- <para>This specifies the absolute path of a differencing
- program, used when Subversion generates
- <quote>diff</quote> output (such as when using the
- <command>svn diff</command> command). By default
- Subversion uses an internal differencing
- library—setting this option will cause it to
- perform this task using an external program. See
- <xref linkend="svn.advanced.externaldifftools"/> for
- more details on using such programs.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>diff3-cmd</literal></term>
- <listitem>
- <para>This specifies the absolute path of a three-way
- differencing program. Subversion uses this program to
- merge changes made by the user with those received
- from the repository. By default Subversion uses an
- internal differencing library—setting this
- option will cause it to perform this task using an
- external program. See <xref
- linkend="svn.advanced.externaldifftools"/> for more
- details on using such programs.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>diff3-has-program-arg</literal></term>
- <listitem>
- <para>This flag should be set to <literal>true</literal>
- if the program specified by the
- <literal>diff3-cmd</literal> option accepts a
- <option>--diff-program</option> command-line
- parameter.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>The <literal>tunnels</literal> section allows you to
- define new tunnel schemes for use with
- <command>svnserve</command> and <literal>svn://</literal>
- client connections. For more details, see <xref
- linkend="svn.serverconfig.svnserve.sshauth"/>.</para>
-
- <para>The <literal>miscellany</literal> section is where
- everything that doesn't belong elsewhere winds up.
- <footnote>
- <para>Anyone for potluck dinner?</para>
- </footnote>
- In this section, you can find:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>global-ignores</literal></term>
- <listitem>
- <para>When running the <command>svn status</command>
- command, Subversion lists unversioned files and
- directories along with the versioned ones, annotating
- them with a <literal>?</literal> character (see <xref
- linkend="svn.tour.cycle.examine.status" />). Sometimes, it can
- be annoying to see uninteresting, unversioned
- items—for example, object files that result from
- a program's compilation—in this display. The
- <literal>global-ignores</literal> option is a list of
- whitespace-delimited globs which describe the names of
- files and directories that Subversion should not
- display unless they are versioned. The default value
- is <literal>*.o *.lo *.la #*# .*.rej *.rej .*~ *~
- .#* .DS_Store</literal>.</para>
-
- <para>As well as <command>svn status</command>, the
- <command>svn add</command> and <command>svn import</command>
- commands also ignore files that match the list
- when they are scanning a directory. You can override this
- behaviour for a single instance of any of these commands
- by explicitly specifying the file name, or by using
- the <option>--no-ignore</option> command-line flag.</para>
-
- <para>For information on more fine-grained control of
- ignored items, see <xref linkend="svn.advanced.props.special.ignore"
- />.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>enable-auto-props</literal></term>
- <listitem>
- <para>This instructs Subversion to automatically set
- properties on newly added or imported files. The
- default value is <literal>no</literal>, so set this to
- <literal>yes</literal> to enable Auto-props.
- The <literal>auto-props</literal> section of this file
- specifies which properties are to be set on which files.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>log-encoding</literal></term>
- <listitem>
- <para>This variable sets the default character set
- encoding for commit log messages. It's a permanent
- form of the <option>--encoding</option> option (see
- <xref linkend="svn.ref.svn.sw"/>). The Subversion
- repository stores log messages in UTF-8, and assumes
- that your log message is written using your operating
- system's native locale. You should specify a
- different encoding if your commit messages are written
- in any other encoding.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>use-commit-times</literal></term>
- <listitem>
- <para>Normally your working copy files have timestamps
- that reflect the last time they were touched by any
- process, whether that be your own editor or by some
- <command>svn</command> subcommand. This is generally
- convenient for people developing software, because
- build systems often look at timestamps as a way of
- deciding which files need to be recompiled.</para>
-
- <para>In other situations, however, it's sometimes nice
- for the working copy files to have timestamps that
- reflect the last time they were changed in the
- repository. The <command>svn export</command> command
- always places these <quote>last-commit
- timestamps</quote> on trees that it produces. By
- setting this config variable to
- <literal>yes</literal>, the <command>svn
- checkout</command>, <command>svn update</command>,
- <command>svn switch</command>, and <command>svn
- revert</command> commands will also set last-commit
- timestamps on files that they touch.</para>
- </listitem>
- </varlistentry>
-
- <!-- ###TODO add description of other options shown in example
- registry file, e.g., template-root -->
- </variablelist>
-
- <para>The <literal>auto-props</literal> section controls
- the Subversion client's ability to automatically set
- properties on files when they are added or imported.
- It contains any number of key-value pairs in the
- format <literal>PATTERN = PROPNAME=PROPVALUE</literal>
- where <literal>PATTERN</literal> is a file pattern
- that matches a set of filenames and the rest of the
- line is the property and its value. Multiple matches
- on a file will result in multiple propsets for that
- file; however, there is no guarantee that auto-props
- will be applied in the order in which they are listed
- in the config file, so you can't have one rule
- <quote>override</quote> another. You can find several
- examples of auto-props usage in the
- <filename>config</filename> file. Lastly, don't
- forget to set <literal>enable-auto-props</literal> to
- <literal>yes</literal> in the <literal>miscellany</literal>
- section if you want to enable auto-props.</para>
-
- </sect3>
-
- </sect2>
- </sect1>
-
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.advanced.props">
- <title>Properties</title>
-
- <para>We've already covered in detail how Subversion stores and
- retrieves various versions of files and directories in its
- repository. Whole chapters have been devoted to this most
- fundamental piece of functionality provided by the tool. And
- if the versioning support stopped there, Subversion would still
- be complete from a version control perspective. But it
- doesn't stop there.</para>
-
- <para>In addition to versioning your directories and files,
- Subversion provides interfaces for adding, modifying, and
- removing versioned metadata on each of your versioned
- directories and files. We refer to this metadata as
- <firstterm>properties</firstterm>, and they can be thought of as
- two-column tables that map property names to arbitrary values
- attached to each item in your working copy. Generally speaking,
- the names and values of the properties can be whatever you want
- them to be, with the constraint that the names must be
- human-readable text. And the best part about these properties
- is that they, too, are versioned, just like the textual contents
- of your files. You can modify, commit, and revert property
- changes as easily as committing textual changes. And you
- receive other people's property changes as you update your
- working copy.</para>
-
- <sidebar>
- <title>Other Properties in Subversion</title>
-
- <para>Properties show up elsewhere in Subversion, too. Just as
- files and directories may have arbitrary property names and
- values attached to them, each revision as a whole may have
- arbitrary properties attached to it. The same constraints
- apply—human-readable, text names and anything-you-want,
- binary values—except that revision properties are not
- versioned. See <xref linkend="svn.reposadmin.basics.revprops" /> for more
- information on these unversioned properties.</para>
- </sidebar>
-
- <para>In this section, we will examine the utility—both to
- users of Subversion, and to Subversion itself—of property
- support. You'll learn about the property-related
- <command>svn</command> subcommands, and how property
- modifications affect your normal Subversion workflow.
- Hopefully, you'll be convinced that Subversion properties can
- enhance your version control experience.</para>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.props.why">
- <title>Why Properties?</title>
-
- <para>Properties can be very useful additions to your working
- copy. In fact, Subversion itself uses properties to house
- special information, and as a way to denote that certain
- special processing might be needed. Likewise, you can use
- properties for your own purposes. Of course, anything you can
- do with properties you could also do using regular versioned
- files, but consider the following example of Subversion
- property use.</para>
-
- <para>Say you wish to design a website that houses many digital
- photos, and displays them with captions and a datestamp. Now,
- your set of photos is constantly changing, so you'd like to
- have as much of this site automated as possible. These photos
- can be quite large, so as is common with sites of this nature,
- you want to provide smaller thumbnail images to your site
- visitors. You can do this with traditional files. That is,
- you can have your <filename>image123.jpg</filename> and an
- <filename>image123-thumbnail.jpg</filename> side-by-side in a
- directory. Or if you want to keep the filenames the same, you
- might have your thumbnails in a different directory, like
- <filename>thumbnails/image123.jpg</filename>. You can also
- store your captions and datestamps in a similar fashion, again
- separated from the original image file. Soon, your tree of
- files is a mess, and grows in multiples with each new photo
- added to the site.</para>
-
- <para>Now consider the same setup using Subversion's file
- properties. Imagine having a single image file,
- <filename>image123.jpg</filename>, and then properties set on
- that file named <literal>caption</literal>,
- <literal>datestamp</literal>, and even
- <literal>thumbnail</literal>. Now your working copy directory
- looks much more manageable—in fact, it looks like there
- are nothing but image files in it. But your automation
- scripts know better. They know that they can use
- <command>svn</command> (or better yet, they can use the
- Subversion language bindings—see <xref
- linkend="svn.developer.usingapi.otherlangs" />) to dig out the extra
- information that your site needs to display without having to
- read an index file or play path manipulation games.</para>
-
- <para>How (and if) you use Subversion properties is up to you.
- As we mentioned, Subversion has it own uses for properties,
- which we'll discuss a little later in this chapter. But
- first, let's discuss how to manipulate properties using the
- <command>svn</command> program.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.props.manip">
- <title>Manipulating Properties</title>
-
- <para>The <command>svn</command> command affords a few ways to
- add or modify file and directory properties. For properties
- with short, human-readable values, perhaps the simplest way to
- add a new property is to specify the property name and value
- on the command-line of the <command>propset</command>
- subcommand.</para>
-
- <screen>
-$ svn propset copyright '(c) 2003 Red-Bean Software' calc/button.c
-property 'copyright' set on 'calc/button.c'
-$
-</screen>
-
- <para>But we've been touting the flexibility that Subversion
- offers for your property values. And if you are planning to
- have a multi-line textual, or even binary, property value, you
- probably do not want to supply that value on the command-line.
- So the <command>propset</command> subcommand takes a
- <option>--file</option> (<option>-F</option>) option for
- specifying the name of
- a file which contains the new property value.</para>
-
- <screen>
-$ svn propset license -F /path/to/LICENSE calc/button.c
-property 'license' set on 'calc/button.c'
-$
-</screen>
-
- <para>There are some restrictions on the names you can use for
- properties. A property name must start with a letter, a colon
- (<literal>:</literal>), or an underscore
- (<literal>_</literal>); after that, you can also use digits,
- hyphens (<literal>-</literal>), and periods
- (<literal>.</literal>).
- <footnote>
- <para>If you're familiar with XML, this is pretty much the
- ASCII subset of the syntax for XML "Name".</para>
- </footnote>
- </para>
-
- <para>In addition to the <command>propset</command> command, the
- <command>svn</command> program supplies the
- <command>propedit</command> command. This command uses the
- configured editor program (see <xref
- linkend="svn.advanced.confarea.opts.config" />) to add or modify properties.
- When you run the command, <command>svn</command> invokes your
- editor program on a temporary file that contains the current
- value of the property (or which is empty, if you are adding a
- new property). Then, you just modify that value in your
- editor program until it represents the new value you wish to
- store for the property, save the temporary file, and then exit
- the editor program. If Subversion detects that you've
- actually changed the existing value of the property, it will
- accept that as the new property value. If you exit your
- editor without making any changes, no property modification
- will occur.</para>
-
- <screen>
-$ svn propedit copyright calc/button.c ### exit the editor without changes
-No changes to property 'copyright' on 'calc/button.c'
-$
-</screen>
-
- <para>We should note that, as with other <command>svn</command>
- subcommands, those related to properties can act on multiple
- paths at once. This enables you to modify properties on whole
- sets of files with a single command. For example, we could
- have done:</para>
-
- <screen>
-$ svn propset copyright '(c) 2002 Red-Bean Software' calc/*
-property 'copyright' set on 'calc/Makefile'
-property 'copyright' set on 'calc/button.c'
-property 'copyright' set on 'calc/integer.c'
-…
-$
-</screen>
-
- <para>All of this property adding and editing isn't really very
- useful if you can't easily get the stored property value. So
- the <command>svn</command> program supplies two subcommands
- for displaying the names and values of properties stored on
- files and directories. The <command>svn proplist</command>
- command will list the names of properties that exist on a
- path. Once you know the names of the properties on the node,
- you can request their values individually using <command>svn
- propget</command>. This command will, given a path (or set of
- paths) and a property name, print the value of the property to
- the standard output stream.</para>
-
- <screen>
-$ svn proplist calc/button.c
-Properties on 'calc/button.c':
- copyright
- license
-$ svn propget copyright calc/button.c
-(c) 2003 Red-Bean Software
-</screen>
-
- <para>There's even a variation of the
- <command>proplist</command> command that will list both the
- name and value of all of the properties. Simply supply the
- <option>--verbose</option> (<option>-v</option>) option.</para>
-
- <screen>
-$ svn proplist --verbose calc/button.c
-Properties on 'calc/button.c':
- copyright : (c) 2003 Red-Bean Software
- license : ================================================================
-Copyright (c) 2003 Red-Bean Software. All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions
-are met:
-
-1. Redistributions of source code must retain the above copyright
-notice, this list of conditions, and the recipe for Fitz's famous
-red-beans-and-rice.
-…
-</screen>
-
- <para>The last property-related subcommand is
- <command>propdel</command>. Since Subversion allows you to
- store properties with empty values, you can't remove a
- property altogether using <command>propedit</command> or
- <command>propset</command>. For example, this command will
- <emphasis>not</emphasis> yield the desired effect:</para>
-
- <screen>
-$ svn propset license '' calc/button.c
-property 'license' set on 'calc/button.c'
-$ svn proplist --verbose calc/button.c
-Properties on 'calc/button.c':
- copyright : (c) 2003 Red-Bean Software
- license :
-$
-</screen>
-
- <para>You need to use the <command>propdel</command> command to
- delete properties altogether. The syntax is similar to the
- other property commands:</para>
-
- <screen>
-$ svn propdel license calc/button.c
-property 'license' deleted from 'calc/button.c'.
-$ svn proplist --verbose calc/button.c
-Properties on 'calc/button.c':
- copyright : (c) 2003 Red-Bean Software
-$
-</screen>
-
- <para>Now that you are familiar with all of the
- property-related <command>svn</command> subcommands, let's see
- how property modifications affect the usual Subversion
- workflow. As we mentioned earlier, file and directory
- properties are versioned, just like your file contents. As a
- result, Subversion provides the same opportunities for
- merging—in cleanly or conflicting fashions—someone
- else's modifications into your own.</para>
-
- <sidebar>
- <title>Modifying Revision Properties</title>
-
- <para>Remember those unversioned revision properties? You can
- modify those, too, with the <command>svn</command> program.
- Simply add the <option>--revprop</option> command-line
- parameter, and specify the revision whose property you wish
- to modify. Since revisions are global, you don't need to
- specify a path in this case as long as you are positioned in
- the working copy of the repository whose revision property
- you wish to modify. For example, you might want to replace
- the commit log message of an existing revision.
- <footnote>
- <para>Fixing spelling errors, grammatical gotchas, and
- <quote>just-plain-wrongness</quote> in commit log
- messages is perhaps the most common use case for the
- <option>--revprop</option> option.</para>
- </footnote></para>
-
- <screen>
-$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop
-property 'svn:log' set on repository revision '11'
-$
-</screen>
-
- <para>Note that the ability to modify these unversioned
- properties must be explicitly added by the repository
- administrator (see <xref linkend="svn.reposadmin.create.hooks" />).
- Since the properties aren't versioned, you run the risk of
- losing information if you aren't careful with your edits.
- The repository administrator can setup methods to protect
- against this loss, and by default, modification of
- unversioned properties is disabled.</para>
-
- </sidebar>
-
- <para>And as with file contents, your property changes are local
- modifications, only made permanent when you commit them to the
- repository with <command>svn commit</command>. Your property
- changes can be easily unmade, too—the <command>svn
- revert</command> command will restore your files and
- directories to their un-edited states, contents, properties,
- and all. Also, you can receive interesting information about
- the state of your file and directory properties by using the
- <command>svn status</command> and <command>svn diff</command>
- commands.</para>
-
- <screen>
-$ svn status calc/button.c
- M calc/button.c
-$ svn diff calc/button.c
-Property changes on: calc/button.c
-___________________________________________________________________
-Name: copyright
- + (c) 2003 Red-Bean Software
-
-$
-</screen>
-
- <para>Notice how the <command>status</command> subcommand
- displays <literal>M</literal> in the second column instead of
- the first. That is because we have modified the properties on
- <filename>calc/button.c</filename>, but not modified its
- textual contents. Had we changed both, we would have seen
- <literal>M</literal> in the first column, too (see <xref
- linkend="svn.tour.cycle.examine.status" />).</para>
-
- <sidebar>
- <title>Property Conflicts</title>
-
- <para>As with file contents, local property modifications can
- conflict with changes committed by someone else. If you
- update your working copy directory and receive property
- changes on a versioned resource that clash with your own,
- Subversion will report that the resource is in a conflicted
- state.</para>
-
- <screen>
-% svn update calc
-M calc/Makefile.in
- C calc/button.c
-Updated to revision 143.
-$
-</screen>
-
- <para>Subversion will also create, in the same directory as
- the conflicted resource, a file with a
- <filename>.prej</filename> extension which contains the
- details of the conflict. You should examine the contents of
- this file so you can decide how to resolve the conflict.
- Until the conflict is resolved, you will see a
- <literal>C</literal> in the second column of <command>svn
- status</command> output for that resource, and attempts to
- commit your local modifications will fail.</para>
-
- <screen>
-$ svn status calc
- C calc/button.c
-? calc/button.c.prej
-$ cat calc/button.c.prej
-prop 'linecount': user set to '1256', but update set to '1301'.
-$
-</screen>
-
- <para>To resolve property conflicts, simply ensure that the
- conflicting properties contain the values that they should,
- and then use the <command>svn resolved</command> command to
- alert Subversion that you have manually resolved the
- problem.</para>
-
- </sidebar>
-
- <para>You might also have noticed the non-standard way that
- Subversion currently displays property differences. You can
- still run <command>svn diff</command> and redirect the output
- to create a usable patch file. The <command>patch</command>
- program will ignore property patches—as a rule, it
- ignores any noise it can't understand. This does
- unfortunately mean that to fully apply a patch generated by
- <command>svn diff</command>, any property modifications will
- need to be applied by hand.</para>
-
- <para>As you can see, the presence of property modifications has
- no outstanding effect on the typical Subversion workflow.
- Your general patterns of updating your working copy, checking
- the status of your files and directories, reporting on the
- modifications you have made, and committing those
- modifications to the repository are completely immune to the
- presence or absence of properties. The <command>svn</command>
- program has some additional subcommands for actually making
- property changes, but that is the only noticeable asymmetry.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.props.special">
-
- <title>Special Properties</title>
-
- <para>Subversion has no particular policy regarding
- properties—you can use them for any purpose. Subversion
- asks only that you not use property names that begin with the
- prefix <literal>svn:</literal>. That's the namespace that it
- sets aside for its own use. In fact, Subversion defines
- certain properties that have magical effects on the files and
- directories to which they are attached. In this section,
- we'll untangle the mystery, and describe how these special
- properties make your life just a little easier.</para>
-
- <sect3 id="svn.advanced.props.special.executable">
- <title><literal>svn:executable</literal></title>
-
- <para>The <literal>svn:executable</literal> property is used
- to control a versioned file's filesystem-level execute
- permission bit in a semi-automated way. This property has
- no defined values—its mere presence indicates a desire
- that the execute permission bit be kept enabled by Subversion.
- Removing this property will restore full control of the
- execute bit back to the operating system.</para>
-
- <para>On many operating systems, the ability to execute a file
- as a command is governed by the presence of an execute
- permission bit. This bit usually defaults to being
- disabled, and must be explicitly enabled by the user for
- each file that needs it. In a working copy, new files are
- being created all the time as new versions of existing files
- are received during an update. This means that you might
- enable the execute bit on a file, then update your working
- copy, and if that file was changed as part of the update,
- its execute bit might get disabled. So, Subversion provides
- the <literal>svn:executable</literal> property as a way to
- keep the execute bit enabled.</para>
-
- <para>This property has no effect on filesystems that have no
- concept of an executable permission bit, such as FAT32 and
- NTFS.
- <footnote>
- <para>The Windows filesystems use file extensions (such as
- <literal>.EXE</literal>, <literal>.BAT</literal>, and
- <literal>.COM</literal>) to denote executable
- files.</para>
- </footnote>
- Also, although it has no defined values, Subversion will force
- its value to <literal>*</literal> when setting this property.
- Finally, this property is valid only on files, not on
- directories.</para>
-
- </sect3>
-
- <sect3 id="svn.advanced.props.special.mime-type">
- <title><literal>svn:mime-type</literal></title>
-
- <para>The <literal>svn:mime-type</literal> property serves
- many purposes in Subversion. Besides being a
- general-purpose storage location for a file's Multipurpose
- Internet Mail Extensions (MIME) classification, the value of
- this property determines some behavioral characteristics
- of Subversion itself.</para>
-
- <para>For example, if a file's
- <literal>svn:mime-type</literal> property is set to a
- non-text MIME type (generally, something that doesn't begin
- with <literal>text/</literal>, though there are exceptions),
- Subversion will assume that the file contains
- binary—that is, not human-readable—data. One of
- the benefits that Subversion typically provides is
- contextual, line-based merging of changes received from the
- server during an update into your working file. But for
- files believed to contain binary data, there is no concept
- of a <quote>line</quote>. So, for those files, Subversion
- does not attempt to perform contextual merges during
- updates. Instead, any time you have locally modified a
- binary working copy file that is also being updated, your
- file is renamed with a <filename>.orig</filename> extension,
- and then Subversion stores a new working copy file that
- contains the changes received during the update, but not
- your own local modifications, at the original filename.
- This behavior is really for the protection of the user
- against failed attempts at performing contextual merges on
- files that simply cannot be contextually merged.</para>
-
- <para>Also, if the <literal>svn:mime-type</literal>
- property is set, then the Subversion Apache module will use
- its value to populate the <literal>Content-type:</literal>
- HTTP header when responding to GET requests. This gives a
- crucial clue about how to display a file when perusing
- your repository with a web browser.</para>
-
- </sect3>
-
- <sect3 id="svn.advanced.props.special.ignore">
- <title><literal>svn:ignore</literal></title>
-
- <para>The <literal>svn:ignore</literal> property contains a
- list of file patterns which certain Subversion operations
- will ignore. Perhaps the most commonly used special
- property, it works in conjunction with the
- <literal>global-ignores</literal> run-time configuration
- option (see <xref linkend="svn.advanced.confarea.opts.config" />) to
- filter unversioned files and directories out of commands
- <command>svn status</command>, <command>svn
- add</command>, and <command>svn import</command>.</para>
-
- <para>The rationale behind the <literal>svn:ignore</literal>
- property is easily explained. Subversion does not assume
- that every file or subdirectory in a working copy directory
- is intended for version control. Resources must be
- explicitly placed under Subversion's management using the
- <command>svn add</command> or <command>svn import</command>
- commands. As a result, there are often many resources in a
- working copy that are not versioned.</para>
-
- <para>Now, the <command>svn status</command> command displays
- as part of its output every unversioned file or subdirectory
- in a working copy that is not already filtered out by the
- <literal>global-ignores</literal> option (or its built-in
- default value). This is done so that users can see if
- perhaps they've forgotten to add a resource to version
- control.</para>
-
- <para>But Subversion cannot possibly guess the names of
- every resource that should be ignored. Also, quite often
- there are things that should be ignored in
- <emphasis>every</emphasis> working copy of a particular
- repository. To force every user of that repository to add
- patterns for those resources to their run-time configuration
- areas would be not just a burden, but has the potential to
- clash with the configuration needs of other working copies
- that the user has checked out.</para>
-
- <para>The solution is to store ignore patterns that are unique
- to the resources likely to appear in a given directory with
- the directory itself. Common examples of unversioned
- resources that are basically unique to a directory, yet
- likely to appear there, include output from program
- compilations. Or—to use an example more appropriate
- to this book—the HTML, PDF, or PostScript files
- generated as the result of a conversion of some source
- DocBook XML files to a more legible output format.</para>
-
- <sidebar>
- <title>Ignore Patterns for CVS Users</title>
-
- <para>The Subversion <literal>svn:ignore</literal> property
- is very similar in syntax and function to the CVS
- <filename>.cvsignore</filename> file. In fact, if you are
- migrating a CVS working copy to Subversion, you can
- directly migrate the ignore patterns by using the
- <filename>.cvsignore</filename> file as input file to the
- <command>svn propset</command> command:</para>
-
- <screen>
-$ svn propset svn:ignore -F .cvsignore .
-property 'svn:ignore' set on '.'
-$
-</screen>
-
- <para>There are, however, some differences in the ways that
- CVS and Subversion handle ignore patterns. The two systems
- use the ignore patterns at some different times, and there
- are slight discrepancies in what the ignore patterns apply
- to. Also, Subversion does not recognize the use of the
- <literal>!</literal> pattern as a reset back to having no
- ignore patterns at all.</para>
-
- </sidebar>
-
- <para>For this purpose, the <literal>svn:ignore</literal>
- property is the solution. Its value is a multi-line
- collection of file patterns, one pattern per line. The
- property is set on the directory in which you wish the
- patterns to be applied.
- <footnote>
- <para>The patterns are strictly for that
- directory—they do not carry recursively into
- subdirectories.</para>
- </footnote>
- For example, say you have the following output from
- <command>svn status</command>:</para>
-
- <screen>
-$ svn status calc
- M calc/button.c
-? calc/calculator
-? calc/data.c
-? calc/debug_log
-? calc/debug_log.1
-? calc/debug_log.2.gz
-? calc/debug_log.3.gz
-</screen>
-
- <para>In this example, you have made some property
- modifications to <filename>button.c</filename>, but in your
- working copy you also have some unversioned files:
- the latest <filename>calculator</filename> program
- that you've compiled from your source code, a source file
- named <filename>data.c</filename>, and a set of debugging
- output log files. Now, you know that your build system
- always results in the <filename>calculator</filename>
- program being generated.
- <footnote>
- <para>Isn't that the whole point of a build system?</para>
- </footnote>
- And you know that your test suite always leaves those
- debugging log files lying around. These facts are true for
- all working copies, not just your own. And you know that
- you aren't interested in seeing those things every time you
- run <command>svn status</command>. So you use <command>svn
- propedit svn:ignore calc</command> to add some ignore
- patterns to the <filename>calc</filename> directory. For
- example, you might add this as the new value of the
- <literal>svn:ignore</literal> property:</para>
-
- <programlisting>
-calculator
-debug_log*
-</programlisting>
-
- <para>After you've added this property, you will now have a
- local property modification on the <filename>calc</filename>
- directory. But notice what else is different about your
- <command>svn status</command> output:</para>
-
- <screen>
-$ svn status
- M calc
- M calc/button.c
-? calc/data.c
-</screen>
-
- <para>Now, all the cruft is missing from the output! Of
- course, those files are still in your working copy.
- Subversion is simply not reminding you that they are present
- and unversioned. And now with all the trivial noise removed
- from the display, you are left with more interesting
- items—such as that source code file that you probably
- forgot to add to version control.</para>
-
- <para>If you want to see the ignored files, you can pass the
- <option>--no-ignore</option> option to Subversion:</para>
-
- <screen>
-$ svn status --no-ignore
- M calc/button.c
-I calc/calculator
-? calc/data.c
-I calc/debug_log
-I calc/debug_log.1
-I calc/debug_log.2.gz
-I calc/debug_log.3.gz
-</screen>
-
- <para>The list of patterns to ignore is also used by
- <command>svn add</command> and <command>svn
- import</command>. Both of these operations involve asking
- 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 to determine which files
- should not be swept into the version control system as part
- of a larger recursive addition or import operation.</para>
-
- </sect3>
-
- <sect3 id="svn.advanced.props.special.keywords">
- <title><literal>svn:keywords</literal></title>
-
- <para>Subversion has the ability to substitute
- <firstterm>keywords</firstterm>—pieces of useful,
- dynamic information about a versioned file—into the
- contents of the file itself. Keywords generally describe
- information about the last time the file was known to be
- modified. Because this information changes each time the
- file changes, and more importantly, just
- <emphasis>after</emphasis> the file changes, it is a hassle
- for any process except the version control system to keep
- the data completely up-to-date. Left to human authors, the
- information would inevitably grow stale.</para>
-
- <para>For example, say you have a document in which you would
- like to display the last date on which it was modified. You
- could burden every author of that document to, just before
- committing their changes, also tweak the part of the
- document that describes when it was last changed. But
- sooner or later, someone would forget to do that. Instead
- simply ask Subversion to perform keyword substitution on the
- <literal>LastChangedDate</literal> keyword. You control
- where the keyword is inserted into your document by placing
- a <firstterm>keyword anchor</firstterm> at the desired
- location in the file. This anchor is just a string of text
- formatted as
- <literal>$</literal><replaceable>KeywordName</replaceable><literal>$</literal>.</para>
-
- <para>All keywords are case-sensitive where they appear as
- anchors in files: you must use the correct capitalization in
- order for the keyword to be expanded. You should consider the
- value of the <literal>svn:keywords</literal> property to be
- case-sensitive too—certain keyword names will be recognized
- regardless of case, but this behavior is deprecated.</para>
-
- <para>Subversion defines the list of keywords available for
- substitution. That list contains the following five keywords,
- some of which have aliases that you can also use:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>Date</literal></term>
- <listitem>
- <para>This keyword describes the last time the file was
- known to have been changed in the repository, and
- looks something like <literal>$Date:
- 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002)
- $</literal>. It may also be specified as
- <literal>LastChangedDate</literal>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>Revision</literal></term>
- <listitem>
- <para>This keyword describes the last known revision in
- which this file changed in the repository, and looks
- something like <literal>$Revision: 144 $</literal>.
- It may also be specified as
- <literal>LastChangedRevision</literal> or
- <literal>Rev</literal>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>Author</literal></term>
- <listitem>
- <para>This keyword describes the last known user to
- change this file in the repository, and looks
- something like <literal>$Author: harry $</literal>.
- It may also be specified as
- <literal>LastChangedBy</literal>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>HeadURL</literal></term>
- <listitem>
- <para>This keyword describes the full URL to the latest
- version of the file in the repository, and looks
- something like <literal>$HeadURL:
- http://svn.collab.net/repos/trunk/README $</literal>.
- It may be abbreviated as
- <literal>URL</literal>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>Id</literal></term>
- <listitem>
- <para>This keyword is a compressed combination of the
- other keywords. Its substitution looks something like
- <literal>$Id: calc.c 148 2002-07-28 21:30:43Z sally
- $</literal>, and is interpreted to mean that the file
- <filename>calc.c</filename> was last changed in revision
- 148 on the evening of July 28, 2002 by the user
- <literal>sally</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Simply adding keyword anchor text to your file does
- nothing special. Subversion will never attempt to perform
- textual substitutions on your file contents unless
- explicitly asked to do so. After all, you might be writing
- a document
- <footnote>
- <para>… or maybe even a section of a book …</para>
- </footnote>
- about how to use keywords, and you don't want Subversion to
- substitute your beautiful examples of un-substituted keyword
- anchors!</para>
-
- <para>To tell Subversion whether or not to substitute keywords
- on a particular file, we again turn to the property-related
- subcommands. The <literal>svn:keywords</literal> property,
- when set on a versioned file, controls which keywords will
- be substituted on that file. The value is a space-delimited
- list of the keyword names or aliases found in the previous
- table.</para>
-
- <para>For example, say you have a versioned file named
- <filename>weather.txt</filename> that looks like
- this:</para>
-
- <programlisting>
-Here is the latest report from the front lines.
-$LastChangedDate$
-$Rev$
-Cumulus clouds are appearing more frequently as summer approaches.
-</programlisting>
-
- <para>With no <literal>svn:keywords</literal> property set on
- that file, Subversion will do nothing special. Now, let's
- enable substitution of the
- <literal>LastChangedDate</literal> keyword.</para>
-
- <screen>
-$ svn propset svn:keywords "Date Author" weather.txt
-property 'svn:keywords' set on 'weather.txt'
-$
-</screen>
-
- <para>Now you have made a local property modification on the
- <filename>weather.txt</filename> file. You will see no
- changes to the file's contents (unless you made some of your
- own prior to setting the property). Notice that the file
- contained a keyword anchor for the <literal>Rev</literal>
- keyword, yet we did not include that keyword in the property
- value we set. Subversion will happily ignore requests to
- substitute keywords that are not present in the file, and
- will not substitute keywords that are not present in the
- <literal>svn:keywords</literal> property value.</para>
-
- <sidebar>
- <title>Keywords and Spurious Differences</title>
-
- <para>The user-visible result of keyword substitution might
- lead you to think that every version of a file with that
- feature in use differs from the previous version in at
- least the area where the keyword anchor was placed.
- However, this is actually not the case. While checking
- for local modifications during <command>svn
- diff</command>, and before transmitting those local
- modifications during <command>svn commit</command>,
- Subversion <quote>un-substitutes</quote> any keywords that
- it previously substituted. The result is that the
- versions of the file that are stored in the repository
- contain only the real modifications that users make to the
- file.</para>
-
- </sidebar>
-
- <para>Immediately after you commit this property change,
- Subversion will update your working file with the new
- substitute text. Instead of seeing your keyword anchor
- <literal>$LastChangedDate$</literal>, you'll see its
- substituted result. That result also contains the name of
- the keyword, and continues to be bounded by the dollar sign
- (<literal>$</literal>) characters. And as we predicted, the
- <literal>Rev</literal> keyword was not substituted because
- we didn't ask for it to be.</para>
-
- <para>Note also that we set the <literal>svn:keywords</literal>
- property to <quote>Date Author</quote> yet the keyword
- anchor used the alias <literal>$LastChangedDate$</literal>
- and still expanded correctly.</para>
-
- <screen>
-Here is the latest report from the front lines.
-$LastChangedDate: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002) $
-$Rev$
-Cumulus clouds are appearing more frequently as summer approaches.
-</screen>
-
- <para>If someone else now commits a change to
- <filename>weather.txt</filename>, your copy of that file
- will continue to display the same substituted keyword value
- as before—until you update your working copy. At that
- time the keywords in your <filename>weather.txt</filename>
- file will be re-substituted with information that
- reflects the most recent known commit to that file.</para>
-
- <para>Subversion 1.2 introduced a new variant of the keyword
- syntax which brought additional, useful—though perhaps
- atypical—functionality. You can now tell Subversion
- to maintain a fixed length (in terms of the number of bytes
- consumed) for the substituted keyword. By using a
- double-colon (<literal>::</literal>) after the keyword name,
- followed by a number of space characters, you define that
- fixed width. When Subversion goes to substitute your
- keyword for the keyword and its value, it will essentially
- replace only those space characters, leaving the overall
- width of the keyword field unchanged. If the substituted
- value is shorter than the defined field width, there will be
- extra padding characters (spaces) at the end of the
- substituted field; if it is too long, it is truncated with a
- special hash (<literal>#</literal>) character just before
- the final dollar sign terminator.</para>
-
- <para>For example, say you have a document in which you have
- some section of tabular data reflecting the document's
- Subversion keywords. Using the original Subversion keyword
- substitution syntax, your file might look something
- like:</para>
-
- <screen>
-$Rev$: Revision of last commit
-$Author$: Author of last commit
-$Date$: Date of last commit
-</screen>
-
- <para>Now, that looks nice and tabular at the start of things.
- But when you then commit that file (with keyword substitution
- enabled, of course), you see:</para>
-
- <screen>
-$Rev: 12 $: Revision of last commit
-$Author: harry $: Author of last commit
-$Date: 2006-03-15 02:33:03 -0500 (Wed, 15 Mar 2006) $: Date of last commit
-</screen>
-
- <para>The result is not so beautiful. And you might be
- tempted to then adjust the file after the substitution so
- that it again looks tabular. But that only holds as long as
- the keyword values are the same width. If the last
- committed revision rolls into a new place value (say, from
- 99 to 100), or if another person with a longer username
- commits the file, stuff gets all crooked again. However, if
- you are using Subversion 1.2 or better, you can use the new
- fixed-length keyword syntax, define some field widths that
- seem sane, and now your file might look like this:</para>
-
- <screen>
-$Rev:: $: Revision of last commit
-$Author:: $: Author of last commit
-$Date:: $: Date of last commit
-</screen>
-
- <para>You commit this change to your file. This time,
- Subversion notices the new fixed-length keyword syntax, and
- maintains the width of the fields as defined by the padding
- you placed between the double-colon and the trailing dollar
- sign. After substitution, the width of the fields is
- completely unchanged—the short values for
- <literal>Rev</literal> and <literal>Author</literal> are
- padded with spaces, and the long <literal>Date</literal>
- field is truncated by a hash character:</para>
-
- <screen>
-$Rev:: 13 $: Revision of last commit
-$Author:: harry $: Author of last commit
-$Date:: 2006-03-15 0#$: Date of last commit
-</screen>
-
- <para>The use of fixed-length keywords is especially handy
- when performing substitutions into complex file formats that
- themselves use fixed-length fields for data, or for which
- the stored size of a given data field is overbearingly
- difficult to modify from outside the format's native
- application (such as for Microsoft Office documents).</para>
-
- <warning>
- <para>Be aware that because the width of a keyword field is
- measured in bytes, the potential for corruption of
- multi-byte values exists. For example, a username which
- contains some multi-byte UTF-8 characters might suffer
- truncation in the middle of the string of bytes which make
- up one of those characters. The result will be a mere
- truncation when viewed at the byte level, but will likely
- appear as a string with an incorrect or garbled final
- character when viewed as UTF-8 text. It is conceivable
- that certain applications, when asked to load the file,
- would notice the broken UTF-8 text and deem the entire
- file corrupt, refusing to operate on the file
- altogether.</para>
- </warning>
-
- </sect3>
-
- <sect3 id="svn.advanced.props.special.eol-style">
- <title><literal>svn:eol-style</literal></title>
-
- <para>Unless otherwise noted using a versioned file's
- <literal>svn:mime-type</literal> property, Subversion
- assumes the file contains human-readable data. Generally
- speaking, Subversion only uses this knowledge to determine
- if contextual difference reports for that file are
- possible. Otherwise, to Subversion, bytes are bytes.</para>
-
- <para>This means that by default, Subversion doesn't pay any
- attention to the type of <firstterm>end-of-line (EOL)
- markers</firstterm> used in your files. Unfortunately,
- different operating systems use different tokens to represent
- the end of a line of text in a file. For example, the usual
- line ending token used by software on the Windows platform
- is a pair of ASCII control characters—carriage return
- (<literal>CR</literal>) and line feed
- (<literal>LF</literal>). Unix software, however, just uses
- the <literal>LF</literal> charact