B.4 ApplyTask
Prev | Appendix B. Core tasks | Next

## B.4 ApplyTask

Applies a system command on each resource of the specified resource collection.

When the os attribute is specified, then the command is only executed when run on one of the specified operating systems.

The files of a number of Resource Collections – including but not restricted to FileSets or FileLists – are passed as arguments to the system command.

Table B.4: Attributes

Name | Type | Description | Default | Required | Alias
--- | --- | --- | --- | --- | ---
`executable` | `String` | The command to execute without any command line arguments. | n/a | Yes |
`dir` | `String` | The directory the command is to be executed in. | n/a | No |
`output` | `String` | Where to direct stdout. | n/a | No |
`error` | `String` | Where to direct stderr. | n/a | No |
`os` | `String` | Only execute if the Appendix A, Fact Sheet property contains specified text. | n/a | No |
`escape` | `Boolean` | Escape shell metacharacters before execution. Setting this to true will enable the escape precaution. | `false` | No |
`passthru` | `Boolean` | Whether to use PHP's passthru() function instead of exec(). | `false` | No |
`spawn` | `Boolean` | Whether to spawn unix programs to the background, redirecting stdout. | `false` | No |
`returnProperty` | `String` | Property name to set return value to from the execution. | n/a | No |
`outputProperty` | `String` | Property name to set output value to from the execution. | n/a | No |
`checkreturn` | `Boolean` | Whether to check the return code of the execution, throws a BuildException when returncode != 0. | `false` | No | failonerror
`append` | `Boolean` | Whether output (and error) should be appended to or overwrite an existing file. If you set parallel to false, you will probably want to set this one to true. | `false` | No |
`parallel` | `Boolean` | Run the command only once, appending all files as arguments. If false, command will be executed once for every file. | `false` | No |
`addsourcefile` | `Boolean` | Whether source file name(s) should be added to the end of command-line automatically. If you need to place it somewhere different, use a nested <srcfile> element between your <arg> elements to mark the insertion point. | `true` | No |
`spawn` | `Boolean` | Whether the command(s) to be executed are spawned as background process. If a command is spawned, its output will not be logged by Phing. | `false` | No |
`relative` | `Boolean` | Whether the filenames should be passed on the command line as relative pathnames (relative to the base directory of the corresponding fileset/list for source files). | `false` | No |
`forwardslash` | `Boolean` | Whether the file names should be passed with forward slashes even if the operating system requires other file separator. | `false` | No |
`maxparallel` | `Boolean` | Limit the amount of parallelism by passing at most this many sourcefiles at once. Set it to <= 0 for unlimited. | `false` | No |

### B.4.1 Examples

    <!-- Invokes somecommand arg1 SOURCEFILENAME arg2 for each file in /tmp -->
    <apply executable="somecommand" parallel="false">
      <arg value="arg1"/>
      <srcfile/>
      <arg value="arg2"/>
      <fileset dir="/tmp"/>
    </apply>

    <!-- List all the .conf files of "/etc" to the "out.log" file. -->
    <apply executable="ls" output="/tmp/out.log" append="true" >
      <arg value="-alh" />
      <fileset dir="/etc" >
        <include name="*.conf" />
      </fileset>
    </apply>

### B.4.2 Supported Nested Tags

- `arg`

  Table B.5: Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  `value` | `String` | A single command-line argument; can contain space characters. | n/a | One of these
  `file` | `String` | The name of a file as a single command-line argument; will be replaced with the absolute filename of the file. | n/a
  `path` | `String` | A string that will be treated as a path-like string as a single command-line argument; you can use ; or : as path separators and Phing will convert it to the platform's local conventions. | n/a
  `line` | `String` | A space-delimited list of command-line arguments. | n/a

- `fileset`

- `filelist`

- `srcfile`

Prev | Up | Next
B.3 AppendTask | Home | B.5 AvailableTask