Tar

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

Crea un archivo tar ("tarball") del directorio dir. El archivo resultante se escribe en la ruta tarball o, si no se especifica ninguna ruta, se crea una ruta temporal y se devuelve mediante la llamada a la función. Si tarball es un objeto IO, entonces el contenido del tarball se escribe en ese manejador en su lugar (el manejador permanece abierto).

Si se pasa una función predicate, se llama a esta en cada ruta del sistema que se encuentra al buscar recursivamente en dir y path solo se incluye en el tarball si predicate(path) es verdadero. Si predicate(path) devuelve falso para un directorio, entonces el directorio se excluye por completo: nada bajo ese directorio se incluirá en el archivo.

Si se pasa la palabra clave skeleton, entonces el archivo o manejador IO dado se utiliza como un "esqueleto" para generar el tarball. Creas un archivo esqueleto pasando la palabra clave skeleton al comando extract. Si se llama a create con ese archivo esqueleto y los archivos extraídos no han cambiado, se recrea un tarball idéntico. Los argumentos skeleton y predicate no se pueden usar juntos.

Si la bandera portable es verdadera, entonces se verifica la validez de los nombres de ruta en Windows, lo que asegura que no contengan caracteres ilegales o tengan nombres que estén reservados. Consulta https://stackoverflow.com/a/31976060/659248 para más detalles.

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

Extrae un archivo tar ("tarball") ubicado en la ruta tarball en el directorio dir. Si tarball es un objeto IO en lugar de una ruta, entonces el contenido del archivo se leerá desde ese flujo IO. El archivo se extrae en dir, que debe ser un directorio vacío existente o una ruta no existente que se puede crear como un nuevo directorio. Si dir no se especifica, el archivo se extrae en un directorio temporal que es devuelto por extract.

Si se pasa una función predicate, se llama a esta en cada objeto Header que se encuentra al extraer tarball y la entrada solo se extrae si predicate(hdr) es verdadero. Esto se puede usar para extraer selectivamente solo partes de un archivo, para omitir entradas que causen que extract lance un error, o para registrar lo que se extrae durante el proceso de extracción.

Antes de ser pasado a la función predicate, el objeto Header se modifica un poco respecto al encabezado en bruto en el tarball: el campo path se normaliza para eliminar entradas . y reemplazar múltiples barras consecutivas con una sola barra. Si la entrada tiene tipo :hardlink, la ruta del objetivo del enlace se normaliza de la misma manera para que coincida con la ruta de la entrada objetivo; el campo de tamaño se establece en el tamaño de la ruta objetivo (que debe ser un archivo ya visto).

Si se pasa la palabra clave skeleton, entonces un "esqueleto" del tarball extraído se escribe en el archivo o manejador IO dado. Este archivo esqueleto se puede usar para recrear un tarball idéntico pasando la palabra clave skeleton a la función create. Los argumentos skeleton y predicate no se pueden usar juntos.

Si copy_symlinks es true, en lugar de extraer enlaces simbólicos como tales, se extraerán como copias de lo que enlazan si son internos al tarball y si es posible hacerlo. Los symlinks no internos, como un enlace a /etc/passwd, no se copiarán. Los symlinks que son de alguna manera cíclicos tampoco se copiarán y se omitirán. Por defecto, extract detectará si se pueden crear symlinks en dir o no y copiará automáticamente los symlinks si no se pueden crear.

Si set_permissions es false, no se establecen permisos en los archivos extraídos.

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

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

Lista el contenido de un archivo tar ("tarball") ubicado en la ruta tarball. Si tarball es un manejador de IO, lee el contenido del tar desde ese flujo. Devuelve un vector de estructuras Header. Consulta Header para más detalles.

Si se proporciona un callback, en lugar de devolver un vector de encabezados, se llama al callback en cada Header. Esto puede ser útil si el número de elementos en el tarball es grande o si deseas examinar elementos antes de un error en el tarball. Si la función callback puede aceptar un segundo argumento de tipo Vector{UInt8} o Vector{Pair{Symbol, String}}, entonces se llamará con una representación de los datos del encabezado en bruto, ya sea como un único vector de bytes o como un vector de pares que mapean nombres de campo a los datos en bruto para ese campo (si estos campos están concatenados, el resultado es los datos en bruto del encabezado).

Por defecto, list generará un error si encuentra algún contenido del tarball que la función extract se negaría a extraer. Con strict=false, omitirá estas verificaciones y listará todo el contenido del archivo tar, ya sea que extract los extraiga o no. Ten cuidado, ya que los tarballs maliciosos pueden hacer todo tipo de cosas astutas e inesperadas para intentar engañarte y hacer algo malo.

Si el argumento tarball es un archivo esqueleto (consulta extract y create), entonces list detectará eso a partir del encabezado del archivo y listará o iterará apropiadamente los encabezados del archivo esqueleto.

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

Reescribe old_tarball al formato estándar que genera create, mientras también verifica que no contenga nada que cause que extract genere un error. Esto es funcionalmente equivalente a hacer

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

Sin embargo, nunca extrae nada en el disco y en su lugar utiliza la función seek para navegar por los datos del antiguo tarball. Si no se pasa un argumento new_tarball, el nuevo tarball se escribe en un archivo temporal cuyo camino se devuelve.

