Hyrum K. Wright wrote:
> Yesterday, I posted a patch which allowed the 'svn status' command to
> accept the '--targets' argument. This was a follow up to Julian's
> suggestion that all commands which accept an arbitrary number of targets
> should use this switch [1]. I've done a little bit more research, and
> the following patch addresses all such commands (including 'svn status').
Excellent - thanks for working on this.
> Add support for the '--targets' switch to 'list', 'mkdir', 'propdel',
> 'propedit', 'propget', 'proplist', 'status', and 'update'.
Looking at the array of commands, I can see several more that take a variable
number of targets: blame, cat, checkout, cleanup, diff, switch --relocate.
I've investigated and had a think, and come up with a proposal.
SUPPORTING THE "--targets" OPTION
The "--targets" option is currently described in the on-line help as "pass
contents of file ARG as additional args", and in the book as "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."
In practice, where implemented so far, the additional targets are added on to
the end of the list of command-line arguments.
When a command takes a variable number of arguments that are all "targets",
this use of "--targets" is simple and uncontroversial. These commands are:
/ add
blame
cat
cleanup
/ commit
/ delete
diff (syntax 1 and 2)
/ info
list
/ lock
mkdir
proplist (syntax 1: without --revprop)
/ resolved
/ revert
status
/ unlock
update
("/" indicates that "--targets" is already supported.)
Some commands also take one or more "fixed" arguments that have a different
meaning from the arguments in the arbitrary-length list, inferred (at least in
part) from their position. These commands are currently:
checkout URL... [PATH]
/ log URL [PATH...] (syntax 2)
propdel PROP [PATH...] (syntax 1: without --revprop)
propedit PROP PATH... (syntax 1: without --revprop)
propget PROP [TARGET...] (syntax 1: without --revprop)
/ propset PROPNAME PROPVAL PATH... (syntax 1: without --revprop)
switch --relocate FROM TO [PATH...] (syntax 2)
In this case, I propose that "--targets" should be allowed to provide only the
variable-length, homogeneous list of targets, and never a fixed argument, even
if it could be described as a "target". We should try to enforce this because
we would otherwise be providing a general-purpose "additional arguments"
option, not an "additional targets" option.
Special cases:
* When a fixed argument appears after the variable-length list, as in "checkout
URL... [PATH]" and possibly, in the future, commands like "copy SRC... DST",
the additional targets should be inserted at the end of the variable-length
list, not after all of the command-line arguments.
* A "target" in this context means something like a path or URL referring to a
(potentially) version-controlled item, perhaps augmented by things such as
"@REV". This "--targets" option should not be used to provide other types of
argument, such as in "svn help [SUBCOMMAND...]".
* Some commands have both forms that do and forms that don't allow an arbitrary
number of targets, including "diff URL URL" (syntax 3) and "switch" (syntax 1).
In these cases, strictly we ought to check that the "--targets" option is
absent in the forms where it is not appropriate, but we may well accept that in
practice it is sufficient to check that the number of extra targets is zero.
Description:
In the on-line help I would change "args" to "targets" so that it reads "pass
contents of file ARG as additional targets". For the book, I suggest the
following paragraph:
When a command accepts an arbitrary-length list of targets on which to operate,
identified by "..." in the syntax description, the "--targets" option causes
Subversion to operate on the targets listed in the specified file after any
that are listed directly on the command line. This applies only to a single
list of targets; any other arguments required (or optional) for the command
must be specified on the command line. When the syntax description requires at
least one target, this refers to the combination of command-line arguments and
those read from the "--targets" file, so a target need not appear on the
command line. The file contains one target per line, with blank lines and
leading and trailing whitespace ignored, embedded whitespace retained, and no
escaping mechanism, in the native character encoding. The "--targets" option
can only be used once.
Existing Bugs:
* If multiple "--targets" options are given, all but the last are silently ignored.
* The exising support in "log" and "propset" may allow arguments other than the
main list of targets to come from the "--targets" file. (Not verified.)
> * subversion/svn/main.c:
> (svn_cl__cmd_table): Add svn_cl__targets_opt to commands which take
> an arbitrary number of targets.
Wow - I didn't realise that was all that is required. A quick look indicates
that code to make use of these extra targets is basically already present in
the commands that you tackled. Early in their operation, they combine the list
of explicit arguments with the list provided by "--targets". I haven't looked
carefully to check whether they use that combined list exclusively thereafter;
have you?
Would you be prepared to review this proposal and, if you like it, expand your
work on this further, so that we can announce full support for the "--targets"
option in all commands where it makes sense?
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Apr 25 18:16:00 2006