[svnbook commit] r2581 - branches/ora-2e-reorg/src/en/book
cmpilato
noreply at red-bean.com
Sun Dec 24 02:59:04 CST 2006
Author: cmpilato
Date: Sun Dec 24 02:59:03 2006
New Revision: 2581
Modified:
branches/ora-2e-reorg/src/en/book/app-svn-for-cvs-users.xml
branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml
branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml
branches/ora-2e-reorg/src/en/book/ch-reference.xml
Log:
Branch: ora-2e-reorg
My first pass across chapter 4. There's still much to be done, but
I think the basic framework is correct now, at least.
* src/en/book/ch-advanced-topics.xml
Gut the Properties section, reorganizing things to be topically
keyed instead of trying to read like an exhausing property
reference.
* src/en/book/ch-basic-usage.xml
Move the first mention of symbolic links into this chapter.
* src/en/book/ch-reference.xml
* src/en/book/app-svn-for-cvs-users.xml
Update some xref IDs.
Modified: branches/ora-2e-reorg/src/en/book/app-svn-for-cvs-users.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/app-svn-for-cvs-users.xml (original)
+++ branches/ora-2e-reorg/src/en/book/app-svn-for-cvs-users.xml Sun Dec 24 02:59:03 2006
@@ -295,7 +295,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: branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml Sun Dec 24 02:59:03 2006
@@ -42,11 +42,6 @@
<sect1 id="svn.advanced.props">
<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
@@ -71,18 +66,27 @@
receive other people's property changes as you update your
working copy.</para>
- <sidebar>
- <title>Other Properties in Subversion</title>
-
- <para>Properties show up elsewhere in Subversion, too. Just as
- files and directories may have arbitrary property names and
- values attached to them, each revision as a whole may have
- arbitrary properties attached to it. The same constraints
- apply—human-readable, text names and anything-you-want,
- binary values—except that revision properties are not
- versioned. See <xref linkend="svn.reposadmin.basics.revprops" /> for more
- information on these unversioned properties.</para>
- </sidebar>
+ <para>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.</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. 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>
<para>In this section, we will examine the utility—both to
users of Subversion, and to Subversion itself—of property
@@ -96,14 +100,14 @@
<sect2 id="svn.advanced.props.why">
<title>Why Properties?</title>
- <para>Properties can be very useful additions to your working
- copy. In fact, Subversion itself uses properties to house
- special information, and as a way to denote that certain
- special processing might be needed. Likewise, you can use
- properties for your own purposes. Of course, anything you can
- do with properties you could also do using regular versioned
- files, but consider the following example of Subversion
- property use.</para>
+ <para>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>
<para>Say you wish to design a website that houses many digital
photos, and displays them with captions and a datestamp. Now,
@@ -137,11 +141,42 @@
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>
+ <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 user's interface to them—has 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>
+
+ </sidebar>
</sect2>
@@ -444,192 +479,444 @@
</sect2>
<!-- =============================================================== -->
- <sect2 id="svn.advanced.props.special">
-
- <title>Special Properties</title>
+ <sect2 id="svn.advanced.props.auto">
+ <title>Automatic Property Setting</title>
- <para>Subversion has no particular policy regarding
- properties—you can use them for any purpose. Subversion
- asks only that you not use property names that begin with the
- prefix <literal>svn:</literal>. That's the namespace that it
- sets aside for its own use. In fact, Subversion defines
- certain properties that have magical effects on the files and
- directories to which they are attached. In this section,
- we'll untangle the mystery, and describe how these special
- properties make your life just a little easier.</para>
+ <para>Properties are a powerful feature of Subversion, acting as
+ key components of many Subversion features discussed elsewhere
+ in this and other chapters—textual diff and merge
+ support, keyword substitution, newline translation, etc. But
+ to get the full benefit of properties, they must be set on the
+ right files and directories. Unfortunately, that can be a
+ step easily forgotten in the routine of things, especially
+ since failing to set a property doesn't usually result in an
+ obvious error condition (at least compared to, say, failing to
+ add a file to version control). To help your properties get
+ applied to the places that need them, Subversion provides a
+ couple of simple but useful features.</para>
+
+ <para>Whenever you introduce a file to version control using the
+ <command>svn add</command> or <command>svn import</command>
+ commands, Subversion runs a very basic heuristic to determine
+ if that file consists of human-readable or non-human-readable
+ content. If the latter is the decision made, Subversion will
+ automatically set the <literal>svn:mime-type</literal>
+ property on that file to
+ <literal>application/octet-stream</literal> (the generic
+ <quote>this is a collection of bytes</quote> MIME type). Of
+ course, if Subversion guesses incorrectly, or if you wish to
+ set the <literal>svn:mime-type</literal> property to something
+ more precise—perhaps <literal>image/png</literal> or
+ <literal>application/x-shockwave-flash</literal>—you can
+ always remove or edit that property.</para>
+
+ <para>Subversion also provides the auto-props feature, which
+ allows you to create mappings of filename patterns to property
+ names and values. These mappings are made in your runtime
+ configuration area. They again affect adds and imports, and
+ not only can override any default MIME type decision made by
+ Subversion during those operations, they can also set
+ additional Subversion or custom properties, too. For example,
+ you might create a mapping that says that any time you add
+ JPEG files—ones that match the pattern
+ <literal>*.jpg</literal>—Subversion should automatically
+ set the <literal>svn:mime-type</literal> property on those
+ files to <literal>image/jpeg</literal>. Or perhaps any files
+ that match <literal>*.cpp</literal> should have
+ <literal>svn:eol-style</literal> set to
+ <literal>native</literal>, and <literal>svn:keywords</literal>
+ set to <literal>Id</literal>. Auto-prop support is perhaps
+ the handiest property related tool in the Subversion toolbox.
+ See <xref linkend="svn.advanced.confarea.opts.config"/> for more about
+ configuring that support.</para>
+
+ </sect2>
+ </sect1>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.props.file-portability">
+ <title>File Portability</title>
+
+ <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 pieces
+ 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 linsk; 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>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.special.mime-type">
+ <title>File Content Type</title>
- <sect3 id="svn.advanced.props.special.executable">
- <title><literal>svn:executable</literal></title>
+ <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 confusing 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 advent of the 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
+ types are in use 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, 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>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.special.executable">
+ <title>File Executability</title>
- <para>The <literal>svn:executable</literal> property is used
- to control a versioned file's filesystem-level execute
- permission bit in a semi-automated way. This property has
- no defined values—its mere presence indicates a desire
- that the execute permission bit be kept enabled by Subversion.
- Removing this property will restore full control of the
- execute bit back to the operating system.</para>
-
- <para>On many operating systems, the ability to execute a file
- as a command is governed by the presence of an execute
- permission bit. This bit usually defaults to being
- disabled, and must be explicitly enabled by the user for
- each file that needs it. In a working copy, new files are
- being created all the time as new versions of existing files
- are received during an update. This means that you might
- enable the execute bit on a file, then update your working
- copy, and if that file was changed as part of the update,
- its execute bit might get disabled. So, Subversion provides
- the <literal>svn:executable</literal> property as a way to
- keep the execute bit enabled.</para>
-
- <para>This property has no effect on filesystems that have no
- concept of an executable permission bit, such as FAT32 and
- NTFS.
- <footnote>
- <para>The Windows filesystems use file extensions (such as
- <literal>.EXE</literal>, <literal>.BAT</literal>, and
- <literal>.COM</literal>) to denote executable
- files.</para>
- </footnote>
- Also, although it has no defined values, Subversion will force
- its value to <literal>*</literal> when setting this property.
- Finally, this property is valid only on files, not on
- directories.</para>
+ <para>On many operating systems, the ability to execute a file
+ as a command is governed by the presence of an execute
+ permission bit. This bit usually defaults to being disabled,
+ and must be explicitly enabled by the user for each file that
+ needs it. In a working copy, new files are being created all
+ the time as new versions of existing files are received during
+ an update. This means that you might enable the execute bit
+ on a file, then update your working copy, and if that file was
+ changed as part of the update, its execute bit might get
+ disabled. So, Subversion provides the
+ <literal>svn:executable</literal> property as a way to keep
+ the execute bit enabled.</para>
+
+ <para>This property has no effect on filesystems that have no
+ concept of an executable permission bit, such as FAT32 and
+ NTFS.
+ <footnote>
+ <para>The Windows filesystems use file extensions (such as
+ <literal>.EXE</literal>, <literal>.BAT</literal>, and
+ <literal>.COM</literal>) to denote executable
+ files.</para>
+ </footnote>
+ Also, although it has no defined values, Subversion will force
+ its value to <literal>*</literal> when setting this property.
+ Finally, this property is valid only on files, not on
+ directories.</para>
- </sect3>
+ </sect2>
- <sect3 id="svn.advanced.props.special.mime-type">
- <title><literal>svn:mime-type</literal></title>
-
- <para>The <literal>svn:mime-type</literal> property serves
- many purposes in Subversion. Besides being a
- general-purpose storage location for a file's Multipurpose
- Internet Mail Extensions (MIME) classification, the value of
- this property determines some behavioral characteristics
- of Subversion itself.</para>
-
- <para>For example, if a file's
- <literal>svn:mime-type</literal> property is set to a
- non-text MIME type (generally, something that doesn't begin
- with <literal>text/</literal>, though there are exceptions),
- Subversion will assume that the file contains
- binary—that is, not human-readable—data. One of
- the benefits that Subversion typically provides is
- contextual, line-based merging of changes received from the
- server during an update into your working file. But for
- files believed to contain binary data, there is no concept
- of a <quote>line</quote>. So, for those files, Subversion
- does not attempt to perform contextual merges during
- updates. Instead, any time you have locally modified a
- binary working copy file that is also being updated, your
- file is renamed with a <filename>.orig</filename> extension,
- and then Subversion stores a new working copy file that
- contains the changes received during the update, but not
- your own local modifications, at the original filename.
- This behavior is really for the protection of the user
- against failed attempts at performing contextual merges on
- files that simply cannot be contextually merged.</para>
-
- <para>Also, if the <literal>svn:mime-type</literal>
- property is set, then the Subversion Apache module will use
- its value to populate the <literal>Content-type:</literal>
- HTTP header when responding to GET requests. This gives a
- crucial clue about how to display a file when perusing
- your repository with a web browser.</para>
-
- </sect3>
-
- <sect3 id="svn.advanced.props.special.ignore">
- <title><literal>svn:ignore</literal></title>
-
- <para>The <literal>svn:ignore</literal> property contains a
- list of file patterns which certain Subversion operations
- will ignore. Perhaps the most commonly used special
- property, it works in conjunction with the
- <literal>global-ignores</literal> run-time configuration
- option (see <xref linkend="svn.advanced.confarea.opts.config" />) to
- filter unversioned files and directories out of commands
- <command>svn status</command>, <command>svn
- add</command>, and <command>svn import</command>.</para>
-
- <para>The rationale behind the <literal>svn:ignore</literal>
- property is easily explained. Subversion does not assume
- that every file or subdirectory in a working copy directory
- is intended for version control. Resources must be
- explicitly placed under Subversion's management using the
- <command>svn add</command> or <command>svn import</command>
- commands. As a result, there are often many resources in a
- working copy that are not versioned.</para>
-
- <para>Now, the <command>svn status</command> command displays
- as part of its output every unversioned file or subdirectory
- in a working copy that is not already filtered out by the
- <literal>global-ignores</literal> option (or its built-in
- default value). This is done so that users can see if
- perhaps they've forgotten to add a resource to version
- control.</para>
-
- <para>But Subversion cannot possibly guess the names of
- every resource that should be ignored. Also, quite often
- there are things that should be ignored in
- <emphasis>every</emphasis> working copy of a particular
- repository. To force every user of that repository to add
- patterns for those resources to their run-time configuration
- areas would be not just a burden, but has the potential to
- clash with the configuration needs of other working copies
- that the user has checked out.</para>
-
- <para>The solution is to store ignore patterns that are unique
- to the resources likely to appear in a given directory with
- the directory itself. Common examples of unversioned
- resources that are basically unique to a directory, yet
- likely to appear there, include output from program
- compilations. Or—to use an example more appropriate
- to this book—the HTML, PDF, or PostScript files
- generated as the result of a conversion of some source
- DocBook XML files to a more legible output format.</para>
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.special.eol-style">
+ <title>End-of-Line Character Sequences</title>
- <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>
+ <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—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>
+
+ </sect2>
+ </sect1>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.props.special.ignore">
+ <title>Selective Versioning</title>
+
+ <para>### TODO: Need opening ###</para>
+
+ <para>The <literal>svn:ignore</literal> property contains a list
+ of file patterns which certain Subversion operations will
+ ignore. Perhaps the most commonly used special property, it
+ works in conjunction with the <literal>global-ignores</literal>
+ run-time configuration option (see <xref
+ linkend="svn.advanced.confarea.opts.config" />) to filter
+ unversioned files and directories out of commands <command>svn
+ status</command>, <command>svn add</command>, and <command>svn
+ import</command>.</para>
+
+ <para>The rationale behind the <literal>svn:ignore</literal>
+ property is easily explained. Subversion does not assume that
+ every file or subdirectory in a working copy directory is
+ intended for version control. Resources must be explicitly
+ placed under Subversion's management using the <command>svn
+ add</command> or <command>svn import</command> commands. As a
+ result, there are often many resources in a working copy that
+ are not versioned.</para>
+
+ <para>Now, the <command>svn status</command> command displays as
+ part of its output every unversioned file or subdirectory in a
+ working copy that is not already filtered out by the
+ <literal>global-ignores</literal> option (or its built-in
+ default value). This is done so that users can see if perhaps
+ they've forgotten to add a resource to version control.</para>
+
+ <para>But Subversion cannot possibly guess the names of every
+ resource that should be ignored. Also, quite often there are
+ things that should be ignored in <emphasis>every</emphasis>
+ working copy of a particular repository. To force every user of
+ that repository to add patterns for those resources to their
+ run-time configuration areas would be not just a burden, but has
+ the potential to clash with the configuration needs of other
+ working copies that the user has checked out.</para>
+
+ <para>The solution is to store ignore patterns that are unique to
+ the resources likely to appear in a given directory with the
+ directory itself. Common examples of unversioned resources that
+ are basically unique to a directory, yet likely to appear there,
+ include output from program compilations. Or—to use an
+ example more appropriate to this book—the HTML, PDF, or
+ PostScript files generated as the result of a conversion of some
+ source DocBook XML files to a more legible output format.</para>
+
+ <sidebar>
+ <title>Ignore Patterns for CVS Users</title>
+
+ <para>The Subversion <literal>svn:ignore</literal> property is
+ very similar in syntax and function to the CVS
+ <filename>.cvsignore</filename> file. In fact, if you are
+ migrating a CVS working copy to Subversion, you can directly
+ migrate the ignore patterns by using the
+ <filename>.cvsignore</filename> file as input file to the
+ <command>svn propset</command> command:</para>
+
+ <screen>
$ svn propset svn:ignore -F .cvsignore .
property 'svn:ignore' set on '.'
$
</screen>
+
+ <para>There are, however, some differences in the ways that CVS
+ and Subversion handle ignore patterns. The two systems use
+ the ignore patterns at some different times, and there are
+ slight discrepancies in what the ignore patterns apply to.
+ Also, Subversion does not recognize the use of the
+ <literal>!</literal> pattern as a reset back to having no
+ ignore patterns at all.</para>
- <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>
+ </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>
+ <para>For this purpose, the <literal>svn:ignore</literal>
+ property is the solution. Its value is a multi-line
+ collection of file patterns, one pattern per line. The
+ property is set on the directory in which you wish the
+ patterns to be applied.
+ <footnote>
+ <para>The patterns are strictly for that
+ directory—they do not carry recursively into
+ subdirectories.</para>
+ </footnote>
+ For example, say you have the following output from
+ <command>svn status</command>:</para>
- <screen>
+ <screen>
$ svn status calc
M calc/button.c
? calc/calculator
@@ -639,58 +926,57 @@
? calc/debug_log.2.gz
? calc/debug_log.3.gz
</screen>
+
+ <para>In this example, you have made some property modifications
+ to <filename>button.c</filename>, but in your working copy you
+ also have some unversioned files: the latest
+ <filename>calculator</filename> program that you've compiled
+ from your source code, a source file named
+ <filename>data.c</filename>, and a set of debugging output log
+ files. Now, you know that your build system always results in
+ the <filename>calculator</filename> program being generated.
+ <footnote>
+ <para>Isn't that the whole point of a build system?</para>
+ </footnote>
+ And you know that your test suite always leaves those debugging
+ log files lying around. These facts are true for all working
+ copies, not just your own. And you know that you aren't
+ interested in seeing those things every time you run
+ <command>svn status</command>. So you use <command>svn propedit
+ svn:ignore calc</command> to add some ignore patterns to the
+ <filename>calc</filename> directory. For example, you might add
+ this as the new value of the <literal>svn:ignore</literal>
+ property:</para>
- <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 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>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>
+ <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
@@ -700,555 +986,316 @@
I calc/debug_log.2.gz
I calc/debug_log.3.gz
</screen>
+
+ <para>The list of patterns to ignore is also used by <command>svn
+ add</command> and <command>svn import</command>. Both of these
+ operations involve asking Subversion to begin managing some set
+ of files and directories. Rather than force the user to pick
+ and choose which files in a tree she wishes to start versioning,
+ Subversion uses the ignore patterns to determine which files
+ should not be swept into the version control system as part of a
+ larger recursive addition or import operation.</para>
- <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>
+ </sect1>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.props.special.keywords">
+ <title>Keyword Substitution</title>
- <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>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>
+ <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>
+ <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>
- <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>
+ <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>
+ <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>
+ </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>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>
+ <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>
<!-- ================================================================= -->
@@ -1273,13 +1320,15 @@
<para>Subversion's locking feature has two main goals:</para>
<itemizedlist>
- <listitem><para><emphasis>Serializing access to a
+ <listitem>
+ <para><emphasis>Serializing access to a
resource</emphasis>. Allow a user to grab an exclusive
right to change to a file in the repository. If Harry
reserves the right to change <filename>foo.jpg</filename>,
then Sally should not be able to commit a change to it.</para>
</listitem>
- <listitem><para><emphasis>Aiding communication</emphasis>.
+ <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
@@ -1440,16 +1489,17 @@
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>
+ 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>,
@@ -1493,33 +1543,33 @@
</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 walks the working copy (or
+ list of targets, if you provide such a list), and sends all
+ lock tokens it encounters to the server as part of the commit
+ transaction. After the commit completes successfully, all of
+ the repository locks that were mentioned are
+ released—<emphasis>even on files that weren't
+ committed.</emphasis> The rationale here is to discourage
+ users from being sloppy about locking, or from holding locks
+ for too long. For example, suppose Harry were to haphazardly
+ lock thirty files in a directory named
+ <filename>images</filename>, because he's unsure of which
+ files he needs to change. He ends up making changes to only
+ four files. When he runs <command>svn commit
+ images</command>, the process would still release all thirty
+ locks.</para>
<para>This behavior of automatically releasing locks can be
- overridden with the <option>--no-unlock</option> option
- to <command>svn commit</command>. This is best used for
- those times when you want to commit changes, but still plan
- to make more changes and thus need to retain existing locks.
- This behavior is also semi-permanently tweakable, by setting
- <literal>no-unlock = yes</literal> in your run-time
- <filename>config</filename> file (see <xref
- linkend="svn.advanced.confarea"/>).</para>
+ overridden with the <option>--no-unlock</option> option to
+ <command>svn commit</command>. This is best used for those
+ times when you want to commit changes, but still plan to make
+ more changes and thus need to retain existing locks. This
+ behavior is also semi-permanently tweakable, by setting
+ <literal>no-unlock = yes</literal> in your run-time
+ <filename>config</filename> file (see <xref
+ linkend="svn.advanced.confarea"/>).</para>
<para>Of course, locking a file doesn't oblige one to commit a
change to it. The lock can be released at any time with a
@@ -1795,19 +1845,18 @@
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>
+ <emphasis>before</emphasis> the editing begins. 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 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>The mechanism is a special
- property, <literal>svn:needs-lock</literal>. If the property
- is attached to a file (the value is irrelevant), then the file
- will have read-only permissions. When the user locks the file
- and receives a lock token, the file becomes read-write. When
- the lock is released—either explicitly unlocked, or
- released via commit—the file returns to read-only
- again.</para>
-
<para>The theory, then, is that if the image file has this
property attached, then Sally would immediately notice
something is strange when she opens the file for editing. Her
Modified: branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml Sun Dec 24 02:59:03 2006
@@ -668,12 +668,39 @@
normally use. Subversion handles binary files just as easily
as it handles text files—and just as efficiently
too.</para>
-
+
<para>Here is an overview of the four Subversion subcommands
that you'll use most often to make tree changes (we'll cover
<command>svn import</command> and <command>svn mkdir</command>
later).</para>
+ <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>
<para>While you can edit your files with whatever tool you
like, you shouldn't change the structure of your working
Modified: branches/ora-2e-reorg/src/en/book/ch-reference.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-reference.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-reference.xml Sun Dec 24 02:59:03 2006
@@ -3078,7 +3078,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>
@@ -6383,7 +6383,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>
@@ -6394,9 +6394,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>
More information about the svnbook-dev
mailing list