[svnbook commit] r2780 - in trunk/src/nb: . book
sunny256
noreply at red-bean.com
Wed Apr 11 19:53:56 CDT 2007
Author: sunny256
Date: Wed Apr 11 19:53:55 2007
New Revision: 2780
Log:
Sync the Norwegian and English book up to r2585, merged r2579:2585 from
/branches/ora-2e-reorg/.
* src/nb/book/ch-reference.xml
* src/nb/book/ch-advanced-topics.xml
* src/nb/book/ch-preface.xml
* src/nb/book/app-svn-for-cvs-users.xml
* src/nb/book/ch-fundamental-concepts.xml
* src/nb/book/ch-customizing-svn.xml
* src/nb/book/ch-basic-usage.xml
Merged and updated r2580, r2581, r2582, r2583, r2584, r2585.
* src/nb/LAST_SYNC
Updated by "make sync HEAD=2585".
* src/nb/TRANSLATION-STATUS
Updated by "make status".
Modified:
trunk/src/nb/LAST_SYNC
trunk/src/nb/TRANSLATION-STATUS
trunk/src/nb/book/app-svn-for-cvs-users.xml
trunk/src/nb/book/ch-advanced-topics.xml
trunk/src/nb/book/ch-basic-usage.xml
trunk/src/nb/book/ch-customizing-svn.xml
trunk/src/nb/book/ch-fundamental-concepts.xml
trunk/src/nb/book/ch-preface.xml
trunk/src/nb/book/ch-reference.xml
Modified: trunk/src/nb/LAST_SYNC
==============================================================================
--- trunk/src/nb/LAST_SYNC (original)
+++ trunk/src/nb/LAST_SYNC Wed Apr 11 19:53:55 2007
@@ -1 +1 @@
-2579
+2585
Modified: trunk/src/nb/TRANSLATION-STATUS
==============================================================================
--- trunk/src/nb/TRANSLATION-STATUS (original)
+++ trunk/src/nb/TRANSLATION-STATUS Wed Apr 11 19:53:55 2007
@@ -14,12 +14,12 @@
* book/ch-preface.xml
Translation complete
* book/ch-fundamental-concepts.xml
- Untranslated: 0.92% - 21 lines in 2 blocks
+ Untranslated: 0.90% - 21 lines in 2 blocks
* book/ch-basic-usage.xml
- Untranslated: 1.34% - 65 lines in 6 blocks
+ Untranslated: 1.31% - 65 lines in 6 blocks
* book/ch-advanced-topics.xml
- Untranslated: 80.92% - 1874 lines in 3 blocks
- Need proofreading: 19.71% - 481 lines in 1 block
+ Untranslated: 78.90% - 1991 lines in 5 blocks
+ Need proofreading: 21.42% - 575 lines in 2 blocks
* book/ch-branching-and-merging.xml
Untranslated: 5.06% - 125 lines in 1 block
Need proofreading: 10.22% - 242 lines in 1 block
@@ -29,12 +29,12 @@
Untranslated: 1.45% - 53 lines in 4 blocks
Need proofreading: 83.82% - 2070 lines in 1 block
* book/ch-customizing-svn.xml
- Untranslated: 35.90% - 412 lines in 2 blocks
- Need proofreading: 63.74% - 706 lines in 1 block
+ Untranslated: 35.67% - 412 lines in 2 blocks
+ Need proofreading: 63.97% - 711 lines in 1 block
* book/ch-developer-info.xml
Untranslated: 100.00% - 1427 lines in 1 block
* book/ch-reference.xml
- Untranslated: 100.00% - 6482 lines in 1 block
+ Untranslated: 100.00% - 6480 lines in 1 block
* book/app-quickstart.xml
Translation complete
* book/app-svn-for-cvs-users.xml
@@ -47,4 +47,4 @@
* book/copyright.xml
Untranslated: 100.00% - 310 lines in 1 block
-Summa summarum: 59.06% translated, 17.06% need proofreading
+Summa summarum: 58.92% translated, 17.26% need proofreading
Modified: trunk/src/nb/book/app-svn-for-cvs-users.xml
==============================================================================
--- trunk/src/nb/book/app-svn-for-cvs-users.xml (original)
+++ trunk/src/nb/book/app-svn-for-cvs-users.xml Wed Apr 11 19:53:55 2007
@@ -557,7 +557,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)
@@ -570,7 +570,7 @@
C Ressursen inneholder konflikter (forandringer er enda ikke blitt
flettet sammen med depotet og arbeidskopien) (<quote>Conflicts</quote>)
X Ressursen er ekstern i denne arbeidskopien (kan komme fra et annet
- depot. (<quote>eXternal</quote>) Se <xref linkend="svn.advanced.props.special.externals" />)
+ depot (<quote>eXternal</quote>). Se <xref linkend="svn.advanced.externals" />
? Ressursen er ikke under versjonskontroll
! Ressursen mangler eller er ikke komplett (fjernet av et annet
verktøy enn Subversion)
Modified: trunk/src/nb/book/ch-advanced-topics.xml
==============================================================================
--- trunk/src/nb/book/ch-advanced-topics.xml (original)
+++ trunk/src/nb/book/ch-advanced-topics.xml Wed Apr 11 19:53:55 2007
@@ -34,52 +34,323 @@
<!-- @ENGLISH {{{
<para>But the Subversion feature set doesn't stop at <quote>common
- version control operations</quote>.</para>
+ 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>Men funksjonaliteten til Subversion stopper ikke ved
- <quote>vanlige versjonskontrolloperasjoner</quote>.</para>
+ <quote>vanlige versjonskontrolloperasjoner</quote>.
+ Den har annen funksjonalitet som går forbi grunnleggende fil- og
+ katalogversjonering; forbi det å bare sende og motta forandringer
+ til og fra et sentralt depot.</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>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>Dette kapittelet setter fokus på litt av funksjonaliteten til
- Subversion som ikke blir brukt i like stor grad.
- Her vil vi diskutere Subversions støtte for egenskaper (eller
- <quote>metadata</quote>) og hvordan standardoppførselen til
- Subversion kan forandres ved å gjøre forandringer i
- konfigurasjonsområdet.
- Vi vil beskrive hvordan du kan bruke eksterne defineringer for å
- instruere Subversion til å hente data fra flere depoter.
- Vi vil dekke i detalj noen av de verktøyene som er med i
- Subversiondistribusjonen for bruk på klient- og
- &server;siden.</para>
+ Subversion som, selv om den er viktig, ikke er del av den typiske
+ brukerens daglige rutine.
+ Det antas at du er kjent med de grunnleggende mulighetene
+ Subversion har for versjonering av filer og kataloger.
+ Hvis du ikke er det, vil du kanskje lese <xref linkend="svn.basic"
+ /> og <xref linkend="svn.tour" />.
+ Når du mestrer disse grunnleggende tingene og har fordøyd dette
+ kapittelet, vil du være en <!-- ¤
+ -->Subversionmuskelbruker!</para>
+<!-- @CHK }} -->
- <!-- @ENGLISH {{{
- <para>Before reading this chapter, you should be familiar with the
- basic file and directory versioning capabilities of Subversion.
- If you haven't already read about those, or if you need a
- refresher, we recommend that you check out <xref
- linkend="svn.basic" /> and <xref linkend="svn.tour" />. Once
- you've mastered the basics and consumed this chapter, you'll be
- a Subversion power-user!
- </para>
- @ENGLISH }}} -->
- <para>Før du leser dette kapittelet bør du gjøre deg kjent med de
- grunnleggende mulighetene Subversion har for versjonering av filer
- og kataloger.
- Hvis du ikke allerede har lest om dette, eller hvis du trenger å
- friske det opp, anbefaler vi at du leser <xref linkend="svn.basic"
- /> og <xref linkend="svn.tour" />.
- Når du mestrer de grunnleggende tingene og har fordøyd dette
- kapittelet, vil du være en <!-- ¤ -->Subversionmuskelbruker!</para>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+<!-- @TR {{ -->
+ <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>Not that even when you don't explicitly supply a
+ peg-revision, it's still present. For your convenience, it
+ defaults to <literal>BASE</literal> for working copy items,
+ and to <literal>HEAD</literal> for repository 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>
+<!-- @TR }} -->
<!-- ================================================================= -->
@@ -91,30 +362,27 @@
@ENGLISH }}} -->
<title>Egenskaper</title>
- <!-- ¤ Vi oversetter vel ikke sånt? Sikkert ikke. -->
- <!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
-
+<!-- @CHK {{ -->
<!-- @ENGLISH {{{
<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>
@ENGLISH }}} -->
<para>Vi har allerede dekket i detalj hvordan Subversion lagrer og
henter diverse versjoner av filer og kataloger i depotet.
Hele kapitler er viet til disse mest fundamentale delene av
funksjonalitet som verktøyet har.
Og hvis versjoneringsmulighetene stoppet der, ville Subversion
- fortsatt være komplett sett fra et versjonskontrollsynspunkt.
- Men det stopper ikke der.</para>
+ fortsatt være komplett sett fra et
+ versjonskontrollsynspunkt.</para>
+
+ <!-- @ENGLISH {{{
+ <para>But it doesn't stop there.</para>
+ @ENGLISH }}} -->
+ <para>Men det stopper ikke der.</para>
<!-- @ENGLISH {{{
<para>In addition to versioning your directories and files,
@@ -129,9 +397,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 }}} -->
<para>I tillegg til å versjonere kataloger og filer, har Subversion
grensesnitt for å legge til, forandre og fjerne versjonerte
@@ -148,37 +417,70 @@
Og det beste med disse egenskapene er at de også er versjonerte,
akkurat som det tekstbaserte innholdet i filene dine.
Du kan forandre, legge inn og reversere egenskapsforandringer like
- lett som å legge inn tekstforandringer.
- Du vil også motta forandringer i egenskaper gjort av andre brukere
- når du oppdaterer arbeidskopien.</para>
+ lett som å legge inn forandringer i innhold.
+ Og sending og henting av egenskapsforandringer blir en del av dine
+ vanlige innleggingsoperasjoner – du trenger ikke å forandre på
+ rutinene for å få det til.</para>
- <sidebar>
- <!-- @ENGLISH {{{
- <title>Other Properties in Subversion</title>
- @ENGLISH }}} -->
- <title>Andre egenskaper i Subversion</title>
+ <!-- @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 }}} -->
+ <para>Egenskaper finnes også andre steder i Subversion.
+ Akkurat som filer og kataloger kan ha vilkårlige egenskapsnavn og
+ verdier vedlagt, kan hver revisjon som helhet ha vilkårlige
+ egenskaper lagt ved.
+ De samme begrensningene gjelder også her – navnene må være lesbare
+ for mennesker, men verdiene kan være binære og alt hva du vil.
+ Hovedforskjellen er at revisjonsegenskaper ikke er versjonerte.
+ Med andre ord, hvis du forandrer verdien på, eller sletter, en
+ revisjonsegenskap, er det ingen funksjonalitet i Subversion for å
+ sette den tilbake til den forrige verdien.</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, 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>Egenskaper finnes også andre steder i Subversion.
- Akkurat som filer og kataloger kan ha vilkårlige egenskapsnavn
- og verdier vedlagt, kan hver revisjon som helhet ha vilkårlige
- egenskaper lagt ved.
- De samme begrensningene gjelder også her – <!-- ¤ Kanskje den
- engelske setninga bør skrues litt på. Omskrives litt. -->navnene
- må være lesbare for mennesker – unntatt at revisjonsegenskaper
- ikke er versjonerte.
- Se <xref linkend="svn.reposadmin.basics.revprops" /> for mer
- informasjon om disse uversjonerte egenskapene.</para>
- </sidebar>
+ <!-- @ENGLISH {{{
+ <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>Subversion har ingen spesiell policy angående bruken av
+ egenskaper.
+ <!-- ¤ En gang for alle: Kan man omtale Subversion som «den»?
+ Høres rart ut. Eller skal den omtales som «det» (et program)?
+ Høres enda verre ut. Foreløpig får vi nøye oss med omskriving.
+ -->Alt Subversion ber om er at du ikke bruker egenskapsnavn som
+ begynner med forstavelsen <literal>svn:</literal>.
+ Det er det navnerommet som er reservert for egen bruk.
+ Og Subversion bruker faktisk egenskaper, både av den versjonerte
+ og uversjonerte typen.
+ Enkelte versjonerte egenskaper har spesiell betydning eller effekt
+ når de brukes på filer og kataloger, eller lagrer spesiell
+ informasjon om revisjonene de finnes i.
+ Enkelte revisjonsegenskaper legges automatisk til revisjoner av
+ innleggingsprosessen, og inneholder informasjon om revisjonen.
+ Mesteparten av disse egenskapene er nevnt andre steder andre
+ steder i dette eller andre kapitler som del av de mer generelle
+ emnene de hører til.
+ For en fyldig liste over Subversions forhåndsdefinerte egenskaper,
+ se <xref linkend="svn.ref.svnprops"/>.</para>
<!-- @ENGLISH {{{
<para>In this section, we will examine the utility—both to
@@ -208,24 +510,22 @@
<title>Hvorfor bruke egenskaper?</title>
<!-- @ENGLISH {{{
- <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>
- @ENGLISH }}} -->
- <para>Egenskaper kan være meget nyttige tillegg til arbeidskopien
- din.
- Faktisk bruker Subversion selv egenskaper til å lagre spesiell
- informasjon og finne ut når det er nødvendig med spesielle
- fremgangsmåter.
- På samme måte kan du bruke egenskaper til ditt eget bruk.
- Selvfølgelig, alt du kan gjøre med egenskaper kan du også gjøre
- med vanlige versjonerte filer, men se for deg det følgende
- eksempelet på bruk av Subversionegenskaper.</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>Akkurat som Subversion bruker egenskaper for å lagre ekstra
+ informasjon om filer, kataloger og revisjoner som den
+ inneholder, kan du også få god bruk for egenskaper.
+ Noen deler av prosessene rundt bruken din av Subversion, eller
+ kanskje tilleggsprogrammer til Subversion som du bruker, kan få
+ nytte av å ha en plass nær dine versjonerte data der du kan
+ legge spesialsydde metadata om disse dataene.</para>
<!-- @ENGLISH {{{
<para>Say you wish to design a website that houses many digital
@@ -234,16 +534,7 @@
have as much of this site automated as possible. These photos
can be quite large, so as is common with sites of this nature,
you want to provide smaller thumbnail images to your site
- visitors. You can do this with traditional files. That is,
- you can have your <filename>image123.jpg</filename> and an
- <filename>image123-thumbnail.jpg</filename> side-by-side in a
- directory. Or if you want to keep the filenames the same, you
- might have your thumbnails in a different directory, like
- <filename>thumbnails/image123.jpg</filename>. You can also
- store your captions and datestamps in a similar fashion, again
- separated from the original image file. Soon, your tree of
- files is a mess, and grows in multiples with each new photo
- added to the site.</para>
+ visitors.</para>
@ENGLISH }}} -->
<para>Tenk deg at du vil sette opp en hjemmeside som inneholder
mange digitale bilder, og viser dem med tittel og tidspunkt.
@@ -251,63 +542,196 @@
automatisere så mye som mulig.
Disse bildene kan være ganske store, så du vil i likhet med
andre hjemmesider av denne typen vise miniatyrbilder til de
- besøkende.
- Du kan gjøre dette med tradisjonelle bilder, det vil si at du
- kan ha bildet <filename>bilde123.jpg</filename> og en
- <filename>bilde123-mini.jpg</filename> side ved side i en
+ besøkende.</para>
+
+ <!-- @ENGLISH {{{
+ <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. But the problem here
+ is that your collection of files grows in multiples with each
+ new photo added to the site.</para>
+ @ENGLISH }}} -->
+ <para>Nå kan du saktens oppnå denne effekten ved å bruke
+ tradisjonelle filer.
+ Det vil si at du kan ha bildet <filename>bilde123.jpg</filename>
+ og en <filename>bilde123-mini.jpg</filename> side ved side i en
katalog.
Eller hvis du vil bruke det samme filnavnet, kan du ha
miniatyrbildene i en annen katalog, for eksempel
<filename>mini/bilde123.jpg</filename>.
Du kan også lagre titlene og tidspunktene på en lignende måte,
separert fra den originale bildefila.
- Snart blir katalogtreet med filene et salig rot, og for hver ny
- fil øker størrelsen <!-- ¤ multiples -->flere ganger.</para>
+ Men problemet her er at samlingen din av filer vokser noe
+ voldsomt for hvert nytt bilde som blir lagt til
+ hjemmesida.</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>
- @ENGLISH }}} -->
- <para>Så kan du se for deg det samme oppsettet der filegenskapene
- til Subversion brukes.
- Du kan ha en enkelt bildefil, <filename>bilde123.jpg</filename>,
- med egenskaper på denne fila som er kalt
- <literal>tittel</literal>, <literal>tidspunkt</literal> og
- <literal>miniatyr</literal>.
+ 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>Så kan du se for deg den samme hjemmesida lagt opp på en
+ måte som bruker Subversions filegenskaper.
+ Tenk deg å ha en enkelt bildefil,
+ <filename>bilde123.jpg</filename>, med egenskaper på denne fila
+ som er kalt <literal>tittel</literal>,
+ <literal>tidspunkt</literal> og <literal>miniatyr</literal>.
Nå ser arbeidskopien din mye mer oversiktlig ut – faktisk ser
- det ut som det bare er bildefiler i den.
+ det med en vanlig nettleser ut som det bare er bildefiler i den.
Men de automatiserte skriptene dine vet bedre.
De vet at de kan bruke <command>svn</command> (eller enda bedre,
de kan bruke <!-- ¤ -->språkbindingene i Subversion – se <xref
linkend="svn.developer.usingapi.otherlangs" />) for å hente ut
- den ekstra informasjonen som hjemmesiden trenger å vise uten å
- måtte lese en indeksfil eller trikse med filstier.</para>
+ den ekstra informasjonen som hjemmesida trenger for å vise
+ bildet uten å måtte lese en indeksfil eller trikse med
+ filstier.</para>
+
+ <!-- @ENGLISH {{{
+ <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>
+ @ENGLISH }}} -->
+ <para>Spesialsydde revisjonsegenskaper blir også ofte brukt.
+ En vanlig bruksmåte er en egenskap der verdien inneholder en ID
+ fra en feildatabase som revisjonen er assosiert med, kanskje
+ fordi forandringen i den revisjonen ordner en feil som er logget
+ i feildatabasen med den ID-en.
+ Andre bruksmåter kan være å legge ved mer brukervennlige navn i
+ revisjonen – det kan være vanskelig å huske at revisjon 1935 var
+ en gjennomtestet revisjon.
+ Men hvis det er, la oss si, en
+ <literal>testresultat</literal>-egenskap på den revisjonen med
+ en verdi som <literal>Alt OK</literal>, er det god informasjon å
+ ha.</para>
- <!-- @ENGLISH {{{
- <para>How (and if) you use Subversion properties is up to you.
- As we mentioned, Subversion has it own uses for properties,
- which we'll discuss a little later in this chapter. But
- first, let's discuss how to manipulate properties using the
- <command>svn</command> program.</para>
- @ENGLISH }}} -->
- <para>Hvordan (og om) du bruker Subversionegenskaper er opp til
- deg.
- Som vi nevnte, har Subversion sine egne bruksområder for
- egenskaper, som vi vil diskutere litt senere i dette kapittelet.
- Men først ser vi på hvordan vi kan manipulere egenskaper ved å
- bruke <command>svn</command>-programmet.</para>
+ <sidebar>
+ <!-- @ENGLISH {{{
+ <title>Searchability (or, Why <emphasis>Not</emphasis>
+ Properties)</title>
+ @ENGLISH }}} -->
+ <title>Søkbarhet (eller: Hvorfor <emphasis>ikke</emphasis> bruke
+ egenskaper)</title>
+
+ <!-- @ENGLISH {{{
+ <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>
+ @ENGLISH }}} -->
+ <para>På tross av den store nyttigheten, har egenskaper i
+ Subversion – eller, mer nøyaktig, de grensesnittene mot dem
+ som er tilgjengelig – en stor begrensning som minsker den
+ praktiske nytten av dem.
+ Selv om det er en enkel sak å sette en spesialegenskap, er det
+ å <emphasis>finne</emphasis> denne egenskapen senere en helt
+ annen sak.</para>
+
+ <!-- @ENGLISH {{{
+ <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>
+ @ENGLISH }}} -->
+ <para>Å finne en spesialsydd revisjonsegenskap involverer å
+ utføre en lineær vandring gjennom alle revisjonene i depotet
+ mens man spør alle revisjonene: <quote>Har du den egenskapen
+ som jeg leter etter?</quote>.
+ Det å finne en egen versjonert egenskap er også smertefullt,
+ og involverer ofte en rekursiv <command>svn propget</command>
+ gjennom en hel arbeidskopi.
+ Det er mulig at det i din situasjon ikke er like ille som en
+ lineær vandring gjennom alle revisjonene.
+ Men tingenes tilstand kunne så absolutt vært bedre både hva
+ ytelse og sannsynligheten for suksess angår, spesielt hvis
+ søket ditt krever en arbeidskopi hentet ut fra roten av
+ depotet.</para>
+
+ <!-- @ENGLISH {{{
+ <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>
+ @ENGLISH }}} -->
+ <para>På grunn av dette, kan det ofte være bedre – spesielt i
+ tilfellet med revisjonsegenskaper – å rett og slett legge inn
+ metadataene dine inn i revisjonens loggmelding ved å bruke en
+ standardisert (og kanskje påtvunget gjennom programsjekker)
+ formatering som er beregnet på å bli raskt analysert fra
+ utdataene fra <command>svn log</command>.
+ Det er ganske vanlig å se ting som dette i loggmeldingene i
+ Subversion:</para>
+
+ <!-- @ENGLISH {{{
+ <programlisting>
+Issue(s): IZ2376, IZ1919
+Reviewed by: sally
+
+This fixes a nasty segfault in the wort frabbing process
+…
+</programlisting>
+ @ENGLISH }}} -->
+<!-- @TR {{ -->
+ <programlisting>
+Issue(s): IZ2376, IZ1919
+Reviewed by: sally
+
+This fixes a nasty segfault in the wort frabbing process
+…
+</programlisting>
+<!-- @TR }} -->
+
+ <!-- @ENGLISH {{{
+ <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>
+ @ENGLISH }}} -->
+ <para>Men selv med denne metoden ligger uflaksen like om
+ hjørnet.
+ Subversion har ingen mekanismer for loggmaler enda, noe som
+ ville hjulpet brukere langt på vei med å være konsekvent med
+ formateringen på deres logg-innebygde
+ revisjonsmetadata.</para>
+
+ </sidebar>
</sect2>
@@ -410,18 +834,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>I tillegg til <command>propset</command>-kommandoen, har
<command>svn</command>-programmet kommandoen
@@ -642,14 +1066,147 @@
$
</screen>
@ENGLISH }}} -->
- <screen>
-$ svn propdel license calc/button.c
-Egenskapen «license» slettet fra «calc/button.c».
-$ svn proplist --verbose calc/button.c
-Egenskaper for 'calc/button.c':
- copyright : (c) 2003 Red-Bean Software
-$
-</screen>
+ <screen>
+$ svn propdel license calc/button.c
+Egenskapen «license» slettet fra «calc/button.c».
+$ svn proplist --verbose calc/button.c
+Egenskaper for 'calc/button.c':
+ copyright : (c) 2003 Red-Bean Software
+$
+</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>Husker du de uversjonerte revisjonsegenskapene?
+ Du kan modifisere disse også ved hjelp av de samme
+ delkommandoene for <command>svn</command> som vi nettopp
+ beskrev.
+ Bare legg til <option>--revprop</option>-valget på kommandolinja
+ og spesifiser revisjonen for den egenskapen du vil forandre.
+ Siden revisjoner er globale, trenger du ikke å spesifisere en
+ målsti sammen med disse egenskapsrelaterte kommandoene så lenge
+ du er i en arbeidskopi fra depotet som har revisjonsegenskapen
+ du vil forandre.
+ Ellers kan du oppgi URLen for en hvilken som helst sti i depotet
+ det gjelder (inkludert depotets rotadresse).
+ Du vil for eksempel erstatte loggmeldingen for en eksisterende
+ revisjon.<footnote>
+ <para>Retting av skrivefeil, grammatiske flauser og ting som
+ er direkte feil i loggmeldinger er kanskje det vanligste
+ bruksområdet for <option>--revprop</option>-valget.</para>
+ </footnote>
+ Hvis den nåværende katalogen er en del av en arbeidskopi fra
+ depotet ditt, kan du ganske enkelt kjøre kommandoen <command>svn
+ propset</command> uten å spesifisere en målsti:</para>
+
+ <!-- @ENGLISH {{{
+ <screen>
+$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 -ﳢ-revprop
+property 'svn:log' set on repository revision '11'
+$
+</screen>
+ @ENGLISH }}} -->
+ <screen>
+$ svn propset svn:log '* button.c: Fjerna en kompilatoradvarsel.' -r11 --revprop
+Egenskapen «svn:log» satt på depotrevisjon «11»
+$
+</screen>
+
+ <!-- @ENGLISH {{{
+ <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>
+ @ENGLISH }}} -->
+ <para>Men selv om du ikke har hentet ut en arbeidskopi fra
+ depotet, kan du fortsatt forandre egenskapen ved å oppgi URLen
+ til depotroten:</para>
+
+ <!-- @ENGLISH {{{
+ <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 }}} -->
+ <screen>
+$ svn propset svn:log '* button.c: Fjerna en kompilatoradvarsel.' -r11 --revprop \
+ http://svn.example.com/depot/prosjekt
+Egenskapen «svn:log» satt på depotrevisjon «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>Legg merke til at muligheten til å forandre disse
+ uversjonerte egenskapene må settes spesielt av
+ depotadministratoren (se <xref
+ linkend="svn.reposadmin.create.hooks" />).
+ Siden egenskapene ikke er versjonerte, risikerer du å miste
+ informasjon hvis du ikke er forsiktig når du redigerer.
+ Depotadministratoren kan sette opp metoder for å beskytte mot
+ datatap som dette, og standardoppsettet forbyr forandringer i
+ revisjonsegenskaper.</para>
+
+ <tip>
+ <!-- @ENGLISH {{{
+ <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>
+ @ENGLISH }}} -->
+ <para>Brukere bør, der det er mulig, bruke <command>svn
+ propedit</command> istedenfor <command>svn propset</command>.
+ Selv om sluttresultatet er identisk, vil førstnevnte la dem se
+ den nåværende verdien av egenskapen som de er i ferd med å
+ forandre, noe som hjelper dem å kontrollere at de faktisk gjør
+ den endringen som de tror de gjør.
+ Dette gjelder spesielt for modifisering av uversjonerte
+ revisjonsegenskaper.</para>
+ </tip>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.workflow">
+ <!-- @ENGLISH {{{
+ <title>Properties and the Subversion Workflow</title>
+ @ENGLISH }}} -->
+ <title>Egenskaper og arbeidsflyten i Subversion</title>
<!-- @ENGLISH {{{
<para>Now that you are familiar with all of the
@@ -671,80 +1228,6 @@
– med dertil potensielle konflikter – av andres forandringer inn
i dine egne.</para>
- <sidebar>
- <!-- @ENGLISH {{{
- <title>Modifying Revision Properties</title>
- @ENGLISH }}} -->
- <title>Forandre revisjonsegenskaper</title>
-
- <!-- @ENGLISH {{{
- <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 }}} -->
- <para>Husker du de uversjonerte revisjonsegenskapene?
- Du kan modifisere disse også ved hjelp av
- <command>svn</command>-programmet.
- Bare legg til <option>--revprop</option>-valget på
- kommandolinja og spesifiser revisjonen som har den egenskapen
- du vil forandre.
- Siden revisjoner er globale, trenger du ikke å spesifisere en
- sti i dette tilfellet så lenge du står i arbeidskopien til
- depotet som har revisjonsegenskapen som du vil forandre.
- Du vil for eksempel forandre loggmeldingen for en eksisterende
- revisjon.<footnote>
- <para>Retting av skrivefeil, grammatiske flauser og ting som
- er direkte feil i loggmeldinger er kanskje det vanligste
- bruksområdet for <option>--revprop</option>-valget.</para>
- </footnote></para>
-
- <!-- @ENGLISH {{{
- <screen>
-$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 -ﳢ-revprop
-property 'svn:log' set on repository revision '11'
-$
-</screen>
- @ENGLISH }}} -->
- <screen>
-$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop
-Egenskapen «svn:log» satt på depotrevisjon «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>Legg merke til at muligheten til å forandre disse
- uversjonerte egenskapene må bli eksplisitt satt av
- depotadministratoren (se <xref
- linkend="svn.reposadmin.create.hooks" />).
- Siden egenskapene ikke er versjonerte, risikerer du å miste
- informasjon hvis du ikke er forsiktig når du redigerer.
- Depotadministratoren kan sette opp metoder for å beskytte mot
- datatap som dette, og standardoppsettet forbyr forandringer i
- revisjonsegenskaper.</para>
-
- </sidebar>
-
<!-- @ENGLISH {{{
<para>And as with file contents, your property changes are local
modifications, only made permanent when you commit them to the
@@ -957,193 +1440,470 @@
<!-- @CHK }} -->
<!-- =============================================================== -->
- <sect2 id="svn.advanced.props.special">
-
<!-- @TR {{ -->
- <title>Special Properties</title>
+ <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 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>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>
- <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>
+ <!-- =============================================================== -->
+ <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 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>
- <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. 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>
+
+ <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—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>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <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>
+
+ <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
@@ -1153,58 +1913,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
@@ -1214,555 +1977,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>
+ </sect1>
- <sect3 id="svn.advanced.props.special.keywords">
- <title><literal>svn:keywords</literal></title>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <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>
+ <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>
- <programlisting>
+ <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>
- <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
-