asciidoc/settings/caches.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.
////

= caches

*Tag:* caches

[*__since 2.0__*]

[ivysettings.caches]#Configures the Ivy cache system.#

See link:../concept{outfilesuffix}#cache[cache concept] for details on the Ivy cache concept.

By default, Ivy defines one repository cache instance, called `default-cache`, which uses the default cache settings defined using attributes on this tag. This default instance is defined as long as you don't define your own default cache using the `default` attribute, and have at least one dependency resolver which doesn't specify which cache instance to use.

`defaultCacheDir` is the default directory used for both the resolution and repository cache(s). It usually points to a directory in your filesystem. If you want to isolate resolution cache from repository cache, we recommend setting both the `resolutionCacheDir` and `repositoryCacheDir` attributes on this tag instead of using `defaultCacheDir`.

Since repository cache implementations are pluggable, you can either define new cache instances based on the default implementation provided in Ivy using the link:../settings/caches/cache{outfilesuffix}[cache] child element, or use custom cache implementations using child elements as you have defined using link:../settings/typedef{outfilesuffix}[typedef].

`ivyPattern` and `artifactPattern` are used to configure the default way Ivy stores Ivy files and artifacts in repository cache(s). Usually you do not have to change this, unless you want to use the cache directly from another tool, which is not recommended. These patterns are relative to the repository cache base directory.

`checkUpToDate` indicates to Ivy if it must check date of artifacts before retrieving them (i.e. copying them from cache to another place in your filesystem). Usually it is a good thing to check date to avoid unnecessary copy, even if it's most of the time a local copy.


== Attributes


[options="header",cols="15%,50%,35%"]
|=======
|Attribute|Description|Required
|default|the name of the default cache to use on all resolvers not defining the cache instance to use|No, defaults to a default cache manager instance named 'default-cache'
|defaultCacheDir|a path to a directory to use as default basedir for both resolution and repository cache(s)|No, defaults to .ivy2/cache in the user's home directory
|resolutionCacheDir|the path of the directory to use for all resolution cache data|No, defaults to defaultCacheDir
|repositoryCacheDir|the path of the default directory to use for repository cache data. *This should not point to a directory used as a repository!*|No, defaults to defaultCacheDir
|ivyPattern|default pattern used to indicate where Ivy files should be put in the repository cache(s)|No, defaults to [organisation]/[module]/ivy-[revision].xml
|artifactPattern|default pattern used to indicate where artifact files should be put in the repository cache(s)|No, defaults to [organisation]/[module]/[type]s/[artifact]-[revision].[ext]
|[line-through]#checkUpToDate#|__Deprecated, we recommend using overwriteMode on the link:../use/retrieve{outfilesuffix}[retrieve] task instead.__ Indicates if date should be checked before retrieving artifacts from cache.|No, defaults to true
|useOrigin|the default value to use for useOrigin for caches in which it isn't specifically defined. Use true to avoid the copy of local artifacts to the cache and use directly their original location.|No, defaults to false
|lockStrategy|the name of the default link:../settings/lock-strategies{outfilesuffix}[lock strategy] to use when accessing repository cache(s)|No, defaults to _no-lock_
|=======


== Child elements


[options="header"]
|=======
|Element|Description|Cardinality
|link:caches/cache{outfilesuffix}[cache]|defines a new repository cache instance, based on the default repository cache implementation|0..n
|=======


== Examples


[source, xml]
----

<caches>
  <cache name="mycache" basedir="path/to/my/cache/1"/>
  <cache name="mycache2" basedir="path/to/my/cache/2"/>
</caches>

----

Define 2 cache instances, named mycache and mycache2, using two different directories as base directory, and using the default patterns and lock strategies. The default cache instance will still be defined as long as at least one dependency resolver does not declare which cache manager to use.

'''