Manages symbolic links on platforms where Java supports symbolic links. Can be used to make an individual link, delete a link, create multiple links from properties files, or create properties files describing links in the specified directories. Existing files are not overwritten by default.

FileSets are used to select a set of links to record, or a set of property files to create links from.


Attribute Description Required
action The type of action to perform, may be single, "record, recreate or delete. No; defaults to single
link The name of the link to be created or deleted.
Note: this attribute is resolved against the current working directory rather than the project's basedir for historical reasons. It is recommended you always use an absolute path or a path like ${basedir}/some-path as its value.
Yes, for action=single or delete; ignored in other actions
resource The resource the link should point to. Yes, for action=single; ignored in other actions
linkfilename The name of the properties file to create in each included directory. Yes, for action=record; ignored in other actions
overwrite Overwrite existing files or not. If overwrite is set to true, then any existing file, specified by the link attribute, will be overwritten irrespective of whether or not the existing file is a symbolic link. No; defaults to false
failonerror Stop build if true, log a warning message, but do not stop the build, when the an error occurs if false. No; defaults to true

Parameters specified as nested elements


FileSets are used when action=record to select directories and link names to be recorded. They are also used when action=recreate to specify both the name of the property files to be processed, and the directories in which they can be found. At least one fileset is required for each case.


Make a link named foo to a resource named in subdir:

<symlink link="${}/foo" resource="${}/subdir/"/>

Record all links in subdir and it's descendants in files named dir.links

<symlink action="record" linkfilename="dir.links">
    <fileset dir="${}" includes="subdir/**"/>

Recreate the links recorded in the previous example:

<symlink action="recreate">
    <fileset dir="${}" includes="subdir/**/dir.links"/>

Delete a link named foo:

<symlink action="delete" link="${}/foo"/>

Java 1.2 and earlier: Due to limitations on executing system level commands in Java versions earlier than 1.3 this task may have difficulty operating with a relative path in ANT_HOME. The typical symptom is an IOException where Apache Ant can't find /some/working/directory${ANT_HOME}/bin/antRun or something similar. The workaround is to change your ANT_HOME environment variable to an absolute path, which will remove the /some/working/directory portion of the above path and allow Ant to find the correct command line execution script.

Note: Since Ant 1.10.2, this task relies on the symbolic link support introduced in Java 7 through the java.nio.file.Files APIs