9.1 The Subversion Command Line Client: svn | Version Control with Subversion

To use the command line client, you type svn, the subcommand you wish to use,^[1] and any switches or targets that you wish to operate on there is no specific order that the subcommand and the switches must appear in. For example, all of the following are valid ways to use svn status:

^[1] Yes, yes, you don't need a subcommand to use the --version switch, but we'll get to that in just a minute.

$ svn -v status $ svn status -v  $ svn status -v myfile

You can find many more examples of how to use most client commands in Chapter 3 and commands for managing properties in Section 7.2.

9.1.1 svn Switches

While Subversion has different switches for its subcommands, all switches are global that is, each switch is guaranteed to mean the same thing regardless of the subcommand you use it with. For example, --verbose (-v) always means verbose output, regardless of the subcommand with which you use it.

--auto-props

Enables auto-props, overriding the enable-auto-props directive in the config file.

--config-dir DIR

Instructs Subversion to read configuration information from the specified directory instead of the default location (.subversion in the user's home directory).

--diff-cmd CMD

Specifies an external program to use to show differences between files. When svn diff is invoked, it uses Subversion's internal diff engine, which provides unified diffs by default. If you want to use an external diff program, use --diff-cmd. You can pass switches to the diff program with the --extensions switch (more on that later in this section).

--diff3-cmd CMD

Specifies an external program to use to merge files.

--dry-run

Goes through all the motions of running a command, but makes no actual changes either on disk or in the repository.

--editor-cmd CMD

Specifies an external program to use to edit a log message or a property value.

--encoding ENC

Tells 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 encoding.

--extensions (-x ) ARGS

Specifies an argument or arguments that Subversion should pass to an external diff command when providing differences between files. 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 --diff-cmd switch.

--file (-F ) FILENAME

Uses the contents of the file passed as an argument to this switch for the specified subcommand.

--force

Forces a particular command or operation to run. There are some operations that Subversion prevents you from doing in normal usage, but you can pass the force switch to tell Subversion, "I know what I'm doing as well as the possible repercussions of doing it, so let me at `em." (This switch is the programmatic equivalent of doing your own electrical work with the power on if you don't know what you're doing, you're likely to get a nasty shock.)

--force-log

Forces a suspicious parameter passed to the --message (-m) or --file (-F) options to be accepted as valid. By default, Subversion produces an error if parameters to these options look as if they might instead be targets of the subcommand. For example, if you pass a versioned file's path to the --file (-F) option, Subversion will assume you've made a mistake, that the path was instead intended as the target of the operation, and that you simply failed to provide some other unversioned file as the source of your log message. To assert your intent and override these types of errors, pass the --force-log option to commands that accept log messages.

--help (-h or -?)

If used with one or more subcommands, shows the built-in help text for each subcommand. If used alone, it displays the general client help text.

--ignore-ancestry

Ignore ancestry when calculating differences (rely on path contents alone).

--incremental

Prints output in a format suitable for concatenation.

--message (-m ) MESSAGE

Indicates that you will specify a commit message on the command line, following this switch. For example:

$ svn commit -m "They don't make Sunday."

--new ARG

Uses ARG as the newer target.

--no-auth-cache

Prevents caching of authentication information (e.g., username and password) in the Subversion administrative directories.

--no-auto-props

Disable auto-props, overriding the enable-auto-props directive in the config file.

--no-diff-deleted

Prevents Subversion from printing differences for deleted files. The default behavior when you remove a file is for svn diff to print the same differences that you would see if you had left the file but removed all the content.

--no-ignore

Shows files in the status listing that would normally be omitted since they match a pattern in the svn:ignore property. See Section 7.1.3.2 for more information.

--non-interactive

In the case of an authentication failure, or insufficient credentials, prevents prompting for credentials (e.g., username or password). This is useful if you're running Subversion inside of an automated script and it's more appropriate to have Subversion fail than to prompt for more information.

--non-recursive (-N)

Stops a subcommand from recursing into subdirectories. Most subcommands recurse by default, but some subcommands usually those that have the potential to remove or undo your local modifications do not.

--notice-ancestry

Pays attention to ancestry when calculating differences.

--old ARG

Uses ARG as the older target.

--password PASS

Indicates that you are providing your password for authentication on the command line otherwise, if it is needed, Subversion prompts you for it.

--quiet (-q)

Requests that the client print only essential information while performing an operation.

--recursive (-R)

Makes a subcommand recurse into subdirectories. Most subcommands recurse by default.

--relocate FROM TO [PATH...]

Used with the svn switch subcommand, changes the location of the repository that your working copy references. This is useful if the location of your repository changes and you have an existing working copy that you'd like to continue to use. See svn switch for an example.

--revision (-r ) REV

Indicates that you're going to supply a revision (or range of revisions) for a particular operation. You can provide revision numbers, revision keywords, or dates (in curly braces) as arguments to the revision switch. If you wish to provide a range of revisions, you can provide two revisions separated by a colon. For example:

$ svn log -r 1729 $ svn log -r 1729:HEAD $ svn log -r 1729:1744 $ svn log -r {2001-12-04}:{2002-02-17} $ svn log -r 1729:{2002-02-17}

See Section 3.3.2 for more information.

--revprop

Operates on a revision property instead of a Subversion property specific to a file or directory. This switch requires that you pass a revision with the --revision (-r) switch. See Section 5.1.2 for more details on unversioned properties.

--show-updates (-u)

Causes the client to display information about which files in your working copy are out-of-date. This doesn't actually update any of your files it just shows you which files will be updated if you run svn update.

--stop-on-copy

Causes a Subversion subcommand that is traversing the history of a versioned resource to stop harvesting that historical information when a copy that is, a location in history where that resource was copied from another location in the repository is encountered.

--strict

Causes Subversion to use strict semantics, a notion which is rather vague unless talking about specific subcommands.

--targets FILENAME

Tells Subversion to get the list of files that you wish to operate on from the filename you provide instead of listing all the files on the command line.

--username NAME

Indicates that you are providing your username for authentication on the command line otherwise, if it is needed, Subversion will prompt you for it.

--verbose (-v)

Requests that the client print out as much information as it can while running any subcommand. This may result in Subversion printing out additional fields, detailed information about every file, or additional information regarding its actions.

--version

Prints the client version info. This information not only includes the version number of the client, but also a listing of all repository access modules that the client can use to access a Subversion repository.

--xml

Prints output in XML format.

9.1.2 svn Subcommands

svn add

Adds files and directories.

Synopsis

svn add PATH...

Description

Adds files and directories to your working copy and schedules them 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 addition using svn revert.

Alternate Names

None

Changes

Working copy

Switches

--targets FILENAME --non-recursive (-N) --quiet (-q) --config-dir DIR --auto-props --no-auto-props

Examples

To add a file to your working copy:

$ svn add foo.c  A         foo.c

When adding a directory, the default behavior of svn add is to recurse:

$ svn add testdir A         testdir A         testdir/a A         testdir/b A         testdir/c A         testdir/d

You can add a directory without adding its contents:

$ svn add --non-recursive otherdir A         otherdir

svn blame

Shows author and revision information in-line for the specified files or URLs.

Synopsis

svn blame TARGET...

Description

Shows author and revision information in-line for the specified files or URLs. Each line of text is annotated at the beginning with the author (username) and the revision number for the last change to that line.

Alternate Names

praise, annotate, ann

Changes

Nothing

Accesses Repository

Yes

Switches

--revision (-r) REV --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

If you want to see blame-annotated source for readme.txt in your test repository:

$ svn blame http://svn.red-bean.com/repos/test/readme.txt      3      sally This is a README file.      5      harry You should read this.

svn cat

Outputs the contents of the specified files or URLs.

Synopsis

svn cat TARGET...

Description

Outputs the contents of the specified files or URLs. For listing the contents of directories, see svn list.

Alternate Names

None

Changes

Nothing

Accesses Repository

Yes

Switches

--revision (-r) REV --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

If you want to view readme.txt in your repository without checking it out:

$ svn cat http://svn.red-bean.com/repos/test/readme.txt This is a README file. You should read this.

If your working copy is out of date (or you have local modifications) and you want to see the HEAD revision of a file in your working copy, svn cat will automatically fetch the HEAD revision when you give it a path:

$ cat foo.c This file is in my local working copy  and has changes that I've made. $ svn cat foo.c Latest revision fresh from the repository!

svn checkout

Checks out a working copy from a repository.

Synopsis

svn checkout URL... [PATH]

Description

Checks out a working copy from a repository. If PATH is omitted, the basename of the URL will be used as the destination. If multiple URLs are given each is checked out into a subdirectory of PATH, with the name of the subdirectory being the basename of the URL.

Alternate Names

co

Changes

Creates a working copy.

Accesses Repository

Yes

Switches

--revision (-r) REV --quiet (-q) --non-recursive (-N) --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

Check out a working copy into a directory called mine:

$ svn checkout file:///tmp/repos/test mine A  mine/a A  mine/b Checked out revision 2. $ ls mine

Check out two different directories into two separate working copies:

$ svn checkout file:///tmp/repos/test  file:///tmp/repos/quiz A  test/a A  test/b Checked out revision 2. A  quiz/l A  quiz/m Checked out revision 2. $ ls quiz  test

Check out two different directories into two separate working copies, but place both into a directory called working-copies:

$ svn checkout file:///tmp/repos/test  file:///tmp/repos/quiz working-copies A  working-copies/test/a A  working-copies/test/b Checked out revision 2. A  working-copies/quiz/l A  working-copies/quiz/m Checked out revision 2. $ ls working-copies

If you interrupt a checkout (or something else interrupts your checkout, such as 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 A  test/b ^C svn: The operation was interrupted svn: caught SIGINT $ svn checkout file:///tmp/repos/test test A  test/c A  test/d ^C svn: The operation was interrupted svn: caught SIGINT $ cd test $ svn update A  test/e A  test/f Updated to revision 3.

svn cleanup

Recursively cleans up the working copy.

Synopsis

svn cleanup [PATH...]

Description

Recursively cleans up the working copy, removing locks and resuming unfinished operations. If you ever get a working copy locked error, run this command to remove stale locks and get your working copy into a usable state again. See Appendix B.

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 --diff3-cmd to allow cleanup to complete any merging with your external diff program. You can also specify any configuration directory with the --config-dir switch, but you should need these switches extremely infrequently.

Alternate Names

None

Changes

Working copy

Accesses Repository

Switches

--diff3-cmd CMD --config-dir DIR

Examples

Well, there's not much to the examples here, as svn cleanup generates no output. If you pass no PATH, . is used:

$ svn cleanup $ svn cleanup /path/to/working-copy

svn commit

Sends changes from your working copy to the repository.

Synopsis

svn commit [PATH...]

Description

Sends changes from your working copy to the repository. If you do not supply a log message with your commit by using either the --file or --message switch, svn will launch your editor for you to compose a commit message. See editor-cmd in Section 7.1.3.2.

If you begin a commit and Subversion launches your editor to compose the commit message, you can still abort without committing your changes. If you want to cancel your commit, just quit your editor without saving your commit message and Subversion prompts you either to abort the commit, continue with no message, or edit the message again.

Alternate Names

ci (short for "check in," not co, which is short for "check out")

Changes

Working copy, repository

Accesses Repository

Yes

Switches

--message (-m) TEXT --file (-F) FILE --quiet (-q) --non-recursive (-N) --targets FILENAME --force-log --username USER --password PASS --no-auth-cache --non-interactive --encoding ENC --config-dir DIR

Examples

Commit a simple modification to a file with the commit message on the command line and an implicit target of your current directory (.):

$ svn commit -m "added howto section." Sending        a Transmitting file data . Committed revision 3.

Commit a modification to the file foo.c (explicitly specified on the command line) with the commit message in a file named msg:

$ svn commit -F msg foo.c Sending        foo.c Transmitting file data . Committed revision 5.

If you want to use a file that's under version control for your commit message with --file, you need to pass the --force-log switch:

$ svn commit --file file_under_vc.txt foo.c svn: The log message file is under version control svn: Log message file is a versioned file; use '--force-log' to override $ svn commit --force-log --file file_under_vc.txt foo.c Sending        foo.c Transmitting file data . Committed revision 6.

To commit a file scheduled for deletion:

$ svn commit -m "removed file 'c'." Deleting       c Committed revision 7.

svn copy

Copies a file or directory in a working copy or in the repository.

Synopsis

svn copy SRC DST

Description

Copies a file in a working copy or in the repository. SRC and DST can each be either a working copy (WC) path or URL:

WC -> WC: Copy and schedule an item for addition (with history).
WC -> URL: Immediately commit a copy of WC to URL.
URL -> WC: Check out URL into WC, and schedule it for addition.
URL -> URL: Complete server-side copy. This is usually used to branch and tag.

You can only copy files within a single repository. Subversion does not support cross-repository copying.

Alternate Names

cp

Changes

Repository if destination is a URL.

Working copy if destination is a WC path.

Accesses Repository

If source or destination is in the repository, or if needed to look up the source revision number.

Switches

--message (-m) TEXT --file (-F) FILE --revision (-r) REV --quiet (-q) --username USER --password PASS --no-auth-cache --non-interactive --force-log --editor-cmd EDITOR --encoding ENC --config-dir DIR

Examples

Copy an item within your working copy (only schedules the copy nothing goes into the repository until you commit):

$ svn copy foo.txt bar.txt A         bar.txt $ svn status A  +   bar.txt

Copy an item in your working copy to a URL in the repository (an immediate commit, so you must supply a commit message):

$ svn copy near.txt file:///tmp/repos/test/far-away.txt -m "Remote copy." Committed revision 8.

Copy an item from the repository to your working copy (only schedules the copy nothing goes into the repository until you commit):

This is the recommended way to resurrect a dead file in your repository!

$ svn copy file:///tmp/repos/test/far-away near-here A         near-here

And finally, copying between two URLs:

$ svn copy file:///tmp/repos/test/far-away file:///tmp/repos/test/over-there -m  "remote copy." Committed revision 9.

This is the easiest way to tag a revision in your repository just svn copy that revision (usually HEAD) into your tags directory.

$ svn copy file:///tmp/repos/test/trunk file:///tmp/repos/test/tags/0.6.32-prerelease  -m "tag tree" Committed revision 12.

And don't worry if you forgot to tag you can always specify an older revision and tag anytime:

$ svn copy -r 11 file:///tmp/repos/test/trunk file:///tmp/repos/test/tags/0.6.32- prerelease -m "Forgot to tag at rev 11" Committed revision 13.

svn delete

Deletes an item from a working copy or the repository.

Synopsis

svn delete PATH... svn delete URL...

Description

Items specified by PATH are scheduled for deletion upon the next commit. Files (and directories that have not been committed) are immediately removed from the working copy. The command will not remove any unversioned or modified items; use the --force switch to override this behavior.

Items specified by URL are deleted from the repository via an immediate commit. Multiple URLs are committed atomically.

Alternate Names

del, remove, rm

Changes

Working copy if operating on files, repository if operating on URLs

Accesses Repository

Only if operating on URLs

Switches

--force --force-log --message (-m) TEXT --file (-F) FILE --quiet (-q) --targets FILENAME --username USER --password PASS --no-auth-cache --non-interactive --editor-cmd EDITOR --encoding ENC --config-dir DIR

Examples

Using 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:

$ svn delete myfile D         myfile $ svn commit -m "Deleted file 'myfile'." Deleting       myfile Transmitting file data . Committed revision 14.

Deleting a URL, however, is immediate, so you have to supply a log message:

$ svn delete -m "Deleting file 'yourfile'" file:///tmp/repos/test/yourfile Committed revision 15.

Here's an example of how to force deletion of a file that has local mods:

$ svn delete over-there  svn: Attempting restricted operation for modified resource svn: Use --force to override this restriction svn: 'over-there' has local modifications $ svn delete --force over-there  D         over-there

svn diff

Displays the differences between two paths.

Synopsis

svn diff [-r N[:M]] [--old OLD-TGT] [--new NEW-TGT] [PATH...] svn diff -r N:M URL svn diff [-r N[:M]] URL1[@N] URL2[@M]

Description

Displays the differences between two paths. The three different ways you can use svn diff are as follows:

svn diff [-r N[:M]] [--old OLD-TGT] [--new NEW-TGT] [PATH...] displays the differences  between OLD-TGT and NEW-TGT. If PATHs are given, they are treated as relative to OLD-TGT  and NEW-TGT and the output is restricted to differences in only those paths. OLD-TGT  and NEW-TGT may be working copy paths or URL[@REV]. OLD-TGT defaults to the current  working directory and NEW-TGT defaults to OLD-TGT. N defaults to BASE or, if OLD-TGT is  a URL, to HEAD. M defaults to the current working version or, if NEW-TGT is a URL, to  HEAD. svn diff -r N sets the revision of OLD-TGT to N, svn diff -r N:M also sets the  revision of NEW-TGT to M. svn diff -r N:M URL is shorthand for svn diff -r N:M --old=URL --new=URL. svn diff [-r N[:M]] URL1[@N] URL2[@M] is shorthand for svn diff [-r N[:M]] --old=URL1 -- new=URL2.

If TARGET is a URL, then revs N and M can be given either via the --revision or by using @ notation as described earlier.

If TARGET is a working copy path, then the --revision switch means:

--revision N:M: The server compares TARGET@N and TARGET@M.
--revision N: The client compares TARGET@N against working copy.
(no --revision): The client compares base and working copies of TARGET.

If the alternate syntax is used, the server compares URL1 and URL2 at revisions N and M respectively. If either N or M are omitted, a value of HEAD is assumed.

By default, svn diff ignores the ancestry of files and merely compares the contents of the two files being compared. If you use --notice-ancestry, the ancestry of the paths in question will be taken into consideration when comparing revisions (that is, if you run svn diff on two files with identical contents but different ancestry you will see the entire contents of the file as having been removed and added again).

Alternate Names

di

Changes

Nothing

Accesses Repository

For obtaining differences against anything but BASE revision in your working copy

Switches

--revision (-r) REV --old OLD-TARGET --new NEW-TARGET --extensions (-x) "ARGS" --non-recursive (-N) --diff-cmd CMD --notice-ancestry --username USER --password PASS --no-auth-cache --non-interactive --no-diff-deleted --config-dir DIR

Examples

Compare BASE and your working copy (one of the most popular uses of svn diff):

$ svn diff COMMITTERS  Index: COMMITTERS = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --- COMMITTERS        (revision 4404) +++ COMMITTERS        (working copy)

See how your working copy's modifications compare against an older revision:

$ svn diff -r 3900 COMMITTERS  Index: COMMITTERS = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --- COMMITTERS        (revision 3900) +++ COMMITTERS        (working copy)

Compare revision 3000 to revision 3500 using @ syntax:

$ svn diff http://svn.collab.net/repos/svn/trunk/COMMITTERS@3000 http://svn.collab. net/repos/svn/trunk/COMMITTERS@3500 Index: COMMITTERS = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --- COMMITTERS        (revision 3000) +++ COMMITTERS        (revision 3500) ...

Compare revision 3000 to revision 3500 using range notation (you only pass the one URL in this case):

$ svn diff -r 3000:3500 http://svn.collab.net/repos/svn/trunk/COMMITTERS Index: COMMITTERS = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --- COMMITTERS        (revision 3000) +++ COMMITTERS        (revision 3500)

Compare revision 3000 to revision 3500 of all files in trunk using range notation:

$ svn diff -r 3000:3500 http://svn.collab.net/repos/svn/trunk

Compare revision 3000 to revision 3500 of only three files in trunk using range notation:

$ svn diff -r 3000:3500 --old http://svn.collab.net/repos/svn/trunk COMMITTERS README  HACKING

If you have a working copy, you can obtain the differences without typing in the long URLs:

$ svn diff -r 3000:3500 COMMITTERS  Index: COMMITTERS = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --- COMMITTERS        (revision 3000) +++ COMMITTERS        (revision 3500)

Use --diff-cmd CMD -x to pass arguments directly to the external diff program:

$ svn diff --diff-cmd /usr/bin/diff -x "-i -b" COMMITTERS  Index: COMMITTERS = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 0a1,2 > This is a test >

svn export

Exports a clean directory tree.

Synopsis

svn export [-r REV] URL [PATH] svn export PATH1 PATH2

Description

The first form exports a clean directory tree from the repository specified by URL, at revision REV if it is given, otherwise at HEAD, into PATH. If PATH is omitted, the last component of the URL is used for the local directory name.

The second form exports a clean directory tree from the working copy specified by PATH1 into PATH2. All local changes will be preserved, but files not under version control will not be copied.

Alternate Names

None

Changes

Local disk

Accesses Repository

Only if exporting from a URL

Switches

--revision (-r) REV --quiet (-q) --force --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

Export from your working copy (doesn't print every file and directory):

$ svn export a-wc my-export Export complete.

Export directly from the repository (prints every file and directory):

$ svn export file:///tmp/repos my-export A  my-export/test A  my-export/quiz ... Exported revision 15.

svn help

Provides Help!

Synopsis

svn help [SUBCOMMAND...]

Description

Displays Help documentation. This is your best friend when you're using Subversion and this book isn't within reach!

Alternate Names

?, h

Changes

Nothing

Accesses Repository

Switches

--version --quiet (-q)

svn import

Recursively commits a copy of PATH to URL.

Synopsis

svn import [PATH] URL

Description

Recursively commits a copy of PATH to URL. If PATH is omitted . is assumed. Parent directories are created in the repository as necessary.

Alternate Names

None

Changes

Repository

Accesses Repository

Yes

Switches

--message (-m) TEXT --file (-F) FILE --quiet (-q) --non-recursive (-N) --username USER --password PASS --no-auth-cache --non-interactive --force-log --editor-cmd EDITOR --encoding ENC --config-dir DIR --auto-props --no-auto-props

Examples

This imports the local directory myproj into the root of your repository:

$ svn import -m "New import" myproj http://svn.red-bean.com/repos/test Adding         myproj/sample.txt ... Transmitting file data ......... Committed revision 16.

This imports the local directory myproj into trunk/vendors in your repository. The directory trunk/vendors 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/trunk/vendors/myproj Adding         myproj/sample.txt ... Transmitting file data ......... Committed revision 19.

svn info

Prints information about PATHs.

Synopsis

svn info [PATH...]

Description

Prints information about paths in your working copy, including:

Path
Name
URL
Revision
Node kind
Last changed author
Last changed revision
Last changed date
Text last updated
Properties last updated
Checksum

Alternate Names

None

Changes

Nothing

Accesses Repository

Switches

--targets FILENAME --recursive (-R) --config-dir DIR

Examples

svn info shows you all the useful information that it has for items in your working copy. It shows information for files:

$ svn info foo.c Path: foo.c Name: foo.c URL: http://svn.red-bean.com/repos/test/foo.c Revision: 4417 Node Kind: file Schedule: normal Last Changed Author: sally Last Changed Rev: 20 Last Changed Date: 2003-01-13 16:43:13 -0600 (Mon, 13 Jan 2003) Text Last Updated: 2003-01-16 21:18:16 -0600 (Thu, 16 Jan 2003) Properties Last Updated: 2003-01-13 21:50:19 -0600 (Mon, 13 Jan 2003) Checksum: /3L38YwzhT93BWvgpdF6Zw= =

It will also show information for directories:

$ svn info vendors Path: trunk URL: http://svn.red-bean.com/repos/test/vendors Revision: 19 Node Kind: directory Schedule: normal Last Changed Author: harry Last Changed Rev: 19 Last Changed Date: 2003-01-16 23:21:19 -0600 (Thu, 16 Jan 2003)

svn list

Lists directory entries in the repository.

Synopsis

svn list [TARGET...]

Description

Lists each TARGET file and the contents of each TARGET directory as they exist in the repository. If TARGET is a working copy path, the corresponding repository URL will be used.

The default TARGET is ., meaning the repository URL of the current working copy directory.

With --verbose, the following fields show the status of the item:

Revision number of the last commit
Author of the last commit
Size (in bytes)
Date and time of the last commit

Alternate Names

ls

Changes

Nothing

Accesses Repository

Yes

Switches

--revision (-r) REV --verbose (-v) --recursive (-R) --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

svn list is most useful if you want to see what files a repository has without downloading a working copy:

$ svn list http://svn.red-bean.com/repos/test/support README.txt INSTALL examples/ ...

Like Unix ls, you can also pass the --verbose switch for additional information:

$ svn list --verbose file:///tmp/repos      16 sally         28361 Jan 16 23:18 README.txt      27 sally             0 Jan 18 15:27 INSTALL      24 harry               Jan 18 11:27 examples/

For further details, see Section 3.6.4.

svn log

Displays commit log messages.

Synopsis

svn log [PATH] svn log URL [PATH...]

Description

The default target is the path of your current directory. 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 results by specifying a path, one or more revisions, or any combination of the two. The default revision range for a local path is BASE:1.

If you specify a URL alone, then it prints log messages for everything that the URL contains. If you add paths past the URL, only messages for those paths under that URL will be printed. The default revision range for a URL is HEAD:1.

With --verbose, svn log will also print all affected paths with each log message. With --quiet, svn log will not print the log message body itself (this is compatible with --verbose).

Each log message is printed just once, even if more than one of the affected paths for that revision were explicitly requested. Logs follow copy history by default. Use --stop-on-copy to disable this behavior, which can be useful for determining branch points.

Alternate Names

None

Changes

Nothing

Accesses Repository

Yes

Switches

--revision (-r) REV --quiet (-q) --verbose (-v) --targets FILENAME --stop-on-copy --incremental --xml --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

You can see the log messages for all the paths that changed in your working copy by running svn log from the top:

$ svn log ------------------------------------------------------------------------ r20 | harry | 2003-01-17 22:56:19 -0600 (Fri, 17 Jan 2003) | 1 line Tweak. ------------------------------------------------------------------------ r17 | sally | 2003-01-16 23:21:19 -0600 (Thu, 16 Jan 2003) | 2 lines ...

Examine all log messages for a particular file in your working copy:

$ svn log foo.c ------------------------------------------------------------------------ r32 | sally | 2003-01-13 16:43:13 -0600 (Mon, 13 Jan 2003) | 1 line Added defines. ------------------------------------------------------------------------ r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines ...

If you don't have a working copy handy, you can log a URL:

$ svn log http://svn.red-bean.com/repos/test/foo.c ------------------------------------------------------------------------ r32 | sally | 2003-01-13 16:43:13 -0600 (Mon, 13 Jan 2003) | 1 line Added defines. ------------------------------------------------------------------------ r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines ...

If you want several distinct paths underneath the same URL, you can use the URL [PATH...] syntax.

$ svn log http://svn.red-bean.com/repos/test/ foo.c bar.c ------------------------------------------------------------------------ r32 | sally | 2003-01-13 16:43:13 -0600 (Mon, 13 Jan 2003) | 1 line Added defines. ------------------------------------------------------------------------ r31 | harry | 2003-01-10 12:25:08 -0600 (Fri, 10 Jan 2003) | 1 line Added new file bar.c ------------------------------------------------------------------------ r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines ...

That is the same as explicitly placing both URLs on the command line:

$ svn log http://svn.red-bean.com/repos/test/foo.c \           http://svn.red-bean.com/repos/test/bar.c ...

When you're concatenating the results of multiple calls to the log command, you may want to use the --incremental switch. svn log normally prints out a dashed line at the beginning of a log message, after each subsequent log message, and following the final log message. If you ran svn log on a range of two revisions, you would get the following:

$ svn log -r 14:15 ------------------------------------------------------------------------ r14 | ...  ------------------------------------------------------------------------ r15 | ...  ------------------------------------------------------------------------

However, if you wanted to gather two nonsequential log messages into a file, you might do something such as this:

$ svn log -r 14 > mylog $ svn log -r 19 >> mylog $ svn log -r 27 >> mylog $ cat mylog ------------------------------------------------------------------------ r14 | ...  ------------------------------------------------------------------------ ------------------------------------------------------------------------ r19 | ...  ------------------------------------------------------------------------ ------------------------------------------------------------------------ r27 | ...  ------------------------------------------------------------------------

You can avoid the clutter of the double-dashed lines in your output by using the incremental switch:

$ svn log --incremental -r 14 > mylog $ svn log --incremental -r 19 >> mylog $ svn log --incremental -r 27 >> mylog $ cat mylog ------------------------------------------------------------------------ r14 | ...  ------------------------------------------------------------------------ r19 | ...  ------------------------------------------------------------------------ r27 | ...

The --incremental switch provides similar output control when using the --xml switch.

If you run svn log on a specific path and provide a specific revision and get no output at all:

$ svn log -r 20 http://svn.red-bean.com/untouched.txt ------------------------------------------------------------------------

That just means that the path was not modified in that revision. If you log from the top of the repository, or know the file that changed in that revision, you can specify it explicitly:

$ svn log -r 20 touched.txt  ------------------------------------------------------------------------ r20 | sally | 2003-01-17 22:56:19 -0600 (Fri, 17 Jan 2003) | 1 line Made a change. ------------------------------------------------------------------------

svn merge

Applies the differences between two sources to a working copy path.

Synopsis

svn merge sourceURL1[@N] sourceURL2[@M] [WCPATH] svn merge -r N:M SOURCE [PATH]

Description

In the first form, the source URLs are specified at revisions N and M. These are the two sources to be compared. The revisions default to HEAD if omitted.

In the second form, SOURCE can be a URL or working copy item, in which case the corresponding URL is used. This URL, at revisions N and M, defines the two sources to be compared.

WCPATH is the working copy path that will receive the changes. If WCPATH is omitted, a default value of . is assumed, unless the sources have identical basenames that match a file within, in which case the differences will be applied to that file.

Unlike svn diff, the merge command takes the ancestry of a file into consideration when performing a merge operation. This is very important when you're merging changes from one branch into another and you've renamed a file on one branch but not the other.

Alternate Names

None

Changes

Working copy

Accesses Repository

Only if working with URLs

Switches

--revision (-r) REV --non-recursive (-N) --quiet (-q) --force --dry-run --diff3-cmd CMD --ignore-ancestry --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

Merge a branch back into the trunk (assuming that you have a working copy of the trunk, and that the branch was created in revision 250):

$ svn merge -r 250:HEAD http://svn.red-bean.com/repos/branches/my-branch U  myproj/tiny.txt U  myproj/thhgttg.txt U  myproj/win.txt U  myproj/flo.txt

If you branched at revision 23, and you want to merge changes on trunk into your branch, you could do this from inside the working copy of your branch:

$ svn merge -r 23:30 file:///tmp/repos/trunk/vendors U  myproj/thhgttg.txt ...

To merge changes to a single file:

$ cd myproj $ svn merge -r 30:31 thhgttg.txt  U  thhgttg.txt

svn mkdir

Creates a new directory under version control.

Synopsis

svn mkdir PATH... svn mkdir URL...

Description

Creates a directory with a name given by the final component of the PATH or URL. A directory specified by a working copy PATH is scheduled for addition in the working copy. A directory specified by a URL is created in the repository via an immediate commit. Multiple directory URLs are committed atomically. In both cases all the intermediate directories must already exist.

Alternate Names

None

Changes

Working copy, repository if operating on a URL

Accesses Repository

Only if operating on a URL

Switches

--message (-m) TEXT --file (-F) FILE --quiet (-q) --username USER --password PASS --no-auth-cache --non-interactive --editor-cmd EDITOR --encoding ENC --force-log --config-dir DIR

Examples

Create a directory in your working copy:

$ svn mkdir newdir A         newdir

Create one in the repository (instant commit, so a log message is required):

$ svn mkdir -m "Making a new dir." http://svn.red-bean.com/repos/newdir Committed revision 26.

svn move

Moves a file or directory.

Synopsis

svn move SRC DST

Description

This command moves a file or directory in your working copy or in the repository.

This command is equivalent to an svn copy followed by svn delete.

Subversion does not support moving between working copies and URLs. In addition, you can only move files within a single repository Subversion does not support cross-repository moving:

WC -> WC: Move and schedule a file or directory for addition (with history).
URL -> URL: Complete server-side rename.

Alternate Names

mv, rename, ren

Changes

Working copy, repository if operating on a URL

Accesses Repository

Only if operating on a URL

Switches

--message (-m) TEXT --file (-F) FILE --revision (-r) REV --quiet (-q) --force --username USER --password PASS --no-auth-cache --non-interactive --editor-cmd EDITOR --encoding ENC --force-log --config-dir DIR

Examples

Move a file in your working copy:

$ svn move foo.c bar.c A         bar.c D         foo.c

Move a file in the repository (an immediate commit, so it requires a commit message):

$ svn move -m "Move a file" http://svn.red-bean.com/repos/foo.c \                             http://svn.red-bean.com/repos/bar.c Committed revision 27.

svn propdel

Removes a property from an item.

Synopsis

svn propdel PROPNAME [PATH...] svn propdel PROPNAME --revprop -r REV [URL]

Description

Removes properties from files, directories, or revisions. The first form removes versioned properties in working copy, while the second removes unversioned remote properties on a repository revision.

Alternate Names

pdel, pd

Changes

Working copy, repository only if operating on a URL

Accesses Repository

Only if operating on a URL

Switches

--quiet (-q) --recursive (-R) --revision (-r) REV --revprop --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

Delete a property from a file in your working copy:

$ svn propdel svn:mime-type  some-script property 'svn:mime-type' deleted from 'some-script'.

Delete a revision property:

$ svn propdel --revprop -r 26 release-date  property 'release-date' deleted from repository revision '26'

svn propedit

Edits the property of one or more items under version control.

Synopsis

svn propedit PROPNAME PATH... svn propedit PROPNAME --revprop -r REV [URL]

Description

Edits one or more properties using your favorite editor. The first form edits versioned properties in your working copy, while the second edits unversioned remote properties on a repository revision.

Alternate Names

pedit, pe

Changes

Working copy, repository only if operating on a URL

Accesses Repository

Only if operating on a URL

Switches

--revision (-r) REV --revprop --username USER --password PASS --no-auth-cache --non-interactive --encoding ENC --editor-cmd EDITOR --config-dir DIR

Examples

svn propedit makes it easy to modify properties that have multiple values:

$ svn propedit svn:keywords  foo.c      <svn will launch your favorite editor here, with a buffer open     containing the current contents of the svn:keywords property.  You     can add multiple values to a property easily here by entering one     value per line.> Set new value for property 'svn:keywords' on 'foo.c'

svn propget

Prints the value of a property.

Synopsis

svn propget PROPNAME [PATH...] svn propget PROPNAME --revprop -r REV [URL]

Description

Prints the value of a property on files, directories, or revisions. The first form prints the versioned property of an item or items in your working copy, while the second prints unversioned remote property on a repository revision. See Section 7.2 for more information on properties.

Alternate Names

pget, pg

Changes

Working copy, repository only if operating on a URL

Accesses Repository

Only if operating on a URL

Switches

--recursive (-R) --revision (-r) REV --revprop --strict --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

Examine a property of a file in your working copy:

$ svn propget svn:keywords foo.c Author Date Rev

The same goes for a revision property:

$ svn propget svn:log --revprop -r 20  Began journal.

svn proplist

Lists all properties.

Synopsis

svn proplist [PATH...] svn proplist --revprop -r REV [URL]

Description

Lists all properties on files, directories, or revisions. The first form lists versioned properties in working copy, while the second lists unversioned remote properties on a repository revision.

Alternate Names

plist, pl

Changes

Working copy, repository only if operating on a URL

Accesses Repository

Only if operating on a URL

Switches

--verbose (-v) --recursive (-R) --revision (-r) REV --quiet (-q) --revprop --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

You can use proplist to see the properties on an item in your working copy:

$ svn proplist foo.c Properties on 'foo.c':   svn:mime-type   svn:keywords   owner

But with the --verbose flag, svn proplist is extremely handy as it also shows you the values for the properties:

$ svn proplist --verbose foo.c Properties on 'foo.c':   svn:mime-type : text/plain   svn:keywords : Author Date Rev   owner : sally

svn propset

Sets PROPNAME to PROPVAL on files, directories, or revisions.

Synopsis

svn propset PROPNAME [PROPVAL | -F VALFILE] PATH... svn propset PROPNAME --revprop -r REV [PROPVAL | -F VALFILE] [URL]

Description

Sets PROPNAME to PROPVAL on files, directories, or revisions. The first example creates a versioned, local property change in the working copy, and the second creates an unversioned, remote property change on a repository revision.

Subversion has a number of special properties that affect its behavior. See Section 7.2.3 for more on these properties.

Alternate Names

pset, ps

Changes

Working copy, repository only if operating on a URL

Accesses Repository

Only if operating on a URL

Switches

--file (-F) FILE --quiet (-q) --revision (-r) REV --targets FILENAME --recursive (-R) --revprop --username USER --password PASS --no-auth-cache --non-interactive --encoding ENC --force --config-dir DIR

Examples

Set the mimetype on a file:

$ svn propset svn:mime-type image/jpeg foo.jpg  property 'svn:mime-type' set on 'foo.jpg'

On a Unix system, if you want a file to have the executable permission set:

$ svn propset svn:executable ON somescript property 'svn:executable' set on 'somescript'

Perhaps you have an internal policy to set certain properties for the benefit of your coworkers:

$ svn propset owner sally foo.c property 'owner' set on 'foo.c'

If you made a mistake in a log message for a particular revision and want to change it, use --revprop and set svn:log to the new log message:

$ svn propset --revprop -r 25 svn:log "Journaled about trip to New York." property 'svn:log' set on repository revision '25'

Or, if you don't have a working copy, you can provide a URL.

$ svn propset --revprop -r 26 svn:log "Document nap." http://svn.red-bean.com/repos property 'svn:log' set on repository revision '25'

Lastly, you can tell propset to take its input from a file. You could even use this to set the contents of a property to something binary:

$ svn propset owner-pic -F sally.jpg moo.c  property 'owner-pic' set on 'moo.c'

By default, you cannot modify revision properties in a Subversion repository. Your repository administrator must explicitly enable revision property modifications by creating a hook named pre-revprop-change. See Section 5.2.1 for more information on hook scripts.

svn resolved

Removes conflicted state on working copy files or directories.

Synopsis

svn resolved PATH...

Description

Removes conflicted state on working copy files or directories. This routine does not semantically resolve conflict markers; it merely removes conflict-related artifact files and allows PATH to be committed again; that is, it tells Subversion that the conflicts have been resolved. See Section 3.5.4 for an in-depth look at resolving conflicts.

Alternate Names

None

Changes

Working copy

Accesses Repository

Switches

--targets FILENAME --recursive (-R) --quiet (-q) --config-dir DIR

Examples

If you get a conflict on an update, your working copy sprouts three new files:

$ svn update C  foo.c Updated to revision 31. $ ls foo.c foo.c.mine foo.c.r30 foo.c.r31

Once you've resolved the conflict and foo.c is ready to be committed, run svn resolved to let your working copy know you've taken care of everything.

You can just remove the conflict files and commit, but svn resolved fixes up some bookkeeping data in the working copy administrative area in addition to removing the conflict files, so we recommend that you use this command.

svn revert

Undoes all local edits.

Synopsis

svn revert PATH...

Description

Reverts any local changes to a file or directory and resolves any conflicted states. svn revert will not only revert the contents of an item in your working copy, but also any property changes. Finally, you can use it to undo any scheduling operations that you may have done (e.g., files scheduled for addition or deletion can be unscheduled).

Alternate Names

None

Changes

Working copy

Accesses Repository

Switches

--targets FILENAME --recursive (-R) --quiet (-q) --config-dir DIR

Examples

Discard changes to a file:

$ svn revert foo.c Reverted foo.c

If you want to revert a whole directory of files, use the --recursive flag:

$ svn revert --recursive . Reverted newdir/afile Reverted foo.c Reverted bar.txt

Lastly, you can undo any scheduling operations:

$ svn add mistake.txt whoops A         mistake.txt A         whoops A         whoops/oopsie.c $ svn revert mistake.txt whoops Reverted mistake.txt Reverted whoops $ svn status ?      mistake.txt ?      whoops

If you provide no targets to svn revert, it will do nothing to protect you from accidentally losing changes in your working copy, svn revert requires you to provide at least one target.

svn status

Prints the status of working copy files and directories.

Synopsis

svn status [PATH...]

Description

Prints the status of working copy files and directories. With no arguments, it prints only locally modified items (no repository access). With --show-updates, add working revision and server out-of-date information. With --verbose, print full revision information on every item.

The first five columns in the output are each one character wide, and each column gives you information about different aspects of each working copy item.

The first column indicates that an item was added, deleted, or otherwise changed.

' ` (blank): No modifications.
A: Item is scheduled for Addition.
D: Item is scheduled for Deletion.
M: Item has been modified.
C: Item is in conflict with updates received from the repository.
I: Item is being ignored (e.g., with the svn:ignore property)
?: Item is not under version control.
!: Item is missing (e.g., you moved or deleted it without using svn). This also indicates that a directory is incomplete (a checkout or update was interrupted).
~: Item is versioned as a directory, but has been replaced by a file, or vice versa

The second column tells the status of a file's or directory's properties.

' ` (blank): No modifications.
M: Properties for this item have been modified.
C: Properties for this item are in conflict with property updates received from the repository.

The third column is populated only if the working copy directory is locked.

' ` (blank): Item is not locked.
L: Item is locked.

The fourth column is populated only if the item is scheduled for addition-with-history.

' ` (blank): No history scheduled with commit.
+: History scheduled with commit.

The fifth column is populated only if the item is switched relative to its parent (see Section 4.5).

' ` (blank): Item is child of its parent directory.
S: Item is switched.

The out-of-date information appears in the eighth column (only if you pass the --show-updates switch).

' ` (blank): The item in your working copy is up-to-date.
*: A newer revision of the item exists on the server.

The remaining fields are variable width and delimited by spaces. The working revision is the next field if the --show-updates or --verbose switches are passed.

If the --verbose switch is passed, the last committed revision and last committed author are displayed next.

The working copy path is always the final field, so it can include spaces.

Alternate Names

stat, st

Changes

Nothing

Accesses Repository

Only if using --show-updates

Switches

--show-updates (-u) --verbose (-v) --non-recursive (-N) --quiet (-q) --no-ignore --username USER --password PASS --no-auth-cache --non-interactive --config-dir

Examples

This is the easiest way to find out what changes you have made to your working copy:

$ svn status wc  M     wc/bar.c A  +   wc/qax.c

If you want to find out what files in your working copy are out-of-date, pass the --show-updates switch (this will not make any changes to your working copy). Here you can see that wc/foo.c has changed in the repository since we last updated our working copy:

$ svn status --show-updates wc  M           965    wc/bar.c        *     965    wc/foo.c A  +         965    wc/qax.c Status against revision:    981

--show-updates only places an asterisk next to items that are out of date (that is, items that will be updated from the repository if you run svn update). --show-updates 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 the status subcommand:

$ svn status --show-updates --verbose wc  M           965       938 sally        wc/bar.c        *     965       922 harry        wc/foo.c A  +         965       687 harry        wc/qax.c              965       687 harry        wc/zig.c Head revision:   981

For many more examples of svn status, see Section 3.5.3.1.

svn switch

Updates working copy to a different URL.

Synopsis

svn switch URL [PATH]

Description

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 Section 4.5 for an in-depth look at switching.

Alternate Names

sw

Changes

Working copy

Accesses Repository

Yes

Switches

--revision (-r) REV --non-recursive (-N) --quiet (-q) --diff3-cmd CMD --relocate --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

If you're currently inside the directory vendors which was branched to vendors-with-fix and you'd like to switch your working copy to that branch:

$ svn switch http://svn.red-bean.com/repos/branches/vendors-with-fix . U  myproj/foo.txt U  myproj/bar.txt U  myproj/baz.c U  myproj/qux.c Updated to revision 31.

And to switch back, just provide the URL to the location in the repository from which you originally checked out your working copy:

$ svn switch http://svn.red-bean.com/repos/trunk/vendors . U  myproj/foo.txt U  myproj/bar.txt U  myproj/baz.c U  myproj/qux.c Updated to revision 31.

You can just switch part of your working copy to a branch if you don't want to switch your entire working copy.

If the location of your repository changes and you have an existing working copy that you'd like to continue to use, you can use svn switch relocate to change your working copy from one URL to another:

$ svn checkout file:///tmp/repos test A  test/a A  test/b ... $ mv repos newlocation $ cd test/ $ svn update svn: Unable to open an ra_local session to URL svn: Unable to open repository 'file:///tmp/repos' $ svn switch --relocate file:///tmp/repos file:///tmp/newlocation . $ svn update At revision 3.

svn update

Updates your working copy.

Synopsis

svn update [PATH...]

Description

svn update brings changes from the repository into your working copy. If no revision 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 --revision switch.

For each updated item a line will start with a character reporting the action taken. These characters have the following meaning:

A: Added
D: Deleted
U: Updated
C: Conflict
G: Merged

A character in the first column signifies an update to the actual file, while updates to the file's properties are shown in the second column.

Alternate Names

up

Changes

Working copy

Accesses Repository

Yes

Switches

--revision (-r) REV --non-recursive (-N) --quiet (-q) --diff3-cmd CMD --username USER --password PASS --no-auth-cache --non-interactive --config-dir DIR

Examples

Pick up repository changes that have happened since your last update:

$ svn update A  newdir/toggle.c A  newdir/disclose.c A  newdir/launch.c D  newdir/README Updated to revision 32.

You can also update your working copy to an older revision (Subversion doesn't have the concept of sticky files like CVS does; see Appendix A):

$ svn update -r30 A  newdir/README D  newdir/toggle.c D  newdir/disclose.c D  newdir/launch.c U  foo.c Updated to revision 30.

If you want to examine an older revision of a single file, you may want to use svn cat.