Tar

# Tar.create — Function

create(
    [ predicate, ] dir, [ tarball ];
    [ skeleton, ] [ portable = false ]
) -> tarball

    predicate :: String --> Bool
    dir       :: AbstractString
    tarball   :: Union{AbstractString, AbstractCmd, IO}
    skeleton  :: Union{AbstractString, AbstractCmd, IO}
    portable  :: Bool

Создает tar-архив (tarball) каталога dir. Результирующий архив записывается по пути tarball. Если путь не указан, создается временный путь, который возвращается при вызове функции. Если tarball является объектом ввода-вывода, содержимое tar-архива записывается в этот дескриптор (дескриптор остается открытым).

Если передана функция predicate, она вызывается для каждого системного пути, встречающемся при рекурсивном поиске dir, и path включается в tar-архив, только если predicate(path) имеет значение true. Если predicate(path) возвращает значение false для каталога, каталог полностью исключается: никакие объекты в этом каталоге не будут включены в архив.

Если передано ключевое слово skeleton, заданный файл или дескриптор ввода-вывода используется в качестве основы для создания tar-архива. Чтобы создать файл-основу, передайте ключевое слово skeleton команде extract. Если create вызывается с этим файлом-основой и извлеченные файлы не изменились, повторно создается аналогичный tar-архив. Аргументы skeleton и predicate нельзя использовать вместе.

Если флаг portable имеет значение true, имена путей проверяются на допустимость в Windows. Это позволяет гарантировать, что в них нет недопустимых символов и что не используются зарезервированные имена. Подробные сведения см. на странице https://stackoverflow.com/a/31976060/659248.

# Tar.extract — Function

extract(
    [ predicate, ] tarball, [ dir ];
    [ skeleton = <none>, ]
    [ copy_symlinks = <auto>, ]
    [ set_permissions = true, ]
) -> dir

    predicate       :: Header --> Bool
    tarball         :: Union{AbstractString, AbstractCmd, IO}
    dir             :: AbstractString
    skeleton        :: Union{AbstractString, AbstractCmd, IO}
    copy_symlinks   :: Bool
    set_permissions :: Bool

Извлекает tar-архив (tarball), расположенный по пути tarball, в каталог dir. Если tarball является объектом ввода-вывода, а не путем, содержимое архива будет считано из этого потока ввода-вывода. Архив извлекается в каталог (dir), который должен быть существующим пустым каталогом или несуществующим путем, который будет создан в качестве нового каталога. Если каталог (dir) не указан, архив извлекается во временный каталог, возвращаемый функцией extract.

Если передана функция predicate, она вызывается для каждого объекта Header, появляющегося при извлечении архива (tarball). Запись извлекается, только если predicate(hdr) имеет значение true. Это можно использовать для выборочного извлечения только частей архива, для пропуска записей, из-за которых функция extract вызывает ошибку, или для записи извлекаемого содержимого.

Перед передачей в предикативную функцию объект Header несколько изменяется по сравнению с исходным заголовком в tar-архиве: поле path нормализуется для удаления записей . и замены нескольких последовательных слэшей одним. Если запись имеет тип :hardlink, то целевой путь ссылки нормализуется таким же образом, чтобы он соответствовал пути к целевой записи; для поля размера задается размер целевого пути (который должен быть уже видимым файлом).

Если передано ключевое слово skeleton, основа извлеченного tar-архива записывается в заданный файл или дескриптор ввода-вывода. Этот файл-основу можно использовать для повторного создания идентичного tar-архива путем передачи ключевого слова skeleton функции create. Аргументы skeleton и predicate нельзя использовать вместе.

Если copy_symlinks имеет значение true, тогда вместо извлечения символьных ссылок как таковых они будут извлечены как копии того, на что они ссылаются, если они являются внутренними по отношению к tar-архиву и если это возможно. Не являющиеся внутренними символьные ссылки, такие как ссылка на /etc/passwd, скопированы не будут. Циклические символьные ссылки также не будут копироваться, а будут пропускаться. По умолчанию extract определит, можно ли создавать символьные ссылки в каталоге (dir), и автоматически скопирует символьные ссылки, если их нельзя создать.

Если set_permissions имеет значение false, разрешения для извлеченных файлов не заданы.

# Tar.list — Function

list(tarball; [ strict = true ]) -> Vector{Header}
list(callback, tarball; [ strict = true ])

    callback  :: Header, [ <data> ] --> Any
    tarball   :: Union{AbstractString, AbstractCmd, IO}
    strict    :: Bool

Перечисляет содержимое tar-архива (tarball), расположенного по пути tarball. Если tarball является дескриптором ввода-вывода, считывает содержимое архива из этого потока. Возвращает вектор структур Header. Дополнительные сведения см. в описании Header.

Если указан обратный вызов (callback), вместо возврата вектора заголовков обратный вызов вызывается для каждого заголовка (Header). Это может быть полезно, если количество элементов в tar-архиве велико или нужно исследовать элементы до ошибки в tar-архиве. Если функция callback может принимать второй аргумент типа Vector{UInt8} или Vector{Pair{Symbol, String}}, она будет вызвана с представлением необработанных данных заголовка либо в виде однобайтового вектора, либо в виде вектора пар, сопоставляющих имена полей с необработанными данными для этого поля (если эти поля объединяются, результатом являются необработанные данные заголовка).

По умолчанию list выдаст ошибку, если обнаружит содержимое tar-архива, которое функция extract откажется извлекать. При strict=false она пропустит эти проверки и перечислит все содержимое tar-файла, независимо от того, извлечет его функция extract или нет. Помните, что вредоносные tar-архивы предназначены для самых разных и неожиданных вещей и будут пытаться обманом заставить вас сделать что-то опасное.

