Section 5.1. The Subversion Client

5.1. The Subversion Client

When interacting with Subversion, the primary client program that you will end up using from the command line is the svn command, which provides most of the features that you will need for interacting with a repository or working copy as a client user. To run the svn command, you will also need to give it a subcommand such as commit or update. Each command has its own set of options that you can use to control the behavior of the command. Many of the options, though, are common to many different commands. For instance, in almost every Subversion client command, you can specify a revision (or range of revisions) using the --revision option.

5.1.1. Common Command Options

Because many of these options are common to a variety of commands, let's take a look at them before diving into the Subversion commands themselves. The following commonly used options are common to most commands and have usage that is worth discussing before taking a look at the commands themselves.

--message

Whenever Subversion creates a new revision, it attaches a log message to that revision that describes what changes were made in the revision, and why. Normally, Subversion will open an editor to allow you to enter in the log message, but if the message is short (or you're running the command from a script) it can be easier to specify the log message directly on the command line. To allow you to do that, all Subversion commands that create a new revision in the repository allow you to use the --message option. To specify a log message, you just give the command --message followed by a message, enclosed in quotes. For example, the following command performs a repository-side copy, and specifies the log message to use:

 $ svn commit --message "Fixed bug #1154." 

--no-auth-cache

Normally, Subversion caches your repository authorization information (username, password, etc.) as a convenience, so you don't have to type it in every time. Sometimes, though, you don't want that information to be stored. For example, you might be using someone else's workstation (or worse, a public workstation). If, for whatever reason, you don't want Subversion to cache your authorization information, you can turn the cache off using the --no-auth-cache option. This option will work with every Subversion command that contacts the repository.

--recursive/--non-recursive

Every Subversion command that can operate on multiple files defaults to either recursive behavior or non-recursive behavior, depending on the command. Basically, commands that can destroy data (such as svn revert) are non-recursive by default. Everything else defaults to recursive. Regardless of which default a program uses, you can override the default using --recursive or --non-recursive. For instance, the following command will revert all local changes in the trunk directory:

 $ svn revert --recursive trunk/ 

--revision

Many Subversion commands require you to specify a specific revision in the repository, or a range of revisions. For any command that takes a revision, you can supply it using the --revision option. Single revisions can be specified by following the option with a single revision number. Or, if the command takes a range of revisions, you can give two revision numbers separated by a colon. For example, the following command will display the log messages for revisions 1 through 50.

 $ svn log --revision 1:50 

To make your life a little bit easier, Subversion also defines a few aliases that can be used to refer to certain revision numbers by their context, rather than their explicit number. Those aliases are HEAD, BASE, COMMITTED, and PREV. Each one can be used in any Subversion command, when a revision number is called foralthough BASE, COMMITTED, and PREV can only be used when referencing a working copy because they require the working copy to give them context. The HEAD alias refers to the greatest numerical revision in a repository. This is the same for every file, regardless of when they were last committed. The BASE alias, on the other hand, points to the base revision for the working copy file or directory being referenced. So, for example, if you check out the trunk directory at revision 3497, BASE would point to 3497. If you then commit a modified file inside the trunk directory at revision 3583, the BASE for that file will point to 3583, whereas the base for the trunk directory and the rest of its contents will still point to 3497. If you later update the trunk to 3583, its BASE will then point to 3583. The remaining two, COMMITTED and PREV, are then relative to the BASE revision. COMMITTED refers to the most recent commit at or before the working copy item's BASE revision, and PREV refers to the revision prior to COMMITTED. So, for instance, if you want to show the log messages from the first revision to the most recently committed revision, you could run the following command.

 $ svn log --revision 1:COMMITTED 

5.1.2. Paths

In addition to options that are common across commands, the format for specifying paths in a working copy or repository are also common. For most Subversion commands, you can reference files and directories that reside locally in a working copy or in a remote repository. Working copy files/directories are referenced by giving a local path to that file (either absolute or relative to the current directory). Repositories are referenced with URLs. For instance, you might reference the trunk directory in a remote repository that is served via Apache with http://svn.example.com/repos/trunk/. Most commands will take either local paths or URLs on the command line, and in most cases you can mix URLs and local paths in the same commandto copy from the repository to a working copy, for example.

 $ svn cp http://svn.example.com/repos/trunk/foo.c~/repos_wc/trunk/bar.c