[svnbook commit] r2572 - branches/ora-2e-reorg/src/en/book
cmpilato
noreply at red-bean.com
Wed Dec 20 15:34:59 CST 2006
Author: cmpilato
Date: Wed Dec 20 15:34:58 2006
New Revision: 2572
Added:
branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml
- copied, changed from r2570, /branches/ora-2e-reorg/src/en/book/ch-guided-tour.xml
branches/ora-2e-reorg/src/en/book/ch-fundamental-concepts.xml
- copied, changed from r2571, /branches/ora-2e-reorg/src/en/book/ch-basic-concepts.xml
Removed:
branches/ora-2e-reorg/src/en/book/ch-basic-concepts.xml
branches/ora-2e-reorg/src/en/book/ch-guided-tour.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-branching-and-merging.xml
branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml
Log:
Branch: ora-2e-reorg
Continue the reorganization effort.
* src/en/book/ch-fundamental-concepts.xml,
* src/en/book/ch-basic-usage.xml
Title tweaks.
* src/en/book/ch-guided-tour.xml (deleted)
Renamed to ch-basic-usage.xml.
* src/en/book/ch-basic-concepts.xml (deleted)
Renamed to ch-fundamental-concepts.xml.
* src/en/book/book.xml
Track renamed files.
* src/en/book/ch-advanced-topics.xml
(svn.advanced.confarea svn.advanced.confarea.layout
svn.advanced.confarea.windows-registry svn.advanced.confarea.opts
svn.advanced.confarea.opts.servers, svn.advanced.confarea.opts.config):
Moved to ch-customizing-svn.xml.
(svn.advanced.vendorbr, svn.advanced.vendorbr.general,
svn.advanced.vendorbr.svn_load_dirs): Moved to ch-branching-and-merging.xml.
* src/en/book/ch-customizing-svn.xml
(svn.advanced.confarea svn.advanced.confarea.layout
svn.advanced.confarea.windows-registry svn.advanced.confarea.opts
svn.advanced.confarea.opts.servers, svn.advanced.confarea.opts.config):
Moved from ch-advanced-topics.xml, with a TODO about moving
the reference-y stuff into the Reference chapter.
* src/en/book/ch-branching-and-merging.xml
(svn.advanced.vendorbr, svn.advanced.vendorbr.general,
svn.advanced.vendorbr.svn_load_dirs): Moved from ch-advanced-topics.xml.
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:34:58 2006
@@ -5,8 +5,8 @@
%vers;
<!ENTITY foreword SYSTEM "foreword.xml">
<!ENTITY ch00 SYSTEM "ch-preface.xml">
-<!ENTITY ch01 SYSTEM "ch-basic-concepts.xml">
-<!ENTITY ch02 SYSTEM "ch-guided-tour.xml">
+<!ENTITY ch01 SYSTEM "ch-fundamental-concepts.xml">
+<!ENTITY ch02 SYSTEM "ch-basic-usage.xml">
<!ENTITY ch03 SYSTEM "ch-advanced-topics.xml">
<!ENTITY ch04 SYSTEM "ch-branching-and-merging.xml">
<!ENTITY ch05 SYSTEM "ch-repository-admin.xml">
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:34:58 2006
@@ -39,647 +39,6 @@
</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>
-
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -2927,365 +2286,6 @@
the subcommand.</para>
</sect1>
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.advanced.vendorbr">
- <title>Vendor branches</title>
-
- <para>As is especially the case when developing software, the data
- that you maintain under version control is often closely related
- to, or perhaps dependent upon, someone else's data. Generally,
- the needs of your project will dictate that you stay as
- up-to-date as possible with the data provided by that external
- entity without sacrificing the stability of your own project.
- This scenario plays itself out all the time—anywhere that
- the information generated by one group of people has a direct
- effect on that which is generated by another group.</para>
-
- <para>For example, software developers might be working on an
- application which makes use of a third-party library.
- Subversion has just such a relationship with the Apache Portable
- Runtime library (see <xref linkend="svn.developer.usingapi.apr" />). The
- Subversion source code depends on the APR library for all its
- portability needs. In earlier stages of Subversion's
- development, the project closely tracked APR's changing API,
- always sticking to the <quote>bleeding edge</quote> of the
- library's code churn. Now that both APR and Subversion have
- matured, Subversion attempts to synchronize with APR's library
- API only at well-tested, stable release points.</para>
-
- <para>Now, if your project depends on someone else's information,
- there are several ways that you could attempt to synchronize that
- information with your own. Most painfully, you could issue oral
- or written instructions to all the contributors of your project,
- telling them to make sure that they have the specific versions
- of that third-party information that your project needs. If the
- third-party information is maintained in a Subversion
- repository, you could also use Subversion's externals
- definitions to effectively <quote>pin down</quote> specific
- versions of that information to some location in your own
- working copy directory (see <xref linkend="svn.advanced.externals" />).</para>
-
- <para>But sometimes you want to maintain custom modifications to
- third-party data in your own version control system. Returning
- to the software development example, programmers might need to
- make modifications to that third-party library for their own
- purposes. These modifications might include new functionality
- or bug fixes, maintained internally only until they become part
- of an official release of the third-party library. Or the
- changes might never be relayed back to the library maintainers,
- existing solely as custom tweaks to make the library further
- suit the needs of the software developers.</para>
-
- <para>Now you face an interesting situation. Your project could
- house its custom modifications to the third-party data in some
- disjointed fashion, such as using patch files or full-fledged
- alternate versions of files and directories. But these quickly
- become maintenance headaches, requiring some mechanism by which
- to apply your custom changes to the third-party data, and
- necessitating regeneration of those changes with each successive
- version of the third-party data that you track.</para>
-
- <para>The solution to this problem is to use <firstterm>vendor
- branches</firstterm>. A vendor branch is a directory tree in
- your own version control system that contains information
- provided by a third-party entity, or vendor. Each version of
- the vendor's data that you decide to absorb into your project is
- called a <firstterm>vendor drop</firstterm>.</para>
-
- <para>Vendor branches provide two key benefits. First, by storing
- the currently supported vendor drop in your own version control
- system, the members of your project never need to question
- whether they have the right version of the vendor's data. They
- simply receive that correct version as part of their regular
- working copy updates. Secondly, because the data lives in your
- own Subversion repository, you can store your custom changes to
- it in-place—you have no more need of an automated (or
- worse, manual) method for swapping in your customizations.</para>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.vendorbr.general">
- <title>General Vendor Branch Management Procedure</title>
-
- <para>Managing vendor branches generally works like this. You
- create a top-level directory (such as
- <filename>/vendor</filename>) to hold the vendor branches.
- Then you import the third party code into a subdirectory of
- that top-level directory. You then copy that subdirectory
- into your main development branch (for example,
- <filename>/trunk</filename>) at the appropriate location. You
- always make your local changes in the main development branch.
- With each new release of the code you are tracking you bring
- it into the vendor branch and merge the changes into
- <filename>/trunk</filename>, resolving whatever conflicts
- occur between your local changes and the upstream
- changes.</para>
-
- <para>Perhaps an example will help to clarify this algorithm.
- We'll use a scenario where your development team is creating a
- calculator program that links against a third-party complex
- number arithmetic library, libcomplex. We'll begin with the
- initial creation of the vendor branch, and the import of the
- first vendor drop. We'll call our vendor branch directory
- <filename>libcomplex</filename>, and our code drops will go
- into a subdirectory of our vendor branch called
- <filename>current</filename>. And since <command>svn
- import</command> creates all the intermediate parent
- directories it needs, we can actually accomplish both of these
- steps with a single command.</para>
-
- <screen>
-$ svn import /path/to/libcomplex-1.0 \
- http://svn.example.com/repos/vendor/libcomplex/current \
- -m 'importing initial 1.0 vendor drop'
-…
-</screen>
-
- <para>We now have the current version of the libcomplex source
- code in <filename>/vendor/libcomplex/current</filename>. Now,
- we tag that version (see <xref linkend="svn.branchmerge.tags" />)
- and then copy it into the main development branch. Our copy
- will create a new directory called
- <filename>libcomplex</filename> in our existing
- <filename>calc</filename> project directory. It is in this
- copied version of the vendor data that we will make our
- customizations.</para>
-
- <screen>
-$ svn copy http://svn.example.com/repos/vendor/libcomplex/current \
- http://svn.example.com/repos/vendor/libcomplex/1.0 \
- -m 'tagging libcomplex-1.0'
-…
-$ svn copy http://svn.example.com/repos/vendor/libcomplex/1.0 \
- http://svn.example.com/repos/calc/libcomplex \
- -m 'bringing libcomplex-1.0 into the main branch'
-…
-</screen>
-
- <para>We check out our project's main branch—which now
- includes a copy of the first vendor drop—and we get to
- work customizing the libcomplex code. Before we know it, our
- modified version of libcomplex is now completely integrated
- into our calculator program.
- <footnote>
- <para>And entirely bug-free, of course!</para>
- </footnote>
- </para>
-
- <para>A few weeks later, the developers of libcomplex release a
- new version of their library—version 1.1—which
- contains some features and functionality that we really want.
- We'd like to upgrade to this new version, but without losing
- the customizations we made to the existing version. What we
- essentially would like to do is to replace our current
- baseline version of libcomplex 1.0 with a copy of libcomplex
- 1.1, and then re-apply the custom modifications we previously
- made to that library to the new version. But we actually
- approach the problem from the other direction, applying the
- changes made to libcomplex between versions 1.0 and 1.1 to our
- modified copy of it.</para>
-
- <para>To perform this upgrade, we checkout a copy of our vendor
- branch, and replace the code in the
- <filename>current</filename> directory with the new libcomplex
- 1.1 source code. We quite literally copy new files on top of
- existing files, perhaps exploding the libcomplex 1.1 release
- tarball atop our existing files and directories. The goal
- here is to make our <filename>current</filename> directory
- contain only the libcomplex 1.1 code, and to ensure that all
- that code is under version control. Oh, and we want to do
- this with as little version control history disturbance as
- possible.</para>
-
- <para>After replacing the 1.0 code with 1.1 code, <command>svn
- status</command> will show files with local modifications as
- well as, perhaps, some unversioned or missing files. If we
- did what we were supposed to do, the unversioned files are
- only those new files introduced in the 1.1 release of
- libcomplex—we run <command>svn add</command> on those to
- get them under version control. The missing files are files
- that were in 1.0 but not in 1.1, and on those paths we run
- <command>svn delete</command>. Finally, once our
- <filename>current</filename> working copy contains only the
- libcomplex 1.1 code, we commit the changes we made to get it
- looking that way.</para>
-
- <para>Our <filename>current</filename> branch now contains the
- new vendor drop. We tag the new version (in the same way we
- previously tagged the version 1.0 vendor drop), and then merge
- the differences between the tag of the previous version and
- the new current version into our main development
- branch.</para>
-
- <screen>
-$ cd working-copies/calc
-$ svn merge http://svn.example.com/repos/vendor/libcomplex/1.0 \
- http://svn.example.com/repos/vendor/libcomplex/current \
- libcomplex
-… # resolve all the conflicts between their changes and our changes
-$ svn commit -m 'merging libcomplex-1.1 into the main branch'
-…
-</screen>
-
- <para>In the trivial use case, the new version of our
- third-party tool would look, from a files-and-directories
- point of view, just like the previous version. None of the
- libcomplex source files would have been deleted, renamed or
- moved to different locations—the new version would
- contain only textual modifications against the previous one.
- In a perfect world, our modifications would apply cleanly to
- the new version of the library, with absolutely no
- complications or conflicts.</para>
-
- <para>But things aren't always that simple, and in fact it is
- quite common for source files to get moved around between
- releases of software. This complicates the process of
- ensuring that our modifications are still valid for the new
- version of code, and can quickly degrade into a situation
- where we have to manually recreate our customizations in the
- new version. Once Subversion knows about the history of a
- given source file—including all its previous
- locations—the process of merging in the new version of
- the library is pretty simple. But we are responsible for
- telling Subversion how the source file layout changed from
- vendor drop to vendor drop.</para>
-
- </sect2>
-
- <!-- TODO: Try to clarify some of the steps for svn_load_dirs.pl
- (Garrett sez they've been "glossed over". Also, consider
- another section on bypassing svn_load_dirs.pl altogether and
- running with just svn merge, now that it ignores ancestry. -->
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.vendorbr.svn_load_dirs">
- <title><command>svn_load_dirs.pl</command></title>
-
- <para>Vendor drops that contain more than a few deletes,
- additions and moves complicate the process of upgrading to
- each successive version of the third-party data. So
- Subversion supplies the <command>svn_load_dirs.pl</command>
- script to assist with this process. This script automates the
- importing steps we mentioned in the general vendor branch
- management procedure to make sure that mistakes are minimized.
- You will still be responsible for using the merge commands to
- merge the new versions of the third-party data into your main
- development branch, but <command>svn_load_dirs.pl</command>
- can help you more quickly and easily arrive at that
- stage.</para>
-
- <para>In short, <command>svn_load_dirs.pl</command> is an
- enhancement to <command>svn import</command> that has several
- important characteristics:</para>
-
- <itemizedlist>
- <listitem>
- <para>It can be run at any point in time to bring an existing
- directory in the repository to exactly match an external
- directory, performing all the necessary adds and deletes,
- and optionally performing moves, too.</para>
- </listitem>
- <listitem>
- <para>It takes care of complicated series of operations between
- which Subversion requires an intermediate commit—such
- as before renaming a file or directory twice.</para>
- </listitem>
- <listitem>
- <para>It will optionally tag the newly imported directory.</para>
- </listitem>
- <listitem>
- <para>It will optionally add arbitrary properties to files and
- directories that match a regular expression.</para>
- </listitem>
- </itemizedlist>
-
- <para><command>svn_load_dirs.pl</command> takes three mandatory
- arguments. The first argument is the URL to the base
- Subversion directory to work in. This argument is followed by
- the URL—relative to the first argument—into which the
- current vendor drop will be imported. Finally, the third
- argument is the local directory to import. Using our previous
- example, a typical run of <command>svn_load_dirs.pl</command>
- might look like:</para>
-
- <screen>
-$ svn_load_dirs.pl http://svn.example.com/repos/vendor/libcomplex \
- current \
- /path/to/libcomplex-1.1
-…
-</screen>
-
- <para>You can indicate that you'd like
- <command>svn_load_dirs.pl</command> to tag the new vendor drop
- by passing the <option>-t</option> command-line option and
- specifying a tag name. This tag is another URL relative to
- the first program argument.</para>
-
- <screen>
-$ svn_load_dirs.pl -t libcomplex-1.1 \
- http://svn.example.com/repos/vendor/libcomplex \
- current \
- /path/to/libcomplex-1.1
-…
-</screen>
-
- <para>When you run <command>svn_load_dirs.pl</command>, it
- examines the contents of your existing <quote>current</quote>
- vendor drop, and compares them with the proposed new vendor
- drop. In the trivial case, there will be no files that are in
- one version and not the other, and the script will perform the
- new import without incident. If, however, there are
- discrepancies in the file layouts between versions,
- <command>svn_load_dirs.pl</command> will prompt you for how
- you would like to resolve those differences. For example, you
- will have the opportunity to tell the script that you know
- that the file <filename>math.c</filename> in version 1.0 of
- libcomplex was renamed to <filename>arithmetic.c</filename> in
- libcomplex 1.1. Any discrepancies not explained by moves
- are treated as regular additions and deletions.</para>
-
- <para>The script also accepts a separate configuration file for
- setting properties on files and directories matching a regular
- expression that are <emphasis>added</emphasis> to the
- repository. This configuration file is specified to
- <command>svn_load_dirs.pl</command> using the
- <option>-p</option> command-line option. Each line of the
- configuration file is a whitespace-delimited set of two or
- four values: a Perl-style regular expression to match the
- added path against, a control keyword (either
- <literal>break</literal> or <literal>cont</literal>), and then
- optionally a property name and value.</para>
-
- <screen>
-\.png$ break svn:mime-type image/png
-\.jpe?g$ break svn:mime-type image/jpeg
-\.m3u$ cont svn:mime-type audio/x-mpegurl
-\.m3u$ break svn:eol-style LF
-.* break svn:eol-style native
-</screen>
-
- <para>For each added path, the configured property changes whose
- regular expression matches the path are applied in order,
- unless the control specification is <literal>break</literal>
- (which means that no more property changes should be applied
- to that path). If the control specification is
- <literal>cont</literal>—an abbreviation for
- <literal>continue</literal>—then matching will continue
- with the next line of the configuration file.</para>
-
- <para>Any whitespace in the regular expression, property name,
- or property value must be surrounded by either single or
- double quote characters. You can escape quote characters that
- are not used for wrapping whitespace by preceding them with a
- backslash (<literal>\</literal>) character. The backslash
- escapes only quotes when parsing the configuration file, so do
- not protect any other characters beyond what is necessary for
- the regular expression.</para>
-
- </sect2>
- </sect1>
-
</chapter>
<!--
Copied: branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml (from r2570, /branches/ora-2e-reorg/src/en/book/ch-guided-tour.xml)
==============================================================================
--- /branches/ora-2e-reorg/src/en/book/ch-guided-tour.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml Wed Dec 20 15:34:58 2006
@@ -1,5 +1,5 @@
<chapter id="svn.tour">
- <title>Guided Tour</title>
+ <title>Basic Usage</title>
<simplesect>
Modified: branches/ora-2e-reorg/src/en/book/ch-branching-and-merging.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-branching-and-merging.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-branching-and-merging.xml Wed Dec 20 15:34:58 2006
@@ -2084,6 +2084,365 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
+ <sect1 id="svn.advanced.vendorbr">
+ <title>Vendor branches</title>
+
+ <para>As is especially the case when developing software, the data
+ that you maintain under version control is often closely related
+ to, or perhaps dependent upon, someone else's data. Generally,
+ the needs of your project will dictate that you stay as
+ up-to-date as possible with the data provided by that external
+ entity without sacrificing the stability of your own project.
+ This scenario plays itself out all the time—anywhere that
+ the information generated by one group of people has a direct
+ effect on that which is generated by another group.</para>
+
+ <para>For example, software developers might be working on an
+ application which makes use of a third-party library.
+ Subversion has just such a relationship with the Apache Portable
+ Runtime library (see <xref linkend="svn.developer.usingapi.apr" />). The
+ Subversion source code depends on the APR library for all its
+ portability needs. In earlier stages of Subversion's
+ development, the project closely tracked APR's changing API,
+ always sticking to the <quote>bleeding edge</quote> of the
+ library's code churn. Now that both APR and Subversion have
+ matured, Subversion attempts to synchronize with APR's library
+ API only at well-tested, stable release points.</para>
+
+ <para>Now, if your project depends on someone else's information,
+ there are several ways that you could attempt to synchronize that
+ information with your own. Most painfully, you could issue oral
+ or written instructions to all the contributors of your project,
+ telling them to make sure that they have the specific versions
+ of that third-party information that your project needs. If the
+ third-party information is maintained in a Subversion
+ repository, you could also use Subversion's externals
+ definitions to effectively <quote>pin down</quote> specific
+ versions of that information to some location in your own
+ working copy directory (see <xref linkend="svn.advanced.externals" />).</para>
+
+ <para>But sometimes you want to maintain custom modifications to
+ third-party data in your own version control system. Returning
+ to the software development example, programmers might need to
+ make modifications to that third-party library for their own
+ purposes. These modifications might include new functionality
+ or bug fixes, maintained internally only until they become part
+ of an official release of the third-party library. Or the
+ changes might never be relayed back to the library maintainers,
+ existing solely as custom tweaks to make the library further
+ suit the needs of the software developers.</para>
+
+ <para>Now you face an interesting situation. Your project could
+ house its custom modifications to the third-party data in some
+ disjointed fashion, such as using patch files or full-fledged
+ alternate versions of files and directories. But these quickly
+ become maintenance headaches, requiring some mechanism by which
+ to apply your custom changes to the third-party data, and
+ necessitating regeneration of those changes with each successive
+ version of the third-party data that you track.</para>
+
+ <para>The solution to this problem is to use <firstterm>vendor
+ branches</firstterm>. A vendor branch is a directory tree in
+ your own version control system that contains information
+ provided by a third-party entity, or vendor. Each version of
+ the vendor's data that you decide to absorb into your project is
+ called a <firstterm>vendor drop</firstterm>.</para>
+
+ <para>Vendor branches provide two key benefits. First, by storing
+ the currently supported vendor drop in your own version control
+ system, the members of your project never need to question
+ whether they have the right version of the vendor's data. They
+ simply receive that correct version as part of their regular
+ working copy updates. Secondly, because the data lives in your
+ own Subversion repository, you can store your custom changes to
+ it in-place—you have no more need of an automated (or
+ worse, manual) method for swapping in your customizations.</para>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.vendorbr.general">
+ <title>General Vendor Branch Management Procedure</title>
+
+ <para>Managing vendor branches generally works like this. You
+ create a top-level directory (such as
+ <filename>/vendor</filename>) to hold the vendor branches.
+ Then you import the third party code into a subdirectory of
+ that top-level directory. You then copy that subdirectory
+ into your main development branch (for example,
+ <filename>/trunk</filename>) at the appropriate location. You
+ always make your local changes in the main development branch.
+ With each new release of the code you are tracking you bring
+ it into the vendor branch and merge the changes into
+ <filename>/trunk</filename>, resolving whatever conflicts
+ occur between your local changes and the upstream
+ changes.</para>
+
+ <para>Perhaps an example will help to clarify this algorithm.
+ We'll use a scenario where your development team is creating a
+ calculator program that links against a third-party complex
+ number arithmetic library, libcomplex. We'll begin with the
+ initial creation of the vendor branch, and the import of the
+ first vendor drop. We'll call our vendor branch directory
+ <filename>libcomplex</filename>, and our code drops will go
+ into a subdirectory of our vendor branch called
+ <filename>current</filename>. And since <command>svn
+ import</command> creates all the intermediate parent
+ directories it needs, we can actually accomplish both of these
+ steps with a single command.</para>
+
+ <screen>
+$ svn import /path/to/libcomplex-1.0 \
+ http://svn.example.com/repos/vendor/libcomplex/current \
+ -m 'importing initial 1.0 vendor drop'
+…
+</screen>
+
+ <para>We now have the current version of the libcomplex source
+ code in <filename>/vendor/libcomplex/current</filename>. Now,
+ we tag that version (see <xref linkend="svn.branchmerge.tags" />)
+ and then copy it into the main development branch. Our copy
+ will create a new directory called
+ <filename>libcomplex</filename> in our existing
+ <filename>calc</filename> project directory. It is in this
+ copied version of the vendor data that we will make our
+ customizations.</para>
+
+ <screen>
+$ svn copy http://svn.example.com/repos/vendor/libcomplex/current \
+ http://svn.example.com/repos/vendor/libcomplex/1.0 \
+ -m 'tagging libcomplex-1.0'
+…
+$ svn copy http://svn.example.com/repos/vendor/libcomplex/1.0 \
+ http://svn.example.com/repos/calc/libcomplex \
+ -m 'bringing libcomplex-1.0 into the main branch'
+…
+</screen>
+
+ <para>We check out our project's main branch—which now
+ includes a copy of the first vendor drop—and we get to
+ work customizing the libcomplex code. Before we know it, our
+ modified version of libcomplex is now completely integrated
+ into our calculator program.
+ <footnote>
+ <para>And entirely bug-free, of course!</para>
+ </footnote>
+ </para>
+
+ <para>A few weeks later, the developers of libcomplex release a
+ new version of their library—version 1.1—which
+ contains some features and functionality that we really want.
+ We'd like to upgrade to this new version, but without losing
+ the customizations we made to the existing version. What we
+ essentially would like to do is to replace our current
+ baseline version of libcomplex 1.0 with a copy of libcomplex
+ 1.1, and then re-apply the custom modifications we previously
+ made to that library to the new version. But we actually
+ approach the problem from the other direction, applying the
+ changes made to libcomplex between versions 1.0 and 1.1 to our
+ modified copy of it.</para>
+
+ <para>To perform this upgrade, we checkout a copy of our vendor
+ branch, and replace the code in the
+ <filename>current</filename> directory with the new libcomplex
+ 1.1 source code. We quite literally copy new files on top of
+ existing files, perhaps exploding the libcomplex 1.1 release
+ tarball atop our existing files and directories. The goal
+ here is to make our <filename>current</filename> directory
+ contain only the libcomplex 1.1 code, and to ensure that all
+ that code is under version control. Oh, and we want to do
+ this with as little version control history disturbance as
+ possible.</para>
+
+ <para>After replacing the 1.0 code with 1.1 code, <command>svn
+ status</command> will show files with local modifications as
+ well as, perhaps, some unversioned or missing files. If we
+ did what we were supposed to do, the unversioned files are
+ only those new files introduced in the 1.1 release of
+ libcomplex—we run <command>svn add</command> on those to
+ get them under version control. The missing files are files
+ that were in 1.0 but not in 1.1, and on those paths we run
+ <command>svn delete</command>. Finally, once our
+ <filename>current</filename> working copy contains only the
+ libcomplex 1.1 code, we commit the changes we made to get it
+ looking that way.</para>
+
+ <para>Our <filename>current</filename> branch now contains the
+ new vendor drop. We tag the new version (in the same way we
+ previously tagged the version 1.0 vendor drop), and then merge
+ the differences between the tag of the previous version and
+ the new current version into our main development
+ branch.</para>
+
+ <screen>
+$ cd working-copies/calc
+$ svn merge http://svn.example.com/repos/vendor/libcomplex/1.0 \
+ http://svn.example.com/repos/vendor/libcomplex/current \
+ libcomplex
+… # resolve all the conflicts between their changes and our changes
+$ svn commit -m 'merging libcomplex-1.1 into the main branch'
+…
+</screen>
+
+ <para>In the trivial use case, the new version of our
+ third-party tool would look, from a files-and-directories
+ point of view, just like the previous version. None of the
+ libcomplex source files would have been deleted, renamed or
+ moved to different locations—the new version would
+ contain only textual modifications against the previous one.
+ In a perfect world, our modifications would apply cleanly to
+ the new version of the library, with absolutely no
+ complications or conflicts.</para>
+
+ <para>But things aren't always that simple, and in fact it is
+ quite common for source files to get moved around between
+ releases of software. This complicates the process of
+ ensuring that our modifications are still valid for the new
+ version of code, and can quickly degrade into a situation
+ where we have to manually recreate our customizations in the
+ new version. Once Subversion knows about the history of a
+ given source file—including all its previous
+ locations—the process of merging in the new version of
+ the library is pretty simple. But we are responsible for
+ telling Subversion how the source file layout changed from
+ vendor drop to vendor drop.</para>
+
+ </sect2>
+
+ <!-- TODO: Try to clarify some of the steps for svn_load_dirs.pl
+ (Garrett sez they've been "glossed over". Also, consider
+ another section on bypassing svn_load_dirs.pl altogether and
+ running with just svn merge, now that it ignores ancestry. -->
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.vendorbr.svn_load_dirs">
+ <title><command>svn_load_dirs.pl</command></title>
+
+ <para>Vendor drops that contain more than a few deletes,
+ additions and moves complicate the process of upgrading to
+ each successive version of the third-party data. So
+ Subversion supplies the <command>svn_load_dirs.pl</command>
+ script to assist with this process. This script automates the
+ importing steps we mentioned in the general vendor branch
+ management procedure to make sure that mistakes are minimized.
+ You will still be responsible for using the merge commands to
+ merge the new versions of the third-party data into your main
+ development branch, but <command>svn_load_dirs.pl</command>
+ can help you more quickly and easily arrive at that
+ stage.</para>
+
+ <para>In short, <command>svn_load_dirs.pl</command> is an
+ enhancement to <command>svn import</command> that has several
+ important characteristics:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It can be run at any point in time to bring an existing
+ directory in the repository to exactly match an external
+ directory, performing all the necessary adds and deletes,
+ and optionally performing moves, too.</para>
+ </listitem>
+ <listitem>
+ <para>It takes care of complicated series of operations between
+ which Subversion requires an intermediate commit—such
+ as before renaming a file or directory twice.</para>
+ </listitem>
+ <listitem>
+ <para>It will optionally tag the newly imported directory.</para>
+ </listitem>
+ <listitem>
+ <para>It will optionally add arbitrary properties to files and
+ directories that match a regular expression.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para><command>svn_load_dirs.pl</command> takes three mandatory
+ arguments. The first argument is the URL to the base
+ Subversion directory to work in. This argument is followed by
+ the URL—relative to the first argument—into which the
+ current vendor drop will be imported. Finally, the third
+ argument is the local directory to import. Using our previous
+ example, a typical run of <command>svn_load_dirs.pl</command>
+ might look like:</para>
+
+ <screen>
+$ svn_load_dirs.pl http://svn.example.com/repos/vendor/libcomplex \
+ current \
+ /path/to/libcomplex-1.1
+…
+</screen>
+
+ <para>You can indicate that you'd like
+ <command>svn_load_dirs.pl</command> to tag the new vendor drop
+ by passing the <option>-t</option> command-line option and
+ specifying a tag name. This tag is another URL relative to
+ the first program argument.</para>
+
+ <screen>
+$ svn_load_dirs.pl -t libcomplex-1.1 \
+ http://svn.example.com/repos/vendor/libcomplex \
+ current \
+ /path/to/libcomplex-1.1
+…
+</screen>
+
+ <para>When you run <command>svn_load_dirs.pl</command>, it
+ examines the contents of your existing <quote>current</quote>
+ vendor drop, and compares them with the proposed new vendor
+ drop. In the trivial case, there will be no files that are in
+ one version and not the other, and the script will perform the
+ new import without incident. If, however, there are
+ discrepancies in the file layouts between versions,
+ <command>svn_load_dirs.pl</command> will prompt you for how
+ you would like to resolve those differences. For example, you
+ will have the opportunity to tell the script that you know
+ that the file <filename>math.c</filename> in version 1.0 of
+ libcomplex was renamed to <filename>arithmetic.c</filename> in
+ libcomplex 1.1. Any discrepancies not explained by moves
+ are treated as regular additions and deletions.</para>
+
+ <para>The script also accepts a separate configuration file for
+ setting properties on files and directories matching a regular
+ expression that are <emphasis>added</emphasis> to the
+ repository. This configuration file is specified to
+ <command>svn_load_dirs.pl</command> using the
+ <option>-p</option> command-line option. Each line of the
+ configuration file is a whitespace-delimited set of two or
+ four values: a Perl-style regular expression to match the
+ added path against, a control keyword (either
+ <literal>break</literal> or <literal>cont</literal>), and then
+ optionally a property name and value.</para>
+
+ <screen>
+\.png$ break svn:mime-type image/png
+\.jpe?g$ break svn:mime-type image/jpeg
+\.m3u$ cont svn:mime-type audio/x-mpegurl
+\.m3u$ break svn:eol-style LF
+.* break svn:eol-style native
+</screen>
+
+ <para>For each added path, the configured property changes whose
+ regular expression matches the path are applied in order,
+ unless the control specification is <literal>break</literal>
+ (which means that no more property changes should be applied
+ to that path). If the control specification is
+ <literal>cont</literal>—an abbreviation for
+ <literal>continue</literal>—then matching will continue
+ with the next line of the configuration file.</para>
+
+ <para>Any whitespace in the regular expression, property name,
+ or property value must be surrounded by either single or
+ double quote characters. You can escape quote characters that
+ are not used for wrapping whitespace by preceding them with a
+ backslash (<literal>\</literal>) character. The backslash
+ escapes only quotes when parsing the configuration file, so do
+ not protect any other characters beyond what is necessary for
+ the regular expression.</para>
+
+ </sect2>
+ </sect1>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
<sect1 id="svn.branchmerge.summary">
<title>Summary</title>
Modified: branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml Wed Dec 20 15:34:58 2006
@@ -10,6 +10,652 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
+ <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>### TODO: Rework and move this section to the Reference ###</para>
+
+ <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.l10n">
<title>Localization</title>
Copied: branches/ora-2e-reorg/src/en/book/ch-fundamental-concepts.xml (from r2571, /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-fundamental-concepts.xml Wed Dec 20 15:34:58 2006
@@ -1,5 +1,5 @@
<chapter id="svn.basic">
- <title>Basic Concepts</title>
+ <title>Fundamental Concepts</title>
<simplesect>
<para>This chapter is a short, casual introduction to Subversion.
More information about the svnbook-dev
mailing list