Mapping Files

Tasks like package, packageSrc, and packageDoc accept mappings of
type Seq[(File, String)] from an input file to the path to use in the
resulting artifact (jar). Similarly, tasks that copy files accept
mappings of type Seq[(File, File)] from an input file to the
destination file. There are some methods on
PathFinder and
Path that can be useful for constructing
the Seq[(File, String)] or Seq[(File, File)] sequences.

A common way of making this sequence is to start with a PathFinder or
Seq[File] (which is implicitly convertible to PathFinder) and then
call the pair method. See the
PathFinder API for details, but
essentially this method accepts a function File => Option[String] or
File => Option[File] that is used to generate mappings.

Relative to a directory

The Path.relativeTo method is used to map a File to its path
String relative to a base directory or directories. The relativeTo
method accepts a base directory or sequence of base directories to
relativize an input file against. The first directory that is an
ancestor of the file is used in the case of a sequence of base
directories.

Rebase

The Path.rebase method relativizes an input file against one or more
base directories (the first argument) and then prepends a base String or
File (the second argument) to the result. As with relativeTo, the
first base directory that is an ancestor of the input file is used in
the case of multiple base directories.

For example, the following demonstrates building a Seq[(File, String)]
using rebase:

Flatten

The Path.flat method provides a function that maps a file to the last
component of the path (its name). For a File to File mapping, the input
file is mapped to a file with the same name in a given target directory.
For example:

Alternatives

To try to apply several alternative mappings for a file, use |, which
is implicitly added to a function of type A => Option[B]. For example,
to try to relativize a file against some base directories but fall back
to flattening: