Tar

create(
    [ prédicat, ] dir, [ tarball ];
    [ squelette, ] [ portable = false ]
) -> tarball

    prédicat :: String --> Bool
    dir       :: AbstractString
    tarball   :: Union{AbstractString, AbstractCmd, IO}
    squelette  :: Union{AbstractString, AbstractCmd, IO}
    portable  :: Bool

Créez une archive tar ("tarball") du répertoire dir. L'archive résultante est écrite à l'emplacement tarball ou, si aucun emplacement n'est spécifié, un emplacement temporaire est créé et renvoyé par l'appel de fonction. Si tarball est un objet IO, alors le contenu du tarball est écrit dans ce handle à la place (le handle reste ouvert).

Si une fonction prédicat est passée, elle est appelée sur chaque chemin système rencontré lors de la recherche récursive dans dir et path n'est inclus dans le tarball que si prédicat(path) est vrai. Si prédicat(path) renvoie faux pour un répertoire, alors le répertoire est entièrement exclu : rien sous ce répertoire ne sera inclus dans l'archive.

Si le mot-clé squelette est passé, alors le fichier ou le handle IO donné est utilisé comme "squelette" pour générer le tarball. Vous créez un fichier squelette en passant le mot-clé squelette à la commande extract. Si create est appelé avec ce fichier squelette et que les fichiers extraits n'ont pas changé, un tarball identique est recréé. Les arguments squelette et prédicat ne peuvent pas être utilisés ensemble.

Si le drapeau portable est vrai, alors les noms de chemin sont vérifiés pour leur validité sur Windows, ce qui garantit qu'ils ne contiennent pas de caractères illégaux ou n'ont pas de noms réservés. Voir https://stackoverflow.com/a/31976060/659248 pour plus de détails.

extract(
    [ prédicat, ] tarball, [ dir ];
    [ squelette = <aucun>, ]
    [ copier_liens_symboliques = <auto>, ]
    [ définir_permissions = true, ]
) -> dir

    prédicat        :: Header --> Bool
    tarball         :: Union{AbstractString, AbstractCmd, IO}
    dir             :: AbstractString
    squelette       :: Union{AbstractString, AbstractCmd, IO}
    copier_liens_symboliques :: Bool
    définir_permissions :: Bool

Extraire une archive tar ("tarball") située au chemin tarball dans le répertoire dir. Si tarball est un objet IO au lieu d'un chemin, alors le contenu de l'archive sera lu à partir de ce flux IO. L'archive est extraite dans dir, qui doit être soit un répertoire vide existant, soit un chemin inexistant qui peut être créé en tant que nouveau répertoire. Si dir n'est pas spécifié, l'archive est extraite dans un répertoire temporaire qui est renvoyé par extract.

Si une fonction prédicat est passée, elle est appelée sur chaque objet Header rencontré lors de l'extraction de tarball et l'entrée n'est extraite que si prédicat(hdr) est vrai. Cela peut être utilisé pour extraire sélectivement uniquement des parties d'une archive, pour ignorer des entrées qui provoquent une erreur lors de l'extraction, ou pour enregistrer ce qui est extrait pendant le processus d'extraction.

Avant d'être passée à la fonction prédicat, l'objet Header est quelque peu modifié par rapport à l'en-tête brut dans le tarball : le champ path est normalisé pour supprimer les entrées . et remplacer plusieurs barres obliques consécutives par une seule barre oblique. Si l'entrée a le type :hardlink, le chemin cible du lien est normalisé de la même manière afin qu'il corresponde au chemin de l'entrée cible ; le champ de taille est défini sur la taille du chemin cible (qui doit être un fichier déjà vu).

Si le mot-clé squelette est passé, alors un "squelette" du tarball extrait est écrit dans le fichier ou le handle IO donné. Ce fichier squelette peut être utilisé pour recréer un tarball identique en passant le mot-clé squelette à la fonction create. Les arguments squelette et prédicat ne peuvent pas être utilisés ensemble.

Si copier_liens_symboliques est true, alors au lieu d'extraire les liens symboliques tels quels, ils seront extraits comme des copies de ce à quoi ils se lient s'ils sont internes au tarball et si cela est possible. Les liens symboliques non internes, tels qu'un lien vers /etc/passwd, ne seront pas copiés. Les liens symboliques qui sont d'une manière ou d'une autre cycliques ne seront également pas copiés et seront plutôt ignorés. Par défaut, extract détectera si des liens symboliques peuvent être créés dans dir ou non et copiera automatiquement les liens symboliques s'ils ne peuvent pas être créés.

