Argument files

Command lines can become very long when multiple options are specified. To keep your command lines short and avoid any potential issues with terminals that don't support very long command lines, you can make use of argument files to define your optional arguments:

• Create an argument file and specify this on the dcover create command line using [@<argumentFile>...] - see Argument files below.

• Use an .args file which is applied to commands by default - see Default argument files below.

Argument files

Arguments can be defined in a plain text file with an arbitrary name, e.g. myargs.txt. This file can then be passed to dcover create by adding the option @myargs.txt.

For example: dcover create @myargs.txt

Arguments passed in this way can be added to the file - one per line or separated by a space on the same line. Comments can also be added.

Example file:

--verbose --batch
--patch-only=C:\Users\MyUserName\myproject\patch.diff
# We don't want to create tests for this class (this is a comment).
--exclude=a.class.i.want.ToIgnore.

PowerShell

If you're using the argument files feature with PowerShell, typically on Windows, you may experience the following error:

The splatting operator '@' cannot be used to reference variables in an expression.

In this case make sure that you quote the config argument file to stop PowerShell from trying to interpret the @ symbol.

For example: dcover create '@myargs.txt'

Default argument files

If you have a certain set of arguments that you frequently use across all commands, you can add them to the plain text files in the following location of your project instead of using the @ notation on the command line:

• .diffblue/common.args

This will allow you to run common arguments across all commands, without having to repeatedly specify them on the command line.

If you have a certain set of specific arguments that you want to use for certain commands, you can add them to the plain text files in the following .diffblue directory of your project instead of using the @ notation on the command line.

For example:

• .diffblue/create.args for dcover create arguments,

• .diffblue/clean.args for dcover clean arguments, or

• .diffblue/build.args for dcover build arguments.

These files are command-specific, so any arguments added to .diffblue/create.args will only affect the dcover create command. Without these files under .diffblue, all desired arguments will have to be specified when running the relevant command.

As with the "standard" argument files detailed above, arguments passed using default argument files can be added one per line or separated by a space on the same line. Comments can also be added.

Example file:

--verbose --batch --maven
# Always use this class name for tests written by Diffblue Cover (this is a comment).
--class-name-template=${CLASS_NAME}AItests

Conflicts & overrides

In general, you should avoid conflicts between command line and argument file options, but note the following:

• Command line options take priority and will override options specified within argument files.

• Options defined in argument files specified on the command line using the @ annotation will override options specified within default argument files (.args files).

• If the same option is set in different places, precedence is given in the following order:

  • direct arguments to the CLI

  • args files for the command

  • common args file

  • system properties

  • environment variables

  • Diffblue properties file

• The --maven and --gradle options are mutually exclusive and cannot be overridden. If you add these parameters to your argument files, you will need to temporarily remove the option to specify a different value.

• To override arguments, you can either specify an alternative <value> (for arguments that require a value) or set the argument to true / false as needed.

For example of overriding, assume the args file contains the following:

--verbose --batch
--patch-only=C:\Users\MyUserName\myproject\patch.diff
# We don't want to create tests for this class (this is a comment).
--exclude=a.class.i.want.ToIgnore.

then the verbose option and patch file can be overridden by the following on the command line (the remaining options would be unchanged and be applied as normal):

dcover create @myargs.txt --verbose=false --patch-only=C:\myjavaproject\patch.diff