[svnbook commit] r2646 - trunk/src/ru/book
dmitriy
noreply at red-bean.com
Sun Feb 4 07:36:47 CST 2007
Author: dmitriy
Date: Sun Feb 4 07:36:46 2007
New Revision: 2646
Added:
trunk/src/ru/book/app-quickstart.xml (contents, props changed)
- copied, changed from r2645, /trunk/src/ru/book/ch-introduction.xml
trunk/src/ru/book/ch-customizing-svn.xml (contents, props changed)
- copied, changed from r2644, /trunk/src/ru/book/ch-advanced-topics.xml
Removed:
trunk/src/ru/book/ch-introduction.xml
Modified:
trunk/src/ru/book/book.xml (contents, props changed)
trunk/src/ru/book/ch-advanced-topics.xml (contents, props changed)
trunk/src/ru/book/ch-basic-concepts.xml (contents, props changed)
Log:
Book Russian. Merge with changes from r2571 of the src/en/book. More detail in log for r2571.
Copied: trunk/src/ru/book/app-quickstart.xml (from r2645, /trunk/src/ru/book/ch-introduction.xml)
==============================================================================
--- /trunk/src/ru/book/ch-introduction.xml (original)
+++ trunk/src/ru/book/app-quickstart.xml Sun Feb 4 07:36:46 2007
@@ -1,44 +1,49 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="svn.intro">
+<appendix id="svn.intro">
<!-- @ENGLISH {{{
- <title>Introduction</title>
+ <title>Subversion Quick-Start Guide</title>
@ENGLISH }}} -->
- <title>Введение</title>
- <chapterinfo>
+ <title>Быстрый старт в Subversion</title>
+ <appendixinfo>
<othername id="svn.intro.architecture.dia-1.prepositional-case"
role="title-variant">рисунке 1.1, «Архитектура
Subversion»</othername>
- </chapterinfo>
+ </appendixinfo>
<!-- See also svn.preface.organization -->
<simplesect>
+
<!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Управление версиями — это искусство управления изменяющейся
- информацией. Это искусство долгое время было жизненно важным
- инструментом для программистов, которые большую часть своего времени
- пишут программу небольшими кусками, но иногда им нужно отменить все
- сегодняшние изменения. Но сфера применения систем управления версиями
- выходит далеко за пределы мира разработчиков программного обеспечения.
- Управление версиями требуется повсюду, где люди работают с постоянно
- изменяющейся информацией. Именно тогда на сцену выходит Subversion.</para>
+ <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>
+ @ENGLISH }}} -->
+ <para>Некоторые испытывают трудности поглощения новой технологии
+ читая приближение <quote>с верху вниз</quote>, предлагаемое этой
+ книгой. Этот раздел представляет собой очень короткое введение в
+ Subversion и предназначен для того, что бы помочь изучающим
+ <quote>снизу вверх</quote>. Если вы из тех, кто предпочитает
+ учиться на экспериментах то последующая демонстрация поможет
+ вам начать. По ходу дела мы давали ссылки на соответствующие
+ главы книги.
+ </para>
<!-- @ENGLISH {{{
- <para>This chapter contains a high-level introduction to
- Subversion—what it is; what it does; how to get it.</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>
@ENGLISH }}} -->
- <para>В этой главе даются общие знания о Subversion —
- что это такое, что она делает и как её получить.</para>
+ <para>Если вы не совсем знакомы с концепциями контроля версий или
+ моделью <quote>копирование-изменение-слияние</quote>, используемой
+ как CVS так и Subversion, перед тем как идти дальше, вам нужно
+ прочитать <xref linkend="svn.basic"/>.</para>
</simplesect>
@@ -142,55 +147,35 @@
<sect1 id="svn.intro.quickstart">
<!-- @ENGLISH {{{
- <title>A Quick Start</title>
- @ENGLISH }}} -->
- <title>Быстрый старт</title>
-
- <!-- @ENGLISH {{{
- <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>
@ENGLISH }}} -->
- <para>Некоторые испытывают трудности поглощения новой технологии
- читая приближение <quote>с верху вниз</quote>, предлагаемое этой
- книгой. Этот раздел представляет собой очень короткое введение в
- Subversion и предназначен для того, что бы помочь изучающим
- <quote>снизу вверх</quote>. Если вы из тех, кто предпочитает
- учиться на экспериментах то последующая демонстрация поможет
- вам начать. По ходу дела мы давали ссылки на соответствующие
- главы книги.
- </para>
+ <title>High-speed Tutorial</title>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Если вы не совсем знакомы с концепциями контроля версий или
- моделью <quote>копирование-изменение-слияние</quote>, используемой
- как CVS так и Subversion, перед тем как идти дальше, вам нужно
- прочитать <xref linkend="svn.basic"/>.</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>
<!-- @ENGLISH {{{
- <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
later (run <command>svn -ﳢ-version</command> to check.)</para>
@ENGLISH }}} -->
- <para>Последующий пример предполагает наличие у вас работающих
- Subversion клиента для командной строки <command>svn</command> и
- инструмента администрирования <command>svnadmin</command>.
- Кроме этого он рассчитан на то, что вы используете Subversion
- версии 1.2 или более поздней (для того, чтобы это проверить,
- выполните <command>svn --version</command>).</para>
+ <para>Примеры, используемые в этом приложении предполагают наличие у
+ вас работающих Subversion клиента для командной строки
+ <command>svn</command> и инструмента администрирования
+ <command>svnadmin</command>. Кроме этого он рассчитан на то, что вы
+ используете Subversion версии 1.2 или более поздней (для того, чтобы
+ это проверить, выполните <command>svn --version</command>).</para>
</note>
<!-- @ENGLISH {{{
@@ -434,14 +419,17 @@
знакомства с различными типами доступных серверных процессов
и методами их настройки.</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:
vim: tw=78:ft=svnbook
-->
Modified: trunk/src/ru/book/book.xml
==============================================================================
--- trunk/src/ru/book/book.xml (original)
+++ trunk/src/ru/book/book.xml Sun Feb 4 07:36:46 2007
@@ -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">
]>
@@ -112,6 +113,7 @@
&appa;
&appb;
&appc;
+ &appd;
&license;
</book>
Modified: trunk/src/ru/book/ch-advanced-topics.xml
==============================================================================
--- trunk/src/ru/book/ch-advanced-topics.xml (original)
+++ trunk/src/ru/book/ch-advanced-topics.xml Sun Feb 4 07:36:46 2007
@@ -4163,492 +4163,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: trunk/src/ru/book/ch-basic-concepts.xml
==============================================================================
--- trunk/src/ru/book/ch-basic-concepts.xml (original)
+++ trunk/src/ru/book/ch-basic-concepts.xml Sun Feb 4 07:36:46 2007
@@ -568,6 +568,78 @@
<para>Настало время перейти от абстракций к конкретике. В этом разделе мы покажем
реальные примеры использования Subversion.</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">
<!-- @ENGLISH {{{
Copied: trunk/src/ru/book/ch-customizing-svn.xml (from r2644, /trunk/src/ru/book/ch-advanced-topics.xml)
==============================================================================
--- /trunk/src/ru/book/ch-advanced-topics.xml (original)
+++ trunk/src/ru/book/ch-customizing-svn.xml Sun Feb 4 07:36:46 2007
@@ -1,4168 +1,18 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="svn.advanced">
+<chapter id="svn.customization">
<!-- @ENGLISH {{{
- <title>Advanced Topics</title>
+ <title>Customizing Your Subversion Experience</title>
@ENGLISH }}} -->
<title>Профессиональное использование Subversion</title>
<!-- See also svn.preface.organization -->
<simplesect>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Если эту книгу вы читали главу за главой, от начала до
- конца, то к настоящему моменту должны иметь достаточно знаний
- для использования Subversion клиента при выполнении типичных
- управлению версиями операций. Вы понимаете, как создавать
- рабочую копию. Знаете как используя команды <command>svn
- commit</command> и <command>svn update</command> отправлять и
- получать изменения. Возможно у вас уже даже выработался рефлекс
- бессознательного запуска <command>svn status</command>. Вы готовы
- применять Subversion в большинстве возможных типовых
- ситуаций.</para>
-
- <para>Однако предоставляемая Subversion функциональность не
- ограничивается <quote>типовыми операциями управления
- версиями</quote>.</para>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Эта глава рассказывает о не часто используемых возможностях
- Subversion. В ней мы рассмотрим поддержку свойств (или
- <quote>метаданных</quote>) и способы изменения стандартного поведения
- Subversion изменяя ее параметры времени выполнения. Мы расскажем
- как используя внешние зависимости заставить Subversion получать
- информацию из нескольких хранилищ. Подробно рассмотрим клиентские и
- серверные инструменты, входящие в поставку Subversion.</para>
-
- <para>Перед чтением этой главы, необходимо хорошо представлять
- механизмы версионированния файлов и директорий в Subversion.
- Если вы еще этого не прочитали или просто хотите освежить в памяти
- эту информацию, рекомендуем просмотреть <xref linkend="svn.basic" />
- и <xref linkend="svn.tour" />. После того как вы овладеете
- основами и примами, рассмотренными в этой главе, вы станете продвинутым
- пользователем Subversion!</para>
+ <para>### TODO ###</para>
</simplesect>
- <sect1 id="svn.advanced.confarea">
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <title>Параметры времени выполнения</title>
-
- <para>Subversion имеет множество контролируемых пользователем
- опциональных параметров поведения. Возможно пользователь
- хотел бы применять некоторые из этих параметров во всех
- операциях Subversion. Поэтому для того, что бы не заставлять
- пользователей помнить ключи командной строки используемые для
- указания этих параметров и не указывать их при всех выполняемых
- операциях, Subversion использует конфигурационные файлы, выделенные
- в область конфигурации Subversion.</para>
-
- <para><firstterm>Область конфигурации</firstterm> Subversion
- имеет двухуровневую иерархию имен параметров и их значений.
- Как правило, она сводится к отдельной директории, содержащей
- <firstterm>конфигурационные файлы</firstterm> (первый уровень)
- являющиеся простыми текстовыми файлами в стандартном INI формате
- (с <quote>разделами</quote>, обеспечивающими второй уровень).
- Эти файлы содержат директивы используемые клиентом для определения
- поведения клиента предпочитаемого пользователем, и могут быть легко
- отредактированы используя ваш любимый редактор (например, Emacs
- или vi).</para>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.confarea.layout">
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <title>Структура области конфигурации</title>
-
- <para>Во время первого запуска клиент для командной строки
- <command>svn</command> создает отдельную для каждого пользователя
- область конфигурации. На Unix-подобных системах эта директория
- называется <filename>.subversion</filename> и находиться в домашней
- директории пользователя. На Win32 системах Subversion создает
- папку с именем <filename>Subversion</filename> в области
- <filename>Application Data</filename> директории с профилем
- пользователя (которая, кстати говоря, обычно является скрытой
- директорией). Однако на этой платформе точное местоположение
- отличается от системы к системе и указывается в реестре
- Windows. <footnote><para>Переменная среды окружения
- <literal>APPDATA</literal> указывает на папку <filename>Application
- Data</filename> поэтому к этой директории можно всегда обращаться
- как к <filename>%APPDATA%\Subversion</filename>.</para></footnote>
- При обращении к пользовательской области конфигурации мы будем
- использовать ее Unix-название.</para>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>В дополнение к пользовательской области конфигурации,
- Subversion использует общесистемную область конфигурации. Это
- дает возможность системным администраторам устанавливать
- параметры по умолчанию для всех пользователей отдельно взятой
- машины. Помните, что системная область конфигурации не
- устанавливает безоговорочные правила — параметры, заданные
- пользовательской конфигурацией переопределяют системные параметры,
- а аргументы командной строки, передаваемые программе
- <command>svn</command>, имеют последнее слово. На Unix-подобных
- платформах ожидаемым местоположением системной области конфигурации
- является директория <filename>/etc/subversion</filename>; на
- Windows машинах ищется директория <filename>Subversion</filename>
- внутри общесистемной области <filename>Application Data</filename>
- (также определяемой реестром). В отличие от пользовательской,
- системную область конфигурации <command>svn</command> не
- создает.</para>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>На сегодняшний момент область конфигурации содержит три
- файла — два файла конфигурации (<filename>config</filename>
- и <filename>servers</filename>) и <filename>README.txt</filename>,
- который содержит описание INI формата. После их создания, эти файлы
- содержат значения по умолчанию для всех, поддерживаемых Subversion
- параметров, обычно закомментированных и объединенных с текстовым
- описанием значений ключей, влияющих на поведение Subversion.
- Для того, что бы изменить отдельный параметр все, что нужно, просто
- загрузить соответствующий файл в текстовый редактор и изменить
- значение нужного параметра. Если в какой-то момент вы захотите
- восстановить параметры по умолчанию, необходимо просто удалить
- (или переименовать) директорию с конфигурацией, после чего
- выполнить какую-то безобидную команду <command>svn</command>,
- например, <command>svn --version</command>. В результате будет
- создана новая директория с конфигурацией и содержимым по
- умолчанию.</para>
-
- <para>Кроме того, пользовательская область конфигурации содержит
- кеш идентификационной информации. Директория <filename>auth</filename>
- объединяет набор поддиректорий, содержащих кешированну информацию,
- используемую в различных, поддерживаемых Subversion методах
- авторизации. Эта директория создается так, что бы только сам
- пользователь имел право просматривать ее содержимое.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.confarea.windows-registry">
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <title>Конфигурация и реестр Windows</title>
-
- <para>В дополнение к обычным INI-настройкам, Subversion-клиент,
- работающий на платформе Windows, может использовать для
- хранения настроек Windows-реестр. Имена параметров и их значения
- точно такие же, как и в INI-файлах. Иерархия <quote>файлов</quote>
- сохраняется, только немного меняется способ адресации —
- файлы и разделы просто заменяются уровнями в дереве ключей
- реестра.</para>
-
- <para>За общесистемными настройками Subversion обращается к ключу
- <literal>HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion</literal>
- Например, параметр <literal>global-ignores</literal>, находящийся в
- разделе <literal>miscellany</literal> файла
- <filename>config</filename> будет находиться в <literal>HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Config\Miscellany\global-ignores</literal>. Пользовательские настройки хранятся в ключе
- <literal>HKEY_CURRENT_USER\Software\Tigris.org\Subversion</literal>.
- </para>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Параметры конфигурации, указанные в реестре обрабатываются
- <emphasis>до</emphasis> эквивалентных параметров в файлах
- конфигурации, поэтому они заменяются значениями, найденными,
- в файлах конфигурации. Другими словами, на Windows-системе
- приоритеты расположены в следующем порядке:</para>
-
- <orderedlist>
- <listitem>
- <para>Параметры командной строки</para>
- </listitem>
- <listitem>
- <para>Пользовательские INI-файлы</para>
- </listitem>
- <listitem>
- <para>Параметры в реестре</para>
- </listitem>
- <listitem>
- <para>Системные INI-файлы</para>
- </listitem>
- <listitem>
- <para>Общесистемные параметры в реестре</para>
- </listitem>
- </orderedlist>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Кроме того, реестр Windows не поддерживает механизма
- <quote>комментирования</quote>. Тем не менее, Subversion
- игнорирует параметры, у которых имена начинаются с
- символа <quote>решетка</quote> (<literal>#</literal>).
- Это позволяет закомментировать параметр, не удаляя ключ из
- реестра, что значительно упрощает процесс восстановления этого
- параметра.</para>
-
- <para>Клиент для командной строки <command>svn</command>
- никогда ничего не записывает и не создает первоначальные
- <quote>умолчательные</quote> параметры в реестре Windows.
- Нужные вам ключи вы можете создать используя программу
- <command>REGEDIT</command>. Либо, можно создать
- <filename>.reg</filename>-файл и двойным щелчком на этом файле
- в Explorer добавить информацию в реестр.</para>
-
- <example id="svn.advanced.confarea.windows-registry.ex-1">
- <title>Пример указания параметров в (.reg) файле реестра.</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>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>В предыдущем примере показано содержимое
- <filename>.reg</filename>-файла, содержащего часто используемые
- параметры и их значения по умолчанию. Обратите внимание, что
- приведены как общесистемные (сетевые настройки, относящиеся к
- прокси-серверу) и пользовательские параметры (программы-редакторы
- и сохранение паролей, среди прочего). Так же обратите внимание,
- что все параметры закомментированы. Необходимо будет просто удалить
- символ <quote>решетка</quote> (<literal>#</literal>) и установить
- нужное значение.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.confarea.opts">
- <!-- @ENGLISH {{{
- <title>Configuration Options</title>
-
- <para>In this section, we will discuss the specific
- run-time configuration options that are currently supported
- by Subversion.</para>
- @ENGLISH }}} -->
- <title>Параметры конфигурации</title>
-
- <para>В этом разделе рассматриваются поддерживаемые
- Subversion параметры времени выполнения.</para>
-
- <sect3 id="svn.advanced.confarea.opts.servers">
- <title>Servers</title>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>В файле <filename>servers</filename> находятся настройки,
- относящиеся к работе Subversion через сеть. Он содержит
- два специальных раздела — <literal>groups</literal> и
- <literal>global</literal>. Раздел <literal>groups</literal>
- представляет собой просто перекрестную таблицу. Ключи этого
- раздела являются именами последующих разделов файла; значения
- ключей представляют собой <firstterm>обобщения</firstterm> —
- текстовые блоки, которые могут содержать подстановочные символы
- — сравниваемые с именами машин, к которым Subversion
- направляет запросы.</para>
-
- <programlisting>
-[groups]
-beanie-babies = *.red-bean.com
-collabnet = svn.collab.net
-
-[beanie-babies]
-…
-
-[collabnet]
-…
-</programlisting>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>При работе через сеть, Subversion ищет совпадения между
- именем сервера, с которым устанавливается связь и именем группы
- в разделе <literal>groups</literal>. Если найдено совпадение,
- Subversion обращается к файлу <filename>servers</filename>,
- к разделу с именем, совпадающим с именем группы. Из этого раздела
- берутся необходимые сетевые настройки.</para>
-
- <para>Раздел <literal>global</literal> содержит настройки,
- используемые для всех серверов, не подпадающих ни под одно
- обобщение раздела <literal>groups</literal>. Здесь указываются
- те-же, что и для остальных серверных разделов файла параметры
- (конечно, за исключением специального раздела
- <literal>groups</literal>), используемые параметры приведены
- ниже:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>http-proxy-host</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Указывает имя компьютера-посредника, через который
- Subversion должна отправлять HTTP-запросы. По умолчанию,
- этот параметр имеет пустое значение, которое говорит
- Subversion о том, что она должна направлять HTTP-запросы
- не через компьютер-посредник, а связываться с целевой машиной
- напрямую.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-proxy-port</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <para>This specifies the port number on the proxy host
- to use. It defaults to an empty value.</para>
- @ENGLISH }}} -->
- <para>Указывает номер используемого порта на промежуточном
- компьютере. По умолчанию имеет пустое значение.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-proxy-username</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <para>This specifies the username to supply to the proxy
- machine. It defaults to an empty value.</para>
- @ENGLISH }}} -->
- <para>Указывает имя пользователя, передаваемого
- компьютеру-посреднику. По умолчанию имеет пустое
- значение.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-proxy-password</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <para>This specifies the password to supply to the proxy
- machine. It defaults to an empty value.</para>
- @ENGLISH }}} -->
- <para>Указывает пароль, передаваемый
- компьютеру-посреднику. По умолчанию имеет пустое
- значение.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-timeout</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Указывает, в секундах, промежуток времени ожидания
- ответа сервера. Если при низкоскоростном сетевом соединении
- у вас возникает проблема превышения времени ожидания,
- следует увеличить это значение. Значение по умолчанию
- <literal>0</literal> означает для низлежащей HTTP библиотеки,
- Neon, использовать свое собственное значение времени
- ожидания.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-compression</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Указывает, должна или нет Subversion использовать
- сжатие сетевых запросов, выполняющихся к DAV-серверам.
- Значением по умолчанию является <literal>yes</literal>
- (однако выполняться сжатие будет только если такая
- возможность поддерживается сетевым слоем). Установите
- этот параметр в <literal>no</literal>, для отключения
- сжатия, например при отладке сетевых транзакций.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>neon-debug-mask</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Целочисленная маска, которая используется низлежащей
- HTTP-библиотекой, Neon, для определения типа выводимой
- отладочной информации. По умолчанию установлено значение
- <literal>0</literal>, скрывающие весь отладочный вывод.
- Подробнее о том как Subversion использует Neon читайте в
- разделе <xref linkend="svn.developer" />.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ssl-authority-files</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Разделенный точкой с запятой перечень путей к файлам,
- содержащим сертификаты авторизации (или CAs), используемые
- Subversion-клиентом при обращении к хранилищу через
- HTTPS.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ssl-trust-default-ca</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Установите значение этой переменной в
- <literal>yes</literal>, если хотите чтобы Subversion
- автоматически доверяла набору поставляемых вместе
- с OpenSSL сертификатов (CAs).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ssl-client-cert-file</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Если хост (или хосты) требуют SSL сертификат клиента,
- у вас будет запрошен путь к вашему сертификату. Установите
- значение этой переменной и Subversion сможет автоматически
- находить ваш сертификат, без запроса. Нет стандартного места
- для хранения сертификата на диске; Subversion будет
- использовать тот, который располагается по указанному вами
- пути.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ssl-client-cert-password</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Если ваш клиентский SSL сертификат защищен паролем,
- при обращении к нему Subversion запросит у вас пароль.
- Если это вам надоедает (и вас не пугает хранить пароль
- в файле <filename>servers</filename>), можно присвоить
- значению этой переменной пароль сертификата. После этого
- пароль больше запрашиваться не будет.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect3>
- <sect3 id="svn.advanced.confarea.opts.config">
- <title>Config</title>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Остальные доступные параметры времени выполнения Subversion,
- не относящиеся к сетевой работе, находятся в файле
- <filename>config</filename>. В данный момент существует всего
- несколько параметров, но они тоже сгруппированы в разделы,
- в расчете на их увеличение в будущем.</para>
-
- <para>Раздел <literal>auth</literal> содержит параметры, относящиеся
- к аутентификации и авторизации в хранилище. Он содержит:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>store-passwords</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Устанавливает, используется или не используется
- кеширование паролей, введенных пользователем в ответ на
- запрос при аутентификации на сервере. Значением по умолчанию
- является <literal>да</literal>. Для запрета кеширования
- паролей на диск установите этот параметр в
- <literal>нет</literal>. Для отдельного запуска
- <command>svn</command> этот параметр можно переопределить,
- используя параметр командной строки
- <option>--no-auth-cache</option> (для тех команд, которые его
- поддерживают). За более подробной информацией обратитесь к
- разделу <xref linkend="svn.serverconfig.netmodel.credcache"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>store-auth-creds</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Этот параметр такой же как и
- <literal>store-passwords</literal>, за исключением того,
- что он разрешает или запрещает дисковое кеширование
- <emphasis>всей</emphasis> информации для аутентификации:
- имен пользователей, паролей, серверных сертификатов и всей
- другой кешируемой информации.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <!-- @ENGLISH {{{
- <para>The <literal>helpers</literal> section controls which
- external applications Subversion uses to accomplish its
- tasks. Valid options in this section are:</para>
- @ENGLISH }}} -->
- <para>Раздел <literal>helpers</literal> определяет, какие внешние
- приложения, при выполнении своих задач, будет использовать
- Subversion. Доступные параметры:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>editor-cmd</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Определяет программу, которую будет использовать
- Subversion для ввода лог сообщений, в тех случаях, когда
- <command>svn commit</command> используется без параметров
- <option>--message</option> (<option>-m</option>) или
- <option>--file</option> (<option>-F</option>). Эта же
- программа используется с командой <command>svn
- propedit</command> — вызывается временный файл,
- содержащий текущее значение редактируемого пользователем
- свойства и редактирование выполняется прямо в
- программе-редакторе (см. <xref
- linkend="svn.advanced.props" />). По умолчанию значение
- этого свойства не установлено. Порядок определения
- используемого редактора следующий:</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>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Здесь указывается абсолютный путь к программе
- определения отличий, используемой, Subversion для
- <quote>diff</quote>-вывода (такого как при использовании
- команды <command>svn diff</command>). По умолчанию для
- определения отличий Subversion использует внутреннюю
- библиотеку — установка этого параметра
- заставит ее использовать внешнюю программу. Подробнее
- об использовании таких программ читайте в разделе
- <xref linkend="svn.advanced.externaldifftools"/>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>diff3-cmd</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Здесь указывается абсолютный путь к программе
- трехстороннего сравнения. Subversion использует эту
- программу при объединении изменений, сделанных
- пользователем, с теми, которые были получены из
- хранилища. По умолчанию для определения отличий Subversion
- использует внутреннюю библиотеку — установка этого
- параметра заставит ее использовать внешнюю программу.
- Подробнее об использовании таких программ читайте в разделе
- <xref linkend="svn.advanced.externaldifftools"/>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>diff3-has-program-arg</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Этот флаг должен быть установлен в
- <literal>true</literal> если программа, указанная в
- параметре <literal>diff3-cmd</literal> использует
- параметр командной строки
- <option>--diff-program</option>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Раздел <literal>tunnels</literal> позволяет определить
- новые схемы туннелирования при использовании
- <command>svnserve</command> и клиентских подключений через
- <literal>svn://</literal>. За более подробной информацией
- обращайтесь в раздел <xref
- linkend="svn.serverconfig.svnserve.sshauth"/>.</para>
-
- <para>Все что не попало в другие разделы собирается в разделе
- <literal>miscellany</literal><footnote><para>Anyone for potluck
- dinner?</para></footnote>. В этом разделе можно найти:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>global-ignores</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Про выполнении команды <command>svn status</command>,
- Subversion перечисляет не версионированные файлы и
- директории вместе с версионированными, отмечая их
- символом <literal>?</literal> (см. <xref
- linkend="svn.tour.cycle.examine.status" />). Просмотр
- не интересных, не версионированных элементов при просмотре
- может раздражать — например объектные файлы, полученные
- в результате компиляции программы. Параметр
- <literal>global-ignores</literal> является перечислением
- разделннных пробелом обобщений, представляющих имена файлов и
- директорий которые Subversion не должна показывать, если они
- не версионированны. Значением, присвоенным по умолчанию,
- является <literal>*.o *.lo *.la #*# .*.rej *.rej .*~ *~
- .#* .DS_Store</literal>.</para>
-
- <para>Также как и <command>svn status</command>, команды
- <command>svn add</command> и <command>svn import</command>
- при просмотре директорий тоже игнорируют файлы, подходящие
- к этому списку. Можно переопределить этот параметр, используя
- флаг командной строки <option>--no-ignore</option>. Более
- подробнее о контроле игнорирования см. <xref
- linkend="svn.advanced.props.special.ignore" />.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>enable-auto-props</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Определяет автоматическую установку свойств
- для вновь добавляемых или импортированных файлов.
- Значением по умолчанию является <literal>no</literal>,
- поэтому для разрешения авто-свойств установите
- <literal>yes</literal>. Раздел <literal>auto-props</literal>
- этого файла определяет, какие свойства и для каких файлов
- должны устанавливаться.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>log-encoding</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Эта переменная задает набор символов кодировки для
- лог-сообщений фиксаций. Это перманентная форма параметра
- <option>--encoding</option> (см. <xref
- linkend="svn.ref.svn.sw"/>). Хранилище Subversion
- хранит лог-сообщения в UTF8, и предполагает, что ваше
- лог-сообщение написано используя родную локаль операционной
- ситемы. Кодировку необходимо указывать, если
- используется любая другая кодировка.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>use-commit-times</literal></term>
- <listitem>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Как правило, файлы рабочей копии имеют отметки
- времени, отражающие время последнего обращения к
- ним какого-либо процесса, был ли это ваш редактор,
- или подкоманды <command>svn</command>. Это должно
- быть близко людям, разрабатывающим программное
- обеспечение, потому, что как правило, системы
- сборки определяют по метке времени какие файлы
- требуют перекомпиляции.</para>
-
- <para>С другой стороны, иногда бывает выгодно, что бы
- рабочие файлы имели метки времени отражающие время их
- последнего изменения в хранилище. Команда <command>svn
- export</command> всегда устанавливает <quote>метку времени
- последней фиксации</quote> для создаваемого ею дерева
- файлов. При установке значения этой переменной в
- <literal>yes</literal> команды <command>svn
- checkout</command>, <command>svn update</command>,
- <command>svn switch</command> и <command>svn
- revert</command> для используемых ими файлов,
- так же будут устанавливать метку времени последней
- фиксации.</para>
- </listitem>
- </varlistentry>
-
- <!-- ###TODO add description of other options shown in example
- registry file, e.g., template-root -->
- </variablelist>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Раздел <literal>auto-props</literal> определяет возможность
- Subversion-клиента автоматически устанавливать свойства файлов,
- когда они добавлялись или импортировались. Он содержит любое
- количество пар ключ-значение, в формате
- <literal>PATTERN = PROPNAME=PROPVALUE</literal>, где
- <literal>PATTERN</literal> является файловым шаблоном,
- соответствующих набору имен файлов, а остальная часть строки
- является свойством и его значением. Множественные совпадения
- для одного файла приведут к множественной установке свойств для
- этого файла; однако не гарантируется, что порядок установки
- авто-свойств будет таким же в каком они указаны в файле
- конфигурации, поэтому нельзя будет одним правилом
- <quote>перекрыть</quote> другое. Несколько примеров использования
- авто-свойств можно найти в файле <filename>config</filename>.
- Наконец, если хотите использовать авто-свойства, не забудьте в
- разделе <literal>miscellany</literal> установить
- <literal>enable-auto-props</literal> в
- <literal>yes</literal>.</para>
-
- </sect3>
-
- </sect2>
- </sect1>
-
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.advanced.props">
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <title>Свойства</title>
-
- <para>Мы уже рассмотрели как Subversion сохраняет и получает
- разные версии файлов и директорий из хранилища. Целые главы были
- посвящены этой самой фундаментальной части функциональных
- возможностей этого инструмента. И если поддержка версионирования
- этим ограничится, Subversion все равно останется полноценным
- инструментом с точки зрения управления версиями. Однако
- версионирование этим не ограничивается.</para>
-
- <para>Дополнительно к версионированнию директорий и файлов,
- Subversion предоставляет для каждой версионированной директории
- и файла интерфейс для добавления, изменения и удаления
- версионированных метаданных. К этим метаданным мы обращаемся как
- к <firstterm>свойствам</firstterm>, присоединенным к каждому
- элементу рабочей копии, которые можно представить
- в виде таблицы с двумя столбцами, которая сопоставляет
- имена свойств соответствующим значениям. Вообще, имена
- и значения свойств могут быть тем, чем вы хотите чтобы они были,
- за исключением того, что имена должны быть читаемым текстом.
- И лучшим из всего является то, что они тоже версионированы
- также как и текстовое содержимое файлов. Можно также просто как и
- для текстовых изменений изменять, фиксировать и отменять изменения
- свойств. При обновлении рабочей копии также получаются
- и изменения свойств.</para>
-
- <sidebar>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <title>Еще один тип свойств в Subversion</title>
-
- <para>Подобные приведенным выше, свойства используются и Subversion.
- Так же как и произвольные имена свойств и соответствующие им значения,
- имеются у файлов и директорий, каждая правка может иметь
- произвольные свойства, присоединенные к ней. С теми же исключениями
- — читаемое, текстовое имя и любое бинарное значение —
- исключая версионирование свойств правок. Подробнее о таких
- неверсионированных свойствах см. <xref
- linkend="svn.reposadmin.basics.revprops" />.</para>
- </sidebar>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>В этом разделе мы рассмотрим полезность — как для
- пользователя, так и для самой Subversion — поддержки
- свойств. Вы узнаете о командах <command>svn</command>, относящихся к
- свойствам и том как модификация свойств влияет на привычный рабочий
- цикл. Надеемся, вы убедитесь в том, что свойства в Subversion
- расширяют возможности контроля версий.</para>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.props.why">
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <title>Зачем нужны свойства?</title>
-
- <para>Свойства могут быть очень полезной добавкой к рабочей копии.
- Фактически, сама Subversion использует свойства для хранения
- служебной информации и определения того, какие действия необходимо
- выполнить. Подобным образом и вы можете использовать свойства для
- своих целей. Конечно, все для чего можно использовать свойства
- можно делать, используя обычные версионированные файлы, однако
- обратите внимание на приведенный ниже пример использования
- Subversion-свойств.</para>
-
- <para>Скажем, вы хотите разработать веб-сайт, содержащий много
- цифровых фотографий и показывающий их с подписью и датой.
- Набор этих фотографий постоянно изменяется и вы захотите
- по возможности максимально автоматизировать этот сайт. Фотографии
- могут быть большого размера и как обычно делают на таких
- сайтах, для своих посетителей вам будет необходимо показывать
- миниатюры изображений. Сделать это вы можете с помощью обычных
- файлов. То есть рядом, в директории, вы можете иметь файлы
- <filename>image123.jpg</filename> и
- <filename>image123-thumbnail.jpg</filename>. Подобным образом,
- отдельно от графического файла, можно хранить и дату. В результате
- ваше дерево файлов будет захламлено и будет многократно увеличиваться
- при каждом добавлении на сайт фотографии.</para>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Представим эту же ситуацию при использовании Subversion-свойств
- файлов. Допустим, имеется файл <filename>image123.jpg</filename>
- и у этого файла установлено свойство
- <literal>caption</literal>, <literal>datestamp</literal> и даже
- <literal>thumbnail</literal>. В этом случае рабочая копия выглядит
- гораздо более управляемо — фактически она будет выглядеть
- так, как-будто она ничего кроме графических файлов не содержит.
- Однако ваш скрипт автоматизации знает больше. Он знает, что может
- воспользоваться <command>svn</command> (а еще лучше языковой обвязкой
- Subversion — см. <xref
- linkend="svn.developer.usingapi.otherlangs" />) для получения
- дополнительной, необходимой для показа на сайте информации,
- не занимаясь чтением индексного файла или играми с путями
- файлов.</para>
-
- <para>Как (и для чего) использовать Subversion-свойства вы решаете
- самостоятельно. Как уже говорилось, Subversion имеет свои применения
- свойств, которые мы рассмотрим в этой главе немного позже. А с начала
- давйте поговорим как работать со свойствами используя программу
- <command>svn</command>.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.props.manip">
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <title>Использование свойств</title>
-
- <para>Команда <command>svn</command> предоставляет несколько
- способов добавления или изменения свойств файлов и директорий.
- Свойства с короткими, читаемыми значениями, наверное проще всего
- добавить указав имя и значение свойства в командной строке
- подкоманды <command>propset</command>.</para>
-
- <screen>
-$ svn propset copyright '(c) 2003 Red-Bean Software' calc/button.c
-property 'copyright' set on 'calc/button.c'
-$
-</screen>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Однако мы уже знаем о гибкости, предлагаемой Subversion
- для значений свойств. И если вам необходимо иметь многострочное
- текстовое, или даже бинарное значение свойства, передавать
- такое значение через командную строку не удобно. Для
- таких случаев команда <command>propset</command> имеет
- параметр <option>--file</option> (<option>-F</option>), указывающий
- имя файла, содержащего новое значение свойства.</para>
-
- <screen>
-$ svn propset license -F /path/to/LICENSE calc/button.c
-property 'license' set on 'calc/button.c'
-$
-</screen>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Для имен свойств существует ряд ограничений. Имя свойства должно
- начинаться с буквы, двоеточия (<literal>:</literal>) или подчеркивания
- (<literal>_</literal>); дальше можно использовать цифры, тире
- (<literal>-</literal>) и точки (<literal>.</literal>).
- <footnote>
- <para>Если вы знакомы с XML, то синтаксис XML "Name" использует
- практически тот же ASCII набор.</para>
- </footnote>
- </para>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Дополнительно к команде <command>propset</command>,
- <command>svn</command> имеет команду <command>propedit</command>.
- Эта команда использует для добавления или изменения свойств указанную
- программу-редактор (см. <xref
- linkend="svn.advanced.confarea.opts.config" />). При выполнении
- команды, <command>svn</command> вызывает редактор с временным файлом,
- содержащим текущее значение свойства (или с пустым файлом, если
- добавляется новое свойство). Затем вы просто меняете в редакторе
- значение, пока оно не станет таким, каким бы вы хотели его видеть,
- сохраняете временный файл и выходите из редактора. Если Subversion
- обнаружит, что вы действительно изменили существующие значение
- свойства, будет установлено новое значение. Если вы вышли из
- редактора не внеся изменений, модификации свойства не
- произойдет.</para>
-
- <screen>
-$ svn propedit copyright calc/button.c ### exit the editor without changes
-No changes to property 'copyright' on 'calc/button.c'
-$
-</screen>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Обращаем ваше внимание на то, что как и другие команды
- <command>svn</command>, команды, относящиеся к свойствам
- могут применяться к нескольким путям за раз. Это дает возможность
- одной командой изменять свойства целого набора файлов. Например,
- можно сделать вот так:</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>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Все эти добавления и редактирования свойств не очень полезны,
- если нельзя просто узнать значение свойства. Поэтому для показа
- сохраненных для файлов и директорий имен и значений свойств,
- программа <command>svn</command> предлагает две подкоманды.
- Команда <command>svn proplist</command> перечисляет существующие
- для указанного пути свойства. После того как вы знаете имя свойства,
- можно, используя <command>svn propget</command>, запросить его
- значение. Эта команда выведет на стандартный поток ввода-вывода
- значение свойства для элемента по указанному пути (или путями) и с
- указанным именем.</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>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Существует даже вариант команды <command>proplist</command>,
- который перечисляет как имена, так и значения свойств. Просто
- добавьте параметр <option>--verbose</option>
- (<option>-v</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>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Последней, относящейся к свойствам подкомандой является
- <command>propdel</command>. Не смотря на то, что Subversion
- позволяет сохранять свойства с пустыми значениями, полностью
- удалить свойство, используя <command>propedit</command> или
- <command>propset</command>, нельзя. Например, такая команда
- не даст желаемого эффекта:</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>
-
- <!-- @ENGLISH {{{
- <para>You need to use the <command>propdel</command> command to
- delete properties altogether. The syntax is similar to the
- other property commands:</para>
- @ENGLISH }}} -->
- <para>Для полного удаления свойств необходимо использовать
- команду <command>propdel</command>. Ее синтаксис такой же
- как и у других команд работы со свойствами:</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>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Теперь, когда вы познакомились со всеми <command>svn</command>
- командами, имеющими отношение к свойствам, давайте посмотрим
- как модификация свойств влияет на привычный порядок работы с
- Subversion. Как мы уже говорили, так же как и содержимое файлов,
- свойства файлов и директорий версионированы. В результате,
- Subversion предоставляет те-же возможности по слиянию
- — в случае конфликтных ситуаций — чужих изменений
- с вашими собственными.</para>
-
- <sidebar>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <title>Редактирование свойств правок</title>
-
- <para>Помните, мы говорили о неверсионированных свойствах
- правок? Их то же можно менять с помощью <command>svn</command>.
- Просто добавьте параметр командной строки <option>--revprop</option>
- и укажите правку, чье свойство вы хотите изменить. Учитывая
- глобальность правок, в этом случае не нужно указывать путь, так как
- вы находитесь в рабочей копии хранилища, в котором вы хотите
- изменить свойство правки. Например, может понадобиться заменить
- лог-сообщение фиксации в существующей правке. <footnote>
- <para>Исправление в лог сообщениях орфографических, грамматических
- ошибок, <quote>просто ошибочных</quote> записей, наверно,
- самые распространенные случаи использования параметра
- <option>--revprop</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>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Обратите внимание на то, что изменение этих
- неверсионированных свойств должно быть явно разрешено
- администратором (см. <xref
- linkend="svn.reposadmin.create.hooks" />). Учитывая то, что
- свойства не версионируются, при не аккуратном редактировании,
- вы рискуете потерять информацию. Для исключения потери информации,
- администратор хранилища может принять меры предосторожности и
- по умолчанию, изменение неверсионированных свойств
- запрещено.</para>
-
- </sidebar>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Так же как и в случае с содержимым файлов, изменение свойств
- является локальной модификацией и становится постоянной при ее
- фиксации в хранилище с помощью <command>svn commit</command>.
- Изменение свойств можно легко отменить — команда
- <command>svn revert</command> восстановит файлы и директории
- до их первоначального состояния, включая содержимое, свойства и
- все остальное. Кроме того, интересную информацию о состоянии
- свойств файлов и директорий можно получить с помощью команд
- <command>svn status</command> и <command>svn
- diff</command>.</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>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Обратите внимание на то, что подкоманда <command>status</command>
- показывает <literal>M</literal> не в первой, а во второй колонке.
- Это потому, что в <filename>calc/button.c</filename> изменились
- свойства, а текстовое содержимое нет. Если бы мы изменили и то и
- другое, в первой колонке то же была бы буква <literal>M</literal>
- (см. <xref linkend="svn.tour.cycle.examine.status" />).</para>
-
- <sidebar>
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <title>Конфликты свойств</title>
-
- <para>Так же как и в случае с содержимым файлов, локальные
- модификации свойств могут конфликтовать с изменениями,
- зафиксированными кем-то другим. При обновлении рабочей копии
- директории и получении изменений свойств для версионированного
- элемента, которые идут в разрез вашими собственными, Subversion
- сообщит о конфликтном состоянии элемента.</para>
-
- <screen>
-% svn update calc
-M calc/Makefile.in
- C calc/button.c
-Updated to revision 143.
-$
-</screen>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>В директории с конфликтующим элементом Subversion
- создает файл с расширением <filename>.prej</filename>,
- с подробностями о конфликте. Для разрешения конфликта
- необходимо познакомиться с содержимым этого файла. Пока
- не будет решен конфликт, во второй колонке вывода
- команды <command>svn status</command> будет присутствовать
- буква <literal>C</literal>, а попытки фиксации локальных
- изменений будут отклоняться.</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>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Для разрешения конфликтующих свойств, просто убедитесь,
- что свойства имеют нужные значения, после чего, с помощь команды
- <command>svn resolved</command>, уведомьте Subversion о том, что
- вы решили проблему вручную.</para>
-
- </sidebar>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Кроме того нужно помнить о нестандартном подходе, используемом
- Subversion при выводе различий для свойств. Безусловно, можно
- запустить <command>svn diff</command> перенправить вывод, для создания
- работоспособного файла отличий. Програма <command>patch</command>
- будет просто игнорировать различия свойств — как правило,
- она игнорирует любой мусор, который неможет обработать. К сожалению,
- это значит, что для полного применения отличий, сгенерированных
- <command>svn diff</command>, изменения свойств нужно вносить в
- ручную.</para>
-
- <para>Как видите, наличие измененных свойств никак не отражается
- на привычном рабочем цикле. Операции обновления рабочей копии,
- проверки статуса файлов и директорий, вывод сообщений о сделанных
- изменениях и фиксация этих измениий в хранилище никак не зависят от
- наличия или отсутствия свойств. У <command>svn</command> просто
- имеется несколько дополнительных подкоманд для внесения изменений в
- свойства однако это просто достойное внимания отличие.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.props.special">
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <title>Специальные свойства</title>
-
- <para>У Subversion нет каких то отдельных правил для свойств
- — использовать их можно как угодно. Единственно
- что Subversion требует от вас не использовать в названиях
- свойств префикс <literal>svn:</literal>. Потому, что это
- пространство имен для ее личного использования. Subversion
- выделяет несколько свойств, имеющих особый магический эффект
- для файлов и директорий, для которых они установлены.
- В этом разделе мы раскроем тайну и расскажем, как эти
- специальные свойства делают жизнь немного проще.</para>
-
- <sect3 id="svn.advanced.props.special.executable">
- <title><literal>svn:executable</literal></title>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Свойство <literal>svn:executable</literal> для версионированного
- файла контролирует в полуавтоматическом режиме бит файловой
- системы, разрешающий исполнение. Это свойство не имеет определенного
- значения — просто его наличие говорит о необходимости для
- Subversion выставлять бит разрешения выполнения. Удаление этого
- свойства востанавливает полный контроль операционной системы над
- битом выполнения.</para>
-
- <para>На многих операционных системах возможность выполнения файла
- как команды определяется битом разрешения выполнения. Обычно по
- умолчанию этот бит не установлен и для файлов которым это
- необходимо, он должен быть явно установлен пользователем.
- Файлы в рабочей копии при обновлении создаются каждый раз
- заново если во время обновления получается новая версия.
- Это значит, что вы можете установить бит разрешения выполнения,
- а если при выполнении обновления обновился и этот файл,
- бит разрешения выполнения может оказаться опять сброшеным.
- Для таких случаев Subversion и предлагает использовать
- свойство <literal>svn:executable</literal>, как способ сохранения
- бита разрешения выполнения.</para>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Это свойство не имеет ни какой силы на таких файловых
- системах, как FAT32 и NTFS, не имеющих понятия бита разрешения
- выполнения<footnote><para>Для определения исполняемых файлов,
- файловая система Windows использует расширения файлов (такие, как
- <literal>.EXE</literal>, <literal>.BAT</literal> и
- <literal>.COM</literal>).</para></footnote>. Кроме того,
- так как оно не имеет определенного значения, при его установке
- Subversion принудительно устанавливает значение
- <literal>*</literal>. Наконец, это свойство действительно только
- для файлов, не для директорий.</para>
-
- </sect3>
-
- <sect3 id="svn.advanced.props.special.mime-type">
- <title><literal>svn:mime-type</literal></title>
-
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Свойство <literal>svn:mime-type</literal> имеет в Subversion
- несколько значений. Кроме общего назначения хранения информации о
- файле согласно Универсальному Расширению Интернет Почты (MIME),
- значение этого свойства определяет некоторые правила поведения самой
- Subversion.</para>
-
- <para>Например, если у файла свойство <literal>svn:mime-type</literal>
- имеет не текстовый MIME-тип (проще говоря, кроме некоторых
- исключений, не начинается с чего то вроде <literal>text/</literal>)
- Subversion предпологает бинарное — не читаемое —
- содержимое файла. Одной из положительных характеристик, предлагаемых
- Subversion, является контекстное, построчное объединение изменений,
- полученых с сервера при обновлении, с рабочим файлом. Однако файлы,
- считающиеся бинарными, не имеют понятия <quote>строка</quote>.
- Следовательно для таких файлов, при обновлении, Subversion не
- пытается выполнить контекстное объединение. Вместо этого, при
- локально измененной рабочей копии бинарного файла, для которого
- выполняется обновление, файл рабочей копии переименовывается
- добавлением расширения <filename>.orig</filename>, после чего,
- под первоначальным именем, Subversion сохраняет новую рабочую копию,
- содержащую изменения, полученные при обновлении и не содержащую ваших
- собственных изменений. Такой подход используется для того, чтобы защитить
- пользователя от попыток контекстного объединения файлов, которые просто
- не могут быть контекстно объединены.</para>
-
- <para>Кроме того, если уствновлено свойство <literal>svn:mime-type</literal>,
- Apache-модуль будет использовать это значение при заполнении HTTP
- заголовка <literal>Content-type:</literal> при ответе на GET-запросы.
- Это имеет ключевой значение при определении того, как показывать файл
- при просмотре хранилища используя web-браузер.</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> character to denote the end of a
- line.</para>
-
- <para>Not all of the various tools on these operating systems
- are prepared to understand files that contain line endings
- in a format that differs from the <firstterm>native line
- ending style</firstterm> of the operating system on which
- they are running. Common results are that Unix programs
- treat the <literal>CR</literal> character present in Windows
- files as a regular character (usually rendered as
- <literal>^M</literal>), and that Windows programs combine
- all of the lines of a Unix file into one giant line because
- no carriage return-linefeed (or <literal>CRLF</literal>)
- character combination was found to denote the end of
- line.</para>
-
- <para>This sensitivity to foreign EOL markers can become
- frustrating for folks who share a file across different
- operating systems. For example, consider a source code
- file, and developers that edit this file on both Windows and
- Unix systems. If all the developers always use tools which
- preserve the line ending style of the file, no problems
- occur.</para>
-
- <para>But in practice, many common tools either fail to
- properly read a file with foreign EOL markers, or they
- convert the file's line endings to the native style when the
- file is saved. If the former is true for a developer, he
- has to use an external conversion utility (such as
- <command>dos2unix</command> or its companion,
- <command>unix2dos</command>) to prepare the file for
- editing. The latter case requires no extra preparation.
- But both cases result in a file that differs from the
- original quite literally on every line! Prior to committing
- his changes, the user has two choices. Either he can use a
- conversion utility to restore the modified file to the same
- line ending style that it was in before his edits were made.
- Or, he can simply commit the file—new EOL markers and
- all.</para>
-
- <para>The result of scenarios like these include wasted time
- and unnecessary modifications to committed files. Wasted
- time is painful enough. But when commits change every line
- in a file, this complicates the job of determining which of
- those lines were changed in a non-trivial way. Where was
- that bug really fixed? On what line was a syntax error
- introduced?</para>
-
- <para>The solution to this problem is the
- <literal>svn:eol-style</literal> property. When this
- property is set to a valid value, Subversion uses it to
- determine what special processing to perform on the file so
- that the file's line ending style isn't flip-flopping with
- every commit that comes from a different operating
- system. The valid values are:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>native</literal></term>
- <listitem>
- <para>This causes the file to contain the EOL markers
- that are native to the operating system on which
- Subversion was run. In other words, if a user on a
- Windows machine checks out a working copy that
- contains a file with an
- <literal>svn:eol-style</literal> property set to
- <literal>native</literal>, that file will contain
- <literal>CRLF</literal> EOL markers. A Unix user
- checking out a working copy which contains the same
- file will see <literal>LF</literal> EOL markers in his
- copy of the file.</para>
-
- <para>Note that Subversion will actually store the file
- in the repository using normalized
- <literal>LF</literal> EOL markers regardless of the
- operating system. This is basically transparent to
- the user, though.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>CRLF</literal></term>
- <listitem>
- <para>This causes the file to contain
- <literal>CRLF</literal> sequences for EOL markers,
- regardless of the operating system in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>LF</literal></term>
- <listitem>
- <para>This causes the file to contain
- <literal>LF</literal> characters for EOL markers,
- regardless of the operating system in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>CR</literal></term>
- <listitem>
- <para>This causes the file to contain
- <literal>CR</literal> characters for EOL markers,
- regardless of the operating system in use. This line
- ending style is not very common. It was used on older
- Macintosh platforms (on which Subversion doesn't even
- run).</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect3>
-
- <sect3 id="svn.advanced.props.special.externals">
- <title><literal>svn:externals</literal></title>
-
- <para>The <literal>svn:externals</literal> property contains
- instructions for Subversion to populate a versioned
- directory with one or more other checked-out Subversion
- working copies. For more information on this keyword and
- its use, see <xref linkend="svn.advanced.externals"/>.</para>
-
- </sect3>
-
- <sect3 id="svn.advanced.props.special.special">
- <title><literal>svn:special</literal></title>
-
- <para>The <literal>svn:special</literal> property is the only
- <literal>svn:</literal> property that isn't meant to be
- directly set or modified by users. Subversion automatically
- sets this property whenever a <quote>special</quote> object
- is scheduled for addition, such as a symbolic link. The
- repository stores an <literal>svn:special</literal> object as
- an ordinary file. However, when a client sees this property
- during checkouts or updates, it interprets the contents of
- the file and translates the item back into the special type
- of object. In versions of Subversion current at the time of
- writing, only versioned symbolic links have this property
- attached, but in future versions of Subversion other special
- types of nodes will probably use this property as
- well.</para>
-
- <para>Note: Windows clients don't have symbolic links, and
- thus ignore any <literal>svn:special</literal> files coming
- from a repository that claim to be symbolic links. On
- Windows, the user ends up with an ordinary versioned file in
- the working copy.</para>
- </sect3>
-
- <sect3 id="svn.advanced.props.special.needs-lock">
- <title><literal>svn:needs-lock</literal></title>
-
- <para>This property is used to signify that the file it's
- attached to ought to be locked before editing. The value of
- the property is irrelevant; Subversion will normalize its
- value to <literal>*</literal>. When present, the file will
- be read-only <emphasis>unless</emphasis> the user has
- explicitly locked the file. When a lock-token is present
- (as a result of running <command>svn lock</command>), the
- file becomes read-write. When the lock is released, the
- file becomes read-only again.</para>
-
- <para>To learn more about how, when, and why this property
- should be used, see
- <xref
- linkend="svn.advanced.locking.lock-communication"/>.</para>
- </sect3>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.props.auto">
- <title>Automatic Property Setting</title>
-
- <para>Properties are a powerful feature of Subversion, acting as
- key components of many Subversion features discussed elsewhere
- in this and other chapters—textual diff and merge
- support, keyword substitution, newline translation, etc. But
- to get the full benefit of properties, they must be set on the
- right files and directories. Unfortunately, that can be a
- step easily forgotten in the routine of things, especially
- since failing to set a property doesn't usually result in an
- obvious error condition (at least compared to, say, failing to
- add a file to version control). To help your properties get
- applied to the places that need them, Subversion provides a
- couple of simple but useful features.</para>
-
- <para>Whenever you introduce a file to version control using the
- <command>svn add</command> or <command>svn import</command>
- commands, Subversion runs a very basic heuristic to determine
- if that file consists of human-readable or non-human-readable
- content. If the latter is the decision made, Subversion will
- automatically set the <literal>svn:mime-type</literal>
- property on that file to
- <literal>application/octet-stream</literal> (the generic
- <quote>this is a collection of bytes</quote> MIME type). Of
- course, if Subversion guesses incorrectly, or if you wish to
- set the <literal>svn:mime-type</literal> property to something
- more precise—perhaps <literal>image/png</literal> or
- <literal>application/x-shockwave-flash</literal>—you can
- always remove or edit that property.</para>
-
- <para>Subversion also provides the auto-props feature, which
- allows you to create mappings of filename patterns to property
- names and values. These mappings are made in your runtime
- configuration area. They again affect adds and imports, and
- not only can override any default MIME type decision made by
- Subversion during those operations, they can also set
- additional Subversion or custom properties, too. For example,
- you might create a mapping that says that any time you add
- JPEG files—ones that match the pattern
- <literal>*.jpg</literal>—Subversion should automatically
- set the <literal>svn:mime-type</literal> property on those
- files to <literal>image/jpeg</literal>. Or perhaps any files
- that match <literal>*.cpp</literal> should have
- <literal>svn:eol-style</literal> set to
- <literal>native</literal>, and <literal>svn:keywords</literal>
- set to <literal>Id</literal>. Auto-prop support is perhaps
- the handiest property related tool in the Subversion toolbox.
- See <xref linkend="svn.advanced.confarea.opts.config"/> for more about
- configuring that support.</para>
-
- </sect2>
- </sect1>
-
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.advanced.locking">
- <title>Locking</title>
-
- <para>Subversion's <quote>copy-modify-merge</quote> model is
- optimal when users are collaborating on projects that consist of
- line-based text files, such as program source code. However, as
- discussed in <xref
- linkend="svn.basic.vsn-models.copy-merge.sb-1"/>, sometimes one
- has to use the <quote>lock-modify-unlock</quote> model instead
- of Subversion's standard concurrent model. When a file consists
- of binary data, it's often difficult or impossible to merge two
- sets of changes made in parallel by different users. For this
- reason, Subversion 1.2 and later offers a feature known as
- <firstterm>locking</firstterm>, often known as <quote>reserved
- checkouts</quote> in other version control systems.</para>
-
- <para>Subversion's locking feature has two main goals:</para>
-
- <itemizedlist>
- <listitem><para><emphasis>Serializing access to a
- resource</emphasis>. Allow a user to grab an exclusive
- right to change to a file in the repository. If Harry
- reserves the right to change <filename>foo.jpg</filename>,
- then Sally should not be able to commit a change to it.</para>
- </listitem>
- <listitem><para><emphasis>Aiding communication</emphasis>.
- Prevent users from wasting time on unmergeable changes. If
- Harry has reserved the right to change
- <filename>foo.jpg</filename>, then it should be easy for
- Sally to notice this fact and avoid working on the
- file.</para>
- </listitem>
- </itemizedlist>
-
- <para>Subversion's locking feature is currently limited to files
- only—it's not yet possible to reserve access to a whole
- directory tree.</para>
-
- <sidebar id="svn.advanced.locking.meanings">
- <title>Three meanings of <quote>lock</quote></title>
-
- <para>In this section, and almost everywhere in this book, the
- words <quote>lock</quote> and <quote>locking</quote> describe
- a mechanism for mutual exclusion between users to avoid
- clashing commits. Unfortunately, there are two other sorts
- of <quote>lock</quote> with which Subversion, and therefore
- this book, sometimes needs to be concerned.</para>
-
- <itemizedlist>
-
- <listitem><para><firstterm>Working copy locks</firstterm>,
- used internally by Subversion to prevent clashes between
- multiple Subversion clients operating on the same working
- copy. This is the sort of lock indicated by
- an <computeroutput>L</computeroutput> in the third column
- of <command>svn status</command> output, and removed by
- the <command>svn cleanup</command> command, as described in
- <xref linkend="svn.tour.other.cleanup"/>.</para>
- </listitem>
-
- <listitem><para><firstterm>Database locks</firstterm>, used
- internally by the Berkeley DB backend to prevent clashes
- between multiple programs trying to access the
- database. This is the sort of lock whose unwanted
- persistence after an error can cause a repository to
- be <quote>wedged</quote>, as described in
- <xref linkend="svn.reposadmin.maint.recovery"/>.</para>
- </listitem>
-
- </itemizedlist>
-
- <para>You can generally forget about these other sorts of lock,
- until something goes wrong that requires you to care about
- them. In this book, <quote>lock</quote> means the first sort
- unless the contrary is either clear from context or explicitly
- stated.</para>
- </sidebar>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.locking.creation">
- <title>Creating locks</title>
-
- <para>In the Subversion repository, a
- <firstterm>lock</firstterm> is a piece of metadata which
- grants exclusive access to one user to change a file. This
- user is said to be the <firstterm>lock owner</firstterm>.
- Each lock also has a unique identifier, typically a long
- string of characters, known as the <firstterm>lock
- token</firstterm>. The repository manages locks in a separate
- table, and enforces locks during a commit operation. If any
- commit transaction attempts to modify or delete the file (or
- delete a parent of the file), the repository will demand two
- pieces of information:</para>
-
- <orderedlist>
- <listitem><para><emphasis role="bold">User
- authentication</emphasis>. The client performing the commit
- must be authenticated as the lock owner.</para>
- </listitem>
- <listitem><para><emphasis role="bold">Software
- authorization</emphasis>. The user's working copy must send
- the lock token with the commit, proving that it knows
- exactly which lock it's using.</para>
- </listitem>
- </orderedlist>
-
- <para>An example is in order, to demonstrate. Let's say that
- Harry has decided to change a JPEG image. To prevent other
- people from committing changes to the file, he locks the file
- in the repository using the <command>svn lock</command>
- command:</para>
-
- <screen>
-$ svn lock banana.jpg --message "Editing file for tomorrow's release."
-'banana.jpg' locked by user 'harry'.
-
-$ svn status
- K banana.jpg
-
-$ svn info banana.jpg
-Path: banana.jpg
-Name: banana.jpg
-URL: http://svn.example.com/repos/project/banana.jpg
-Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
-Revision: 2198
-Node Kind: file
-Schedule: normal
-Last Changed Author: frank
-Last Changed Rev: 1950
-Last Changed Date: 2005-03-15 12:43:04 -0600 (Tue, 15 Mar 2005)
-Text Last Updated: 2005-06-08 19:23:07 -0500 (Wed, 08 Jun 2005)
-Properties Last Updated: 2005-06-08 19:23:07 -0500 (Wed, 08 Jun 2005)
-Checksum: 3b110d3b10638f5d1f4fe0f436a5a2a5
-Lock Token: opaquelocktoken:0c0f600b-88f9-0310-9e48-355b44d4a58e
-Lock Owner: harry
-Lock Created: 2005-06-14 17:20:31 -0500 (Tue, 14 Jun 2005)
-Lock Comment (1 line):
-Editing file for tomorrow's release.
-
-</screen>
-
- <para>There are a number of new things demonstrated in the
- previous example. First, notice that Harry passed the
- <option>--message</option> option to <command>svn
- lock</command>. Similar to <command>svn commit</command>,
- the <command>svn lock</command> command can take comments
- (either via
- <option>--message (-m)</option> or <option>--file
- (-F)</option>) to describe the reason for locking the file.
- Unlike <command>svn commit</command>, however, <command>svn
- lock</command> will not demand a message by launching your
- preferred text editor. Lock comments are optional, but still
- recommended to aid communication.</para>
-
- <para>Second, the lock attempt succeeded. This means that the
- file wasn't already locked, and that Harry had the latest
- version of the file. If Harry's working copy of the file had
- been out-of-date, the repository would have rejected the
- request, forcing harry to <command>svn update</command> and
- reattempt the locking command.</para>
-
- <para>Also notice that after creating the lock in the
- repository, the working copy has cached information about the
- lock—most importantly, the lock token. The presence of
- the lock token is critical. It gives the working copy
- authorization to make use of the lock later on. The
- <command>svn status</command> command shows a
- <literal>K</literal> next to the file (short for locKed),
- indicating that the lock token is present.</para>
-
- <sidebar>
- <title>Regarding lock tokens</title>
-
- <para>A lock token isn't an authentication token, so much as
- an <emphasis>authorization</emphasis> token. The token
- isn't a protected secret. In fact, a lock's unique token is
- discoverable by anyone who runs <command>svn info
- URL</command>.</para>
-
- <para>A lock token is special only when it lives inside a
- working copy. It's proof that the lock was created in that
- particular working copy, and not somewhere else by some
- other client. Merely authenticating as the lock owner isn't
- enough to prevent accidents.</para>
-
- <para>For example: suppose you lock a file using a computer at
- your office, perhaps as part of a changeset in progress. It
- should not be possible for a working copy (or alternate
- Subversion client) on your home computer to accidentally
- commit a change to that same file, just because you've
- authenticated as the lock's owner. In other words, the lock
- token prevents one piece of Subversion-related software from
- undermining the work of another. (In our example, if you
- really need to change the file from an alternate working
- copy, you would need to break the lock and re-lock the
- file.)</para>
- </sidebar>
-
- <para>Now that Harry has locked <filename>banana.jpg</filename>,
- Sally is unable to change or delete that file:</para>
-
- <screen>
-$ whoami
-sally
-
-$ svn delete banana.jpg
-D banana.jpg
-
-$ svn commit -m "Delete useless file."
-Deleting banana.jpg
-svn: Commit failed (details follow):
-svn: DELETE of
-'/repos/project/!svn/wrk/64bad3a9-96f9-0310-818a-df4224ddc35d/banana.jpg':
-423 Locked (http://svn.example.com)
-
-</screen>
-
- <para>But Harry, after touching up the banana's shade of yellow,
- is able to commit his changes to the file. That's because he
- authenticates as the lock owner, and also because his working
- copy holds the correct lock token:</para>
-
- <screen>
-$ whoami
-harry
-
-$ svn status
-M K banana.jpg
-
-$ svn commit -m "Make banana more yellow"
-Sending banana.jpg
-Transmitting file data .
-Committed revision 2201.
-
-$ svn status
-$
-</screen>
-
- <para>Notice that after the commit is finished, <command>svn
- status</command> shows that the lock token is no longer
- present in working copy. This is the standard behavior
- of <command>svn commit</command>: it walks the working copy
- (or list of targets, if you provide such a list), and sends
- all lock tokens it encounters to the server as part of the
- commit transaction. After the commit completes
- successfully, all of the repository locks that were
- mentioned are released—<emphasis>even on files that
- weren't committed.</emphasis> The rationale here is to
- discourage users from being sloppy about locking, or from
- holding locks for too long. For example, suppose Harry were
- to haphazardly lock thirty files in a directory named
- <filename>images</filename>, because he's unsure of which
- files he needs to change. He ends up making changes to only
- four files. When he runs <command>svn commit
- images</command>, the process would still release all thirty
- locks.</para>
-
- <para>This behavior of automatically releasing locks can be
- overridden with the <option>--no-unlock</option> option
- to <command>svn commit</command>. This is best used for
- those times when you want to commit changes, but still plan
- to make more changes and thus need to retain existing locks.
- This behavior is also semi-permanently tweakable, by setting
- <literal>no-unlock = yes</literal> in your run-time
- <filename>config</filename> file (see <xref
- linkend="svn.advanced.confarea"/>).</para>
-
- <para>Of course, locking a file doesn't oblige one to commit a
- change to it. The lock can be released at any time with a
- simple
- <command>svn unlock</command> command:</para>
-
- <screen>
-$ svn unlock banana.c
-'banana.c' unlocked.
-</screen>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.locking.discovery">
- <title>Discovering locks</title>
-
- <para>When a commit fails due to someone else's locks, it's
- fairly easy to learn about them. The easiest of
- these is <command>svn status --show-updates</command>:</para>
-
- <screen>
-$ whoami
-sally
-
-$ svn status --show-updates
-M 23 bar.c
-M O 32 raisin.jpg
- * 72 foo.h
-Status against revision: 105
-</screen>
-
- <para>In this example, Sally can see not only that her copy of
- <filename>foo.h</filename> is out-of-date, but that one of the
- two modified files she plans to commit is locked in the
- repository. The <literal>O</literal> symbol stands for
- <quote>Other</quote>, meaning that a lock exists on the file,
- and was created by somebody else. If she were to attempt a
- commit, the lock on <filename>raisin.jpg</filename> would
- prevent it. Sally is left wondering who made the lock, when,
- and why. Once again, <command>svn info</command> has the
- answers:</para>
-
- <screen>
-$ svn info http://svn.example.com/repos/project/raisin.jpg
-Path: raisin.jpg
-Name: raisin.jpg
-URL: http://svn.example.com/repos/project/raisin.jpg
-Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
-Revision: 105
-Node Kind: file
-Last Changed Author: sally
-Last Changed Rev: 32
-Last Changed Date: 2005-01-25 12:43:04 -0600 (Tue, 25 Jan 2005)
-Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
-Lock Owner: harry
-Lock Created: 2005-02-16 13:29:18 -0500 (Wed, 16 Feb 2005)
-Lock Comment (1 line):
-Need to make a quick tweak to this image.
-</screen>
-
- <para>Just as <command>svn info</command> can be used to examine
- objects in the working copy, it can also be used to examine
- objects in the repository. If the main argument to
- <command>svn info</command> is a working copy path, then all
- of the working copy's cached information is displayed; any
- mention of a lock means that the working copy is holding a
- lock token (if a file is locked by another user or in another
- working copy, <command>svn info</command> on a working copy
- path will show no lock information at all). If the main
- argument to <command>svn info</command> is a URL, then the
- information reflects the latest version of an object in the
- repository; any mention of a lock describes the current lock
- on the object.</para>
-
- <para>So in this particular example, Sally can see that Harry
- locked the file on February 16th to <quote>make a quick
- tweak</quote>. It being June, she suspects that he probably
- forgot all about the lock. She might phone Harry to complain
- and ask him to release the lock. If he's unavailable, she
- might try to forcibly break the lock herself or ask an
- administrator to do so.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.locking.break-steal">
- <title>Breaking and stealing locks</title>
-
- <para>A repository lock isn't sacred; it can be released not
- only by the person who created it, but by anyone at all. When
- somebody other than the original lock creator destroys a lock,
- we refer to this as <firstterm>breaking</firstterm> the
- lock.</para>
-
- <para>From the administrator's chair, it's simple to break
- locks. The <command>svnlook</command>
- and <command>svnadmin</command> programs have the ability to
- display and remove locks directly from the repository. (For
- more information about these tools, see
- <xref linkend="svn.reposadmin.maint.tk"/>.)</para>
-
- <screen>
-$ svnadmin lslocks /usr/local/svn/repos
-Path: /project2/images/banana.jpg
-UUID Token: opaquelocktoken:c32b4d88-e8fb-2310-abb3-153ff1236923
-Owner: frank
-Created: 2005-06-15 13:29:18 -0500 (Wed, 15 Jun 2005)
-Expires:
-Comment (1 line):
-Still improving the yellow color.
-
-Path: /project/raisin.jpg
-UUID Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
-Owner: harry
-Created: 2005-02-16 13:29:18 -0500 (Wed, 16 Feb 2005)
-Expires:
-Comment (1 line):
-Need to make a quick tweak to this image.
-
-$ svnadmin rmlocks /usr/local/svn/repos /project/raisin.jpg
-Removed lock on '/project/raisin.jpg'.
-</screen>
-
- <para>The more interesting option is allowing users to break
- each other's locks over the network. To do this, one simply
- needs to pass the <option>--force</option> to the unlock
- command:</para>
-
- <screen>
-$ whoami
-sally
-
-$ svn status --show-updates
-M 23 bar.c
-M O 32 raisin.jpg
- * 72 foo.h
-Status against revision: 105
-
-$ svn unlock raisin.jpg
-svn: 'raisin.jpg' is not locked in this working copy
-
-$ svn info raisin.jpg | grep URL
-URL: http://svn.example.com/repos/project/raisin.jpg
-
-$ svn unlock http://svn.example.com/repos/project/raisin.jpg
-svn: Unlock request failed: 403 Forbidden (http://svn.example.com)
-
-$ svn unlock --force http://svn.example.com/repos/project/raisin.jpg
-'raisin.jpg' unlocked.
-</screen>
-
- <para>Sally's initial attempt to unlock failed because she
- ran <command>svn unlock</command> directly on her working copy
- of the file, and no lock token was present. To remove the
- lock directly from the repository, she needs to pass a URL
- to <command>svn unlock</command>. Her first attempt to unlock
- the URL fails, because she can't authenticate as the lock
- owner (nor does she have the lock token). But when she
- passes <option>--force</option>, the authentication and
- authorization requirements are ignored, and the remote lock is
- broken.</para>
-
- <para>Of course, simply breaking a lock may not be enough. In
- the running example, Sally may not only want to break Harry's
- long-forgotten lock, but re-lock the file for her own use.
- She can accomplish this by running <command>svn unlock
- --force</command> and then <command>svn lock</command>
- back-to-back, but there's a small chance that somebody else
- might lock the file between the two commands. The simpler thing
- to is <firstterm>steal</firstterm> the lock, which involves
- breaking and re-locking the file all in one atomic step. To
- do this, pass the <option>--force</option> option
- to <command>svn lock</command>:</para>
-
- <screen>
-$ svn lock raisin.jpg
-svn: Lock request failed: 423 Locked (http://svn.example.com)
-
-$ svn lock --force raisin.jpg
-'raisin.jpg' locked by user 'sally'.
-</screen>
-
- <para>In any case, whether the lock is broken or stolen, Harry
- may be in for a surprise. Harry's working copy still
- contains the original lock token, but that lock no longer
- exists. The lock token is said to
- be <firstterm>defunct</firstterm>. The lock represented by
- the lock-token has either been broken (no longer in the
- repository), or stolen (replaced with a different lock).
- Either way, Harry can see this by asking <command>svn
- status</command> to contact the repository:</para>
-
- <screen>
-$ whoami
-harry
-
-$ svn status
- K raisin.jpg
-
-$ svn status --show-updates
- B 32 raisin.jpg
-
-$ svn update
- B raisin.jpg
-
-$ svn status
-
-$
-</screen>
-
- <para>If the repository lock was broken, then <command>svn
- status --show-updates</command> displays
- a <literal>B</literal> (Broken) symbol next to the file.
- If a new lock exists in place of the old one, then
- a <literal>T</literal> (sTolen) symbol is shown.
- Finally, <command>svn update</command> notices any defunct
- lock tokens and removes them from the working copy.</para>
-
- <sidebar>
- <title>Locking Policies</title>
-
- <para>Different systems have different notions of how strict
- a lock should be. Some folks argue that locks must be
- strictly enforced at all costs, releasable only by the
- original creator or administrator. They argue that if
- anyone can break a lock, then chaos breaks loose and the
- whole point of locking is defeated. The other side argues
- that locks are first and foremost a communication tool.
- If users are constantly breaking each others' locks, then
- it represents a cultural failure within the team and the
- problem falls outside the scope of software
- enforcement.</para>
-
- <para>Subversion defaults to the <quote>softer</quote>
- approach, but still allows administrators to create
- stricter enforcement policies through the use of hook
- scripts. In particular, the <filename>pre-lock</filename>
- and <filename>pre-unlock</filename> hooks allow
- administrators to decide when lock creation and lock
- releases are allowed to happen. Depending on whether or
- not a lock already exists, these two hooks can decide
- whether or not to allow a certain user to break or steal a
- lock. The <filename>post-lock</filename>
- and <filename>post-unlock</filename> hooks are also
- available, and can be used to send email after locking
- actions.</para>
-
- <para>To learn more about repository hooks, see
- <xref linkend="svn.reposadmin.create.hooks"/>.</para>
- </sidebar>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.advanced.locking.lock-communication">
- <title>Lock Communication</title>
-
- <para>We've seen how <command>svn lock</command>
- and <command>svn unlock</command> can be used to create,
- release, break, and steal locks. This satisfies the goal of
- serializing commit access to a file. But what about the
- larger problem of preventing wasted time?</para>
-
- <para>For example, suppose Harry locks an image file and then
- begins editing it. Meanwhile, miles away, Sally wants to do
- the same thing. She doesn't think to run <command>svn status
- --show-updates</command>, so she has no idea that Harry has
- already locked the file. She spends hours editing the file,
- and when she tries to commit her change, she discovers that
- either the file is locked or that she's out-of-date.
- Regardless, her changes aren't mergeable with Harry's. One of
- these two people has to throw away their work, and a lot of
- time has been wasted.</para>
-
- <para>Subversion's solution to this problem is provide a
- mechanism to remind users that a file ought to be locked
- <emphasis>before</emphasis> the editing begins.</para>
-
- <para>The mechanism is a special
- property, <literal>svn:needs-lock</literal>. If the property
- is attached to a file (the value is irrelevant), then the file
- will have read-only permissions. When the user locks the file
- and receives a lock token, the file becomes read-write. When
- the lock is released—either explicitly unlocked, or
- released via commit—the file returns to read-only
- again.</para>
-
- <para>The theory, then, is that if the image file has this
- property attached, then Sally would immediately notice
- something is strange when she opens the file for editing. Her
- application would be unable to save changes, or (better yet)
- tell her that the file is read-only. This reminds her to lock
- the file before editing, whereby she discovers the
- pre-existing lock:</para>
-
- <screen>
-$ /usr/local/bin/gimp raisin.jpg
-gimp: error: file is read-only!
-
-$ ls -l raisin.jpg
--r--r--r-- 1 sally sally 215589 Jun 8 19:23 raisin.jpg
-
-$ svn lock raisin.jpg
-svn: Lock request failed: 423 Locked (http://svn.example.com)
-
-$ svn info http://svn.example.com/repos/project/raisin.jpg | grep Lock
-Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
-Lock Owner: harry
-Lock Created: 2005-06-08 07:29:18 -0500 (Thu, 08 June 2005)
-Lock Comment (1 line):
-Making some tweaks. Locking for the next two hours.
-
-</screen>
-
- <para>As a matter of <quote>best practice</quote>, both users
- and administrators are encouraged to attach
- the <literal>svn:needs-lock</literal> property to any file
- which cannot be contextually merged. It's the main
- technique for encouraging good locking habits and preventing
- wasted effort.</para>
-
- <para>Note that this property is a communication tool which
- works independently from the locking system. In other
- words, any file can be locked, whether or not this property
- is present. And conversely, the presence of this property
- doesn't make the repository require a lock when
- committing.</para>
-
- <para>The system isn't flawless, either. It's possible that
- even when a file has the property, the read-only reminder
- won't always work. Sometimes applications misbehave and
- <quote>hijack</quote> the read-only file, silently allowing
- users to edit and save the file anyway. Unfortunately,
- there's not much Subversion can do about this.</para>
-
- </sect2>
-
- </sect1>
-
-
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.advanced.pegrevs">
- <title>Peg and Operative Revisions</title>
-
- <para>We make use of the ability to copy, move, rename, and
- completely replace files and directories on our computers all
- that time. And your version control system shouldn't get in the
- way of your doing these things with your version controlled
- files and directories, either. Subversion's file management
- support is quite liberating, affording almost as much
- flexibility for versioned files that you'd expect when
- manipulating your unversioned ones. But that flexibility means
- that across the lifetime of your repository, a given versioned
- resource might have many paths, and a given path might represent
- several entirely different versioned resources. And this
- introduces a certain level of complexity to your interactions
- with those paths and resources.</para>
-
- <para>Subversion is pretty smart about noticing when an object's
- version history includes such <quote>changes of address</quote>.
- For example, if you ask for all the logs of a particular file
- that was renamed last week, Subversion happily provides all
- those logs—the revision in which the rename itself
- happened, plus the logs of relevant revisions both before and
- after that rename. So, most of the time, you don't even have to
- think about such things. But occasionally, Subversion needs
- your help to clear up ambiguities.</para>
-
- <para>The simplest example of this occurs when a directory or file
- is deleted from version control, and then a new directory or
- file is created with the same name and added to version control.
- Clearly the thing you deleted and the thing you later added
- aren't the same thing, they merely happen to have had the same
- path, which we'll call <filename>/trunk/object</filename>.
- What, then, does it mean to ask Subversion about the history of
- <filename>/trunk/object</filename>? Are you asking about the
- thing currently at that location, or the old thing you deleted
- from that location? Are you asking about the operations that
- have happened to all the objects that have lived at that path?
- Clearly, Subversion needs a hint about what you are really
- asking.</para>
-
- <para>And thanks to moves, versioned resource history can get far
- more twisted than that, even. For example, you might have a
- directory named <filename>concept</filename>, containing some
- nascent software project you've been toying with. Eventually,
- though, that project matures to the point that the idea seems to
- actually have some wings, so you do the unthinkable and decide
- to give the project a name.
- <footnote>
- <para><quote>You're not supposed to name it. Once you name it,
- you start getting attached to it.</quote> — Mike
- Wazowski</para>
- </footnote>
- Let's say you called your software Frabnaggilywort. At this
- point, it makes sense to rename the directory to reflect the
- project's new name, so <filename>concept</filename> is renamed
- to <filename>frabnaggilywort</filename>. Life goes on,
- Frabnaggilywort releases a 1.0 version, and is downloaded and
- used daily by hordes of people aiming to improve their
- lives.</para>
-
- <para>It's a nice story, really, but it doesn't end there.
- Entrepreneur that you are, you've already got another think in
- the tank. So you make a new directory,
- <filename>concept</filename>, and the cycle begins again. In
- fact, the cycle begins again many times over the years, each
- time starting with that old <filename>concept</filename>
- directory, then sometimes seeing that directory renamed as the
- idea cures, sometimes seeing it deleted when you scrap the idea.
- Or, to get really sick, maybe you rename
- <filename>concept</filename> to something else for a while, but
- later rename the thing back to <filename>concept</filename> for
- some reason.</para>
-
- <para>When scenarios like these occur, attempting to instruct
- Subversion to work with these re-used paths can be a little like
- instructing a motorist in Chicago's West Suburbs to drive east
- down Roosevelt Road and turn left onto Main Street. In a mere
- twenty minutes, you can cross <quote>Main Street</quote> in
- Wheaton, Glen Ellyn, and Lombard. And no, they aren't the same
- street. Our motorist—and our Subversion—need a
- little more detail in order to do the right thing.</para>
-
- <para>In version 1.1, Subversion introduced a way for you to tell
- it exactly which Main Street you meant. It's called the
- <firstterm>peg revision</firstterm>, and it is a revision
- provided to Subversion for the sole purpose of identifying a
- unique line of history. Because at most one versioned resource
- may occupy a path at any given time—or, more precisely, in
- any one revision—the combination of a path and a peg
- revision is all that is needed to refer to a specific line of
- history. Peg revisions are specified to the Subversion
- command-line client using <firstterm>at syntax</firstterm>, so
- called because the syntax involves appending an <quote>at
- sign</quote> (<literal>@</literal>) and the peg revision to the
- end of the path with which the revision is associated.</para>
-
- <para>But what of the <option>--revision (-r)</option> of which
- we've spoken so much in this book? That revision (or set of
- revisions) is called the <firstterm>operative
- revision</firstterm> (or <firstterm>operative revision
- range</firstterm>). Once a particular line of history has been
- identified using a path and peg revision, Subversion performs
- the requested operation using the operative revision(s). To map
- this to our Chicagoland streets analogy, if we are told to go to
- 606 N. Main Street in Wheaton,
- <footnote>
- <para>606 N. Main Street, Wheaton, Illinois, is the home of
- the Wheaton History Center. Get it—<quote>History
- Center</quote>? It seemed appropriate….</para>
- </footnote>
- we can think of <quote>Main Street</quote> as our path and
- <quote>Wheaton</quote> as our peg revision. These two pieces of
- information identify a unique path which can travelled (north or
- south on Main Street), and will keep us from travelling up and
- down the wrong Main Street in search of our destination. Now we
- throw in <quote>606 N.</quote> as our operative revision, of
- sorts, and we know <emphasis>exactly</emphasis> where to
- go.</para>
-
- <sidebar>
- <title>The "peg-revision" algorithm</title>
-
- <para>When the commandline client sees a command of the
- form:</para>
-
- <screen>
-$ svn <replaceable>command</replaceable> -r <replaceable>OPERATIVE-REV</replaceable> item@<replaceable>PEG-REV</replaceable>
-</screen>
-
- <para>…it performs the following algorithm:</para>
-
- <itemizedlist>
-
- <listitem>
- <para>Go to revision <replaceable>PEG-REV</replaceable>, and
- find <replaceable>item</replaceable>. This locates a unique
- object in the repository.</para>
- </listitem>
-
- <listitem>
- <para>Trace the object's history backwards (through any
- possible renames) to its ancestor in
- revision <replaceable>OPERATIVE-REV</replaceable>.</para>
- </listitem>
-
- <listitem>
- <para>Perform the requested action on that ancestor,
- wherever it is located, or whatever its name might
- be.</para>
- </listitem>
-
- </itemizedlist>
-
- <para>Remember that even when you don't explicitly supply a
- peg-revision, it's still present. It defaults to BASE for
- working copy items, and to HEAD for URLs.</para>
-
- </sidebar>
-
- <para>Say that long ago we created our repository, and in revision 1
- added our first <filename>concept</filename> directory, plus an
- <filename>IDEA</filename> file in that directory talking about
- the concept. After several revisions in which real code was
- added and tweaked, we, in revision 20, renamed this directory to
- <filename>frabnaggilywort</filename>. By revision 27, we had a
- new concept, a new <filename>concept</filename> directory to
- hold it, and a new <filename>IDEA</filename> file to describe
- it. And then five years and twenty thousand revisions flew by,
- just like they would in any good romance story.</para>
-
- <para>Now, years later, we wonder what the
- <filename>IDEA</filename> file looked like back in revision 1.
- But Subversion needs to know if we are asking about how the
- <emphasis>current</emphasis> file looked back in revision 1, or
- are we asking for the contents of whatever file lived at
- <filename>concepts/IDEA</filename> in revision 1? Certainly
- those questions have different answers, and because of peg
- revisions, you can ask either of them. To find out how the
- current <filename>IDEA</filename> file looked in that old
- revision, you run:</para>
-
- <screen>
-$ svn cat -r 1 concept/IDEA
-subversion/libsvn_client/ra.c:775: (apr_err=20014)
-svn: Unable to find repository location for 'concept/IDEA' in revision 1
-</screen>
-
- <para>Of course, in this example, the current
- <filename>IDEA</filename> file didn't exist yet in revision 1,
- so Subversion gives an error. The command above is shorthand
- for a longer notation which explicitly lists a peg revision.
- The expanded notation is:</para>
-
- <screen>
-$ svn cat -r 1 concept/IDEA at BASE
-subversion/libsvn_client/ra.c:775: (apr_err=20014)
-svn: Unable to find repository location for 'concept/IDEA' in revision 1
-</screen>
-
- <para>And when executed, it has the expected results. Peg revisions
- generally default to a value of <literal>BASE</literal> (the
- revision currently present in the working copy) when applied to
- working copy paths, and of <literal>HEAD</literal> when applied
- to URLs.</para>
-
- <para>Let's ask the other question, then—in revision 1, what
- were the contents of whatever file occupied the address
- <filename>concepts/IDEA</filename> at the time? We'll use an
- explicit peg revision to help us out.</para>
-
- <screen>
-$ svn cat concept/IDEA at 1
-The idea behind this project is to come up with a piece of software
-that can frab a naggily wort. Frabbing naggily worts is tricky
-business, and doing it incorrectly can have serious ramifications, so
-we need to employ over-the-top input validation and data verification
-mechanisms.
-</screen>
-
- <para>This appears to be the right output. The text even mentions
- frabbing naggily worts, so this is almost certainly the file
- which describes the software now called Frabnaggilywort. In
- fact, we can verify this using the combination of an explicit
- peg revision and explicit operative revision. We know that in
- <literal>HEAD</literal>, the Frabnaggilywort project is located
- in the <filename>frabnaggilywort</filename> directory. So we
- specify that we want to see how the line of history identified
- in <literal>HEAD</literal> as the path
- <filename>frabnaggilywort/IDEA</filename> looked in revision
- 1.</para>
-
- <screen>
-$ svn cat -r 1 frabnaggilywort/IDEA at HEAD
-The idea behind this project is to come up with a piece of software
-that can frab a naggily wort. Frabbing naggily worts is tricky
-business, and doing it incorrectly can have serious ramifications, so
-we need to employ over-the-top input validation and data verification
-mechanisms.
-</screen>
-
- <para>And the peg and operative revisions need not be so trivial,
- either. For example, say <filename>frabnaggilywort</filename>
- had been deleted from <literal>HEAD</literal>, but we know it
- existed in revision 20, and we want to see the diffs for its
- <filename>IDEA</filename> file between revisions 4 and 10. We
- can use the peg revision 20 in conjunction with the URL that
- would have held Frabnaggilywort's <filename>IDEA</filename> file
- in revision 20, and then use 4 and 10 as our operative revision
- range.</para>
-
- <screen>
-$ svn diff -r 4:10 http://svn.red-bean.com/projects/frabnaggilywort/IDEA@20
-Index: frabnaggilywort/IDEA
-===================================================================
---- frabnaggilywort/IDEA (revision 4)
-+++ frabnaggilywort/IDEA (revision 10)
-@@ -1,5 +1,5 @@
--The idea behind this project is to come up with a piece of software
--that can frab a naggily wort. Frabbing naggily worts is tricky
--business, and doing it incorrectly can have serious ramifications, so
--we need to employ over-the-top input validation and data verification
--mechanisms.
-+The idea behind this project is to come up with a piece of
-+client-server software that can remotely frab a naggily wort.
-+Frabbing naggily worts is tricky business, and doing it incorrectly
-+can have serious ramifications, so we need to employ over-the-top
-+input validation and data verification mechanisms.
-</screen>
-
- <para>Fortunately, most folks aren't faced with such complex
- situations. But when you are, remember that peg revisions are
- that extra hint Subversion needs to clear up ambiguity.</para>
-
- </sect1>
-
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.advanced.externals">
- <title>Externals Definitions</title>
-
- <para>Sometimes it is useful to construct a working copy that is
- made out of a number of different checkouts. For example, you
- may want different subdirectories to come from different
- locations in a repository, or perhaps from different
- repositories altogether. You could certainly setup such a
- scenario by hand—using <command>svn checkout</command> to
- create the sort of nested working copy structure you are trying
- to achieve. But if this layout is important for everyone who
- uses your repository, every other user will need to perform the
- same checkout operations that you did.</para>
-
- <para>Fortunately, Subversion provides support for
- <firstterm>externals definitions</firstterm>. An externals
- definition is a mapping of a local directory to the
- URL—and possibly a particular revision—of a
- versioned resource. In Subversion, you declare externals
- definitions in groups using the <literal>svn:externals</literal>
- property. You can create or modify this property using
- <command>svn propset</command> or <command>svn
- propedit</command> (see <xref linkend="svn.advanced.props.why"/>).
- It can be set on any versioned directory,
- and its value is a multi-line table of subdirectories (relative
- to the versioned directory on which the property is set) and
- fully qualified, absolute Subversion repository URLs.</para>
-
- <screen>
-$ svn propget svn:externals calc
-third-party/sounds http://sounds.red-bean.com/repos
-third-party/skins http://skins.red-bean.com/repositories/skinproj
-third-party/skins/toolkit -r21 http://svn.red-bean.com/repos/skin-maker
-</screen>
-
- <para>The convenience of the <literal>svn:externals</literal>
- property is that once it is set on a versioned directory,
- everyone who checks out a working copy with that directory also
- gets the benefit of the externals definition. In other words,
- once one person has made the effort to define those nested
- working copy checkouts, no one else has to
- bother—Subversion will, upon checkout of the original
- working copy, also checkout the external working copies.</para>
-
- <para>Note the previous externals definition example. When
- someone checks out a working copy of the
- <filename>calc</filename> directory, Subversion also continues
- to checkout the items found in its externals definition.</para>
-
- <screen>
-$ svn checkout http://svn.example.com/repos/calc
-A calc
-A calc/Makefile
-A calc/integer.c
-A calc/button.c
-Checked out revision 148.
-
-Fetching external item into calc/third-party/sounds
-A calc/third-party/sounds/ding.ogg
-A calc/third-party/sounds/dong.ogg
-A calc/third-party/sounds/clang.ogg
-…
-A calc/third-party/sounds/bang.ogg
-A calc/third-party/sounds/twang.ogg
-Checked out revision 14.
-
-Fetching external item into calc/third-party/skins
-…
-</screen>
-
- <para>If you need to change the externals definition, you can do
- so using the regular property modification subcommands. When
- you commit a change to the <literal>svn:externals</literal>
- property, Subversion will synchronize the checked-out items
- against the changed externals definition when you next run
- <command>svn update</command>. The same thing will happen when
- others update their working copies and receive your changes to
- the externals definition.</para>
-
- <para>The <command>svn status</command> command also recognizes
- externals definitions, displaying a status code of
- <literal>X</literal> for the disjoint subdirectories into which
- externals are checked out, and then recursing into those
- subdirectories to display the status of the external items
- themselves.</para>
-
- <tip>
- <para>You should strongly consider using explicit revision
- numbers in all of your externals definitions. Doing so means
- that you get to decide when to pull down a different snapshot
- of external information, and exactly which snapshot to pull.
- Besides the common sense aspect of not being surprised by
- changes to third-party repositories that you might not have
- any control over, using explicit revision numbers also means
- that as you backdate your working copy to a previous
- revision, your externals definitions will also revert to the
- way they looked in that previous revision, which in turn means
- that the external working copies will be updated to match they
- way <emphasis>they</emphasis> looked back when your repository was
- at that previous revision. For software projects, this could
- be the difference between a successful and a failed build of
- an older snapshot of your complex codebase.</para>
- </tip>
-
- <para>The support that exists for externals definitions in
- Subversion today can be a little misleading, though. First, an
- externals definition can only point to directories, not files.
- Second, the externals definition cannot point to relative paths
- (paths like <filename>../../skins/myskin</filename>). Third, the
- working copies created via the externals definition support are
- still disconnected from the primary working copy (on whose
- versioned directories the <literal>svn:externals</literal>
- property was actually set). And Subversion still only truly
- operates on non-disjoint working copies. So, for example, if
- you want to commit changes that you've made in one or more of
- those external working copies, you must run <command>svn
- commit</command> explicitly on those working
- copies—committing on the primary working copy will not
- recurse into any external ones.</para>
-
- <para>Also, since the definitions themselves use absolute URLs,
- moving or copying a directory to which they are attached will
- not affect what gets checked out as an external (though the
- relative local target subdirectory will, of course, move with
- renamed directory). This can be confusing—even
- frustrating—in certain situations. For example, if you
- use externals definitions on a directory in your
- <filename>/trunk</filename> development line which point to
- other areas of that same line, and then you use <command>svn
- copy</command> to branch that line to some new location
- <filename>/branches/my-branch</filename>, the externals
- definitions on items in your new branch will still refer to
- versioned resources in <filename>/trunk</filename>. Be aware,
- too, that if you need to re-parent your working copy (using
- <command>svn switch --relocate</command>), externals definitions
- will <emphasis>not</emphasis> also be re-parented.</para>
-
- <para>Finally, there might be times when you would prefer that
- <command>svn</command> subcommands would not recognize or
- otherwise operate on the external working copies created as the
- result of externals definition handling. In those instances,
- you can pass the <option>--ignore-externals</option> option to
- 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>
-
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -4575,80 +425,6 @@
</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>
<!--
More information about the svnbook-dev
mailing list