Tar モジュールは、tar アーカイブを扱うためのシンプルなインターフェースを提供します。アーカイブの作成、アーカイブからの選択したファイルの展開、メタデータへのアクセスが可能です。
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ディレクトリ dir の tar アーカイブ(「tarball」)を作成します。作成したアーカイブはパス tarball に書き込まれます。パスが指定されていない場合は、一時パスが作成され、関数呼び出しによって返されます。tarball が IO オブジェクトの場合は、代わりにそのハンドルへ tarball の内容を書き込みます(ハンドルは開いたままにします)。
predicate 関数が渡された場合、dir を再帰的に検索する際に見つかった各システムパスに対してその関数を呼び出します。path は、predicate(path) が true の場合にのみ tarball に含まれます。ディレクトリに対して predicate(path) が false を返すと、そのディレクトリは完全に除外され、配下の内容もアーカイブに含まれません。
skeleton キーワードを渡すと、指定したファイルまたは IO ハンドルを「スケルトン」として使用し、tarball を生成します。extract コマンドに skeleton キーワードを渡すと、スケルトンファイルを作成できます。そのスケルトンファイルを使って create を呼び出し、展開したファイルに変更がなければ、同一の tarball が再作成されます。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パス tarball にある tar アーカイブ(「tarball」)を、ディレクトリ dir に展開します。tarball がパスではなく IO オブジェクトの場合、アーカイブの内容はその IO ストリームから読み込まれます。アーカイブは dir に展開されます。このディレクトリは、既存の空ディレクトリか、新しいディレクトリとして作成可能な未作成のパスでなければなりません。dir が指定されていない場合、アーカイブは一時ディレクトリに展開され、そのディレクトリが extract によって返されます。
predicate 関数が渡された場合、アーカイブ tarball の展開中に見つかった各 Header オブジェクトに対してその関数が呼び出され、predicate(hdr) が true の場合にのみ、そのエントリが展開されます。これにより、アーカイブの一部だけを選択して展開したり、extract がエラーをスローするエントリをスキップしたり、展開中に何が展開されたかを記録したりできます。
述語関数に渡される前に、Header オブジェクトは tarball 内の生のヘッダーから多少変更されます。path フィールドは、. エントリを取り除き、連続する複数のスラッシュを単一のスラッシュに置き換えるよう正規化されます。エントリの型が :hardlink の場合、リンク先のパスも同様に正規化され、対象エントリのパスと一致するようになります。また、size フィールドにはリンク先のパスのサイズが設定されます(対象となるファイルは、すでに読み込まれている必要があります)。
skeleton キーワードを渡すと、展開した tarball の「スケルトン」が、指定されたファイルまたは IO ハンドルに書き込まれます。このスケルトンファイルは、create 関数に skeleton キーワードを渡すことで、同一の tarball を再作成するために使用できます。skeleton と predicate の引数は同時に使用できません。
copy_symlinks が true の場合、シンボリックリンクはそのままではなく、tarball 内部を指しており、かつ可能であれば、リンク先のコピーとして展開されます。/etc/passwd へのリンクなど、tarball 内部を指していないシンボリックリンクはコピーされません。循環を含むシンボリックリンクもコピーされず、スキップされます。デフォルトでは、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パス tarball にある tar アーカイブ(「tarball」)の内容を一覧表示します。tarball が IO ハンドルの場合は、そのストリームから tar の内容を読み取ります。Header 構造体のベクトルを返します。詳細は Header を参照してください。
callback が指定されている場合、ヘッダーのベクトルを返す代わりに、各 Header に対してコールバックが呼び出されます。tarball 内の項目数が多い場合や、エラーが発生する前の項目を調べたい場合に便利です。callback 関数が、型 Vector{UInt8} または Vector{Pair{Symbol, String}} のいずれかの第 2 引数を受け取れる場合、その引数には生のヘッダーデータを表す値が渡されます。これは、単一のバイトベクトル、またはフィールド名とそのフィールドの生データを対応付けたペアのベクトルです(これらのフィールドを連結すると、ヘッダーの生データになります)。
デフォルトでは、list は、extract 関数が展開を拒否する tarball の内容に遭遇するとエラーになります。strict=false を指定すると、これらのチェックを省略し、extract が展開するかどうかにかかわらず、tar ファイルの内容をすべて一覧表示します。悪意のある tarball は、危険な操作をさせようと、巧妙で予期しないさまざまな手口を使うことがあるため注意してください。
tarball 引数がスケルトンファイル(extract および create を参照)の場合、list はファイルヘッダーからそれを判別し、スケルトンファイルのヘッダーを適切に一覧表示または反復処理します。
Tar.rewrite — Function
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 :: Boolold_tarball を create が生成する標準形式に書き換えます。同時に、extract でエラーを引き起こす内容が含まれていないことも確認します。これは機能的には次の処理と同等です。
Tar.create(Tar.extract(predicate, old_tarball), new_tarball)ただし、ディスクへの展開は一切行わず、代わりに seek 関数を使って元の tarball 内のデータをたどります。new_tarball 引数を渡さなかった場合、新しい tarball は一時ファイルに書き込まれ、そのパスが返されます。
predicate 関数を渡した場合、old_tarball の展開中に見つかった各 Header オブジェクトに対してその関数が呼び出され、predicate(hdr) が true でない限り、そのエントリはスキップされます。これにより、アーカイブの一部だけを選択的に書き換えたり、extract でエラーを引き起こすエントリをスキップしたり、書き換え処理中に見つかった内容を記録したりできます。
述語関数に渡される前に、Header オブジェクトには tarball 内の生のヘッダーからいくつかの変更が加えられます。path フィールドは正規化され、. の要素が取り除かれ、連続する複数のスラッシュが単一のスラッシュに置き換えられます。エントリの型が :hardlink の場合、リンク先のパスも同様に正規化され、リンク先エントリのパスと一致するようになります。また、サイズフィールドにはリンク先のパスが指すファイルのサイズが設定されます。このファイルは、それまでに処理済みでなければなりません。
portable フラグが true の場合、パス名が Windows で有効かどうかを検査し、使用できない文字が含まれていないことや、予約された名前が使われていないことを確認します。詳細は https://stackoverflow.com/a/31976060/659248 を参照してください。
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 :: Booltarball に含まれるファイルツリーのツリーハッシュ値を計算します。デフォルトでは、git のツリーハッシュアルゴリズムと SHA1 暗号学的ハッシュ関数(現在の git のバージョンと同様)を使用します。つまり、git が表現できるファイルツリー(ファイル、シンボリックリンク、空でないディレクトリのみを含むツリー)であれば、この関数が計算するハッシュ値は、git がそのファイルツリーに対して計算するハッシュ値と一致します。tarball では空のディレクトリを含むファイルツリーも表現できますが、git は空のディレクトリを保存できません。この関数は空のディレクトリを含むツリーのハッシュも生成できますが、デフォルトでは(この動作を変更する方法については下記の skip_empty を参照)、空のディレクトリを省いた tarball のハッシュとは異なります。つまり、このハッシュ関数は git が表現できるすべてのツリーについて git と同じ結果を返しつつ、git では表現できないツリーにも一貫した方法でハッシュ可能な範囲を広げています。
predicate 関数が渡された場合、tarball の処理中に見つかった各 Header オブジェクトに対してその関数が呼び出され、predicate(hdr) が true の場合に限り、そのエントリがハッシュ化されます。これにより、アーカイブの一部だけを選択してハッシュ化したり、extract がエラーをスローするエントリをスキップしたり、ハッシュ計算中に展開された内容を記録したりできます。
述語関数に渡される前に、Header オブジェクトには tarball の生のヘッダーからいくつか変更が加えられます。path フィールドは、. エントリを取り除き、連続する複数のスラッシュを単一のスラッシュに置き換える形で正規化されます。エントリの型が :hardlink の場合は、リンク先のエントリのパスと一致するよう、リンク先パスも同じ方法で正規化されます。また、サイズフィールドにはリンク先パスのサイズが設定されます(リンク先は、すでに確認済みのファイルでなければなりません)。
現在、algorithm に指定できる値は git-sha1(デフォルト)と git-sha256 です。後者は git-sha1 と同じ基本アルゴリズムを使いますが、SHA1 ハッシュ関数を SHA2-256 に置き換えます。SHA2-256 は、SHA1 に対する既知の攻撃を受けて、将来 git が採用する予定のハッシュ関数です。今後、ほかのファイルツリーハッシュアルゴリズムもサポートされる可能性があります。
skip_empty オプションは、tarball 内にある、ファイルもシンボリックリンクも再帰的に含まないディレクトリをハッシュに含めるか、無視するかを制御します。一般に、tarball やファイルツリーの内容をハッシュ化する場合、空でないディレクトリだけでなく、すべてのディレクトリが対象となるため、デフォルトでは空のディレクトリもハッシュに含めます。それでは、なぜこの関数には空のディレクトリをスキップするオプションがあるのでしょうか。git は空のディレクトリを保存せず、リポジトリに追加しようとしても無視するためです。そのため、ファイルを git リポジトリに追加してから git にツリーハッシュを問い合わせて参照用のツリーハッシュを計算すると、得られるハッシュ値は、tree_hash に skip_empty=true を指定した場合に計算されるハッシュ値と一致します。つまり、このオプションを使うと、tree_hash は空のディレクトリを含むツリーに対する git のハッシュ計算を再現できます。ただし、空のディレクトリを含む可能性のあるツリー(つまり、git リポジトリ由来ではないツリー)をハッシュ化する場合は、空のディレクトリを無視しないツール(このツールなど)を使うことをおすすめします。
Tar.Header — Type
Header 型は、tar ファイル内の単一レコードに関する基本的なメタデータを表す構造体で、次のように定義されています。
struct Header
path :: String # path relative to the root
type :: Symbol # type indicator (see below)
mode :: UInt16 # mode/permissions (best viewed in octal)
size :: Int64 # size of record data in bytes
link :: String # target path of a symlink
end型は次のシンボルで表されます: file、hardlink、symlink、chardev、blockdev、directory、fifo。不明な型の場合は、typeflag の文字をシンボルとして使用します。extract は、file、symlink、directory 以外のレコード型の展開を拒否します。また、list は、strict=false を指定して呼び出した場合に限り、その他の種類のレコードを一覧表示します。
tar 形式には、ユーザー ID とグループ ID、ユーザー名とグループ名、タイムスタンプなど、レコードに関するさまざまなメタデータも含まれています。Tar パッケージは、設計上、これらを完全に無視します。tar ファイルを作成する際、これらのフィールドは常にゼロまたは空に設定されます。tar ファイルを読み込む際は、各ヘッダーレコードのすべてのフィールドについてヘッダーのチェックサムを検証する場合を除き、これらのフィールドは無視されます。