Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

fetch-archive

Declares one archive downloaded and unpacked at a destination where nothing is.

[[actions]]
type = "fetch-archive"
id = "fzf"
source = "https://example.com/fzf-0.65.2.tar.gz"
dest = "~/.local/fzf"
archive-root = "*"
FieldTypeRequiredDescription
sourcetemplate stringyesAn http://, https://, or file:// URL. Not a repository path.
desttemplate stringyesWhere the unpacked directory goes, exactly. Never empty; ~ is the home.
sha256template stringno64 hexadecimal digits: the digest the fetched archive must have.
archive-rootstringnoA prefix every entry is written without, spelled as an entry path is, or * for the archive’s single top-level directory.
includeglob or listnoEntries to unpack, by their path once the root is stripped; absent, every entry. See entry filters.
excludeglob or listnoEntries not to unpack.
executableglob or listnoFiles to make executable, by their path once the root is stripped.

The shared transfer supplies the archive. The seed policy installs one whole directory: an occupied dest, including one an earlier create-dir made, causes no request. Refresh replaces the whole tree. Extraction follows archive safety, permissions, and staged publication.

Formats are detected from leading bytes:

FormatSupport
TarPlain, gzip, or bzip2; concatenated compressed streams; V7, ustar, GNU, and pax
ZipStored, deflated, or bzip2 entries; no encryption or other compression methods

Plain tar is recognized by its first header’s checksum. Zip must begin with an entry or an empty central-directory ending; self-extracting prefixes are not supported. Unsupported bodies fail with the detected format, such as xz or zstd. Zip names use UTF-8 when flagged or valid, otherwise code page 437; backslashes in names are refused. Unix modes determine zip symlink and permission metadata.

archive-root strips a prefix. "*" requires a single top-level directory and strips it; multiple roots fail naming them. An explicit prefix installs only entries beneath it. A prefix with nothing beneath it fails. Prefixes follow entry-path syntax: absolute paths and .. are load errors.

Filters and executable match paths after root stripping:

[[actions]]
type = "fetch-archive"
source = "https://example.com/tool.tar.gz"
dest = "~/.local/tool"
archive-root = "*"
include = ["bin", "lib"]
exclude = "**/*.md"
executable = ["bin", "lib/*.so"]

Directories needed to hold selected entries retain their archive modes. Selecting nothing, or selecting a hard link whose target is excluded, fails. Filters do not relax archive safety. Unmatched patterns are reported at -v only when extraction runs, never during a dry run.

executable adds owner, group, and other execute bits to matched files and files beneath matched directories, regardless of archive modes. It does not change directories, symlinks, or excluded files; hard links share their target’s mode. A pattern marking no file is reported at -v. It has no effect on Windows.

See common action fields for id, group, and conditions.