Если аргумент tarball является файлом-основой (см. описание extract и create), list определит это по заголовку файла и соответствующим образом перечислит или выполнит итерацию заголовков файла-основы.

# Tar.rewrite — Function

rewrite(
    [ predicate, ] old_tarball, [ new_tarball ];
    [ portable = false, ]
) -> new_tarball

    predicate   :: Header --> Bool
    old_tarball :: Union{AbstractString, AbtractCmd, IO}
    new_tarball :: Union{AbstractString, AbtractCmd, IO}
    portable    :: Bool

Переписывает old_tarball в стандартный формат, который генерирует create, а также проверяет, что он не содержит ничего, что могло бы стать причиной, по которой extract выведет ошибку. Это функционально эквивалентно выполнению следующей операции.

Tar.create(Tar.extract(predicate, old_tarball), new_tarball)

Однако здесь ничего не извлекается на диск, а используется функция seek для перемещения по данным старого tar-архива. Если аргумент new_tarball не передан, новый tar-архив записывается во временный файл, путь которого возвращается.

Если передана функция predicate, она вызывается для каждого объекта Header, появляющегося при извлечении архива (old_tarball). Запись извлекается, только если predicate(hdr) имеет значение true. Это можно использовать для выборочного извлечения только частей архива, для пропуска записей, из-за которых функция extract вызывает ошибку, или для записи содержимого, которое встречается в процессе перезаписи.

# Tar.tree_hash — Function

tree_hash([ predicate, ] tarball;
          [ algorithm = "git-sha1", ]
          [ skip_empty = false ]) -> hash::String

    predicate  :: Header --> Bool
    tarball    :: Union{AbstractString, AbstractCmd, IO}
    algorithm  :: AbstractString
    skip_empty :: Bool

Вычисляет значение хэша дерева для дерева файлов, содержащегося в tar-архиве. По умолчанию здесь используется алгоритм хэширования gi с функцией защищенного хэша SHA1 (как в текущих версиях git). Это означает, что для любого tar-архива, дерево файлов которого может представить git (т. е. только с файлами, символьными ссылками и непустыми каталогами), значение хэша, вычисляемое этой функцией, будет аналогично значению, вычисляемому в git для этого дерева файлов. Обратите внимание, что tar-архивы могут представлять деревья файлов с пустыми каталогами, которые не могут храниться в git, а эта функция может создавать для них хэши, которые будут по умолчанию (см. описание skip_empty ниже об изменении этого поведения) отличаться от хэша tar-архива, который пропускает пустые каталоги. Короче говоря, хэш-функция соглашается с git в отношении всех деревьев, которые может представить git, но расширяет (согласованно) область хэшируемых деревьев на другие деревья, которые git не может представить.

Если передана функция predicate, она вызывается для каждого объекта Header, который встречается при обработке tarball, и запись хэшируется, только если predicate(hdr) имеет значение true. Это можно использовать для выборочного хэширования только частей архива, для пропуска записей, из-за которых функция extract вызывает ошибку, или для записи содержимого, извлекаемого во время процесса хэширования.

В настоящее время поддерживаются следующие значения для algorithm: git-sha1 (по умолчанию) и git-sha256, который использует тот же базовый алгоритм, что и git-sha1, но заменяет хэш-функцию SHA1 на SHA2-256 — хэш-функцию, на использование которой git перейдет в будущем (в связи с известными атаками на SHA1). В будущем может быть добавлена поддержка других алгоритмов хэширования деревьев файлов.

Параметр skip_empty управляет тем, будут ли каталоги в tar-архиве, рекурсивно не содержащие файлы или символьные ссылки, включены в хэш или проигнорированы. В общем случае, если вы хэшируете содержимое tar-архива или дерева файлов, вам важны все каталоги, а не только непустые, поэтому по умолчанию они включаются в вычисляемый хэш. Так почему же эта функция вообще предоставляет возможность пропускать пустые каталоги? Потому что git отказывается хранить пустые каталоги и будет игнорировать их, если вы попытаетесь добавить их в репозиторий. Таким образом, если вы вычисляете хэш дерева ссылок, добавляя файлы в репозиторий git, а затем запрашивая в git хэш дерева, то полученное значение хэша будет соответствовать значению хэша, вычисленному tree_hash с skip_empty=true. Другими словами, эта возможность позволяет функции tree_hash эмулировать способ, которым git будет хэшировать дерево с пустыми каталогами. Если вы хэшируете деревья, которые могут содержать пустые каталоги (т. е. их источник отличен от репозитория git), рекомендуется использовать средство (такое как это), которое не игнорирует пустые каталоги.

Тип Header — это структура, представляющая основные метаданные для одной записи в tar-файле с данным определением:

struct Header
    path :: String # путь относительно корня
    type :: Symbol # индикатор типа (см. ниже)
    mode :: UInt16 # режим/разрешения (лучше всего просматривать в восьмеричном формате)
    size :: Int64  # размер данных записи в байтах
    link :: String # целевой путь символьной ссылки
end

Типы представлены следующими символами: file, hardlink, symlink, chardev, blockdev, directory, fifo или для неизвестных типов — символом typeflag. Обратите внимание, что extract отказывается извлекать записи типов, отличных от file, symlink и directory. list будет перечислять только другие виды записей, если вызывается с условием strict=false.

Формат tar включает в себя различные другие метаданные о записях, в том числе идентификаторы пользователей и групп, имена пользователей и групп и метки времени. Пакет Tar их полностью игнорирует. При создании tar-файлов этим полям всегда задаются нулевые значения либо они остаются пустыми. При считывании tar-файлов эти поля игнорируются, за исключением проверки контрольных сумм заголовков для каждой записи заголовка на наличие всех полей.