asciidoc/resolver/filesystem.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.
////

= Filesystem resolver

[]
|=======
|Tag|filesystem
|Handle latest|yes
|Handle publish|yes
|=======


[ivysettings.resolvers.filesystem]#This resolver uses the file system to resolve Ivy files and artifacts.# An advantage of this resolver is that it usually provides very good performance. Moreover, it is easy to setup using basic OS file sharing mechanisms.

The configuration of such a resolver is mainly done through Ivy and artifact patterns, indicating where Ivy files and artifacts can be found in the file system. These patterns must be absolute paths (*__since 2.0__*). You can indicate a list of patterns which will be checked one after the other.

(*__since 1.3__*) Using the `m2compatible` attribute, this resolver will convert dots found in organisation into slashes like Maven 2 does for groupId. For instance, it will transform the organisation from `com.company` into `com/company` when replacing the token `[organisation]` in your pattern.

*Limitation*: in `m2compatible` mode, this resolver is not able list available organizations. It means some features like link:../use/repreport{outfilesuffix}[repreport] are not available.


== Atomic publish support

[*__since 2.0__*]

This resolver supports atomic publish, which is useful for environments with a lot of concurrent publish and resolve actions. The atomic publish relies on the atomicity of the rename operation in the underlying filesystem (which includes NTFS and POSIX based filesystems).
In this case the resolver starts by publishing the module according to the pattern, but where a `.part` suffix is appended to the revision. Then the publish is committed with a rename to the final location.

*Limitations*
Atomic publish is currently limited in several ways:

    * you need to use a pattern for both the artifact and the Ivy files which uses the revision as a directory. For instance, `${repository.dir}/[module]/[revision]/[artifact].[ext]` works, `${repository.dir}/[module]/[artifact]-[revision].[ext]` doesn't +

    * both the artifact and Ivy pattern should have the same prefix until the `[revision]` token. +

    * overwrite during publish is not supported +

    * you should not use revision names ending with `.part` +

The `*transactional*` attribute can be used to configure the atomicity behavior:

    * auto +
     use transaction if possible (according to limitation), otherwise don't

    * true +
     always use transaction, fail the build if a limitation is not fulfilled

    * false +
     don't use transaction at all

== Attributes

This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common attributes] of standard resolvers.

[options="header",cols="15%,50%,35%"]
|=======
|Attribute|Description|Required
|m2compatible|True if this resolver should be Maven 2 compatible, false otherwise (*__since 1.3__*)|No, defaults to false
|local|True if this resolver should be considered local, false otherwise (*__since 1.4__*). See useOrigin attribute on the link:../settings/caches{outfilesuffix}[caches] element for details.|No, defaults to true
|transactional|true to force the use of transaction, false to prevent the use of transaction, auto to get transaction when possible (*__since 2.0__*). See above for details.|No, defaults to auto
|=======


== Child elements


[options="header"]
|=======
|Element|Description|Cardinality
|ivy|defines a pattern for Ivy files, using the pattern attribute|0..n
|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
|=======