This documentation was written to describe the 1.6.x series of Subversion. If you are running a different version of Subversion, you are strongly encouraged to visit http://www.svnbook.com/ and instead consult the version of this documentation appropriate for your version of Subversion.
The most obvious way to get data into Subversion is through
the addition of files to version control, committing changes to
those files, and so on. But other pieces of
information besides merely versioned file data live in your
Subversion repository. Some of these bits of
information—commit log messages, lock comments, and some
property values—tend to be textual in nature and are
provided explicitly by users. Most of this information can be
provided to the Subversion command-line client using the
--message
(-m
) and
--file
(-F
) options with the
appropriate subcommands.
Each of these options has its pros and cons. For example,
when performing a commit, --file
(-F
) works well if you've already prepared a
text file that holds your commit log message. If you didn't,
though, you can use --message
(-m
) to provide a log message on the command
line. Unfortunately, it can be tricky to compose anything more
than a simple one-line message on the command line. Users want
more flexibility—multiline, free-form log message editing
on demand.
Subversion supports this by allowing you to specify an external text editor that it will launch as necessary to give you a more powerful input mechanism for this textual metadata. There are several ways to tell Subversion which editor you'd like use. Subversion checks the following things, in the order specified, when it wants to launch such an editor:
--editor-cmd
command-line option
SVN_EDITOR
environment variable
editor-cmd
runtime configuration option
VISUAL
environment variable
EDITOR
environment variable
Possibly, a fallback value built into the Subversion libraries (not present in the official builds)
The value of any of these options or variables is the beginning of a command line to be executed by the shell. Subversion appends to that command line a space and the pathname of a temporary file to be edited. So, to be used with Subversion, the configured or specified editor needs to support an invocation in which its last command-line parameter is a file to be edited, and it should be able to save the file in place and return a zero exit code to indicate success.
As noted, external editors can be used to provide commit log
messages to any of the committing subcommands (such as
svn commit or import,
svn mkdir or delete when
provided a URL target, etc.), and Subversion will try to
launch the editor automatically if you don't specify either of
the --message
(-m
) or
--file
(-F
) options. The
svn propedit command is built almost entirely
around the use of an external editor. And beginning in version
1.5, Subversion will also use the configured external text
editor when the user asks it to launch an editor during
interactive conflict resolution. Oddly, there doesn't appear to
be a way to use external editors to interactively provide lock
comments.