Index: ch09-reference.xml
===================================================================
--- ch09-reference.xml (revision 2737)
+++ ch09-reference.xml (working copy)
@@ -32,10 +32,12 @@
You can find many more examples of how to use most client
- commands in and commands for managing
+ commands in , and commands for managing
properties in .
+
svn Switches
@@ -47,6 +49,13 @@
means verbose output, regardless of the
subcommand you use it with.
+
+
@@ -75,7 +84,7 @@
Specifies an external program to use to show
differences between files. When svn
- diff is invoked, it uses Subversion's internal
+ diff is invoked without this option, it uses Subversion's internal
diff engine, which provides unified diffs by default.
If you want to use an external diff program, use
. You can pass switches to
@@ -116,6 +125,11 @@
ENCTells Subversion that your commit message is encoded
+
in the charset provided. The default is your operating
system's native locale, and you should specify the
encoding if your commit message is in any other
@@ -128,13 +142,15 @@
ARGSSpecifies an argument or arguments that Subversion
- should pass to an external diff command when providing
- differences between files. If you wish to pass multiple
+ should pass to an external diff command. This option is
+ valid only when used with the svn
+ diff or svn merge commands,
+ with the
+ switch.
+ If you wish to pass multiple
arguments, you must enclose all of them in quotes (for
example, svn diff --diff-cmd /usr/bin/diff -x
- "-b -E"). This switch can
- only be used if you also pass the
- switch.
+ "-b -E").
@@ -143,8 +159,11 @@
FILENAME
- Uses the contents of the file passed as an argument
- to this switch for the specified subcommand.
+ Uses the contents of the named file for the specified subcommand. Note that
+ different subcommands do different things with this
+ content—for example, svn commit
+ uses the content as a commit log, whereas svn
+ propset uses it as a property value.
@@ -246,6 +265,8 @@
ARG
+
Uses ARG as the newer
target.
@@ -327,6 +348,12 @@
+
()Stops a subcommand from recursing into
@@ -354,6 +381,9 @@
+
PASS
@@ -398,6 +428,8 @@
()
REV
+
Indicates that you're going to supply a revision (or
range of revisions) for a particular operation. You can
@@ -461,10 +493,14 @@
Causes Subversion to use strict semantics, a notion
which is rather vague unless talking about specific
subcommands.
+
+
FILENAME
@@ -524,7 +560,11 @@
svn Subcommands
-
+
+ Here are the various subcommands:
@@ -545,8 +585,8 @@
Description
- Add files, directories, or symbolic links to your
- working copy and schedule them for addition to the
+ Schedule files, directories, or symbolic links in your
+ working copy for addition to the
repository. They will be uploaded and added to the
repository on your next commit. If you add something and
change your mind before committing, you can unschedule the
@@ -616,7 +656,10 @@
will skip over any directories that are already under
version control. Sometimes, however, you may want to add
every unversioned object in your working copy, including
- those hiding deeper down. Passing the
+ those hiding deeper down.
+
+ Passing the
option makes svn
add recurse into versioned directories:
@@ -698,6 +741,10 @@
5 harry You should read this.
+
@@ -861,7 +908,7 @@
mine
- Check out 2 different directories into two separate
+ Check out two different directories into two separate
working copies:
@@ -876,7 +923,7 @@
quiz test
- Check out 2 different directories into two separate
+ Check out two different directories into two separate
working copies, but place both into a directory called
working-copies:
@@ -893,11 +940,11 @@
If you interrupt a checkout (or something else
- interrupts your checkout like loss of connectivity, etc.),
+ interrupts your checkout, like loss of connectivity, etc.),
you can restart it either by issuing the
identical checkout command again, or by updating the
incomplete working copy:
-
+
$ svn checkout file:///tmp/repos/test test
A test/a
@@ -948,6 +995,10 @@
run this command to remove stale locks and get your working copy
into a usable state again.
+
If, for some reason, an svn update
fails due to a problem running an external diff program
(e.g. user input or network failure), pass the
@@ -1029,9 +1080,12 @@
editor-cmd section in .
- svn commit will send found lock
- tokens and release locks on all
- PATHS committed (recursively)
+
+ svn commit will send any lock
+ tokens that it finds, and will release locks on all
+ PATHS committed (recursively),
unless is passed.
@@ -1187,6 +1241,7 @@
URL -> WC
+
Check out URL into WC, and schedule it for
addition.
@@ -1356,7 +1411,7 @@
Changes
- Working copy if operating on files, Repository if
+ Working copy if operating on files, repository if
operating on URLs
@@ -1389,6 +1444,7 @@
ExamplesUsing svn to delete a file from
+
your working copy merely schedules it to be
deleted. When you commit, the file is deleted in the
repository.
@@ -1438,7 +1494,8 @@
svn diff
- Display the differences between two paths.
+ Display the differences between two paths, or
+ two revisions of one path.Synopsis
@@ -1453,6 +1510,11 @@
different ways you can use svn diff
are:
+
svn diff [-r N[:M]] [--old OLD-TGT] [--new
NEW-TGT] [PATH...] displays the differences
between OLD-TGT and
@@ -1915,29 +1977,33 @@
Examples
- This imports the local directory myproj into the
- root of your repository:
+ This imports the local directory myproj
+ into trunk/misc in your repository.
+ The
+ directory trunk/misc need not exist before
+ you import into it—svn import will
+ recursively create directories for you.
-$ svn import -m "New import" myproj http://svn.red-bean.com/repos/test
+$ svn import -m "New import" myproj http://svn.red-bean.com/repos/trunk/misc
Adding myproj/sample.txt
…
Transmitting file data .........
Committed revision 16.
- This imports the local directory myproj
- into trunk/misc in your repository. The
- directory trunk/misc need not exist before
- you import into it—svn import will
- recursively create directories for you:
+
+ Note that it will not create a
+ directory named myproj in the
+ repository. If that's what you want, simply
+ add myproj to the end of the URL:
+
-$ svn import -m "New import" myproj \
- http://svn.red-bean.com/repos/test/trunk/misc/myproj
+$ svn import -m "New import" myproj http://svn.red-bean.com/repos/trunk/misc/myproj
Adding myproj/sample.txt
…
Transmitting file data .........
-Committed revision 19.
+Committed revision 16.
After importing data, note that the original tree is
@@ -2215,6 +2281,15 @@
24 harry Jan 18 11:27 examples/
+
+
+
For further details, see .
@@ -2302,18 +2377,18 @@
$ svn lock tree.jpg
-svn: warning: Path '/tree.jpg is already locked by user 'harry in \
+svn: warning: Path '/tree.jpg is already locked by user 'sally in \
filesystem '/svn/repos/db'
$ svn lock --force foo
-'tree.jpg' locked by user 'sally'.
+'tree.jpg' locked by user 'harry'.
Lock a file without a working copy:
$ svn lock http://svn.red-bean.com/repos/test/tree.jpg
-'tree.jpg' locked by user 'sally'.
+'tree.jpg' locked by user 'harry'.
For further details, see Description
- The default target is the path of your current
- directory. If no arguments are supplied, svn
+ Shows log messages from the repository.
+ If no arguments are supplied, svn
log shows the log messages for all files and
directories inside of (and including) the current working
directory of your working copy. You can refine the
@@ -2580,6 +2655,10 @@
Apply the differences between two sources to a
working copy path.
+
Synopsissvn merge sourceURL1[@N] sourceURL2[@M] [WCPATH]
@@ -2717,6 +2796,10 @@
Multiple directory URLs are committed atomically. In both
cases all the intermediate directories must already
exist.
+
@@ -2774,6 +2857,23 @@
+
@@ -3286,7 +3386,7 @@
Examples
- Set the mimetype on a file:
+ Set the mime type on a file:
$ svn propset svn:mime-type image/jpeg foo.jpg
@@ -3532,6 +3632,13 @@
? whoops
+
+ svn revert is inherently dangerous, since
+ its entire purpose is to throw away data—namely, your
+ uncommitted changes. Once you've reverted, Subversion
+ provides no way to get back those
+ uncommitted changes, so be careful using it.
+ If you provide no targets to svn
revert, it will do nothing—to protect
@@ -3565,7 +3672,7 @@
Print the status of working copy files and
directories. With no arguments, it prints only locally
modified items (no repository access). With
- , add working revision
+ , adds working revision
and server out-of-date information. With
, print full revision
information on every item.
@@ -3629,7 +3736,7 @@
'X'
- Item is related to an externals definition.
+ Item is present because of an externals definition.
@@ -3800,7 +3907,7 @@
TFile was locked in this working copy, but the
- lock has been stolenand is invalid.
+ lock has been stolen and is invalid.
The file is currently locked in the repository. This
only appears when is
used.
@@ -3811,7 +3918,7 @@
BFile was locked in this working copy, but the
- lock has been brokenand is invalid.
+ lock has been broken and is invalid.
The file is no longer locked This only appears when
is used.
@@ -3929,6 +4036,8 @@
update). does
not cause the status listing to
reflect the repository's version of the item.
+
And finally, the most information you can get out of
@@ -3972,13 +4081,23 @@
Description
- This subcommand updates your working copy to mirror
+ The first variant
+ (without ) of this subcommand updates your working copy to mirror
a new URL—usually a URL which shares a common
ancestor with your working copy, although not
necessarily. This is the Subversion way to move a
working copy to a new branch. See for an in-depth look at
switching.
+
+ The variant does something
+ somewhat different: it updates your working copy to
+ mirror the same repository directory,
+ after that repository has acquired a different URL
+ (typically because an administrator has moved the
+ repository to another server, or to another URL on the
+ same server).
+
@@ -4017,8 +4136,8 @@
ExamplesIf you're currently inside the directory
- vendors which was branched to
- vendors-with-fix and you'd like to
+ vendors, which was branched to
+ vendors-with-fix, and you'd like to
switch your working copy to that branch:
@@ -4054,8 +4173,8 @@
other words, the contents of the repository doesn't
change, but the main URL used to reach the root of the
repository does. For example, the hostname may change,
- the URL scheme, or any part of the URL which leads to the
- repository itself. Rather than checkout a new working
+ the URL scheme may change, and any part of the URL which leads to the
+ repository itself may change. Rather than check out a new working
copy, you can have the svn switch
command rewrite the beginnings of all the
URLs in your working copy. Use the
@@ -4084,6 +4203,12 @@
+
Be careful when using the
option. If you mistype the
argument, you might end up creating nonsensical URLs
@@ -4224,7 +4349,7 @@
Descriptionsvn update brings changes from the
- repository into your working copy. If no revision given,
+ repository into your working copy. If no revision is given,
it brings your working copy up-to-date with the
HEAD revision. Otherwise, it
synchronizes the working copy to the revision given by the
@@ -4234,7 +4359,7 @@
linkend="svn.tour.cleanup"/>) found in the
working copy.
- For each updated item a line will start with a
+ For each updated item, it prints a line that starts with a
character reporting the action taken. These characters
have the following meaning:
@@ -4264,7 +4389,7 @@
C
- Conflict
+ Conflicted
@@ -4329,7 +4454,7 @@
Updated to revision 32.
- You can also update your working copy to an older
+ You can also update your working copy to an older
revision (Subversion doesn't have the concept of
sticky files like CVS does; see ):
@@ -4347,7 +4472,7 @@
If you want to examine an older revision of a
single file, you may want to use svn
- cat.
+ cat instead; it won't change your working copy.
@@ -4375,6 +4500,10 @@
svnadmin Switches
+
@@ -4382,6 +4511,9 @@
(Berkeley DB specific) Disable automatic log removal
of database log files.
+
@@ -4390,6 +4522,9 @@
(Berkeley DB specific) Disables fsync when
committing database transactions.
+
@@ -4424,6 +4559,11 @@
+
By default, when loading an empty repository,
svnadmin will use the
UUID from the dump stream. This
@@ -4492,7 +4632,8 @@
svnadmin Subcommands
-
+
@@ -4575,8 +4716,8 @@
Description
- svnadmin deltify only exists in
- current versions of Subversion due to historical reasons.
+ svnadmin deltify exists in
+ current versions of Subversion only for historical reasons.
This command is deprecated and no longer needed.It dates from a time when Subversion offered
@@ -4637,7 +4778,7 @@
its properties, are presented in the dumpfile; for a
directory, all of its properties are presented.
- There are a pair of useful options which modify the
+ There is a pair of useful options which modify the
dumpfile generator's behavior. The first is the
option, which simply causes
that first revision in the dumpfile stream to contain only
@@ -4645,7 +4786,7 @@
instead of being presented as the addition of a new tree,
and in exactly the same way that every other revision in
the dumpfile is presented. This is useful for generating
- a dumpfile that is to be loaded into another repository
+ a relatively small dumpfile, so long as that dumpfile is to be loaded into another repository
which already has the files and directories that exist in
the original repository.
@@ -4662,7 +4803,12 @@
not to compress as well as their non-deltified counterparts
when using third-party tools like gzip
and bzip2.
-
+
Switches
@@ -4728,7 +4874,8 @@
This subcommand is useful when you're trapped on a
desert island with neither a net connection nor a copy of
this book.
-
+
@@ -4778,6 +4925,15 @@
+
+ As described in
+ ,
+ hot-copied Berkeley
+ DB repositories are not portable across
+ operating systems, nor will they work on a machine with a
+ different word order (aka endianness), nor on a
+ machine with a different word size.
+
@@ -4961,7 +5117,7 @@
This lists the one locked file in the repository at
- /svn/repos
+ /svn/repos:
$ svnadmin lslocks /svn/repos
@@ -5259,6 +5415,8 @@
+
@@ -5544,9 +5702,9 @@
- '_U'
+ ' U'
- Properties of item changed.
+ Properties of item changed. Note the leading space.
@@ -5577,8 +5735,10 @@
Examples
- This shows a list of all the changed files in
- revision 39 of a test repository:
+ This shows a list of all the changed files and
+ directories in
+ revision 39 of a test repository. Note that the first
+ changed item is a directory, as evidenced by the trailing /:
$ svnlook changed -r 39 /usr/local/svn/repos
@@ -5587,7 +5747,7 @@
A trunk/vendors/deli/sandwich.txt
A trunk/vendors/deli/pickle.txt
U trunk/vendors/baker/bagel.txt
-_U trunk/vendors/baker/croissant.txt
+ U trunk/vendors/baker/croissant.txt
UU trunk/vendors/baker/pretzel.txt
D trunk/vendors/baker/baguette.txt
@@ -5595,6 +5755,8 @@
+
@@ -5790,6 +5952,7 @@
+
@@ -6124,6 +6287,7 @@
+
@@ -6264,17 +6428,28 @@
svnservesvnserve allows access to Subversion
- repositories using the svn network protocol.
- You can run svnserve either as a standalone server process, or
- you can have another process, such as inetd,
- xinetd or sshd, launch it
- for you.
+
+ repositories using Subversion's custom network protocol.
- Once the client has selected a repository by transmitting
+
+ You can run svnserve as a standalone server
+ process (for clients that are using
+ the svn:// access method);
+ you can have a daemon such as inetd or
+ xinetd launch it
+ for you on demand (also for
+ svn://),
+ or you can have sshd launch it on demand for
+ the svn+ssh:// access method.
+
+ Regardless of the access method, once the client has selected a repository by transmitting
its URL, svnserve reads a file named
conf/svnserve.conf in the repository
- directory to determine repository-specific settings such as what
- authentication database to use and what authorization policies
+ directory to determine repository-specific settings, such as what
+ authentication database to use, and what authorization policies
to apply. See for details of
the svnserve.conf file.
@@ -6283,7 +6458,7 @@
svnserve SwitchesUnlike the previous commands we've
- described. svnserve has no
+ described, svnserve has no
subcommands—svnserve is controlled
exclusively by switches.
@@ -6300,6 +6475,8 @@
+
=PORTCauses svnserve to listen on
@@ -6368,19 +6545,25 @@
Causes svnserve to run in tunnel
mode, which is just like the inetd
- mode of operation (serve one connection over
- stdin/stdout) except that the connection is considered
+ mode of operation (both modes serve one connection over
+ stdin/stdout, then exit), except that the connection is considered
to be pre-authenticated with the username of the current
- uid. This flag is selected by the client when running
+ uid. This flag is automatically passed for you by the client when running
over a tunnel agent such as
- ssh.
+ ssh.
+ That means there's rarely any need
+ for you, the human, to pass this
+ switch to svnserve. So if you find yourself
+ typing svnserve --tunnel on the
+ command line, and wondering what to do next,
+ read again.
- Used in conjunction with
+ Used in conjunction with the
switch; tells svnserve to assume that
NAME is the authenticated
user, rather than the UID of the svnserve
@@ -6391,6 +6574,8 @@
+
()When running in daemon mode, causes
@@ -6448,6 +6633,10 @@
resultant revision number, or revision range, is written to
standard output.
+ It's common for a build script to include this output
+ in a file that defines the version number of a
+ program.
+
TRAIL_URL, if present, is the
trailing portion of the URL used to determine if
WC_PATH itself is switched
@@ -6455,9 +6644,9 @@
WC_PATH does not rely on
TRAIL_URL).
- When WC_PATH is not defined the current directory
- will be used as the working copy path. TRAIL_URL cannot be
- defined if WC_PATH is not explicitly given.
+ When WC_PATH is not defined, the current directory
+ will be used as the working copy path. TRAIL_URL cannot be
+ defined if WC_PATH is not explicitly given.
@@ -6515,8 +6704,12 @@
4168
- You can add TRAIL_URL to show that the working copy is
- not switched from what you expect. Note that the WC_PATH was
+
+ You can add TRAIL_URL to show that the working copy is
+ not switched from what you expect. Note that the WC_PATH was
required in this command:
@@ -6670,6 +6863,7 @@
SVNReposName
+
Specifies the name of a Subversion repository for
use in HTTP GET requests. This
value will be prepended to the title of all directory
@@ -6730,10 +6924,10 @@
Subversion allows users to invent arbitrarily-named
versioned properties on files and directories, as well as
unversioned properties on revisions. The only restriction is on
- properties prefixed with svn:. Properties in
- that namespace are reserved for Subversion's own use. While
+ properties whose names begin with svn:—
+ those are reserved for Subversion's own use. While
these properties may be set by users to control Subversion's
- behavior, users may not invent new svn:
+ behavior, users may not invent new svn:
properties.
@@ -6773,7 +6967,7 @@
If present on a directory, the value is a list of
- unversioned file patterns to be ignored
+ unversioned file patterns to be ignored
by svn status and other
subcommands. See
If present on a file, the value tells the client
how to manipulate the file's line-endings in the
- working copy. See
+ working copy, and in exported trees. See
.
+ linkend="svn.advanced.props.special.eol-style"/> and
+ .
@@ -6827,7 +7023,10 @@
If present on a file, indicates that the file is
not an ordinary file, but a symbolic link or other
- special object.
+ special objectAs of this writing,
+ symbolic links are indeed the
+ only special objects. But there might
+ be more in future releases of Subversion..
@@ -6869,8 +7068,8 @@
Contains the UTC time the revision was created, in
- ISO format. The value comes from the server
- machine's clock.
+ ISO 8601 format. The value comes from the server
+ machine's clock, not the client's.
@@ -6958,6 +7157,11 @@
access control
+
@@ -7034,12 +7238,12 @@
The post-commit hook is run after the transaction is
committed, and a new revision created. Most people use
- this hook to send out descriptive emails about the commit
+ this hook to send out descriptive emails about the commit,
or to notify some other tool (such as an issue tracker)
that a commit has happened. Some configurations also use
this hook to trigger backup processes.
- The output from and exit value returned by the
+ The output from, and exit value returned by, the
post-commit hook program are ignored.
@@ -7093,9 +7297,9 @@
exit value before a revision property modification can
happen.
- If the pre-revprop-change hook is not implemented or the
- hook program returns a non-zero exit value, no change to the
- property will be made, and anything printed to stderr is
+ If the pre-revprop-change hook doesn't exist, isn't
+ executable, or returns a non-zero exit value, no change to
+ the property will be made, and anything printed to stderr is
marshalled back to the client.
@@ -7123,8 +7327,8 @@
- Additionally, Subversion passes to the hook program via
- standard input the proposed value of the property.
+ Additionally, Subversion passes to the hook program, via
+ standard input, the proposed value of the property.
@@ -7162,7 +7366,7 @@
typically used to send email notification of the property
change.
- The output from and exit value returned by the
+ The output from, and exit value returned by, the
post-revprop-change hook program are ignored.
@@ -7193,8 +7397,8 @@
- Additionally, Subversion passes to the hook program via
- standard input the previous value of the property.
+ Additionally, Subversion passes to the hook program, via
+ standard input, the previous value of the property.
@@ -7230,7 +7434,7 @@
allowed to steal the existing lock.If the pre-lock hook program returns a non-zero exit
- value, the lock action is aborted and anything printed to
+ value, the lock action is aborted, and anything printed to
stderr is marshalled back to the client.
@@ -7283,7 +7487,7 @@
locked. It is typically used to send email notification of
the lock event.
- The output from and exit value returned by the post-look
+ The output from, and exit value returned by, the post-lock
hook program are ignored.
@@ -7305,7 +7509,7 @@
Additionally, the list of paths locked is passed to the
- hook program via standard input, one path per line.
+ hook program, via standard input, one path per line.
@@ -7343,7 +7547,7 @@
by the hook.
If the pre-unlock hook program returns a non-zero exit
- value, the unlock action is aborted and anything printed to
+ value, the unlock action is aborted, and anything printed to
stderr is marshalled back to the client.
@@ -7396,7 +7600,7 @@
been unlocked. It is typically used to send email
notification of the unlock event.
- The output from and exit value returned by the
+ The output from, and exit value returned by, the
post-unlock hook program are ignored.