Si se pasa una función predicate, se llama a esta en cada objeto Header que se encuentra al extraer old_tarball y la entrada se omite a menos que predicate(hdr) sea verdadero. Esto se puede usar para reescribir selectivamente solo partes de un archivo, para omitir entradas que causarían que extract lanzara un error, o para registrar qué contenido se encuentra durante el proceso de reescritura.

Antes de ser pasado a la función predicate, el objeto Header se modifica un poco del encabezado en bruto en el tarball: el campo path se normaliza para eliminar entradas . y reemplazar múltiples barras consecutivas con una sola barra. Si la entrada tiene tipo :hardlink, la ruta del objetivo del enlace se normaliza de la misma manera para que coincida con la ruta de la entrada objetivo; el campo de tamaño se establece en el tamaño de la ruta objetivo (que debe ser un archivo ya visto).

Si la bandera portable es verdadera, entonces los nombres de las rutas se verifican para su validez en Windows, lo que asegura que no contengan caracteres ilegales o tengan nombres que estén reservados. Consulta https://stackoverflow.com/a/31976060/659248 para más detalles.

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

Calcula un valor de hash de árbol para el árbol de archivos que contiene el tarball. Por defecto, esto utiliza el algoritmo de hash de árbol de git con la función de hash segura SHA1 (como las versiones actuales de git). Esto significa que para cualquier tarball cuyo árbol de archivos git pueda representar—es decir, uno que contenga solo archivos, enlaces simbólicos y directorios no vacíos—el valor de hash calculado por esta función será el mismo que el valor de hash que git calcularía para ese árbol de archivos. Ten en cuenta que los tarballs pueden representar árboles de archivos con directorios vacíos, que git no puede almacenar, y esta función puede generar hashes para esos, que, por defecto (ver skip_empty a continuación para cómo cambiar este comportamiento), diferirán del hash de un tarball que omite esos directorios vacíos. En resumen, la función de hash coincide con git en todos los árboles que git puede representar, pero extiende (de manera consistente) el dominio de árboles hashables a otros árboles que git no puede representar.

Si se pasa una función predicate, se llama a esta en cada objeto Header que se encuentra al procesar tarball y una entrada solo se hashará si predicate(hdr) es verdadero. Esto se puede usar para hashear selectivamente solo partes de un archivo, para omitir entradas que causen que extract lance un error, o para registrar lo que se extrae durante el proceso de hashing.

Antes de ser pasada a la función predicate, el objeto Header se modifica un poco del encabezado en bruto en el tarball: el campo path se normaliza para eliminar entradas . y reemplazar múltiples barras diagonales consecutivas con una sola barra diagonal. Si la entrada tiene tipo :hardlink, la ruta del objetivo del enlace se normaliza de la misma manera para que coincida con la ruta de la entrada objetivo; el campo de tamaño se establece en el tamaño de la ruta objetivo (que debe ser un archivo ya visto).

Los valores actualmente soportados para algorithm son git-sha1 (el predeterminado) y git-sha256, que utiliza el mismo algoritmo básico que git-sha1 pero reemplaza la función de hash SHA1 con SHA2-256, la función de hash que git comenzará a usar en el futuro (debido a ataques conocidos en SHA1). El soporte para otros algoritmos de hash de árboles de archivos puede ser agregado en el futuro.

La opción skip_empty controla si los directorios en el tarball que no contienen recursivamente archivos o enlaces simbólicos se incluyen en el hash o se ignoran. En general, si estás hashando el contenido de un tarball o un árbol de archivos, te importan todos los directorios, no solo los no vacíos, por lo que incluir estos en el hash calculado es el valor predeterminado. Entonces, ¿por qué esta función incluso proporciona la opción de omitir directorios vacíos? Porque git se niega a almacenar directorios vacíos y los ignorará si intentas agregarlos a un repositorio. Así que si calculas un hash de árbol de referencia al agregar archivos a un repositorio git y luego le pides a git el hash de árbol, el valor de hash que obtienes coincidirá con el valor de hash calculado por tree_hash con skip_empty=true. En otras palabras, esta opción permite que tree_hash emule cómo git hasharía un árbol con directorios vacíos. Sin embargo, si estás hashando árboles que pueden contener directorios vacíos (es decir, que no provienen de un repositorio git), se recomienda que los hashes utilizando una herramienta (como esta) que no ignore los directorios vacíos.

El tipo Header es una estructura que representa los metadatos esenciales para un solo registro en un archivo tar con la siguiente definición:

struct Header
    path :: String # ruta relativa a la raíz
    type :: Symbol # indicador de tipo (ver abajo)
    mode :: UInt16 # modo/permisos (mejor visto en octal)
    size :: Int64  # tamaño de los datos del registro en bytes
    link :: String # ruta de destino de un enlace simbólico
end

Los tipos se representan con los siguientes símbolos: file, hardlink, symlink, chardev, blockdev, directory, fifo, o para tipos desconocidos, el carácter typeflag como símbolo. Tenga en cuenta que extract se niega a extraer tipos de registros que no sean file, symlink y directory; list solo enumerará otros tipos de registros si se llama con strict=false.

El formato tar incluye varios metadatos adicionales sobre los registros, incluidos los ID de usuario y grupo, los nombres de usuario y grupo, y las marcas de tiempo. El paquete Tar, por diseño, ignora completamente estos. Al crear archivos tar, estos campos siempre se establecen en cero/vacío. Al leer archivos tar, estos campos se ignoran aparte de verificar las sumas de verificación de los encabezados para cada registro de encabezado para todos los campos.