# `ImagePipe.Source.File`
[🔗](https://github.com/hlindset/image_pipe/blob/v0.2.0/image_pipe/lib/image_pipe/source/file.ex#L1)

Source adapter for image files below a directory.

    media: [
      adapter: ImagePipe.Source.File,
      match: :path,
      options: [root: "/srv/images", root_id: "media"]
    ]

It resolves path sources, so `photos/beach.jpg` and `/photos/beach.jpg` both
read `/srv/images/photos/beach.jpg`. Paths can't leave the root. A path that
names no regular file is not found. Setting up a mount is covered in
[Serving images from local files](serving-local-files.md).

A file that isn't `stable: :immutable` is identified by the SHA-256 of its
bytes. After hashing, its size, mtime, ctime, inode, and device are kept,
and a later request whose stat matches reuses the hash without reading the
file. Stat times have one-second resolution, so a file whose mtime or ctime
falls in the second it was hashed is hashed again on the next request. On
a network filesystem the times come from the server's clock.

## Options

* `:root` (`t:String.t/0`) - Required. Directory the source serves. A relative path is expanded against the working directory when the configuration is built.

* `:root_id` (`t:String.t/0`) - Required. Stable name for the directory. Caches identify the source's files by `:root_id` and path instead of by `:root`, so keep the name when the directory moves, and change it when the directory holds different files. File sources with the same `:root_id` share cache entries and must have the same `:root`.

* `:verify` (`:stat` or `:hash`) - How a file that can change is checked. `:stat` reuses the file's hash while its size, timestamps, inode, and device are unchanged. `:hash` reads and hashes the file on every check, for filesystems whose times can't be trusted, such as a network filesystem whose server clock can lag behind this host's. The default value is `:stat`.

* `:copy` (`:none` or `:keep`) - `:keep` stores a copy of each original in the [originals cache](cache.md#originals-cache), so other sizes and formats don't read the file again. Use it on network filesystems such as EFS or NFS. Needs `:input_cache` configured. The default value is `:none`.

* `:stable` (`:auto` or `:immutable`) - `:immutable` marks an immutable source: an identifier always names the same bytes, so its originals and processed images never expire and are never revalidated. With `:auto`, each original is identified by its content. See [immutable sources](caching-and-freshness.md#immutable-sources). The default value is `:auto`.

* `:cache_policy` (`t:keyword/0`) - Cache policy for this source, with the fields of `ImagePipe.Source.CachePolicy`. Each field it sets replaces that field of the `:source_cache_policy` of `ImagePipe.config/1`. A source with `stable: :immutable` can't set a `:freshness` duration or a `:stale_while_revalidate` window. The default value is `[]`.

* `:internal_cache` (`:enabled` or `:disabled`) - `:disabled` keeps this source's originals and processed images out of the caches, including images that use this source for a watermark. `:enabled` caches what the source's storage policy allows. The default value is `:enabled`.

* `:http_cache` (`:inherit`, `:validators`, `:auto`, `:public`, or `:private`) - HTTP cache headers for responses from this source. `:inherit` uses the mount's `:http_cache` (see `ImagePipe.Plug`), and any other value replaces it. See [per-source modes](cdn-http-cache.md#per-source-modes). The default value is `:inherit`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*