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 there are other pieces of
information besides merely versioned file data that 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—multi-line, free-form log
message editing on demand.
Subversion supports this by allowing you to specify an external text editor which it will launch as necessary in order 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, in order 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, and so on), 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.