[PATCH] Make several commands use the '--targets' switch

["Hyrum K. Wright" <hy...@mail.utexas.edu>]

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').

-Hyrum

[1] http://svn.haxx.se/dev/archive-2006-04/0696.shtml

[[[
Add support for the '--targets' switch to 'list', 'mkdir', 'propdel',
'propedit', 'propget', 'proplist', 'status', and 'update'.

* subversion/svn/main.c:
  (svn_cl__cmd_table):  Add svn_cl__targets_opt to commands which take
  an arbitrary number of targets.
]]]

Re: [PATCH] Make several commands use the '--targets' switch

["Peter N. Lundblad" <pe...@famlundblad.se>]

Julian Foad writes:
 > I've investigated and had a think, and come up with a proposal.
 > 

I think this proposal makes sense.

Thanks,
//Peter

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [PATCH] Make several commands use the '--targets' switch

[Julian Foad <ju...@btopenworld.com>]

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