[svnbook commit] r2649 - trunk/src/ru/book
dmitriy
noreply at red-bean.com
Mon Feb 5 09:15:15 CST 2007
Author: dmitriy
Date: Mon Feb 5 09:15:14 2007
New Revision: 2649
Added:
trunk/src/ru/book/index.xml (props changed)
- copied unchanged from r2601, /trunk/src/en/book/index.xml
Modified:
trunk/src/ru/book/app-quickstart.xml (props changed)
trunk/src/ru/book/app-svn-for-cvs-users.xml (contents, props changed)
trunk/src/ru/book/app-third-party-tools.xml (props changed)
trunk/src/ru/book/app-webdav.xml (contents, props changed)
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-usage.xml (contents, props changed)
trunk/src/ru/book/ch-branching-and-merging.xml (props changed)
trunk/src/ru/book/ch-customizing-svn.xml (contents, props changed)
trunk/src/ru/book/ch-developer-info.xml (contents, props changed)
trunk/src/ru/book/ch-fundamental-concepts.xml (contents, props changed)
trunk/src/ru/book/ch-preface.xml (contents, props changed)
trunk/src/ru/book/ch-reference.xml (contents, props changed)
trunk/src/ru/book/ch-repository-admin.xml (props changed)
trunk/src/ru/book/ch-server-configuration.xml (contents, props changed)
trunk/src/ru/book/copyright.xml (props changed)
trunk/src/ru/book/foreword.xml (props changed)
trunk/src/ru/book/styles.css (props changed)
Log:
Book Russian. Merge with changes from r2580:r2601 of the src/en/book. More detail in logs for corresponding revisions.
Modified: trunk/src/ru/book/app-svn-for-cvs-users.xml
==============================================================================
--- trunk/src/ru/book/app-svn-for-cvs-users.xml (original)
+++ trunk/src/ru/book/app-svn-for-cvs-users.xml Mon Feb 5 09:15:14 2007
@@ -301,7 +301,7 @@
C Resource has Conflicts (changes have not been completely merged
between the repository and working copy version)
X Resource is eXternal to this working copy (may come from another
- repository). See <xref linkend="svn.advanced.props.special.externals" />
+ repository). See <xref linkend="svn.advanced.externals" />
? Resource is not under version control
! Resource is missing or incomplete (removed by another tool than
Subversion)
Modified: trunk/src/ru/book/app-webdav.xml
==============================================================================
--- trunk/src/ru/book/app-webdav.xml (original)
+++ trunk/src/ru/book/app-webdav.xml Mon Feb 5 09:15:14 2007
@@ -419,7 +419,7 @@
repository via autoversioning. The module looks at the file's
named extension and possibly the contents as well; if the file
matches some common patterns, then the the
- file's <literal>svn;mime-type</literal> property will be set
+ file's <literal>svn:mime-type</literal> property will be set
automatically.</para>
</sect1>
@@ -602,7 +602,7 @@
in Java. It's under a free Apache-like license and is
available at <ulink url="http://www.ics.uci.edu/~webdav/"/>.
DAV Explorer does everything cadaver does, but has the
- advantages of being portable and being more user-friendly GUI
+ advantages of being portable and being a more user-friendly GUI
application. It's also one of the first clients to support
the new WebDAV Access Control Protocol (RFC 3744).</para>
@@ -701,7 +701,7 @@
algorithm seems to work consistently on every system. The
general consensus of the WebDAV community is that you should
avoid the new Web Folders implementation and use the old one
- instead, and that if you need real a real filesystem-level
+ instead, and that if you need a real filesystem-level
client for Windows XP, then use a third-party program like
WebDrive or NetDrive.</para>
@@ -721,7 +721,7 @@
<para>Nautilus is the official file manager/browser for the
GNOME desktop (<ulink url="http://www.gnome.org"/>), and
- Konqueror is the manager/browser for KDE desktop (<ulink
+ Konqueror is the manager/browser for the KDE desktop (<ulink
url="http://www.kde.org"/>). Both of these applications have
an explorer-level WebDAV client built-in, and operate just
fine against an autoversioning repository.</para>
@@ -763,7 +763,7 @@
<title>WebDrive, NetDrive</title>
<para>Both WebDrive and NetDrive are excellent commercial
- products which allows a WebDAV share to be attached as drive
+ products which allow a WebDAV share to be attached as drive
letters in Windows. We've had nothing but success with
these products. At the time of writing, WebDrive can be
purchased from South River Technologies (<ulink
@@ -784,14 +784,19 @@
filesystem-level WebDAV client. From the Finder, select the
<guimenuitem>Connect to Server</guimenuitem> item from the
<guimenu>Go menu</guimenu>. Enter a WebDAV URL, and it
- appears as a disk on the desktop, just like any other mounted
- volume.<footnote><para>From the Darwin terminal, one can also
- run <literal>mount -t webdav URL
- /mountpoint</literal></para></footnote>.</para>
+ appears as a disk on the desktop, just like any other
+ mounted volume. You can also mount a WebDAV share from the
+ Darwin terminal by using the <literal>webdav</literal>
+ filesystem type with the <command>mount</command> command:</para>
+
+ <screen>
+$ mount -t webdav http://svn.example.com/repos/project /some/mountpoint
+$
+</screen>
<para>Note that if your mod_dav_svn is older than version 1.2,
OS X will refuse to mount the share as read-write; it will
- appear as read-only. This is because the OS X insists on
+ appear as read-only. This is because OS X insists on
locking support for read-write shares, and the ability to lock
files first appeared in Subversion 1.2.</para>
Modified: trunk/src/ru/book/book.xml
==============================================================================
--- trunk/src/ru/book/book.xml (original)
+++ trunk/src/ru/book/book.xml Mon Feb 5 09:15:14 2007
@@ -19,6 +19,7 @@
<!ENTITY appc SYSTEM "app-webdav.xml">
<!ENTITY appd SYSTEM "app-third-party-tools.xml">
<!ENTITY license SYSTEM "copyright.xml">
+<!ENTITY index SYSTEM "index.xml">
]>
<!-- @ENGLISH {{{
@@ -33,8 +34,9 @@
<bookinfo>
<!-- @ENGLISH {{{
- <subtitle>For Subversion 1.3</subtitle>
+ <subtitle>For Subversion 1.4</subtitle>
@ENGLISH }}} -->
+ <subtitle>Для Subversion 1.4</subtitle>
<!-- Using revnumber would be more appropriate, but our stylesheets -->
<!-- don't seem to render it. -->
@@ -75,6 +77,7 @@
<year>2004</year>
<year>2005</year>
<year>2006</year>
+ <year>2007</year>
<holder>Ben Collins-Sussman</holder>
<holder>Brian W. Fitzpatrick</holder>
<holder>C. Michael Pilato</holder>
@@ -115,6 +118,7 @@
&appc;
&appd;
&license;
+ &index;
</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 Mon Feb 5 09:15:14 2007
@@ -19,19 +19,6 @@
you to run the <command>svn status</command> command almost
unconsciously. For all intents and purposes, you are ready to
use Subversion in a typical environment.</para>
-
- <para>But the Subversion feature set doesn't stop at <quote>common
- version control operations</quote>.</para>
-
- <para>This chapter highlights some of Subversion's features that
- aren't quite so regularly used. In it, we will discuss
- Subversion's property (or <quote>metadata</quote>) support, and
- how to modify Subversion's default behaviors by tweaking its
- run-time configuration area. We will describe how you can use
- externals definitions to instruct Subversion to pull data from
- multiple repositories. We'll cover in detail some of the
- additional client- and server-side tools that are part of the
- Subversion distribution.</para>
@ENGLISH }}} -->
<para>Если эту книгу вы читали главу за главой, от начала до
конца, то к настоящему моменту должны иметь достаточно знаний
@@ -44,46 +31,347 @@
применять 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>But the Subversion feature set doesn't stop at <quote>common
+ version control operations</quote>. It has other bits of
+ functionality that extend beyond basic file and directory
+ versioning; beyond just sending and receiving changes to and from
+ a central repository.</para>
+ @ENGLISH }}} -->
+ <para>Однако предоставляемый Subversion набор возможностей не
+ ограничивается <quote>типовыми операциями управления
+ версиями</quote>. У Subversion есть функыональнось, выходящая за пределы
+ обычного версионирования файлов и директорий; идущая дальше простой
+ отправки и получения разлиций в и из центрального хранилища.
</para>
+ <!-- @ENGLISH {{{
+ <para>This chapter highlights some of Subversion's features that,
+ while important, aren't part of the typical user's daily routine.
+ It assumes that you are familiar with Subversion's basic file and
+ directory versioning capabilities. If you aren't, you'll want to
+ first read <xref linkend="svn.basic" /> and <xref
+ linkend="svn.tour" />. Once you've mastered those basics and
+ consumed this chapter, you'll be a Subversion power-user!</para>
@ENGLISH }}} -->
- <para>Эта глава рассказывает о не часто используемых возможностях
- Subversion. В ней мы рассмотрим поддержку свойств (или
- <quote>метаданных</quote>) и способы изменения стандартного поведения
- Subversion изменяя ее параметры времени выполнения. Мы расскажем
- как используя внешние зависимости заставить Subversion получать
- информацию из нескольких хранилищ. Подробно рассмотрим клиентские и
- серверные инструменты, входящие в поставку Subversion.</para>
-
- <para>Перед чтением этой главы, необходимо хорошо представлять
+ <para>Эта глава рассказывает о тех возможностях Subversion, которые,
+ не смотря на свою важность, не используются в обычном рутинном рабочем
+ цикле. Перед чтением этой главы, необходимо хорошо представлять
механизмы версионированния файлов и директорий в Subversion.
- Если вы еще этого не прочитали или просто хотите освежить в памяти
- эту информацию, рекомендуем просмотреть <xref linkend="svn.basic" />
- и <xref linkend="svn.tour" />. После того как вы овладеете
- основами и примами, рассмотренными в этой главе, вы станете продвинутым
- пользователем Subversion!</para>
+ Если вы этого не знаете, пред тем как продолжить, вам необходимо
+ прочитать <xref linkend="svn.basic" /> и <xref linkend="svn.tour" />.
+ После того как вы овладеете основами и примами, рассмотренными в этой
+ главе, вы станете продвинутым пользователем Subversion!</para>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <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
+ the 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 as 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 the revision history log 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, <filename>/trunk/object</filename> for example. 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 <emphasis>all</emphasis> the objects that have
+ ever lived at that path? Clearly, Subversion needs a hint about
+ what you really want.</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>The Subversion command-line performs the peg-revision
+ algorithm basically any time it needs to resolve possible
+ ambiguities in the paths and revisions provided to it. Here's
+ an example of such an invocation for the purposes of
+ illustrating that algorithm.</para>
+
+ <screen>
+$ svn <replaceable>command</replaceable> -r <replaceable>OPERATIVE-REV</replaceable> item@<replaceable>PEG-REV</replaceable>
+</screen>
+
+ <para>The algorithm has three simple steps:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>Locate <replaceable>item</replaceable> in the revision
+ identified by <replaceable>PEG-REV</replaceable>. There
+ can be only one such object.</para>
+ </listitem>
+
+ <listitem>
+ <para>Trace the object's history backwards (through any
+ possible renames) to its ancestor in the
+ 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 or have been at that time.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>Note that even when you don't explicitly supply a peg
+ revision or operative revision, they are still present. For
+ your convenience, the default peg revision is
+ <literal>BASE</literal> for working copy items and
+ <literal>HEAD</literal> for repository URLs. And when no
+ operative revision is provided, it defaults to being the same
+ revision as the peg revision.</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>The perceptive reader is probably wondering at this point if
+ the peg revision syntax causes problems for working copy paths
+ or URLs that actually have at signs in them. After
+ all, how does <command>svn</command> know whether
+ <literal>news at 11</literal> is the name of a directory in my
+ tree, or just a syntax for <quote>revision 11 of
+ <filename>news</filename></quote>? Thankfully, while
+ <command>svn</command> will always assume the latter, there is a
+ trivial workaround. You need only append an at sign to the
+ end of the path, such as <literal>news at 11@</literal>.
+ <command>svn</command> only cares about the last at sign in
+ the argument, and it is not considered illegal to omit a literal
+ peg revision specifier after that at sign. This workaround
+ even applies to paths that end in an at sign—you would
+ use <literal>filename@@</literal> to talk about a file named
+ <filename>filename@</filename>.</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>Notice that we didn't provide an operative revision this
+ time. That's because when no operative revision is specified,
+ Subversion assumes a default operative revision that's the same
+ as the peg revision.</para>
+
+ <para>As you can see, the output from our operation appears to be
+ correct. 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>
+
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -92,18 +380,14 @@
<!-- @ENGLISH {{{
<title>Properties</title>
- <para>### TODO: This section needs love. It needs to not devolve
- into a property-by-property reference keyed on property names,
- but should instead remain high-level and functionally-keyed.
- Let the Reference be the by-propname lookup. ###</para>
-
<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>
+ be complete from a version control perspective.</para>
+
+ <para>But it doesn't stop there.</para>
<para>In addition to versioning your directories and files,
Subversion provides interfaces for adding, modifying, and
@@ -117,9 +401,10 @@
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>
+ changes as easily as you can file content changes. And the
+ sending and receiving of property changes occurs as part of your
+ typical commit and update operations—you don't have to
+ change your basic processes to accomodate them.</para>
@ENGLISH }}} -->
<title>Свойства</title>
@@ -128,8 +413,9 @@
посвящены этой самой фундаментальной части функциональных
возможностей этого инструмента. И если поддержка версионирования
этим ограничится, Subversion все равно останется полноценным
- инструментом с точки зрения управления версиями. Однако
- версионирование этим не ограничивается.</para>
+ инструментом с точки зрения управления версиями.</para>
+
+ <para>Однако версионирование этим не ограничивается.</para>
<para>Дополнительно к версионированнию директорий и файлов,
Subversion предоставляет для каждой версионированной директории
@@ -144,33 +430,45 @@
И лучшим из всего является то, что они тоже версионированы
также как и текстовое содержимое файлов. Можно также просто как и
для текстовых изменений изменять, фиксировать и отменять изменения
- свойств. При обновлении рабочей копии также получаются
- и изменения свойств.</para>
-
- <sidebar>
- <!-- @ENGLISH {{{
- <title>Other Properties in Subversion</title>
+ свойств. Отправка и получение редактирований свойств происходит точно
+ так же как и обычные фиксации и обновления — для этого нет
+ необходимости менять обычный порядок действий.</para>
- <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 {{{
+ <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 names and anything-you-want binary
+ values. The main difference is that revision properties are not
+ versioned. In other words, if you change the value of, or
+ delete, a revision property, there's no way within the scope of
+ Subversion's functionality to recover the previous value.</para>
@ENGLISH }}} -->
- <title>Еще один тип свойств в Subversion</title>
-
- <para>Подобные приведенным выше, свойства используются и Subversion.
- Так же как и произвольные имена свойств и соответствующие им значения,
- имеются у файлов и директорий, каждая правка может иметь
- произвольные свойства, присоединенные к ней. С теми же исключениями
- — читаемое, текстовое имя и любое бинарное значение —
- исключая версионирование свойств правок. Подробнее о таких
- неверсионированных свойствах см. <xref
- linkend="svn.reposadmin.basics.revprops" />.</para>
- </sidebar>
+ <para>Подобные приведенным выше, свойства используются и Subversion.
+ Так же как и произвольные имена свойств и соответствующие им значения,
+ имеются у файлов и директорий, каждая правка может иметь
+ произвольные свойства, присоединенные к ней. С теми же исключениями
+ — читаемое имя и любое бинарное значение. Главное отличие в том,
+ что свойства правок не версионируются. Другими словами, если изменить
+ значение свойства правки или удалить такое свойство, у Subversion нет
+ возможностей для востановления предыдущего значения.</para>
+
+ <para>Subversion has no particular policy regarding the use of
+ properties. It 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. And Subversion
+ does, in fact, use properties, both the versioned and
+ unversioned variety. Certain versioned properties have special
+ meaning or effects when found on files and directories, or house
+ a particular bit of information about the revisions on which
+ they are found. Certain revision properties are automatically
+ attached to revisions by Subversion's commit process, and carry
+ information about the revision. Most of these properties are
+ mentioned elsewhere in this or other chapters as part of the
+ more general topics to which they are related. For an
+ exhaustive list of Subversion's pre-defined properties, see
+ <xref linkend="svn.ref.svnprops"/>.</para>
<!-- @ENGLISH {{{
<para>In this section, we will examine the utility—both to
@@ -192,83 +490,78 @@
<sect2 id="svn.advanced.props.why">
<!-- @ENGLISH {{{
<title>Why Properties?</title>
+ @ENGLISH }}} -->
+ <title>Зачем нужны свойства?</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>Just as Subversion uses properties to store extra
+ information about the files, directories, and revisions that
+ it contains, you might also find properties to be of similar
+ use. Some part of the processes around Subversion's usage
+ to which you adhere, or maybe some additional tooling around
+ Subversion that you use, might find utility in having a place
+ close to your versioned data to hang custom metadata about
+ that data.</para>
+
+ <!-- @ENGLISH {{{
<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
+ visitors.</para>
+
+ <para>Now, you can get this functionality using 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>
+ separated from the original image file. But the problem here
+ is that your collection of files grows in multiples with each
+ new photo added to the site.</para>
@ENGLISH }}} -->
- <title>Зачем нужны свойства?</title>
-
- <para>Свойства могут быть очень полезной добавкой к рабочей копии.
- Фактически, сама Subversion использует свойства для хранения
- служебной информации и определения того, какие действия необходимо
- выполнить. Подобным образом и вы можете использовать свойства для
- своих целей. Конечно, все для чего можно использовать свойства
- можно делать, используя обычные версионированные файлы, однако
- обратите внимание на приведенный ниже пример использования
- Subversion-свойств.</para>
-
<para>Скажем, вы хотите разработать веб-сайт, содержащий много
цифровых фотографий и показывающий их с подписью и датой.
Набор этих фотографий постоянно изменяется и вы захотите
по возможности максимально автоматизировать этот сайт. Фотографии
могут быть большого размера и как обычно делают на таких
сайтах, для своих посетителей вам будет необходимо показывать
- миниатюры изображений. Сделать это вы можете с помощью обычных
+ миниатюры изображений.</para>
+
+ <para>Сделать это вы можете с помощью обычных
файлов. То есть рядом, в директории, вы можете иметь файлы
<filename>image123.jpg</filename> и
- <filename>image123-thumbnail.jpg</filename>. Подобным образом,
- отдельно от графического файла, можно хранить и дату. В результате
- ваше дерево файлов будет захламлено и будет многократно увеличиваться
- при каждом добавлении на сайт фотографии.</para>
+ <filename>image123-thumbnail.jpg</filename>. Либо если вам необходимо
+ сохранить то-же имя файла, миниатюры должны будут находиться в
+ отдельной директории, например, так
+ <filename>thumbnails/image123.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>,
+ <para>Now consider the same website deployed in a way that makes
+ use of 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>
+ looks much more manageable—in fact, it looks to the
+ casual browser 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>
@ENGLISH }}} -->
- <para>Представим эту же ситуацию при использовании Subversion-свойств
- файлов. Допустим, имеется файл <filename>image123.jpg</filename>
- и у этого файла установлено свойство
+ <para>Представим эту же ситуацию с веб сайтом, но при использовании
+ Subversion-свойств файлов. Допустим, имеется файл
+ <filename>image123.jpg</filename> и у этого файла установлено свойство
<literal>caption</literal>, <literal>datestamp</literal> и даже
<literal>thumbnail</literal>. В этом случае рабочая копия выглядит
гораздо более управляемо — фактически она будет выглядеть
@@ -281,11 +574,63 @@
не занимаясь чтением индексного файла или играми с путями
файлов.</para>
- <para>Как (и для чего) использовать Subversion-свойства вы решаете
- самостоятельно. Как уже говорилось, Subversion имеет свои применения
- свойств, которые мы рассмотрим в этой главе немного позже. А с начала
- давйте поговорим как работать со свойствами используя программу
- <command>svn</command>.</para>
+ <para>Custom revision properties are also frequently used. One
+ common such use is a property whose value contains an issue
+ tracker ID with which the revision is associated, perhaps
+ because the change made in that revision fixes a bug filed in
+ the tracker issue with that ID. Other uses include hanging
+ more friendly names on the revision—it might be hard to
+ remember that revision 1935 was a fully tested revision. But
+ if there's, say, a <literal>test-results</literal> property on
+ that revision with a value <literal>all passing</literal>,
+ that's meaningful information to have.</para>
+
+ <sidebar>
+ <title>Searchability (or, Why <emphasis>Not</emphasis>
+ Properties)</title>
+
+ <para>For all their utility, Subversion properties—or,
+ more accurately, the available interfaces to them—have
+ a major shortcoming which diminishes their practicality.
+ While it is a simple matter to set a custom property,
+ <emphasis>finding</emphasis> that property later is whole
+ different ball of wax.</para>
+
+ <para>Trying to locate a custom revision property generally
+ involves performing a linear walk across all the revisions
+ of the repository, asking of each revision, "Do you have the
+ property I'm looking for?" Trying to find a custom
+ versioned property is painful, too, and often involves a
+ recursive <command>svn propget</command> across an entire
+ working copy. In your situation, that might not be as bad
+ as a linear walk across all revisions. But it certainly
+ leaves much to be desired in terms of both performance and
+ likelihood of success, especially if the scope of your
+ search would require a working copy from the root of your
+ repository.</para>
+
+ <para>For this reason, you might choose—especially in
+ the revision property use-case—to simply add your
+ metadata to the revision's log message, using some
+ policy-driven (and perhaps programmatically-enforced)
+ formatting that is designed to be quickly parsed from the
+ output of <command>svn log</command>. It is quite common to
+ see in Subversion log messages the likes of:</para>
+
+ <programlisting>
+Issue(s): IZ2376, IZ1919
+Reviewed by: sally
+
+This fixes a nasty segfault in the wort frabbing process
+…
+</programlisting>
+
+ <para>But here again lies some misfortune. Subversion doesn't
+ yet provide a log message templating mechanism, which would
+ go a long way toward helping users be consistent with the
+ formatting of their log-embedded revision metadata.</para>
+
+ </sidebar>
</sect2>
@@ -367,18 +712,18 @@
<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>
+ 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>.
@@ -512,7 +857,7 @@
<!-- @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>
+ преимущестпреимуществ:</para>
@ENGLISH }}} -->
<para>Для полного удаления свойств необходимо использовать
команду <command>propdel</command>. Ее синтаксис такой же
@@ -528,6 +873,102 @@
</screen>
<!-- @ENGLISH {{{
+ <para>Remember those unversioned revision properties? You can
+ modify those, too, using the same <command>svn</command>
+ subcommands that we just described. 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 target path
+ to these property-related commands so long as you are
+ positioned in a working copy of the repository whose
+ revision property you wish to modify. Otherwise, you can
+ simply provide the URL of any path in the repository of
+ interest (including the repository's root URL). 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>
+ If your current working directory is part of a working copy of
+ your repository, you can simply run the
+ <command>svn propset</command> command with no target path:</para>
+ @ENGLISH }}} -->
+ <para>Помните, мы говорили о неверсионированных свойствах
+ правок? Их то же можно менять с помощью <command>svn</command>.
+ Просто добавьте параметр командной строки <option>--revprop</option>
+ и укажите правку, чье свойство вы хотите изменить. Учитывая
+ глобальность правок, в этом случае не нужно указывать путь, так как
+ вы находитесь в рабочей копии хранилища, в котором вы хотите
+ изменить свойство правки. В противном случае, нужно просто указать
+ интересующий вас в хранилище URL (в том числе, это может быть и
+ корневой URL хранилища). Например, может понадобиться заменить
+ лог-сообщение фиксации в существующей правке. <footnote>
+ <para>Исправление в лог сообщениях орфографических, грамматических
+ ошибок, <quote>просто ошибочных</quote> записей, наверно,
+ самые распространенные случаи использования параметра
+ <option>--revprop</option>.</para></footnote>Если текущая рабочая
+ директория является частью рабочей копии хранилища, можно просто
+ выполнить команду <command>svn propset</command>, не указывая целевой
+ путь:</para>
+
+ <screen>
+$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop
+property 'svn:log' set on repository revision '11'
+$
+</screen>
+
+ <para>But even if you haven't checked out a working copy from
+ that repository, you can still affect the property change by
+ providing the repository's root URL:</para>
+
+ <screen>
+$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop \
+ http://svn.example.com/repos/project
+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>
+
+ <tip>
+ <para>Users should, where possible, use <command>svn
+ propedit</command> instead of <command>svn
+ propset</command>. While the end result of the commands is
+ identical, the former will allow them to see the current
+ value of the property they are about to change, which helps
+ them to verify that they are, in fact, making the change
+ they think they are making. This is especially true when
+ modifying unversioned revision properties.</para>
+ </tip>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.workflow">
+ <title>Properties and the Subversion Workflow</title>
+
+ <!-- @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
@@ -546,69 +987,6 @@
— в случае конфликтных ситуаций — чужих изменений
с вашими собственными.</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
@@ -773,272 +1151,506 @@
</sect2>
<!-- =============================================================== -->
- <sect2 id="svn.advanced.props.special">
+ <sect2 id="svn.advanced.props.auto">
+ <title>Automatic Property Setting</title>
- <!-- @ENGLISH {{{
- <title>Special Properties</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>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>Whenever you introduce a file to version control using the
+ <command>svn add</command> or <command>svn import</command>
+ commands, Subversion tries to assist by setting some common
+ file properties automatically. First, on operating systems
+ whose filesystems support an execute permission bit,
+ Subversion will automatically set the
+ <literal>svn:executable</literal> property on newly added or
+ imported files whose execute bit is enabled. (See <xref
+ linkend="svn.advanced.props.special.executable" /> for more
+ about this property.) Secondly, it runs a very basic
+ heuristic to determine if that file contains human-readable
+ content. If not, 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. (For more on
+ Subversion's use of MIME types, see <xref
+ linkend="svn.advanced.props.special.mime-type" />.)</para>
+
+ <para>Subversion also provides, via its runtime configuration
+ system, a more flexible automatic property setting feature
+ which allows you to create mappings of filename patterns to
+ property names and values. Once again, these mappings affect
+ adds and imports, and not only can override the default MIME
+ type decision made by Subversion during those operations, but
+ 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.props.file-portability">
+ <title>File Portability</title>
- <para>У Subversion нет каких то отдельных правил для свойств
- — использовать их можно как угодно. Единственно
- что Subversion требует от вас не использовать в названиях
- свойств префикс <literal>svn:</literal>. Потому, что это
- пространство имен для ее личного использования. Subversion
- выделяет несколько свойств, имеющих особый магический эффект
- для файлов и директорий, для которых они установлены.
- В этом разделе мы раскроем тайну и расскажем, как эти
- специальные свойства делают жизнь немного проще.</para>
+ <para>Fortunately for Subversion users who routinely find
+ themselves on different computers with different operating
+ systems, Subversion's command-line programs almost universally
+ behave identically across all those systems. If you know how to
+ wield <command>svn</command> on one platform, you know how to
+ wield it everywhere.</para>
+
+ <para>However, the same is not always true of other general classes
+ of software, or of the actual files you keep in Subversion. For
+ example, on a Windows machine, the definition of a <quote>text
+ file</quote> would be similar to that used on a Linux box, but
+ with a key difference—the character sequences used to mark
+ the ends of the lines of those files. There are other
+ differences, too. Unix platforms have (and Subversion supports)
+ symbolic links; Windows does not. Unix platforms use filesystem
+ permission to determine executability; Windows uses filename
+ extensions.</para>
+
+ <para>Because Subversion is in no position to unite the whole
+ world in common definitions and implementations of all of these
+ things, the best it can do is to try to help make your life
+ simpler when you need to work with your versioned files and
+ directories on multiple computers and operating systems. This
+ section describes some of the ways Subversion does this.</para>
- <sect3 id="svn.advanced.props.special.executable">
- <title><literal>svn:executable</literal></title>
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.special.mime-type">
+ <title>File Content Type</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>
+ <para>Software programs on most modern operating systems make
+ assumptions about the type and format of the contents of a
+ file by the file's name, specifically its file extension. For
+ example, files whose names end in <filename>.txt</filename>
+ are generally assumed to be human-readable, able to be
+ understood by simple perusal rather than requiring complex
+ processing to decipher. Files whose names end in
+ <filename>.png</filename>, on the other hand, are assumed to
+ be of the Portable Network Graphics type—not
+ human-readable at all, and sensible only when interpreted by
+ software which understands the PNG format and can render the
+ information in that format as a raster image.</para>
+
+ <para>Unfortunately, some of those extensions have changed
+ meanings over time. When personal computers first appeared, a
+ file named <filename>README.DOC</filename> would have almost
+ certainly been a plaintext file, just like today's
+ <filename>.txt</filename> files. But by the mid-1990's,
+ you could almost bet that a file of that name would not be a
+ plaintext file at all, but instead a Microsoft Word document
+ with a proprietary, non-human-readable format. But this
+ change didn't occur overnight—there was certainly a
+ period of confusion for computer users over what exactly they
+ had in hand when they saw a <filename>.DOC</filename> file.
+ <footnote>
+ <para>You think that was rough? During that same era,
+ WordPerfect also used <filename>.DOC</filename> for their
+ proprietary file format's preferred extension!</para>
+ </footnote>
+ </para>
+
+ <para>The popularity of computer networking cast still more
+ doubt on the mapping between a file's name and its content.
+ With information being served across networks and generated
+ dynamically by server-side scripts, there was often no real
+ file <foreignphrase>per se</foreignphrase> to speak of, and
+ therefore no file name. Web servers, for example, needed some
+ other way to tell browsers what they were downloading so the
+ browser could do something intelligent with that information,
+ whether that was to display the data using a program
+ registered to handle that data type, or to prompt the user for
+ where on the client machine to store the downloaded
+ data.</para>
+
+ <para>Eventually, a standard emerged for, among other things,
+ describing the contents of a data stream. In 1996, RFC2045
+ was published, the first of five RFCs describing Multipurpose
+ Internet Mail Extensions (MIME). In it, this RFC describes
+ the concept of media types and subtypes, and recommends a
+ syntax for the representation of those types. Today, MIME
+ media types—or, MIME types— are used almost
+ universally across e-mail applications, Web servers, and other
+ software as the <foreignphrase>de facto</foreignphrase>
+ mechanism for clearing up the file content confusion.</para>
+
+ <para>Subversion joins the ranks of applications which recognize
+ and make use of MIME types. Besides being a general-purpose
+ storage location for a file's content type, the value of the
+ <literal>svn:mime-type</literal> file property determines some
+ behavioral characteristics of Subversion itself.</para>
+
+ <para>For example, 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 containing non-textual data, there is often no
+ concept of a <quote>line</quote>. So, for versioned files
+ whose <literal>svn:mime-type</literal> property is set to a
+ non-textual MIME type (generally, something that doesn't begin
+ with <literal>text/</literal>, though there are exceptions),
+ 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 your web browser a
+ crucial clue about how to display a file when using it to
+ peruse your Subversion repository's contents.</para>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.special.executable">
+ <title>File Executability</title>
+
+ <!-- @ENGLISH {{{
+ <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. But it would be a monumental hassle to have to
+ remember exactly which files in freshly checked-out working
+ copy were supposed to have their executable bits toggled on,
+ and then to have to do that toggling. So, Subversion provides
+ the <literal>svn:executable</literal> property as a way to
+ specify that the executable bit for the file on which that
+ property is set should be enabled, and Subversion honors that
+ request when populating working copies with such files.</para>
@ENGLISH }}} -->
- <para>Свойство <literal>svn:executable</literal> для версионированного
- файла контролирует в полуавтоматическом режиме бит файловой
- системы, разрешающий исполнение. Это свойство не имеет определенного
- значения — просто его наличие говорит о необходимости для
- Subversion выставлять бит разрешения выполнения. Удаление этого
- свойства востанавливает полный контроль операционной системы над
- битом выполнения.</para>
-
- <para>На многих операционных системах возможность выполнения файла
- как команды определяется битом разрешения выполнения. Обычно по
- умолчанию этот бит не установлен и для файлов которым это
- необходимо, он должен быть явно установлен пользователем.
- Файлы в рабочей копии при обновлении создаются каждый раз
- заново если во время обновления получается новая версия.
- Это значит, что вы можете установить бит разрешения выполнения,
- а если при выполнении обновления обновился и этот файл,
- бит разрешения выполнения может оказаться опять сброшеным.
- Для таких случаев Subversion и предлагает использовать
- свойство <literal>svn:executable</literal>, как способ сохранения
- бита разрешения выполнения.</para>
+ <para>На многих операционных системах возможность выполнения файла
+ как команды определяется битом разрешения выполнения. Обычно по
+ умолчанию этот бит не установлен и для файлов которым это
+ необходимо, он должен быть явно установлен пользователем.
+ Однако слишком сложно помнить какие именно файлы в только что соданой
+ рабочей копии должны иметь установленый бит выполнения, и
+ устанавливать этот бит. Для таких случаев Subversion предлагает
+ использовать свойство <literal>svn:executable</literal>, как способ
+ показать для каких файлов бит исполнения должен быть установлен, а
+ Subversion в свою очередь, при создании рабочей копии самомстоятельно
+ обрабытывает такой запрос для подобных файлов.</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>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>
+ <para>Это свойство не имеет ни какой силы на таких файловых
+ системах, как FAT32 и NTFS, не имеющих понятия бита разрешения
+ выполнения<footnote><para>Для определения исполняемых файлов,
+ файловая система Windows использует расширения файлов (такие, как
+ <literal>.EXE</literal>, <literal>.BAT</literal> и
+ <literal>.COM</literal>).</para></footnote>. Кроме того,
+ так как оно не имеет определенного значения, при его установке
+ Subversion принудительно устанавливает значение
+ <literal>*</literal>. Наконец, это свойство действительно только
+ для файлов, не для директорий.</para>
+
+ </sect2>
- </sect3>
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.special.eol-style">
+ <title>End-of-Line Character Sequences</title>
- <sect3 id="svn.advanced.props.special.mime-type">
- <title><literal>svn:mime-type</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 have different conventions about
+ which character sequences 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—a carriage return (<literal>CR</literal>)
+ followed by a 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>
+
+ </sect2>
+ </sect1>
- <!-- @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>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.props.special.ignore">
+ <title>Selective Versioning</title>
+
+ <para>In any given working copy there is a good chance that
+ alongside all those versioned files and directories are other
+ files and directories which are not, and are not intended to be,
+ themselved versioned. Text editors litter directories with
+ backup files. Code compilation processes generate
+ intermediate—or even final—files which you typically
+ wouldn't bother to version. And users themselves drop various
+ other files and directories wherever they see fit, often in
+ version control working copies.</para>
+
+ <para>It's ludicrous to expect Subversion working copies to be
+ somehow impervious to this kind of clutter and impurity. In
+ fact, Subversion counts it as a <emphasis>feature</emphasis>
+ that its working copies are just typical directories, just like
+ unversioned trees. But these not-to-be-versioned files and
+ directories can cause some annoyance for Subversion users. For
+ example, because the <command>svn add</command> and <command>svn
+ import</command> commands act recursively by default, and don't
+ know which files in a given tree you do and don't wish to
+ version, it's easy to accidentally add stuff to version control
+ that you didn't mean to. And because <command>svn
+ status</command> reports, by default, every item of interest in
+ a working copy—including unversioned files and
+ directories—its output can get quite noisy where many of
+ these things exist.</para>
+
+ <para>So Subversion provides a pair of ways for telling it which
+ files you would prefer that it simply disregard. One of the
+ ways involves the use of Subversion's runtime configuration
+ system, and therefore applies to all the Subversion operations
+ which make use of that runtime configuration, generally those
+ performed on a particular computer, or by a particular user of a
+ computer. The other way makes use of Subversion's directory
+ property support, is more tightly bound to the versioned tree
+ itself, and therefore affects everyone who has a working copy of
+ that tree. Both of the mechanisms use file patterns.</para>
+
+ <para>The Subversion runtime configuration system provides an
+ option, <literal>global-ignores</literal>, whose value is a
+ whitespace-delimited collection of file patterns (or globs).
+ These patterns are applied to files which are candidates for
+ addition to version control, as well as to unversioned files
+ which the <command>svn status</command> command notices. If the
+ filenames match one of the patterns, Subversion will basically
+ act as if the file didn't exist at all. This is really useful
+ for file patterns which are nearly universally of the variety
+ that you don't want to version, such as editor backup files like
+ Emacs' <literal>*~</literal> and <literal>.*~</literal>
+ files.</para>
+
+ <para>When found on a versioned directory, the
+ <literal>svn:ignore</literal> property is expected to contain a
+ list of newline-delimited file patterns which Subversion should
+ use to determine ignorable objects in that same directory.
+ These patterns do not override those found in the
+ <literal>global-ignores</literal> runtime configuration option,
+ but are instead appended to that list. And it's worth noting
+ again that, unlike the <literal>global-ignores</literal> option,
+ the patterns found in the <literal>svn:eol-ignore</literal>
+ property apply only to the directory on which that property is
+ set, and not to any of its subdirectories. The
+ <literal>svn:ignore</literal> property is a good way to tell
+ Subversion to ignore files that are likely to be present in
+ every user's working copy of that directory, such as compiler
+ output 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>
+
+ <warning>
+ <para>Subversion's support for ignorable file patterns extends
+ only to the one-time process of adding unversioned
+ files and directories to version control. Once an object is
+ under Subversion's watchkeep, the ignore pattern mechanisms no
+ longer apply to it. In other words, don't expect Subversion
+ to avoid committing changes you've made to a versioned file
+ simply because that file's name matches an ignore
+ pattern—Subversion <emphasis>always</emphasis> notices
+ all of its versioned resources.</para>
+ </warning>
- <screen>
+ <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>
- <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>
+ </sidebar>
- <screen>
+ <para>The global list of ignore patterns tends to be more a
+ matter of personal taste, and tied more closely to a user's
+ particular tool chain than to the details of any particular
+ working copy's needs. So, the rest of this section will focus
+ on the <literal>svn:ignore</literal> property and its
+ uses.</para>
+
+ <para>Say you have the following output from <command>svn
+ status</command>:</para>
+
+ <screen>
$ svn status calc
M calc/button.c
? calc/calculator
@@ -1048,58 +1660,61 @@
? 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 of this project, not just your own. And you know that
+ you aren't interested in seeing those things every time you run
+ <command>svn status</command>, and pretty sure that nobody else
+ is interested in them either. 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>
- <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>
+ <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>
- <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>
+ <screen>
$ svn status
M calc
M calc/button.c
? calc/data.c
</screen>
+
+ <para>Now, all that cruft is missing from the output! Of course,
+ your <filename>calculator</filename> compiled program and all
+ those logfiles are still in your working copy. Subversion is
+ simply not reminding you that they are present and unversioned.
+ And now with all the uninteresting noise removed from the
+ display, you are left with more interesting items—such as
+ that source code file <filename>data.c</filename> that you
+ probably forgot to add to version control.</para>
+
+ <para>Of course, this less-verbose report of your working copy
+ status isn't the only one available. If you actually want to
+ see the ignored files as part of the status report, you can pass
+ the <option>--no-ignore</option> option to Subversion:</para>
- <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>
+ <screen>
$ svn status --no-ignore
M calc/button.c
I calc/calculator
@@ -1109,555 +1724,321 @@
I calc/debug_log.2.gz
I calc/debug_log.3.gz
</screen>
+
+ <para>As mentioned earlier, the list of file 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—both the global and the per-directory
+ lists—to determine which files should not be swept into
+ the version control system as part of a larger recursive
+ addition or import operation. And here again, you can use the
+ <option>--no-ignore</option> option to tell Subversion ignore
+ its ignores list and operate on all the files and directories
+ present.</para>
- <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>
+ </sect1>
- <programlisting>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.props.special.keywords">
+ <title>Keyword Substitution</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>
+ <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>
+ <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>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>
+ <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>
- <screen>
+ </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>
+ <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>
+ <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>
- <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>
+ <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>
- <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>
+ <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>
- <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>
+ <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>
+ <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>
- </sect2>
</sect1>
<!-- ================================================================= -->
@@ -1666,40 +2047,125 @@
<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 copy-modify-merge version control model lives
+ and dies by the granularity of the data merging algorithms
+ employed when trying to resolve conflicts caused by multiple
+ users modifying the same file concurrently. Subversion itself
+ provides only one such algorithm, a three-way differencing
+ algorithm which is smart enough to handle data at a granularity
+ of a single line of text. Subversion also allows you to
+ supplement its content merge processing with external
+ differencing utilities (as described in <xref
+ linkend="svn.advanced.externaldifftools.diff3" />), some of which
+ may do an even better job, perhaps providing granularity of a
+ word or a single character of text. But common among those
+ algorithms is that they generally work only on text files. The
+ landscape starts to look pretty grim when you start talking
+ about content merges of non-textual file formats. And when you
+ can't find a tool that can handle that type of merging, you
+ begin to run into problems with the copy-modify-merge
+ model.</para>
+
+ <para>Let's look at a real-life example of where this model runs
+ aground. Harry and Sally are both graphic designers working on
+ the same project, a bit of marketing collateral for an
+ automobile mechanic. Central to the design of a particular
+ poster is an image of a car in need of some body work, stored in
+ a file using the PNG image format. The poster's layout is
+ almost finished, and both Harry and Sally are pleased with the
+ particular photo they chose for their damaged car—a baby
+ blue 1967 Ford Mustang with an unfortunate bit of crumpling on
+ the left front fender.</para>
+
+ <para>Now, as is common in graphic design work, there's a change
+ in plans which causes the car's color to be a concern. So Sally
+ updates her working copy to <literal>HEAD</literal>, fires up
+ her photo editing software, and sets about tweaking the image so
+ that the car is now cherry red. Meanwhile, Harry, feeling
+ particularly inspired that day, decides that the image would
+ have greater impact if the car also appears to have suffered
+ greater impact. He, too, updates to <literal>HEAD</literal>,
+ and then draws some cracks on the vehicle's windshield. He
+ manages to finish his work before Sally finishes hers, and after
+ admiring the fruits of his undeniable talent, commits the
+ modified image. Shortly thereafter, Sally is finished with the
+ car's new finish, and tries to commit her changes. But, as
+ expected, Subversion fails the commit, informing Sally that now
+ her version of the image is out of date.</para>
+
+ <para>Here's where the difficulty sets in. Were Harry and Sally
+ making changes to a text file, Sally would simply update her
+ working copy, receiving Harry's changes in the process. In the
+ worst possible case, they would have modified the same region of
+ the file, and Sally would have to work out by hand the proper
+ resolution to the conflict. But these aren't text
+ files—they are binary images. And while it's a simple
+ matter to describe what one would expect the results of this
+ content merge to be, there is precious little chance that any
+ software exists which is smart enough to examine the common
+ baseline image that each of these graphic artists worked
+ against, the changes that Harry made, and the changes that Sally
+ made, and spit out an image of a busted-up red Mustang with a
+ cracked windshield!</para>
+
+ <para>Clearly, things would have gone more smoothly if Harry and
+ Sally had serialized their modifications to the image. If, say,
+ Harry had waited to draw his windshield cracks on Sally's
+ now-red car, or if Sally had tweaked the color of a car whose
+ windshield was already cracked. As is discussed in <xref
+ linkend="svn.basic.vsn-models.copy-merge" />, much of these
+ types problems go away entirely where perfect communication
+ between Harry and Sally exists.
+ <footnote>
+ <para>Communication wouldn't have been such bad medicine for
+ Harry and Sally's Hollywood namesakes, either, for that
+ matter.</para>
+ </footnote>
+ But as one's version control system is, in fact, one form of
+ communication, it follows that having that software facilitate
+ the serialization of non-parallelizable energies is no bad
+ thing. And this where Subversion's implementation of the
+ lock-modify-unlock model steps into the spotlight. This is
+ where we talk about Subversion's <firstterm>locking</firstterm>
+ feature, which is similar to the reserved checkouts mechanisms
+ of other version control systems.</para>
- <para>Subversion's locking feature has two main goals:</para>
+ <para>Subversion's locking feature serves two main
+ purposes:</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>
+ <para><emphasis>Serializing access to a versioned
+ resource</emphasis>. But allowing a user to
+ programmatically claim the exclusive right to change to a
+ file in the repository, that user can be reasonably
+ confident that energy invested on unmergeable changes won't
+ be wasted; that his commit of those changes will
+ succeed.</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>
+ <para><emphasis>Aiding communication</emphasis>. By alerting
+ other users that serialization is in effect for particular
+ versioned resource, those other users can reasonably expect
+ that the resource is about to be changed by someone else,
+ and they, too, can avoid wasting their time and energy on
+ unmergeable changes that won't be committable due to eventual
+ out-of-dateness.</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>
+ <para>When referring to Subversion's locking feature, one is
+ actually talking about a fairly diverse collection of behaviors
+ which include the ability to lock a versioned file
+ <footnote>
+ <para>Subversion does not currently allow locks on directories.</para>
+ </footnote>
+ (claiming the exclusive right to modify the file), to unlock
+ that file (yielding that exclusive right to modify), to see
+ reports about which files are locked and by whom, to annotate
+ files for which locking before editing is strongly advised, and
+ so on. In this section, we'll cover all of these facets of the
+ larger locking feature.</para>
<sidebar id="svn.advanced.locking.meanings">
<title>Three meanings of <quote>lock</quote></title>
@@ -1711,34 +2177,28 @@
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>The first is <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>
+
+ <para>Secondly, there are <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>
<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
+ them. In this book, <quote>lock</quote> means the first sort
unless the contrary is either clear from context or explicitly
stated.</para>
+
</sidebar>
<!-- =============================================================== -->
@@ -1751,38 +2211,62 @@
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>
+ token</firstterm>. The repository manages locks, ultimately
+ handling their creation, enforcement, and removal. If any
+ commit transaction attempts to modify or delete a locked file
+ (or delete one of the parent directories of the file), the
+ repository will demand two pieces of information—that
+ the client performing the commit be authenticated as the lock
+ owner, and that the lock token has been provided as part of
+ the commit process as a sort of proof that client knows which
+ lock it is using.</para>
+
+ <para>To demonstrate lock creation, let's refer back to our
+ example of multiple graphic designers working with on the same
+ binary image files. Harry has decided to change a JPEG image.
+ To prevent other people from committing changes to the file
+ while he is modifying it (as well as alerting them that he is
+ about to change it), 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."
+[harry] $ svn lock banana.jpg --message "Editing file for tomorrow's release."
'banana.jpg' locked by user 'harry'.
+[harry] $
+</screen>
-$ svn status
+ <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>Secondly, 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. The locking command would also
+ have failed if the file already been locked by someone
+ else.</para>
+
+ <para>As you can see, the <command>svn lock</command> command
+ prints confirmation of the successful lock. At this point,
+ the fact that the file is locked becomes apparent in the
+ output of the <command>svn status</command> and <command>svn
+ info</command> reporting subcommands.</para>
+
+ <screen>
+[harry] $ svn status
K banana.jpg
-$ svn info banana.jpg
+[harry] $ svn info banana.jpg
Path: banana.jpg
Name: banana.jpg
URL: http://svn.example.com/repos/project/banana.jpg
@@ -1802,34 +2286,16 @@
Lock Comment (1 line):
Editing file for tomorrow's release.
+[harry] $
</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
+ <para>That the <command>svn info</command> command, which does
+ not contact the repository when run against working copy
+ paths, can display the lock token reveals an important fact
+ about lock tokens—that they are cached in the working
+ copy. The presence of the lock token is critical. It gives
+ the working copy authorization to make use of the lock later
+ on. Also, 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>
@@ -1840,44 +2306,39 @@
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>
+ URL</command>. 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, but leave work for the day before you finish
+ your changes to that file. It should not be possible to
+ accidentally commit changes to that same file from your home
+ computer later that evening simply 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>
- <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
+[sally] $ svn delete banana.jpg
D banana.jpg
-
-$ svn commit -m "Delete useless file."
+[sally] $ 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)
-
+[sally] $
</screen>
<para>But Harry, after touching up the banana's shade of yellow,
@@ -1886,57 +2347,49 @@
copy holds the correct lock token:</para>
<screen>
-$ whoami
-harry
-
-$ svn status
+[harry] $ svn status
M K banana.jpg
-
-$ svn commit -m "Make banana more yellow"
+[harry] $ svn commit -m "Make banana more yellow"
Sending banana.jpg
Transmitting file data .
Committed revision 2201.
-
-$ svn status
-$
+[harry] $ svn status
+[harry] $
</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>
+ 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 searches the working
+ copy (or list of targets, if you provide such a list) for
+ local modifications, and sends all the lock tokens it
+ encounters during this walk 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>. This is meant to discourage users from
+ being sloppy about locking, or from holding locks for too
+ long. If Harry haphazardly locks thirty files in a directory
+ named <filename>images</filename> because he's unsure of which
+ files he needs to change, yet only only changes four of those
+ file, when he runs <command>svn commit images</command>, the
+ process will 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>
+ 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. You can
+ also make this your default behavior by setting the
+ <literal>no-unlock</literal> runtime configuration option (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>
+ simple <command>svn unlock</command> command:</para>
<screen>
-$ svn unlock banana.c
+[harry] $ svn unlock banana.c
'banana.c' unlocked.
</screen>
@@ -1951,14 +2404,12 @@
these is <command>svn status --show-updates</command>:</para>
<screen>
-$ whoami
-sally
-
-$ svn status --show-updates
+[sally] $ svn status --show-updates
M 23 bar.c
M O 32 raisin.jpg
* 72 foo.h
Status against revision: 105
+[sally] $
</screen>
<para>In this example, Sally can see not only that her copy of
@@ -1973,7 +2424,7 @@
answers:</para>
<screen>
-$ svn info http://svn.example.com/repos/project/raisin.jpg
+[sally] $ 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
@@ -1988,6 +2439,7 @@
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.
+[sally] $
</screen>
<para>Just as <command>svn info</command> can be used to examine
@@ -2001,8 +2453,8 @@
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>
+ repository, and 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
@@ -2018,8 +2470,9 @@
<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
+ <para>A repository lock isn't sacred—in Subversion's
+ default configuration state, locks can be released not only by
+ the person who created them, 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>
@@ -2032,7 +2485,7 @@
<xref linkend="svn.reposadmin.maint.tk"/>.)</para>
<screen>
-$ svnadmin lslocks /usr/local/svn/repos
+[admin] $ svnadmin lslocks /usr/local/svn/repos
Path: /project2/images/banana.jpg
UUID Token: opaquelocktoken:c32b4d88-e8fb-2310-abb3-153ff1236923
Owner: frank
@@ -2049,8 +2502,9 @@
Comment (1 line):
Need to make a quick tweak to this image.
-$ svnadmin rmlocks /usr/local/svn/repos /project/raisin.jpg
+[admin] $ svnadmin rmlocks /usr/local/svn/repos /project/raisin.jpg
Removed lock on '/project/raisin.jpg'.
+[admin] $
</screen>
<para>The more interesting option is allowing users to break
@@ -2059,26 +2513,20 @@
command:</para>
<screen>
-$ whoami
-sally
-
-$ svn status --show-updates
+[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
+[sally] $ svn unlock raisin.jpg
svn: 'raisin.jpg' is not locked in this working copy
-
-$ svn info raisin.jpg | grep URL
+[sally] $ 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
+[sally] $ 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
+[sally] $ svn unlock --force http://svn.example.com/repos/project/raisin.jpg
'raisin.jpg' unlocked.
+[sally] $
</screen>
<para>Sally's initial attempt to unlock failed because she
@@ -2104,82 +2552,73 @@
do this, pass the <option>--force</option> option
to <command>svn lock</command>:</para>
- <screen>
-$ svn lock raisin.jpg
+ <screen>
+[sally] $ svn lock raisin.jpg
svn: Lock request failed: 423 Locked (http://svn.example.com)
-
-$ svn lock --force raisin.jpg
+[sally] $ svn lock --force raisin.jpg
'raisin.jpg' locked by user 'sally'.
+[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>
+ <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
+ <screen>
+[harry] $ svn status
K raisin.jpg
-
-$ svn status --show-updates
+[harry] $ svn status --show-updates
B 32 raisin.jpg
-
-$ svn update
+[harry] $ svn update
B raisin.jpg
+[harry] $ svn status
+[harry] $
+</screen>
-$ svn status
+ <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>
-$
-</screen>
+ <sidebar>
+ <title>Locking Policies</title>
- <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>
+ <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 runs rampant 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. To
+ learn more about repository hooks, see <xref
+ linkend="svn.reposadmin.create.hooks" />.</para>
+
+ </sidebar>
</sect2>
@@ -2204,351 +2643,76 @@
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
+ <para>Subversion's solution to this problem is to 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
+ <emphasis>before</emphasis> the editing begins. The mechanism
+ is a special property, <literal>svn:needs-lock</literal>. If
+ that property is attached to a file (regardless of its value,
+ which is irrelevant), then Subversion will try to use
+ filesystem-level permissions to make the file read-only,
+ unless, of course, 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>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>
+ something is strange when she opens the file for editing.
+ Many applications alert users immediately when a read-only
+ file is opened for editing. And nearly all applications would
+ at least prevert her from saving changes to the file. This
+ reminds her to lock the file before editing, whereby she
+ discovers the pre-existing lock:</para>
<screen>
-$ /usr/local/bin/gimp raisin.jpg
+[sally] $ /usr/local/bin/gimp raisin.jpg
gimp: error: file is read-only!
-
-$ ls -l raisin.jpg
+[sally] $ ls -l raisin.jpg
-r--r--r-- 1 sally sally 215589 Jun 8 19:23 raisin.jpg
-
-$ svn lock raisin.jpg
+[sally] $ 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
+[sally] $ 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.
-
+[sally] $
</screen>
- <para>As a matter of <quote>best practice</quote>, both users
- and administrators are encouraged to attach
+ <tip>
+ <para>Users and administrators alike are encouraged to attach
the <literal>svn:needs-lock</literal> property to any file
- which cannot be contextually merged. It's the main
+ which cannot be contextually merged. This is the primary
technique for encouraging good locking habits and preventing
wasted effort.</para>
+ </tip>
- <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>
+ <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>Unfortunately, the system isn't flawless. 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. There's not much that
+ Subversion can do in this situation—at the end of the
+ day, there's simply no substitution for good interpersonal
+ communication.
+ <footnote>
+ <para>Except, perhaps, a classic Vulcan mind-meld.</para>
+ </footnote>
+ </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>
-
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -2574,11 +2738,11 @@
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>
+ propedit</command> (see <xref linkend="svn.advanced.props.manip"
+ />). 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
Modified: trunk/src/ru/book/ch-basic-usage.xml
==============================================================================
--- trunk/src/ru/book/ch-basic-usage.xml (original)
+++ trunk/src/ru/book/ch-basic-usage.xml Mon Feb 5 09:15:14 2007
@@ -614,7 +614,7 @@
locale settings are compatible with UTF-8, and you don't use
control characters in path names, you should have no trouble
communicating with Subversion. The command-line client adds
- an extra bit of help—it will automatically escape legal
+ an extra bit of help—it will automatically escape illegal
path characters as needed in URLs you type to create
<quote>legally correct</quote> versions for internal
use.</para>
@@ -1150,8 +1150,35 @@
(команды <command>svn import</command> и <command>svn
mkdir</command> мы рассмотрим позже).</para>
- <!-- @ENGLISH {{{
+ <sidebar>
+ <title>Versioning symbolic links</title>
+
+ <para>On platforms which support them, Subversion is able to
+ version files of the special type <firstterm>symbolic
+ link</firstterm> (or, <quote>symlink</quote>). A symlink is
+ a file which acts as a sort of transparent reference to some
+ other object in the filesystem, allowing programs to read
+ and write to those objects indirectly by way of performing
+ operations on the symlink itself.</para>
+
+ <para>When a symlink is committed into a Subversion
+ repository, Subversion retains the fact that the file was in
+ fact a symlink, as well as to what object the symlink
+ <quote>points</quote>. When that symlink is checked out to
+ another working copy on a supporting system, Subversion
+ reconstructs a real filesystem-level symbolic link from the
+ versioned symlink. But that doesn't in any way limit the
+ usability of working copies on systems such as Windows which
+ do not support symlinks. On such systems, Subversion simply
+ constructs a regular text file whose contents are the path
+ to which to the original symlink pointed. While that file
+ can't be used as a symlink on a Windows system, it also
+ won't prevent Windows users from performing their other
+ Subversion-related activities.</para>
+ </sidebar>
+
<warning>
+ <!-- @ENGLISH {{{
<para>While you can edit your files with whatever tool you
like, you shouldn't change the structure of your working
copy without letting Subversion know what you're doing. Use
@@ -1160,17 +1187,16 @@
to change the structure of your working copy, and use the
<command>svn add</command> command to place new files and
directories under version control.</para> </warning>
- @ENGLISH }}} -->
- <warning>
- <para>Не смотря на то, что файлы вы можете редактировать
- как угодно, не следует менять структуру рабочей копии
- не проинформировав о своих действиях Subversion. Для
- изменения структуры рабочей копии используйте команды
- <command>svn copy</command>, <command>svn delete</command>
- и <command>svn move</command>, а для добавления новых файлов
- и директорий под контроль версий используйте
- <command>svn add</command>.</para>
- </warning>
+ @ENGLISH }}} -->
+ <para>Не смотря на то, что файлы вы можете редактировать
+ как угодно, не следует менять структуру рабочей копии
+ не проинформировав о своих действиях Subversion. Для
+ изменения структуры рабочей копии используйте команды
+ <command>svn copy</command>, <command>svn delete</command>
+ и <command>svn move</command>, а для добавления новых файлов
+ и директорий под контроль версий используйте
+ <command>svn add</command>.</para>
+ </warning>
<variablelist>
@@ -1427,11 +1453,8 @@
<quote>difference</quote>) against the pristine version.
Having this cache is a tremendous benefit—even if you
have a fast net connection, it's much faster to send only a
- file's changes rather than the whole file to the server. At
- first glance, this might not seem that important, but
- imagine the repercussions if you try to commit a one line
- change to a 400MB file and have to send the whole file to
- the server!</para>
+ file's changes rather than the whole file to the
+ server.</para>
@ENGLISH }}} -->
<para>Для этого Subversion использует отдельную для каждого
версионированного файла кэшированную в административной области
@@ -1445,10 +1468,7 @@
<quote>различий</quote>) первоначальной версии. Наличие такого
кеша ужасно выгодно — даже если у вас высокоскоростное
соединение намного быстрее отправлять на сервер только изменения
- файла вместо отправки целого файла. На первый взгляд это может
- показаться не таким уж и важным, но представьте себе последствия,
- если вы попытаетесь зафиксировать изменения в одной строчке для
- файла размером 400MБ и отправите на сервер весь файл!</para>
+ файла вместо отправки целого файла.</para>
</sidebar>
@@ -1815,13 +1835,22 @@
linkend="svn.advanced.props"/> for more information on
properties). If an <computeroutput>M</computeroutput>
appears in the second column, then the properties have been
- modified, otherwise a whitespace will be printed.</para>
+ modified. If a <computeroutput>C</computeroutput> appears
+ in that column, then the properties for the file are in a
+ state of conflict, which must be resolved before committing
+ the changes to the repository. Otherwise a whitespace will
+ be printed.</para>
@ENGLISH }}} -->
<para>Вторая колонка показывает статус свойств файлов и
директорий (больше о свойствах см. в <xref
linkend="svn.advanced.props"/>). Если во второй колонке
показывается <computeroutput>M</computeroutput> свойства
- были изменены, иначе печатается пробел.</para>
+ были изменены. Если в этой колонке показывается
+ <computeroutput>C</computeroutput> это значит, что свойства
+ этого файла находятся в состоянии конфликта, который должен быть
+ решен до фиксации изменений в хранилище. Во всех других случаях
+ будет выведен пробел.
+ </para>
<!-- @ENGLISH {{{
<para>The third column will only show whitespace or an
@@ -3402,9 +3431,9 @@
a file, and pass both that and the file in your working copy
to your external diff program.</para>
- <para>Sometimes it's easier to look at an older version of a
- file in its entirety as opposed to just the differences
- between it and another revision.</para>
+ <para>Secondly, it's sometimes just easier to look at an older
+ version of a file in its entirety than to look only at the
+ differences between it and another revision.</para>
@ENGLISH }}} -->
<para>Вероятно, вам интересно почему мы не воспользовались
<command>svn update --revision</command>, что бы обновить
@@ -3421,7 +3450,7 @@
этот файл вместе с файлом в рабочей копии внешней программе
просмотра различий.</para>
- <para>Иногда проще посмотреть полную старую версию файла чем
+ <para>Во-вторых, иногда проще посмотреть полную старую версию файла чем
только различия между ним и его другой правкой.</para>
</sect2>
Modified: trunk/src/ru/book/ch-customizing-svn.xml
==============================================================================
--- trunk/src/ru/book/ch-customizing-svn.xml (original)
+++ trunk/src/ru/book/ch-customizing-svn.xml Mon Feb 5 09:15:14 2007
@@ -7,8 +7,13 @@
<title>Профессиональное использование Subversion</title>
<!-- See also svn.preface.organization -->
- <para>### TODO ###</para>
+ <para>### TODO: Chapter opening ###</para>
+ <para>### TODO: Gut the runtime config stuff like I did the property
+ stuff, making larger topical sections to which the runtime
+ config stuff generally refers. Like already exists for
+ external diff/diff3, add, for example, a section on
+ external editors. ###</para>
<sect1 id="svn.advanced.confarea">
<!-- @ENGLISH {{{
@@ -136,7 +141,7 @@
создает.</para>
<!-- @ENGLISH {{{
- <para>The configuration area currently contains three
+ <para>The per-user 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
@@ -161,18 +166,18 @@
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.
- Для того, что бы изменить отдельный параметр все, что нужно, просто
- загрузить соответствующий файл в текстовый редактор и изменить
- значение нужного параметра. Если в какой-то момент вы захотите
- восстановить параметры по умолчанию, необходимо просто удалить
- (или переименовать) директорию с конфигурацией, после чего
+ <para>На сегодняшний момент пользовательская область конфигурации
+ содержит три файла — два файла конфигурации
+ (<filename>config</filename> и <filename>servers</filename>) и
+ <filename>README.txt</filename>, который содержит описание INI формата.
+ После их создания, эти файлы содержат значения по умолчанию для всех,
+ поддерживаемых Subversion параметров, обычно закомментированных и
+ объединенных с текстовым описанием значений ключей, влияющих на
+ поведение Subversion. Для того, что бы изменить отдельный параметр все,
+ что нужно, просто загрузить соответствующий файл в текстовый редактор
+ и изменить значение нужного параметра. Если в какой-то момент вы
+ захотите восстановить параметры по умолчанию, необходимо просто
+ удалить (или переименовать) директорию с конфигурацией, после чего
выполнить какую-то безобидную команду <command>svn</command>,
например, <command>svn --version</command>. В результате будет
создана новая директория с конфигурацией и содержимым по
@@ -1251,12 +1256,12 @@
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
+ <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>
Modified: trunk/src/ru/book/ch-developer-info.xml
==============================================================================
--- trunk/src/ru/book/ch-developer-info.xml (original)
+++ trunk/src/ru/book/ch-developer-info.xml Mon Feb 5 09:15:14 2007
@@ -353,10 +353,10 @@
<para>For example, here is a code segment that illustrates the
use of both the repository and filesystem interfaces to create
a new revision of the filesystem in which a directory is
- added. Note that in this example (and all others throughout
- this book), the <function>SVN_ERR()</function> macro simply
- checks for a non-successful error return from the function it
- wraps, and returns that error if it exists.</para>
+ added. Note that in this example, the
+ <function>SVN_ERR()</function> macro simply checks for a
+ non-successful error return from the function it wraps, and
+ returns that error if it exists.</para>
<example id="svn.developer.layerlib.repos.ex-1">
<title>Using the Repository Layer</title>
Modified: trunk/src/ru/book/ch-fundamental-concepts.xml
==============================================================================
--- trunk/src/ru/book/ch-fundamental-concepts.xml (original)
+++ trunk/src/ru/book/ch-fundamental-concepts.xml Mon Feb 5 09:15:14 2007
@@ -36,6 +36,7 @@
Subversion может управлять набором файлов любого типа — она не
ограничивается помощью компьютерным программистам.</para>
+
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -133,12 +134,24 @@
<!-- @ENGLISH {{{
<para>The core mission of a version control system is to enable
collaborative editing and sharing of data. But different
- systems use different strategies to achieve this.</para>
+ systems use different strategies to achieve this. It's
+ important to understand these different strategies for a couple
+ of reasons. First, it will help you compare and contrast
+ existing version control systems, in case you encounter other
+ systems similar to Subversion. Beyond that, it will also help
+ you make more effective use of Subversion, since Subversion
+ itself supports a couple of different ways of working.</para>
@ENGLISH }}} -->
<para>Основной задачей системы управления версиями является
обеспечение совместного редактирования и распределения информации.
Однако разные системы используют разные способы для
- достижения этого.</para>
+ достижения этого. Очень важно понимать отличия между этими способами.
+ Во-первых, это поможет сравнить и сопоставить существующие системы
+ управления версиями, в случае, если вы столкнетесь с другими, подобными
+ Subversion системами. А в последствии это поспособствует и более
+ эфективному использованию Subversion, так как Subversion поддерживает
+ несколько различных методов работы.
+ </para>
<!-- =============================================================== -->
<!-- =============================================================== -->
@@ -312,17 +325,17 @@
<para><emphasis>Locking may create a false sense of
security.</emphasis>
- Pretend that Harry locks and edits file A, while
- Sally simultaneously locks and edits file B. But suppose
- that A and B depend on one another, and the changes made
- to each are semantically incompatible. Suddenly A and B
- don't work together anymore. The locking system was
- powerless to prevent the problem—yet it somehow
- provided a false sense of security. It's easy for Harry and
- Sally to imagine that by locking files, each is beginning a
- safe, insulated task, and thus not bother
- discussing their incompatible changes early
- on.</para>
+ Suppose Harry locks and edits file A, while Sally
+ simultaneously locks and edits file B. But what if A and
+ B depend on one another, and the changes made to each are
+ semantically incompatible? Suddenly A and B don't work
+ together anymore. The locking system was powerless to
+ prevent the problem—yet it somehow provided a false
+ sense of security. It's easy for Harry and Sally to
+ imagine that by locking files, each is beginning a safe,
+ insulated task, and thus not bother discussing their
+ incompatible changes early on. Locking often becomes a
+ substitute for real communication.</para>
@ENGLISH }}} -->
<para><emphasis>Блокирование может вызвать ложное чувство
безопасности.</emphasis>
@@ -335,8 +348,9 @@
бессильна в предотвращении проблемы — вместо этого она
обеспечила ложное чувство безопасности. Для Гарри и Салли
просто вообразить, что, блокируя файлы каждый начинает безопасную
- изолированную задачу и не беспокоиться в начале об обсуждении их
- несовместимых изменений.</para>
+ изолированную задачу и не беспокоиться об обсуждении их
+ несовместимых изменений заранее. Зачастую, блокирование подменяет
+ настоящее общение.</para>
</listitem>
</itemizedlist>
@@ -350,29 +364,29 @@
<title>Модель Копирование-Изменение-Слияние</title>
<!-- @ENGLISH {{{
- <para>Subversion, CVS, and other version control systems use a
- <firstterm>copy-modify-merge</firstterm> model as an
+ <para>Subversion, CVS, and a number of other version control
+ systems use a <firstterm>copy-modify-merge</firstterm> model as an
alternative to locking. In this model, each user's client
contacts the project repository and creates a personal
<firstterm>working copy</firstterm>—a local reflection
- of the repository's files and directories. Users then work in
- parallel, modifying their private copies. Finally, the
- private copies are merged together into a new, final version.
- The version control system often assists with the merging, but
- ultimately a human being is responsible for making it happen
- correctly.</para>
+ of the repository's files and directories. Users then work
+ simultaneously and independently, modifying their private
+ copies. Finally, the private copies are merged together into
+ a new, final version. The version control system often
+ assists with the merging, but ultimately a human being is
+ responsible for making it happen correctly.</para>
@ENGLISH }}} -->
- <para>Subversion, CVS и другие системы управления версиями
- пользуются моделью
+ <para>Subversion, CVS и ряд других систем управления версиями
+ пользуется моделью
<firstterm>копирование-изменение-слияние</firstterm> в качестве
альтернативы блокированию. В этой модели каждый пользовательский
клиент связывается с хранилищем проекта и создает персональную
<firstterm>рабочую копию</firstterm> — локальное отражение
- файлов и каталогов хранилища. После этого пользователи работают
- параллельно, изменяя свои личные копии. В конце концов, личные копии
- сливаются в новую, финальную версию. Обычно система управления
- версиями помогает в слиянии, но, разумеется, за его корректное
- выполнение отвечает человек.</para>
+ файлов и каталогов хранилища. После чего, пользователи работают
+ одновременно и не зависимо друг от друга, изменяя свои личные
+ копии. В конце концов, личные копии сливаются в новую, финальную
+ версию. Обычно система управления версиями помогает в слиянии, но,
+ разумеется, за его корректное выполнение отвечает человек.</para>
<!-- @ENGLISH {{{
<para>Here's an example. Say that Harry and Sally each create
@@ -459,8 +473,8 @@
parallel, never waiting for one another. When they work on
the same files, it turns out that most of their concurrent
changes don't overlap at all; conflicts are infrequent. And
- the amount of time it takes to resolve conflicts is far less
- than the time lost by a locking system.</para>
+ the amount of time it takes to resolve conflicts is usually
+ far less than the time lost by a locking system.</para>
@ENGLISH }}} -->
<para>Модель копирование-изменение-слияние может выглядеть немного
хаотично, однако, на практике она отлично работает. Пользователи могут
@@ -468,8 +482,8 @@
работе над одними и теми же файлами оказывается, что большинство
параллельно вносимых изменений совсем не перекрываются; конфликты
бывают редко. И время, которое было потрачено на разрешение
- конфликтов значительно меньше времени отнимаемого блокирующей
- системой.</para>
+ конфликтов, как правило, значительно меньше времени отнимаемого
+ блокирующей системой.</para>
<!-- @ENGLISH {{{
<para>In the end, it all comes down to one critical factor: user
@@ -530,15 +544,17 @@
будут потеряны.</para>
<!-- @ENGLISH {{{
- <para>While CVS and Subversion are still primarily
- copy-modify-merge systems, they both recognize the need to
- lock an occasional file and provide mechanisms for this.
- See <xref linkend="svn.advanced.locking"/>.</para>
+ <para>While Subversion is still primarily a copy-modify-merge
+ system, it still recognizes the need to lock an occasional
+ file ands provide mechanisms for this. This feature is
+ discussed later in this book, in
+ <xref linkend="svn.advanced.locking"/>.</para>
@ENGLISH }}} -->
- <para>Так как и CVS, и Subversion, — в первую очередь системы типа
- копирование-изменение-слияние, то в них обоих признается необходимость
- блокирования определенных файлов и предлагаются механизмы для
- этого. См. <xref linkend="svn.advanced.locking"/>.</para>
+ <para>Несмотря на то, что Subversion в первую очередь является
+ системой типа копирование-изменение-слияние, в ней признается
+ необходимость блокирования определенных файлов и предлагаются
+ механизмы для этого. Подробнее это возможность рассматривается
+ в книге далее, см. <xref linkend="svn.advanced.locking"/>.</para>
</sidebar>
@@ -569,11 +585,11 @@
<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>
+ <para>Throughout this book, Subversion uses URLs to identify
+ versioned files and directories 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
@@ -799,9 +815,12 @@
<!-- @ENGLISH {{{
<para>Subversion repositories can be accessed through many
different methods—on local disk, or through various
- network protocols. A repository location, however, is
- always a URL. <xref linkend="svn.basic.in-action.wc.tbl-1"/> describes how
- different URL schemas map to the available access methods.</para>
+ network protocols, depending on how your administrator has
+ set things up for you. A repository location, however, is
+ always a URL.
+ <xref linkend="svn.basic.in-action.wc.tbl-1"/> describes how
+ different URL schemas map to the available access
+ methods.</para>
@ENGLISH }}} -->
<para>Получить доступ к хранилищу Subversion можно различными
способами — на локальном диске или через ряд сетевых протоколов.
@@ -877,10 +896,16 @@
<!-- @ENGLISH {{{
<para>For more information on how Subversion parses URLs, see
- <xref linkend="svn.advanced.reposurls"/>.</para>
+ <xref linkend="svn.advanced.reposurls"/>. For more
+ information on the different types of network servers
+ available for Subversion, see
+ <xref linkend="svn.serverconfig"/>.</para>
@ENGLISH }}} -->
<para>Подробнее о том, как Subversion обрабатывает URL, см. в
- <xref linkend="svn.advanced.reposurls"/>.</para>
+ <xref linkend="svn.advanced.reposurls"/>. Подробнее различных типах
+ сетевых серверов, доступных для использования совместно с Subversion
+ см. <xref linkend="svn.serverconfig"/>.
+ </para>
</sidebar>
@@ -904,13 +929,13 @@
<!-- @ENGLISH {{{
<para>To publish your changes to others, you can use
- Subversion's <command>commit</command> command:</para>
+ Subversion's <command>commit</command> command.</para>
@ENGLISH }}} -->
<para>Для того, что бы опубликовать ваши изменения вы можете
- воспользоваться командой <command>commit</command>:</para>
+ воспользоваться командой <command>commit</command>.</para>
<screen>
-$ svn commit button.c
+$ svn commit button.c -m "Fixed a typo in button.c."
Sending button.c
Transmitting file data .
Committed revision 57.
@@ -918,12 +943,15 @@
<!-- @ENGLISH {{{
<para>Now your changes to <filename>button.c</filename> have
- been committed to the repository; if another user checks out a
- working copy of <filename>/calc</filename>, they will see
- your changes in the latest version of the file.</para>
+ been committed to the repository, with a note describing your
+ change (namely, that you fixed a typo). If another user
+ checks out a working copy of <filename>/calc</filename>, they
+ will see your changes in the latest version of the
+ file.</para>
@ENGLISH }}} -->
<para>Теперь ваши изменения в <filename>button.c</filename>
- зафиксированы в хранилище; если другой пользователь
+ с примечанием, описывающим эти изменения (а именно, исправление
+ опечатки), зафиксированы в хранилище; если другой пользователь
создаст рабочую копию <filename>/calc</filename>, он увидит
ваши изменения в последней версии файла.</para>
@@ -997,31 +1025,31 @@
<title>Правки</title>
<!-- @ENGLISH {{{
- <para>An <command>svn commit</command> operation can publish
+ <para>An <command>svn commit</command> operation publishes
changes to any number of files and directories as a single
atomic transaction. In your working copy, you can change
files' contents, create, delete, rename and copy files and
- directories, and then commit the complete set of changes as a
- unit.</para>
+ directories, and then commit a complete set of changes as an
+ atomic transaction.</para>
@ENGLISH }}} -->
- <para>Операция <command>svn commit</command> может опубликовать
+ <para>Операция <command>svn commit</command> публикует
изменения любого количества файлов и каталогов за одну
атомарную операцию. В своей рабочей копии вы можете менять
содержимое файлов, создавать, удалять, переименовывать и
копировать файлы и каталоги, а затем зафиксировать все
- изменения за один раз.</para>
+ изменения за одну атомарную транзакцию.</para>
<!-- @ENGLISH {{{
- <para>In the repository, each commit is treated as an atomic
- transaction: either all the commit's changes take place, or
- none of them take place. Subversion tries to retain this
- atomicity in the face of program crashes, system crashes,
- network problems, and other users' actions.</para>
+ <para>By <quote>atomic transaction</quote>, we mean simply this:
+ either all of the changes happen in the repository, or none of
+ them happen. Subversion tries to retain this atomicity in the
+ face of program crashes, system crashes, network problems, and
+ other users' actions.</para>
@ENGLISH }}} -->
- <para>В хранилище каждая фиксация отражается как атомарная
- операция: либо изменения вносятся полностью, либо не вносятся
+ <para>Под <quote>атомарной транзакцией</quote> понимается следующие:
+ либо в хранилище вносятся все изменения полностью, либо не вносятся
вообще. Subversion ведёт себя так, принимая в расчет возможные
- сбои в программах, системные сбои, проблемы с сетью, а также
+ програмнные сбои, системные сбои, проблемы с сетью, а также
неверные действия пользователя.</para>
<!-- @ENGLISH {{{
@@ -1071,34 +1099,38 @@
<title>Глобальные номера правок</title>
<!-- @ENGLISH {{{
- <para>Unlike those of many other version control systems,
- Subversion's revision numbers apply to <emphasis>entire
- trees</emphasis>, not individual files. Each revision
- number selects an entire tree, a particular state of the
- repository after some committed change. Another way to
- think about it is that revision N represents the state of
- the repository filesystem after the Nth commit. When
- Subversion users talk about <quote>revision 5 of
+ <para>Unlike most version control systems, Subversion's
+ revision numbers apply to <emphasis>entire trees</emphasis>,
+ not individual files. Each revision number selects an
+ entire tree, a particular state of the repository after some
+ committed change. Another way to think about it is that
+ revision N represents the state of the repository filesystem
+ after the Nth commit. When Subversion users talk
+ about <quote>revision 5 of
<filename>foo.c</filename></quote>, they really mean
<quote><filename>foo.c</filename> as it appears in revision
5.</quote> Notice that in general, revisions N and M of a
- file do <emphasis>not</emphasis> necessarily differ! Because
- CVS uses per-file revision numbers, CVS users might want to
- see <xref linkend="svn.forcvs"/> for more details.</para>
+ file do <emphasis>not</emphasis> necessarily differ! Many
+ other version control systems use per-file revision numbers,
+ so this concept may seem unusual at first. (Former CVS users
+ might want to see <xref linkend="svn.forcvs"/> for more
+ details.)</para>
@ENGLISH }}} -->
- <para>В отличие от многих других систем управления версиями, номера правок
- в Subversion относятся <emphasis>ко всем</emphasis>, а не только к
- отдельно взятым файлам. Каждый номер правки соответствует целому
- дереву, отдельному состоянию хранилища после зафиксированного
- изменения. Иначе говоря — правка N представляет состояние
- файловой системы хранилища после выполнения N-ой фиксации. Когда
- пользователи Subversion говорят о <quote>правке 5 <filename>foo.c
- </filename></quote>, на самом деле речь идет о <quote><filename>
- foo.c</filename> входящем в правку 5</quote>. Заметьте, что
- обычно правки N и M файла <emphasis>не обязательно</emphasis>
- будут отличаться. Поскольку в CVS используется пофайловая нумерация
- правок, пользователи CVS могут обратиться за более подробной
- информацией к <xref linkend="svn.forcvs"/>.</para>
+ <para>В отличие от большинства систем управления версиями, номера
+ правок в Subversion относятся <emphasis>ко всем</emphasis>,
+ а не только к отдельно взятым файлам. Каждый номер правки
+ соответствует целому дереву, отдельному состоянию хранилища после
+ зафиксированного изменения. Иначе говоря — правка N
+ представляет состояние файловой системы хранилища после выполнения
+ N-ой фиксации. Когда пользователи Subversion говорят о
+ <quote>правке 5 <filename>foo.c</filename></quote>, на самом деле
+ речь идет о <quote><filename>foo.c</filename> входящем в правку
+ 5</quote>. Заметьте, что обычно правки N и M файла
+ <emphasis>не обязательно</emphasis> будут отличаться! Многие
+ системы управления версиями исполюзуют пофайловую нумерацию правок,
+ поэтому этот подход на первых порах может казаться непривычным.
+ (Бывшие пользователи CVS могут обратиться за более подробной
+ информацией к <xref linkend="svn.forcvs"/>.)</para>
</sidebar>
<!-- @ENGLISH {{{
@@ -1264,16 +1296,16 @@
<!-- @ENGLISH {{{
<para>The file has been changed in the working directory,
and no changes to that file have been committed to the
- repository since its base revision. There are local
+ repository since you last updated. There are local
changes that have not been committed to the repository,
thus an <command>svn commit</command> of the file will
succeed in publishing your changes, and an <command>svn
update</command> of the file will do nothing.</para>
@ENGLISH }}} -->
<para>Файл был изменен в рабочей копии, но в хранилище не
- фиксировались изменения этого файла после правки, на которой он
- основан. Есть локальные изменения, которые не были зафиксированы
- в хранилище, поэтому <command>svn commit</command>
+ фиксировались изменения этого файла последнего обновления
+ рабочей копии. Есть локальные изменения, которые не были
+ зафиксированы в хранилище, поэтому <command>svn commit</command>
выполнит фиксацию ваших изменений, а
<command>svn update</command> не сделает ничего.</para>
</listitem>
@@ -1290,15 +1322,15 @@
<para>The file has not been changed in the working
directory, but it has been changed in the repository.
The file should eventually be updated, to make it
- current with the public revision. An <command>svn
+ current with the latest public revision. An <command>svn
commit</command> of the file will do nothing, and an
<command>svn update</command> of the file will fold the
latest changes into your working copy.</para>
@ENGLISH }}} -->
<para>В рабочем каталоге файл не изменялся, но был изменен в
хранилище. Необходимо выполнить обновление файла для того,
- чтобы он соответствовал текущей правке. Команда <command>
- svn commit</command> не сделает ничего, а
+ чтобы он соответствовал текущей опубликованной правке.
+ Команда <command>svn commit</command> не сделает ничего, а
<command>svn update</command> обновит вашу рабочую копию файла в
соответствии с последними изменениями.</para>
</listitem>
@@ -1338,7 +1370,8 @@
<para>This may sound like a lot to keep track of, but the
<command>svn status</command> command will show you the state
of any item in your working copy. For more information on
- that command, see <xref linkend="svn.tour.cycle.examine.status" />.</para>
+ that command, see
+ <xref linkend="svn.tour.cycle.examine.status" />.</para>
@ENGLISH }}} -->
<para>Может показаться, что следить за актуальным состоянием рабочей
копии сложно. Это не так. Для того, чтобы узнать состояние любого
@@ -1596,7 +1629,7 @@
directory unless it's fully up-to-date. You'll learn
about attaching
<quote>properties</quote> to items in <xref
- linkend="svn.serverconfig"/>. A directory's working
+ linkend="svn.advanced"/>. A directory's working
revision defines a specific set of entries and properties,
and thus committing a property change to an out-of-date
directory may destroy properties you've not yet
@@ -1605,7 +1638,7 @@
<para>Во-вторых, нельзя зафиксировать изменение метаданных
для не обновленного каталога. О присвоении
<quote>свойств</quote> к элементам вы узнаете в <xref
- linkend="svn.serverconfig"/>. Рабочая правка каталога
+ linkend="svn.advanced"/>. Рабочая правка каталога
определяет конкретный набор входящих в нее элементов и
свойств, поэтому фиксация изменений свойств для устаревшего
каталога может привести к уничтожению свойств о которых
@@ -1672,7 +1705,7 @@
<!-- @ENGLISH {{{
<para>At this point, you should have a good idea of how Subversion
works in the most general sense. Armed with this knowledge, you
- should now be ready to jump into the next chapter, which is a
+ should now be ready to move into the next chapter, which is a
detailed tour of Subversion's commands and features.</para>
@ENGLISH }}} -->
<para>На данный момент у вас должно быть хорошее представление о том, как
Modified: trunk/src/ru/book/ch-preface.xml
==============================================================================
--- trunk/src/ru/book/ch-preface.xml (original)
+++ trunk/src/ru/book/ch-preface.xml Mon Feb 5 09:15:14 2007
@@ -5,34 +5,51 @@
@ENGLISH }}} -->
<title>Об этой книге</title>
- <!-- @ENGLISH {{{
+ <!-- ### TODO(sussman): I replaced our rope-quote with some cool
+ quotes that (to me) demonstrate some core truths about subversion's
+ design philosophy. We probably don't want to keep both of them in
+ there forever... remove one at some point, after we discuss. -->
+
<blockquote>
- <attribution>Brian W. Fitzpatrick</attribution>
- <para><quote>If C gives you enough rope to hang yourself, think
- of Subversion as a sort of rope storage facility.</quote></para>
+ <attribution>Greg Hudson</attribution>
+ <para><quote>Unnecessary optimization is the root of all evil.
+ (Okay, 65% of all evil.)</quote></para>
</blockquote>
- @ENGLISH }}} -->
+
<blockquote>
- <attribution>Brian W. Fitzpatrick</attribution>
- <para><quote>Если язык C — это клубок верёвок, в
- которых можно легко запутаться, то Subversion — это
- что-то вроде склада для верёвок.</quote></para>
+ <attribution>Greg Hudson</attribution>
+ <para><quote>It is important not to let the perfect become the
+ enemy of the good, even when you can agree on what perfect is.
+ Doubly so when you can't. As unpleasant as it is to be trapped by
+ past mistakes, you can't make any progress by being afraid of your
+ own shadow during design.</quote></para>
</blockquote>
+ <!-- ### NOTE: I've rephrased this section to make CVS sound like
+ it "used" to be the big standard, but no more. :-) -->
+
+ <para>
+ <indexterm>
+ <primary>Concurrent Versions System (CVS)</primary>
+ </indexterm>
+ <indexterm>
+ <primary>###</primary>
+ <secondary>TODO: More indexterms!</secondary>
+ </indexterm>
+
<!-- @ENGLISH {{{
- <para>In the world of open-source software, the Concurrent
- Versions System (CVS) has long been the tool of choice for
- version control. And rightly so. CVS itself is free software,
- and its non-restrictive <foreignphrase>modus
- operandi</foreignphrase> and support for networked
- operation—which allow dozens of geographically dispersed
- programmers to share their work—fits the collaborative
- nature of the open-source world very well. CVS and its
- semi-chaotic development model have become cornerstones of
- open-source culture.
+ In the world of open-source software, the Concurrent Versions
+ System (CVS) was the tool of choice for version control for many
+ years. And rightly so. CVS was open-source software itself, and
+ its non-restrictive <foreignphrase>modus operandi</foreignphrase>
+ and support for networked operation allowed dozens of
+ geographically dispersed programmers to share their work. It fit
+ the collaborative nature of the open-source world very well. CVS
+ and its semi-chaotic development model have since become
+ cornerstones of open-source culture.
</para>
@ENGLISH }}} -->
- <para>В мире программного обеспечения с открытым исходным кодом в
+ В мире программного обеспечения с открытым исходным кодом в
качестве инструмента управления версиями долгое время
использовалась Concurrent Versions System<footnote><para>Система
параллельного управления версиями</para></footnote> (CVS). На
@@ -46,20 +63,22 @@
камнями культуры свободного программного обеспечения.</para>
<!-- @ENGLISH {{{
- <para>But like many tools, CVS is starting to show its age.
- Subversion is a relatively new version control system designed
- to be the successor to CVS. The designers set out to win the
- hearts of CVS users in two ways: by creating an open-source
- system with a design (and <quote>look and feel</quote>) similar
- to CVS, and by attempting to fix most of CVS's noticeable flaws.
- While the result isn't necessarily the next great evolution in
- version control design, Subversion <emphasis>is</emphasis> very
- powerful, very usable, and very flexible.
+ <para>But like many tools, CVS began to show its age, and Subversion
+ entered the picture. Subversion was originally designed as a
+ successor to CVS. The designers set out to win the hearts of CVS
+ users in two ways: by creating an open-source system with a design
+ (and <quote>look and feel</quote>) similar to CVS, and by
+ attempting to fix most of CVS's noticeable flaws. While the
+ result isn't necessarily the next great evolution in version
+ control design, Subversion <emphasis>is</emphasis> very powerful,
+ very usable, and very flexible. And for the most part, almost all
+ newly-started open-source projects now choose Subversion instead
+ of CVS.
</para>
@ENGLISH }}} -->
- <para>Однако, несмотря на все достоинства CVS, её возраст даёт о себе
- знать. Subversion представляет собой относительно молодую систему
- управления версиями, призванную прийти на смену CVS. Её разработчики
+ <para>Однако, несмотря на все достоинства CVS, её возраст стал давать о себе
+ знать, вот здесь на сцену и вышла Subversion. Изначально, Subversion
+ была задумана как правопреемник CVS. Разработчики Subversion
стремятся завоевать сердца пользователей CVS сразу с двух сторон:
во-первых, Subversion создаётся как система с открытым исходным
кодом, которая по своему устройству и ощущениям от работы напоминает
@@ -67,20 +86,22 @@
недостатки CVS. И хотя то, что получается в результате, не
обязательно является новым витком в развитии технологий управления
версиями, Subversion <emphasis>на самом деле</emphasis> очень
- мощное, удобное и гибкое средство.</para>
+ мощное, удобное и гибкое средство. Как правило, едвали не все новые
+ проекты с открытым исходным кодом сейчас вместо CVS выбирают
+ Subversion.</para>
<!-- @ENGLISH {{{
- <para>This book is written to document the 1.3 series of the
- Subversion version control system. We have made every attempt to be
- thorough in our coverage. However, Subversion has a thriving
- and energetic development community, so there are already a
- number of features and improvements planned for future versions
- of Subversion that may change some of the commands and specific
- notes in this book.
+ <para>This book is written to document the 1.4 series of the
+ Subversion version control system. We have made every attempt to
+ be thorough in our coverage. However, Subversion has a thriving
+ and energetic development community, so there are already a number
+ of features and improvements planned for future versions of
+ Subversion that may change some of the commands and specific notes
+ in this book.
</para>
@ENGLISH }}} -->
<para>Эта книга описывает систему управления версиями Subversion
- поколения 1.3. Мы стремились охватить материал как можно шире.
+ поколения 1.4. Мы стремились охватить материал как можно шире.
В то же время следует иметь в виду, что разработкой Subversion
занимается активное энергичное сообщество, так что уже сейчас идёт
работа над рядом особенностей и улучшений, которые будут внесены в
@@ -126,9 +147,7 @@
(<literal>\</literal>) instead of forward slashes
(<literal>/</literal>) for path separators, the input to and
output from this tool when run on Windows are identical to its
- Unix counterpart. However, Windows users may find more success
- by running the examples inside the Cygwin Unix emulation
- environment.</para>
+ Unix counterpart.</para>
@ENGLISH }}} -->
<para>Вместе с тем, программа <command>svn</command> работает и на
других платформах, например в Microsoft Windows. Ввод и вывод этой
@@ -136,9 +155,7 @@
незначительных различий, вроде использования символа обратной
косой черты (<literal>\</literal>) вместо прямой косой
(<literal>/</literal>) в качестве разделителя компонентов пути к
- файлу. Пользователи Windows могут также работать с приведёнными
- примерами в среде эмуляции Unix Cygwin, чтобы свести на нет даже
- самые незначительные различия.</para>
+ файлу.</para>
<!-- @ENGLISH {{{
<para>Most readers are probably programmers or system
@@ -161,17 +178,18 @@
<!-- @ENGLISH {{{
<para>While this book is written with the assumption that the
reader has never used version control, we've also tried to make
- it easy for users of CVS to make a painless leap into
- Subversion. Special sidebars may discuss CVS from time to time,
- and a special appendix summarizes most of the differences
- between CVS and Subversion.</para>
+ it easy for users of CVS (and other systems) to make a painless
+ leap into Subversion. Special sidebars may mention other
+ version control systems from time to time, and a special
+ appendix summarizes many of the differences between CVS and
+ Subversion.</para>
@ENGLISH }}} -->
<para>Мы писали книгу исходя из того, что читатель никогда не
использовал управление версиями раньше, но в то же время пытались
- облегчить переход на Subversion для пользователей CVS. CVS
- посвящены специальные врезки в тексте книги, а обзор основных
- различий между CVS и Subversion вынесен в отдельное
- приложение.</para>
+ облегчить переход на Subversion для пользователей CVS (и других систем).
+ По мере необходимости, в тексте книги встречаются специальные врезки,
+ посвященные другим системам управления версиями, а обзор основных
+ различий между CVS и Subversion вынесен в отдельное приложение.</para>
<!-- @ENGLISH {{{
<para>Note also that the source code examples used throughout the
@@ -218,15 +236,16 @@
<varlistentry>
<term>Experienced System Administrators</term>
<listitem>
- <para>The assumption here is that you've probably used CVS
- before, and are dying to get a Subversion server up and
- running ASAP. <xref linkend="svn.reposadmin"/> and <xref
- linkend="svn.serverconfig"/> will show you how to create
- your first repository and make it available over the
- network. After that's done, <xref linkend="svn.tour"/> and
+ <para>The assumption here is that you've probably used
+ version control before before, and are dying to get a
+ Subversion server up and running ASAP.
+ <xref linkend="svn.reposadmin"/> and
+ <xref linkend="svn.serverconfig"/> will show you how to
+ create your first repository and make it available over
+ the network. After that's done,
+ <xref linkend="svn.tour"/> and
<xref linkend="svn.forcvs"/> are the fastest routes to
- learning the Subversion client while drawing on your CVS
- experience.</para>
+ learning the Subversion client.</para>
</listitem>
</varlistentry>
@ENGLISH }}} -->
@@ -234,14 +253,14 @@
<term>Опытные системные администраторы</term>
<listitem>
<para>Предполагается, что читатели этой группы раннее уже
- использовали CVS и теперь им не терпится поднять сервер
- Subversion как можно скорее. В <xref linkend="svn.reposadmin"/>
+ использовали систему управления версиями и теперь им не терпится
+ поднять сервер Subversion как можно скорее.
+ В <xref linkend="svn.reposadmin"/>
и <xref linkend="svn.serverconfig"/> показано, как
создать первое хранилище и сделать его доступным в сети.
- Далее можно перейти к изучению клиента Subversion, причём
- для пользователей CVS наиболее быстрым путём к цели будет
- чтение <xref linkend="svn.tour"/> и <xref
- linkend="svn.forcvs"/>.</para>
+ Далее можно перейти к изучению клиента Subversion, причём чтение
+ <xref linkend="svn.tour"/> и <xref linkend="svn.forcvs"/>
+ будет наиболее быстрым путём к цели.</para>
</listitem>
</varlistentry>
@@ -251,11 +270,10 @@
<listitem>
<para>Your administrator has probably set up Subversion
already, and you need to learn how to use the client. If
- you've never used a version control system (like CVS),
- then <xref linkend="svn.basic"/> and <xref
- linkend="svn.tour"/> are a vital introduction. If you're
- already an old hand at CVS, chapter 3 and appendix A are
- the best place to start.</para>
+ you've never used a version control system, then
+ <xref linkend="svn.basic"/> is a vital introduction to the
+ ideas behind version control. <xref linkend="svn.tour"/>
+ is a guided tour of the Subversion client.</para>
</listitem>
</varlistentry>
@ENGLISH }}} -->
@@ -264,11 +282,10 @@
<listitem>
<para>По-видимому, администратор уже установил Subversion в
сети и вам необходимо научиться пользоваться клиентом. Если
- вы раньше не использовали систему управления версиями
- (например, CVS), то начать следует с <xref linkend="svn.basic"/>
- и <xref linkend="svn.tour"/>, где содержатся основные вводные
- сведения. Если же вы хорошо знакомы с CVS, то вам больше подойдёт
- изучение главы 3 и приложения A.</para>
+ вы раньше не пользовались системой управления версиями,
+ то <xref linkend="svn.basic"/> будет необходимым введением.
+ А <xref linkend="svn.tour"/> содержит основные сведения о клиенте
+ Subversion.</para>
</listitem>
</varlistentry>
@@ -283,7 +300,7 @@
linkend="svn.branchmerge"/>), how to use Subversion's
property support, how to configure runtime options (<xref
linkend="svn.advanced"/>), and other things. These two
- chapters aren't vital at first, but be sure to read them
+ chapters aren't critical at first, but be sure to read them
once you're comfortable with the basics.</para>
</listitem>
</varlistentry>
@@ -478,22 +495,19 @@
<!-- @ENGLISH {{{
<varlistentry>
- <term><xref linkend="svn.intro"/></term>
+ <term><xref linkend="svn.preface"/></term>
<listitem>
<para>Covers the history of Subversion as well as its
- features, architecture, components, and install
- methods. Also includes a quick-start guide.</para>
+ features, architecture, and components.</para>
</listitem>
</varlistentry>
@ENGLISH }}} -->
<varlistentry>
- <term><xref linkend="svn.intro"/></term>
+ <term><xref linkend="svn.preface"/></term>
<listitem>
<para>В этой главе приводятся сведения об истории
- Subversion, обсуждаются её возможности, архитектура,
- компоненты и способы установки. Здесь же приводится
- краткий курс, позволяющий быстро приступить к работе с
- Subversion.</para>
+ Subversion, обсуждаются её возможности, архитектура и
+ компоненты.</para>
</listitem>
</varlistentry>
@@ -523,8 +537,8 @@
<term><xref linkend="svn.tour"/></term>
<listitem>
<para>Walks you through a day in the life of a Subversion
- user. It demonstrates how to use Subversion to obtain,
- modify, and commit data.</para>
+ user. It demonstrates how to use a Subversion client to
+ obtain, modify, and commit data.</para>
</listitem>
</varlistentry>
@ENGLISH }}} -->
@@ -532,7 +546,7 @@
<term><xref linkend="svn.tour"/></term>
<listitem>
<para>Один день из жизни пользователя Subversion. Глава
- поясняет, как использовать Subversion для получения
+ поясняет, как использовать клиент Subversion для получения
данных, внесения в них изменений и фиксации изменённых
данных в хранилище.</para>
</listitem>
@@ -540,6 +554,26 @@
<!-- @ENGLISH {{{
<varlistentry>
+ <term><xref linkend="svn.advanced"/></term>
+ <listitem>
+ <para>Covers more complex features that regular users will
+ eventually come into contact with, such as versioned
+ metadata, file locking, and peg revisions.</para>
+ </listitem>
+ </varlistentry>
+ @ENGLISH }}} -->
+ <varlistentry>
+ <term><xref linkend="svn.advanced"/></term>
+ <listitem>
+ <para>Рассматриваются сложные вопросы, с которыми постоянные
+ пользователи рано или поздно столкнутся. Например,
+ версионирование метаданных, блокирование файлов и
+ peg revisions.</para>
+ </listitem>
+ </varlistentry>
+
+ <!-- @ENGLISH {{{
+ <varlistentry>
<term><xref linkend="svn.branchmerge"/></term>
<listitem>
<para>Discusses branches, merges, and tagging, including
@@ -587,7 +621,7 @@
<para>Explains how to configure your Subversion server and
the three ways to access your repository:
<literal>HTTP</literal>, the <literal>svn</literal>
- protocol, and local access. It also covers the details
+ protocol, and local disk access. It also covers the details
of authentication, authorization and anonymous
access.</para>
</listitem>
@@ -608,24 +642,21 @@
<!-- @ENGLISH {{{
<varlistentry>
- <term><xref linkend="svn.advanced"/></term>
+ <term><xref linkend="svn.customization"/></term>
<listitem>
<para>Explores the Subversion client configuration files,
- file and directory properties, how to
- <literal>ignore</literal> files in your working copy,
- how to include external trees in your working copy, and
- lastly, how to handle vendor branches.</para>
+ the handling of internationalized text, and how to make
+ external tools cooperate with Subversion.</para>
</listitem>
</varlistentry>
@ENGLISH }}} -->
<varlistentry>
- <term><xref linkend="svn.advanced"/></term>
+ <term><xref linkend="svn.customization"/></term>
<listitem>
<para>В этой главе подробно рассмотрены файлы для настройки
- клиента Subversion, свойства файлов и каталогов, показано,
- как игнорировать отдельные файлы в рабочей копии, как
- помещать в рабочую копию внешние деревья, как работать с
- ветвями от сторонних поставщиков.</para>
+ клиента Subversion, обработка текста на национальнных языках и
+ совместная работа Subversion с программами сторонних
+ разработчиков.</para>
</listitem>
</varlistentry>
@@ -678,6 +709,25 @@
<!-- @ENGLISH {{{
<varlistentry>
+ <term><xref linkend="svn.intro"/></term>
+ <listitem>
+ <para>For the impatient, a whirlwind explanation of how to
+ install Subversion and start using it immediately. You
+ have been warned.</para>
+ </listitem>
+ </varlistentry>
+ @ENGLISH }}} -->
+ <varlistentry>
+ <term><xref linkend="svn.intro"/></term>
+ <listitem>
+ <para>Для самых нетерпеливых, ураганное описание того, как
+ установить и немедленно приступить к использованию
+ Subversion. Мы вас предупредили.</para>
+ </listitem>
+ </varlistentry>
+
+ <!-- @ENGLISH {{{
+ <varlistentry>
<term><xref linkend="svn.forcvs"/></term>
<listitem>
<para>Covers the similarities and differences between
@@ -789,17 +839,19 @@
<listitem>
<!-- @ENGLISH {{{
- <para>You can distribute and make changes to this book however
- you wish—it's under a free license. Of course,
- rather than distribute your own private version of this
- book, we'd much rather you send feedback and patches to the
- Subversion developer community.</para>
+ <para>You can make changes to this book and redistribute it
+ however you wish—it's under a free license. Your only
+ obligation is to maintain proper attribution to the original
+ authors. Of course, rather than distribute your own private
+ version of this book, we'd much rather you send feedback and
+ patches to the Subversion developer community.</para>
@ENGLISH }}} -->
<para>Вы можете распространять эту книгу и вносить в неё
изменения по своему усмотрению — лицензия на
- использование книги является свободной. Конечно, будет лучше
- всего, если вместо того, чтобы распространять собственную
- версию книги, вы поделитесь отзывами и исправлениями с
+ использование книги является свободной. От вас требуется только
+ ссылаться в качестве первоисточника на первоначальных авторов.
+ Конечно, будет лучше всего, если вместо того, чтобы распространять
+ собственную версию книги, вы поделитесь отзывами и исправлениями с
сообществом разработчиков Subversion.</para>
</listitem>
</itemizedlist>
@@ -863,48 +915,52 @@
<para>Finally, we thank the countless people who contributed to
this book with informal reviews, suggestions, and fixes: While
this is undoubtedly not a complete list, this book would be
- incomplete and incorrect without the help of: Jani Averbach,
- Ryan Barrett, Francois Beausoleil, Jennifer Bevan, Matt Blais,
- Zack Brown, Martin Buchholz, Brane Cibej, John R. Daily, Peter
- Davis, Olivier Davy, Robert P. J. Day, Mo DeJong, Brian Denny,
- Joe Drew, Nick Duffek, Ben Elliston, Justin Erenkrantz, Shlomi
- Fish, Julian Foad, Chris Foote, Martin Furter, Dave Gilbert,
- Eric Gillespie, Matthew Gregan, Art Haas, Greg Hudson, Alexis
- Huxley, Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark
- Benedetto King, Andreas J. Koenig, Nuutti Kotivuori, Matt Kraai,
- Scott Lamb, Vincent Lefevre, Morten Ludvigsen, Paul Lussier,
- Bruce A. Mah, Philip Martin, Feliciano Matias, Patrick Mayweg,
- Gareth McCaughan, Jon Middleton, Tim Moloney, Mats Nilsson, Joe
- Orton, Amy Lyn Pilato, Kevin Pilch-Bisson, Dmitriy Popkov,
- Michael Price, Mark Proctor, Steffen Prohaska, Daniel Rall,
- Tobias Ringstrom, Garrett Rooney, Joel Rosdahl, Christian Sauer,
- Larry Shatzer, Russell Steicke, Sander Striker, Erik Sjoelund,
- Johan Sundstroem, John Szakmeister, Mason Thomas, Eric
- Wadsworth, Colin Watson, Alex Waugh, Chad Whitacre, Josef Wolf,
- Blair Zajac, and the entire Subversion community.</para>
+ incomplete and incorrect without the help of: David Anderson,
+ Jani Averbach, Ryan Barrett, Francois Beausoleil, Jennifer
+ Bevan, Matt Blais, Zack Brown, Martin Buchholz, Brane Cibej,
+ John R. Daily, Peter Davis, Olivier Davy, Robert P. J. Day, Mo
+ DeJong, Brian Denny, Joe Drew, Nick Duffek, Ben Elliston, Justin
+ Erenkrantz, Shlomi Fish, Julian Foad, Chris Foote, Martin
+ Furter, Dave Gilbert, Eric Gillespie, David Glasser, Matthew
+ Gregan, Art Haas, Eric Hanchrow, Greg Hudson, Alexis Huxley,
+ Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark Benedetto
+ King, Andreas J. Koenig, Nuutti Kotivuori, Matt Kraai, Scott
+ Lamb, Vincent Lefevre, Morten Ludvigsen, Paul Lussier, Bruce
+ A. Mah, Philip Martin, Feliciano Matias, Patrick Mayweg, Gareth
+ McCaughan, Jon Middleton, Tim Moloney, Christopher Ness, Mats
+ Nilsson, Joe Orton, Amy Lyn Pilato, Kevin Pilch-Bisson, Dmitriy
+ Popkov, Michael Price, Mark Proctor, Steffen Prohaska, Daniel
+ Rall, Jack Repenning, Tobias Ringstrom, Garrett Rooney, Joel
+ Rosdahl, Christian Sauer, Larry Shatzer, Russell Steicke, Sander
+ Striker, Erik Sjoelund, Johan Sundstroem, John Szakmeister,
+ Mason Thomas, Eric Wadsworth, Colin Watson, Alex Waugh, Chad
+ Whitacre, Josef Wolf, Blair Zajac, and the entire Subversion
+ community.</para>
@ENGLISH }}} -->
<para>Наконец, мы благодарим всех тех людей, которые участвовали
в создании этой книги своими обзорами, мнениями и исправлениями:
Без сомнения, это далеко не полный список людей, без помощи
- которых эта книга была бы неполной и неточной: Jani Averbach,
- Ryan Barrett, Francois Beausoleil, Jennifer Bevan, Matt Blais,
- Zack Brown, Martin Buchholz, Brane Cibej, John R. Daily, Peter
- Davis, Olivier Davy, Robert P. J. Day, Mo DeJong, Brian Denny,
- Joe Drew, Nick Duffek, Ben Elliston, Justin Erenkrantz, Shlomi
- Fish, Julian Foad, Chris Foote, Martin Furter, Dave Gilbert,
- Eric Gillespie, Matthew Gregan, Art Haas, Greg Hudson, Alexis
- Huxley, Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark
- Benedetto King, Andreas J. Koenig, Nuutti Kotivuori, Matt Kraai,
- Scott Lamb, Vincent Lefevre, Morten Ludvigsen, Paul Lussier,
- Bruce A. Mah, Philip Martin, Feliciano Matias, Patrick Mayweg,
- Gareth McCaughan, Jon Middleton, Tim Moloney, Mats Nilsson, Joe
- Orton, Amy Lyn Pilato, Kevin Pilch-Bisson, Dmitriy Popkov,
- Michael Price, Mark Proctor, Steffen Prohaska, Daniel Rall,
- Tobias Ringstrom, Garrett Rooney, Joel Rosdahl, Christian Sauer,
- Larry Shatzer, Russell Steicke, Sander Striker, Erik Sjoelund,
- Johan Sundstroem, John Szakmeister, Mason Thomas, Eric
- Wadsworth, Colin Watson, Alex Waugh, Chad Whitacre, Josef Wolf,
- Blair Zajac, а также всё сообщество Subversion.</para>
+ которых эта книга была бы неполной и неточной: David Anderson,
+ Jani Averbach, Ryan Barrett, Francois Beausoleil, Jennifer
+ Bevan, Matt Blais, Zack Brown, Martin Buchholz, Brane Cibej,
+ John R. Daily, Peter Davis, Olivier Davy, Robert P. J. Day, Mo
+ DeJong, Brian Denny, Joe Drew, Nick Duffek, Ben Elliston, Justin
+ Erenkrantz, Shlomi Fish, Julian Foad, Chris Foote, Martin
+ Furter, Dave Gilbert, Eric Gillespie, David Glasser, Matthew
+ Gregan, Art Haas, Eric Hanchrow, Greg Hudson, Alexis Huxley,
+ Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark Benedetto
+ King, Andreas J. Koenig, Nuutti Kotivuori, Matt Kraai, Scott
+ Lamb, Vincent Lefevre, Morten Ludvigsen, Paul Lussier, Bruce
+ A. Mah, Philip Martin, Feliciano Matias, Patrick Mayweg, Gareth
+ McCaughan, Jon Middleton, Tim Moloney, Christopher Ness, Mats
+ Nilsson, Joe Orton, Amy Lyn Pilato, Kevin Pilch-Bisson, Dmitriy
+ Popkov, Michael Price, Mark Proctor, Steffen Prohaska, Daniel
+ Rall, Jack Repenning, Tobias Ringstrom, Garrett Rooney, Joel
+ Rosdahl, Christian Sauer, Larry Shatzer, Russell Steicke, Sander
+ Striker, Erik Sjoelund, Johan Sundstroem, John Szakmeister,
+ Mason Thomas, Eric Wadsworth, Colin Watson, Alex Waugh, Chad
+ Whitacre, Josef Wolf, Blair Zajac, а также всё сообщество
+ Subversion.</para>
<!-- =============================================================== -->
<sect2 id="svn.preface.acks.sussman">
@@ -926,17 +982,18 @@
не могу, откуда у неё столько терпения! Она — великолепный
противовес моему трудоголизму.</para>
+
<!-- @ENGLISH {{{
- <para>Thanks to my extended family for their sincere
+ <para>Thanks to my extended family and friends for their sincere
encouragement, despite having no actual interest in the
- subject. (You know, the ones who say, <quote>Ooh, you're
- writing a book?</quote>, and then when you tell them it's a
- computer book, sort of glaze over.)</para>
- @ENGLISH }}} -->
- <para>Благодарю всю мою родню за их искреннюю поддержку, несмотря
- на отсутствие у них настоящего интереса к моему занятию. (Ну, вы
- знаете, они говорят <quote>О, ты пишешь книгу?</quote>, а когда
- ты говоришь, что это — компьютерная книга, они сразу
+ subject. (You know, the ones who say, <quote>Ooh, you wrote a
+ book?</quote>, and then when you tell them it's a computer
+ book, sort of glaze over.)</para>
+ @ENGLISH }}} -->
+ <para>Благодарю всю мою родню и друзей за их искреннюю поддержку,
+ несмотря на отсутствие у них настоящего интереса к моему занятию.
+ (Ну, вы знаете, они говорят <quote>О, ты пишешь книгу?</quote>,
+ а когда ты говоришь, что это — компьютерная книга, они сразу
теряют весь интерес).</para>
<!-- @ENGLISH {{{
@@ -947,6 +1004,10 @@
богатым человеком. Не смотрите на меня так, вы же знаете, кто
вы.</para>
+ <para>Thanks to my parents for the perfect low-level formatting,
+ and being unbelievable role models. Thanks to my son for the
+ opportunity to pass that on.</para>
+
</sect2>
<!-- =============================================================== -->
@@ -956,6 +1017,8 @@
@ENGLISH }}} -->
<title>От Brian W. Fitzpatrick</title>
+ <!-- ### TODO(fitz): update this? -->
+
<!-- @ENGLISH {{{
<para>Huge thanks to my wife Marie for being incredibly
understanding, supportive, and most of all, patient. Thank
@@ -1008,6 +1071,8 @@
@ENGLISH }}} -->
<title>От C. Michael Pilato</title>
+ <!-- ### TODO(cmpilato): update this? -->
+
<!-- @ENGLISH {{{
<para>Special thanks to my wife, Amy, for her love and patient
support, for putting up with late nights, and for even
@@ -1143,8 +1208,14 @@
@ENGLISH }}} -->
<title>История Subversion</title>
+ <para>
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>history of</secondary>
+ </indexterm>
+
<!-- @ENGLISH {{{
- <para>In early 2000, CollabNet,
+ In early 2000, CollabNet,
Inc. (<ulink url="http://www.collab.net"/>) began seeking
developers to write a replacement for CVS. CollabNet offers a
collaboration software suite called CollabNet Enterprise Edition
@@ -1164,7 +1235,7 @@
write a new version control system from scratch, retaining the
basic ideas of CVS, but without the bugs and misfeatures.</para>
@ENGLISH }}} -->
- <para>В начале 2000 года компания CollabNet, Inc. (<ulink
+ В начале 2000 года компания CollabNet, Inc. (<ulink
url="http://www.collab.net"/>) начала поиск людей для написания
системы, способной заменить CVS. CollabNet предлагает комплекс
программных средств для совместной работы, известный под названием
@@ -1305,7 +1376,7 @@
And if you're not familiar with version control at all, your
eyes may glaze over unless you first read <xref
linkend="svn.basic"/>, in which we provide a gentle introduction
- to version control in general.</para>
+ to version control.</para>
@ENGLISH }}} -->
<para>Обсуждать возможности Subversion удобнее всего в разрезе
её улучшений по сравнению с CVS. Суть некоторых рассматриваемых
@@ -1557,8 +1628,8 @@
<title>Архитектура Subversion</title>
<!-- @ENGLISH {{{
- <para><xref linkend="svn.intro.architecture.dia-1"/> illustrates what one might
- call a <quote>mile-high</quote> view of Subversion's
+ <para><xref linkend="svn.intro.architecture.dia-1"/> illustrates
+ a <quote>mile-high</quote> view of Subversion's
design.</para>
@ENGLISH }}} -->
<para>Общий взгляд на устройство Subversion показан на <xref
@@ -1647,9 +1718,9 @@
<term>svnlook</term>
<listitem>
<!-- @ENGLISH {{{
- <para>A tool for inspecting a Subversion repository.</para>
+ <para>A tool for directly inspecting a Subversion repository.</para>
@ENGLISH }}} -->
- <para>Инструмент для контроля Subversion хранилища.</para>
+ <para>Инструмент прамого управления Subversion хранилищем.</para>
</listitem>
</varlistentry>
@@ -1703,6 +1774,19 @@
для предоставления сетевого доступа к хранилищу.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>svnsync</term>
+ <listitem>
+ <!-- @ENGLISH {{{
+ <para>A program for incrementally mirroring one
+ repository to another over a network.</para>
+ @ENGLISH }}} -->
+ <para>Программа для последовательного зеркалирования
+ одного хранилища в другое через сеть.</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
<!-- @ENGLISH {{{
Modified: trunk/src/ru/book/ch-reference.xml
==============================================================================
--- trunk/src/ru/book/ch-reference.xml (original)
+++ trunk/src/ru/book/ch-reference.xml Mon Feb 5 09:15:14 2007
@@ -1334,7 +1334,7 @@
--no-auth-cache
--non-interactive
--config-dir DIR
---verbose
+--verbose (-v)
</screen>
</refsect1>
@@ -2660,7 +2660,7 @@
--password PASS
--no-auth-cache
--non-interactive
---non-recursive
+--non-recursive (-N)
--config-dir DIR
--native-eol EOL
--ignore-externals
@@ -2921,13 +2921,13 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--recursive (-R)
--targets FILENAME
--incremental
--xml
---username ARG
---password ARG
+--username USER
+--password PASS
--no-auth-cache
--non-interactive
--config-dir DIR
@@ -3153,16 +3153,16 @@
<title>Switches</title>
<screen>
---targets ARG
---message (-m) ARG
---file (-F) ARG
+--targets FILENAME
+--message (-m) TEXT
+--file (-F) FILE
--force-log
---encoding ARG
---username ARG
---password ARG
+--encoding ENC
+--username USER
+--password PASS
--no-auth-cache
--non-interactive
---config-dir ARG
+--config-dir DIR
--force
</screen>
</refsect1>
@@ -4062,7 +4062,7 @@
<tip>
<para>Subversion has a number of <quote>special</quote>
properties that affect its behavior. See <xref
- linkend="svn.advanced.props.special"/> for more on these
+ linkend="svn.ref.properties"/> for more on these
properties.</para>
</tip>
@@ -4685,7 +4685,7 @@
--password PASS
--no-auth-cache
--non-interactive
---config-dir
+--config-dir DIR
--ignore-externals
</screen>
</refsect1>
@@ -4795,7 +4795,7 @@
--non-recursive (-N)
--quiet (-q)
--diff3-cmd CMD
---relocate
+--relocate FROM TO
--username USER
--password PASS
--no-auth-cache
@@ -4942,12 +4942,12 @@
<title>Switches</title>
<screen>
---targets ARG
---username ARG
---password ARG
+--targets FILENAME
+--username USER
+--password PASS
--no-auth-cache
--non-interactive
---config-dir ARG
+--config-dir DIR
--force
</screen>
</refsect1>
@@ -5339,8 +5339,8 @@
<title>Description</title>
<para><command>svnadmin deltify</command> only exists in
- 1.0.x due to historical reasons. This command is
- deprecated and no longer needed.</para>
+ current versions of Subversion due to historical reasons.
+ This command is deprecated and no longer needed.</para>
<para>It dates from a time when Subversion offered
administrators greater control over compression strategies
@@ -5353,8 +5353,8 @@
<title>Switches</title>
<screen>
---revision (-r)
---quiet
+--revision (-r) REV
+--quiet (-q)
</screen>
</refsect1>
</refentry>
@@ -5424,9 +5424,9 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--incremental
---quiet
+--quiet (-q)
--deltas
</screen>
</refsect1>
@@ -5920,7 +5920,7 @@
<title>Switches</title>
<screen>
---revision (-r) ARG
+--revision (-r) REV
--bypass-hooks
</screen>
</refsect1>
@@ -6086,7 +6086,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
</screen>
</refsect1>
@@ -6125,7 +6125,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
</screen>
</refsect1>
@@ -6222,7 +6222,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
</screen>
</refsect1>
@@ -6268,7 +6268,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
</screen>
</refsect1>
@@ -6307,7 +6307,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
--no-diff-added
--no-diff-deleted
@@ -6372,7 +6372,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
</screen>
</refsect1>
@@ -6438,7 +6438,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--show-ids
</screen>
</refsect1>
@@ -6494,7 +6494,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
</screen>
</refsect1>
@@ -6581,7 +6581,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
</screen>
</refsect1>
@@ -6627,7 +6627,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
--revprop
</screen>
@@ -6675,7 +6675,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
--verbose (-v)
--revprop
@@ -6728,7 +6728,7 @@
<title>Switches</title>
<screen>
---revision (-r)
+--revision (-r) REV
--transaction (-t)
--show-ids
</screen>
@@ -6994,7 +6994,7 @@
<refsect1 id="svn.ref.svnversion.re.syn">
<title>Synopsis</title>
- <programlisting>svnversion [OPTIONS] WC_PATH [TRAIL_URL]</programlisting>
+ <programlisting>svnversion [OPTIONS] [WC_PATH [TRAIL_URL]]</programlisting>
</refsect1>
<refsect1 id="svn.ref.svnversion.re.desc">
@@ -7012,6 +7012,10 @@
<replaceable>WC_PATH</replaceable> does not rely on
<replaceable>TRAIL_URL</replaceable>).</para>
+ <para>When WC_PATH is not defined the current directory
+ will be used as the working copy path. TRAIL_URL cannot be
+ defined if WC_PATH is not explicitly given.</para>
+
</refsect1>
<refsect1 id="svn.ref.svnversion.re.sw">
@@ -7063,11 +7067,12 @@
example, immediately after an update), then that revision is
printed out:</para>
- <screen>$ svnversion .
+ <screen>$ svnversion
4168</screen>
<para>You can add TRAIL_URL to show that the working copy is
- not switched from what you expect:</para>
+ not switched from what you expect. Note that the WC_PATH was
+ required in this command:</para>
<screen>$ svnversion . /repos/svn/trunk
4168</screen>
@@ -7075,32 +7080,32 @@
<para>For a mixed-revision working copy, the range of
revisions present is printed:</para>
- <screen>$ svnversion .
+ <screen>$ svnversion
4123:4168</screen>
<para>If the working copy contains modifications, a trailing
"M" is added:</para>
- <screen>$ svnversion .
+ <screen>$ svnversion
4168M</screen>
<para>If the working copy is switched, a trailing "S" is
added:</para>
- <screen>$ svnversion .
+ <screen>$ svnversion
4168S</screen>
<para>Thus, here is a mixed-revision, switched working copy
containing some local modifications:</para>
- <screen>$ svnversion .
+ <screen>$ svnversion
4212:4168MS</screen>
<para>If invoked on a directory that is not a working copy,
<command>svnversion</command> assumes it is an exported
working copy and prints "exported":</para>
- <screen>$ svnversion .
+ <screen>$ svnversion
exported</screen>
</refsect1>
@@ -7367,7 +7372,7 @@
multi-line list of other paths and URLs the client
should check out. See
<xref
- linkend="svn.advanced.props.special.externals"/>.</para>
+ linkend="svn.advanced.externals"/>.</para>
</listitem>
</varlistentry>
@@ -7378,9 +7383,7 @@
<para>If present on a file, indicates that the file is
not an ordinary file, but a symbolic link or other
- special object. See
- <xref
- linkend="svn.advanced.props.special.special"/>.</para>
+ special object.</para>
</listitem>
</varlistentry>
Modified: trunk/src/ru/book/ch-server-configuration.xml
==============================================================================
--- trunk/src/ru/book/ch-server-configuration.xml (original)
+++ trunk/src/ru/book/ch-server-configuration.xml Mon Feb 5 09:15:14 2007
@@ -871,13 +871,14 @@
<para>At the time of writing, the server only knows how to send
a CRAM-MD5 <footnote><para>See RFC 2195.</para></footnote>
- authentication challenge. In essence, the server sends a bit
- of data to the client. The client uses the MD5 hash algorithm
- to create a fingerprint of the data and password combined,
- then sends the fingerprint as a response. The server performs
- the same computation with the stored password to verify that
- the result is identical. <emphasis>At no point does the
- actual password travel over the network.</emphasis></para>
+ authentication challenge. In essence, the server sends a
+ small amount of data to the client. The client uses the MD5
+ hash algorithm to create a fingerprint of the data and
+ password combined, then sends the fingerprint as a response.
+ The server performs the same computation with the stored
+ password to verify that the result is identical. <emphasis>At
+ no point does the actual password travel over the
+ network.</emphasis></para>
<para>It's also possible, of course, for the client to be
externally authenticated via a tunnel agent, such as
@@ -1490,9 +1491,10 @@
<para>Be sure that when you define your new
<literal>Location</literal>, it doesn't overlap with other
exported Locations. For example, if your main
- <literal>DocumentRoot</literal> is <filename>/www</filename>,
- do not export a Subversion repository in <literal><Location
- /www/repos></literal>. If a request comes in for the URI
+ <literal>DocumentRoot</literal> is exported to
+ <filename>/www</filename>, do not export a Subversion
+ repository in <literal><Location /www/repos></literal>.
+ If a request comes in for the URI
<filename>/www/repos/foo.c</filename>, Apache won't know
whether to look for a file <filename>repos/foo.c</filename> in
the <literal>DocumentRoot</literal>, or whether to delegate
@@ -2244,7 +2246,7 @@
<para>All of this path-checking can sometimes be quite
expensive, especially in the case of <command>svn
- log</command>. When retrieving a list revisions, the server
+ log</command>. When retrieving a list of revisions, the server
looks at every changed path in each revision and checks it
for readability. If an unreadable path is discovered, then
it's omitted from the list of the revision's changed paths
More information about the svnbook-dev
mailing list