Si définir_permissions est false, aucune permission n'est définie sur les fichiers extraits.

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

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

Liste le contenu d'une archive tar ("tarball") située à l'emplacement tarball. Si tarball est un handle IO, lis le contenu tar à partir de ce flux. Renvoie un vecteur de structures Header. Voir Header pour plus de détails.

Si un callback est fourni, alors au lieu de renvoyer un vecteur d'en-têtes, le callback est appelé sur chaque Header. Cela peut être utile si le nombre d'éléments dans le tarball est important ou si vous souhaitez examiner les éléments avant une erreur dans le tarball. Si la fonction callback peut accepter un deuxième argument de type Vector{UInt8} ou Vector{Pair{Symbol, String}}, alors elle sera appelée avec une représentation des données d'en-tête brutes soit sous forme de vecteur d'octets unique, soit sous forme de vecteur de paires associant les noms de champs aux données brutes pour ce champ (si ces champs sont concaténés, le résultat est les données brutes de l'en-tête).

Par défaut, list renverra une erreur si elle rencontre des contenus de tarball que la fonction extract refuserait d'extraire. Avec strict=false, elle ignorera ces vérifications et listera tous les contenus du fichier tar, que extract les extraie ou non. Attention, les tarballs malveillants peuvent faire toutes sortes de choses astucieuses et inattendues pour essayer de vous tromper en faisant quelque chose de mauvais.

Si l'argument tarball est un fichier squelette (voir extract et create), alors list détectera cela à partir de l'en-tête du fichier et listera ou itérera de manière appropriée les en-têtes du fichier squelette.

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

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

Réécrit old_tarball au format standard que génère create, tout en vérifiant qu'il ne contient rien qui pourrait provoquer une erreur lors de l'extraction. Cela équivaut fonctionnellement à faire

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

Cependant, il n'extrait jamais rien sur le disque et utilise plutôt la fonction seek pour naviguer dans les données de l'ancien tarball. Si aucun argument new_tarball n'est passé, le nouveau tarball est écrit dans un fichier temporaire dont le chemin est retourné.

Si une fonction predicate est passée, elle est appelée sur chaque objet Header rencontré lors de l'extraction de old_tarball et l'entrée est ignorée à moins que predicate(hdr) ne soit vrai. Cela peut être utilisé pour réécrire sélectivement seulement certaines parties d'une archive, pour ignorer des entrées qui provoqueraient une erreur lors de l'extraction, ou pour enregistrer quel contenu est rencontré pendant le processus de réécriture.

Avant d'être passé à la fonction prédicat, l'objet Header est quelque peu modifié par rapport à l'en-tête brut dans le tarball : le champ path est normalisé pour supprimer les entrées . et remplacer plusieurs barres obliques consécutives par une seule barre oblique. Si l'entrée a le type :hardlink, le chemin de la cible du lien est normalisé de la même manière afin qu'il corresponde au chemin de l'entrée cible ; le champ de taille est défini sur la taille du chemin cible (qui doit être un fichier déjà vu).

Si le drapeau portable est vrai, alors les noms de chemin sont vérifiés pour leur validité sur Windows, ce qui garantit qu'ils ne contiennent pas de caractères illégaux ou n'ont pas de noms réservés. Voir https://stackoverflow.com/a/31976060/659248 pour plus de détails.

tree_hash([ prédicat, ] tarball;
          [ algorithme = "git-sha1", ]
          [ ignorer_vide = false ]) -> hash::String

    prédicat  :: Header --> Bool
    tarball    :: Union{AbstractString, AbstractCmd, IO}
    algorithme  :: AbstractString
    ignorer_vide :: Bool

Calculez une valeur de hachage d'arbre pour l'arborescence de fichiers que contient le tarball. Par défaut, cela utilise l'algorithme de hachage d'arbre de git avec la fonction de hachage sécurisée SHA1 (comme les versions actuelles de git). Cela signifie que pour tout tarball dont l'arborescence de fichiers peut être représentée par git—c'est-à-dire un tarball contenant uniquement des fichiers, des liens symboliques et des répertoires non vides—la valeur de hachage calculée par cette fonction sera la même que la valeur de hachage que git calculerait pour cette arborescence de fichiers. Notez que les tarballs peuvent représenter des arborescences de fichiers avec des répertoires vides, que git ne peut pas stocker, et cette fonction peut générer des hachages pour ceux-ci, qui, par défaut (voir ignorer_vide ci-dessous pour savoir comment changer ce comportement), différeront du hachage d'un tarball qui omet ces répertoires vides. En résumé, la fonction de hachage est d'accord avec git sur tous les arbres que git peut représenter, mais étend (de manière cohérente) le domaine des arbres hachables à d'autres arbres que git ne peut pas représenter.

Si une fonction prédicat est passée, elle est appelée sur chaque objet Header rencontré lors du traitement du tarball et une entrée n'est hachée que si prédicat(hdr) est vrai. Cela peut être utilisé pour hacher sélectivement uniquement certaines parties d'une archive, pour ignorer des entrées qui provoquent une erreur lors de l'extraction, ou pour enregistrer ce qui est extrait pendant le processus de hachage.

Avant d'être passée à la fonction prédicat, l'objet Header est quelque peu modifié par rapport à l'en-tête brut dans le tarball : le champ path est normalisé pour supprimer les entrées . et remplacer plusieurs barres obliques consécutives par une seule barre oblique. Si l'entrée a le type :hardlink, le chemin de la cible du lien est normalisé de la même manière afin qu'il corresponde au chemin de l'entrée cible ; le champ de taille est défini sur la taille du chemin cible (qui doit être un fichier déjà vu).

Les valeurs actuellement prises en charge pour algorithme sont git-sha1 (la valeur par défaut) et git-sha256, qui utilise le même algorithme de base que git-sha1 mais remplace la fonction de hachage SHA1 par SHA2-256, la fonction de hachage que git utilisera à l'avenir (en raison des attaques connues sur SHA1). Le support d'autres algorithmes de hachage d'arborescence de fichiers peut être ajouté à l'avenir.

L'option ignorer_vide contrôle si les répertoires dans le tarball qui ne contiennent récursivement aucun fichier ou lien symbolique sont inclus dans le hachage ou ignorés. En général, si vous hachez le contenu d'un tarball ou d'une arborescence de fichiers, vous vous souciez de tous les répertoires, pas seulement des non vides, donc les inclure dans le hachage calculé est la valeur par défaut. Alors pourquoi cette fonction fournit-elle même l'option d'ignorer les répertoires vides ? Parce que git refuse de stocker des répertoires vides et les ignorera si vous essayez de les ajouter à un dépôt. Donc, si vous calculez un hachage d'arbre de référence en ajoutant des fichiers à un dépôt git et en demandant ensuite à git le hachage d'arbre, la valeur de hachage que vous obtenez correspondra à la valeur de hachage calculée par tree_hash avec ignorer_vide=true. En d'autres termes, cette option permet à tree_hash d'imiter la façon dont git hacherait un arbre avec des répertoires vides. Si vous hachez des arbres qui peuvent contenir des répertoires vides (c'est-à-dire qui ne proviennent pas d'un dépôt git), il est cependant recommandé de les hacher à l'aide d'un outil (comme celui-ci) qui n'ignore pas les répertoires vides.

Le type Header est une structure représentant les métadonnées essentielles pour un seul enregistrement dans un fichier tar avec cette définition :

struct Header
    path :: String # chemin relatif à la racine
    type :: Symbol # indicateur de type (voir ci-dessous)
    mode :: UInt16 # mode/permissions (mieux visualisé en octal)
    size :: Int64  # taille des données de l'enregistrement en octets
    link :: String # chemin cible d'un lien symbolique
end

Les types sont représentés par les symboles suivants : file, hardlink, symlink, chardev, blockdev, directory, fifo, ou pour les types inconnus, le caractère typeflag en tant que symbole. Notez que extract refuse d'extraire des types d'enregistrements autres que file, symlink et directory ; list ne listera d'autres types d'enregistrements que si appelé avec strict=false.

Le format tar inclut diverses autres métadonnées sur les enregistrements, y compris les identifiants d'utilisateur et de groupe, les noms d'utilisateur et de groupe, et les horodatages. Le package Tar, par conception, ignore complètement ces champs. Lors de la création de fichiers tar, ces champs sont toujours définis sur zéro/vide. Lors de la lecture de fichiers tar, ces champs sont ignorés à l'exception de la vérification des sommes de contrôle des en-têtes pour chaque enregistrement d'en-tête pour tous les champs.