asciidoc/use/cachefileset.adoc

////
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     https://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
////

[*__since 1.2__*]

Constructs an Ant `fileset` consisting of artifacts in Ivy's cache for a configuration.

This is a link:../use/postresolvetask{outfilesuffix}[post resolve task], with all the behaviour and attributes common to all post resolve tasks. Note that this task
does not rely on retrieve, because the built fileset is made of artifacts directly in Ivy's cache.

Please prefer the use of retrieve + standard Ant path creation, which make your build more independent from Ivy (once artifacts are properly retrieved, Ivy is not required any more).

Built `fileset` is registered in Ant project with a given id, and can thus be used like any other Ant `fileset` using
`refid`.

== Limitation

A `fileset`, in Ant project, requires a base directory from within which the files are included/excluded. The `cachefileset` task, in Ivy, internally tries to determine a common base directory across all the resolved artifact files that have been downloaded in the Ivy repository cache(s). Given that Ivy can be configured to use multiple repository caches and each one can potentially be on a different filesystem root, there are times, when `cachefileset` cannot determine a common base directory for these resolved artifacts. The `cachefileset` throws an exception in such cases.

== Alternative task

If `cachefileset` doesn't fit the need of your use case (maybe due to the limitations noted above), the link:../use/resources{outfilesuffix}[resources] task could be an alternative task to use in certain cases.

== Attributes

[options="header",cols="15%,50%,35%"]
|=======
|Attribute|Description|Required
|setid|the id to reference the built fileset|Yes
|conf|a comma separated list of the configurations to put in the created path|No. Defaults to the configurations resolved by the last resolve call, or `*` if no resolve was explicitly called
|type|comma separated list of artifact types to accept in the path, `*` for all|No. Defaults to `*`
|settingsRef|(*__since 2.0__*) A reference to Ivy settings that must be used by this task|No, `ivy.instance` is taken by default.
|=======