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

dir dizininde bir tar arşivi ("tarball") oluşturun. Ortaya çıkan arşiv, tarball yoluna yazılır veya eğer bir yol belirtilmemişse, geçici bir yol oluşturulur ve fonksiyon çağrısı ile döndürülür. Eğer tarball bir IO nesnesi ise, tarball içeriği o handle'a yazılır (handle açık kalır).

Bir predicate fonksiyonu geçilirse, bu fonksiyon dir içinde özyinelemeli olarak arama yapılırken karşılaşılan her sistem yolu üzerinde çağrılır ve yalnızca predicate(path) doğruysa path tarball'a dahil edilir. Eğer predicate(path) bir dizin için yanlış dönerse, o dizin tamamen hariç tutulur: o dizin altındaki hiçbir şey arşive dahil edilmez.

skeleton anahtarı geçilirse, verilen dosya veya IO handle, tarball oluşturmak için bir "iskelet" olarak kullanılır. Bir iskelet dosyası oluşturmak için extract komutuna skeleton anahtarını geçersiniz. Eğer create o iskelet dosyası ile çağrılırsa ve çıkarılan dosyalar değişmemişse, aynı tarball yeniden oluşturulur. skeleton ve predicate argümanları birlikte kullanılamaz.

portable bayrağı doğruysa, yol adları Windows'ta geçerlilik açısından kontrol edilir; bu, geçersiz karakterler içermediğinden veya rezerve edilmiş adlar olmadığından emin olur. Ayrıntılar için https://stackoverflow.com/a/31976060/659248 adresine bakın.

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

Bir tar arşivini ("tarball") tarball yolunda bulunan dizine dir çıkartın. Eğer tarball bir IO nesnesi ise, arşiv içeriği bu IO akışından okunacaktır. Arşiv, mevcut boş bir dizine veya yeni bir dizin olarak oluşturulabilecek var olmayan bir yola dir çıkartılır. Eğer dir belirtilmemişse, arşiv geçici bir dizine çıkartılır ve bu dizin extract tarafından döndürülür.

Eğer bir predicate fonksiyonu geçilmişse, bu fonksiyon tarball çıkarılırken karşılaşılan her Header nesnesi üzerinde çağrılır ve yalnızca predicate(hdr) doğruysa giriş çıkarılır. Bu, yalnızca bir arşivin belirli kısımlarını seçerek çıkartmak, extract'in hata fırlatmasına neden olan girişleri atlamak veya çıkarma işlemi sırasında neyin çıkarıldığını kaydetmek için kullanılabilir.

Header nesnesi, arşivdeki ham başlıktan biraz değiştirilerek geçilir: path alanı, . girişlerini kaldırmak ve birden fazla ardışık eğik çizgiyi tek bir eğik çizgi ile değiştirmek için normalize edilir. Giriş :hardlink türündeyse, bağlantı hedef yolu aynı şekilde normalize edilir, böylece hedef girişin yolu ile eşleşir; boyut alanı, hedef yolun boyutuna (zaten görülmüş bir dosya olmalıdır) ayarlanır.

Eğer skeleton anahtarı geçilmişse, çıkarılan tarball'ın bir "iskeleti" verilen dosyaya veya IO tutucusuna yazılır. Bu iskelet dosyası, create fonksiyonuna skeleton anahtarını geçerek özdeş bir tarball'ı yeniden oluşturmak için kullanılabilir. skeleton ve predicate argümanları birlikte kullanılamaz.

Eğer copy_symlinks true ise, sembolik bağlantılar olduğu gibi çıkarılmak yerine, iç tarball'a aitlerse ve bunu yapmak mümkünse, bağlantıların gösterdiği şeylerin kopyaları olarak çıkarılacaktır. /etc/passwd gibi iç olmayan sembolik bağlantılar kopyalanmayacaktır. Herhangi bir şekilde döngüsel olan sembolik bağlantılar da kopyalanmayacak ve bunun yerine atlanacaktır. Varsayılan olarak, extract, dir içinde sembolik bağlantıların oluşturulup oluşturulamayacağını tespit eder ve eğer oluşturulamazlarsa otomatik olarak sembolik bağlantıları kopyalar.

Eğer set_permissions false ise, çıkarılan dosyalar üzerinde hiçbir izin ayarlanmaz.

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

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

Bir tar arşivinin ("tarball") içeriğini tarball yolunda bulunan bir arşivden listeleyin. Eğer tarball bir IO handle ise, tar içeriğini o akıştan okuyun. Bir Header yapılarının vektörünü döndürür. Ayrıntılar için Header bakın.

Eğer bir callback sağlanmışsa, o zaman başlıkların bir vektörünü döndürmek yerine, her Header üzerinde callback çağrılır. Bu, tarball'daki öğe sayısı büyükse veya bir hata öncesinde öğeleri incelemek istiyorsanız yararlı olabilir. Eğer callback fonksiyonu ikinci bir argüman olarak Vector{UInt8} veya Vector{Pair{Symbol, String}} türlerinden birini kabul edebiliyorsa, o zaman bu, alan adlarını o alanın ham verisi ile eşleyen çiftlerin vektörü veya tek bir bayt vektörü olarak ham başlık verisinin bir temsili ile çağrılacaktır (eğer bu alanlar bir araya getirilirse, sonuç başlığın ham verisidir).

Varsayılan olarak list, extract fonksiyonunun çıkarmayı reddedeceği herhangi bir tarball içeriği ile karşılaşırsa hata verecektir. strict=false ile bu kontrolleri atlayacak ve extract bunları çıkarır mı çıkarmaz mı bakılmaksızın tar dosyasının tüm içeriğini listeleyecektir. Kötü niyetli tarball'ların sizi kötü bir şey yapmaya ikna etmek için her türlü kurnaz ve beklenmedik şey yapabileceğini unutmayın.

Eğer tarball argümanı bir iskelet dosyası ise (bkz. extract ve create), o zaman list dosya başlığından bunu tespit edecek ve iskelet dosyasının başlıklarını uygun şekilde listeleyecek veya yineleyecektir.

rewrite(
    [ predicate, ] eski_tarball, [ yeni_tarball ];
    [ taşınabilir = false, ]
) -> yeni_tarball

    predicate   :: Header --> Bool
    eski_tarball :: Union{AbstractString, AbstractCmd, IO}
    yeni_tarball :: Union{AbstractString, AbstractCmd, IO}
    taşınabilir    :: Bool

eski_tarball'ı create'in ürettiği standart formata yeniden yazarken, extract'in hata vermesine neden olabilecek herhangi bir şey içermediğinden emin olun. Bu, işlevsel olarak şuna eşdeğerdir:

Tar.create(Tar.extract(predicate, eski_tarball), yeni_tarball)

Ancak, hiçbir şeyi diske çıkarmadan, bunun yerine eski_tarball'ın verilerinde gezinmek için seek fonksiyonunu kullanır. Eğer bir yeni_tarball argümanı geçilmezse, yeni tarball geçici bir dosyaya yazılır ve bu dosyanın yolu döndürülür.

Eğer bir predicate fonksiyonu geçilirse, bu fonksiyon eski_tarball'ı çıkarırken karşılaşılan her Header nesnesi üzerinde çağrılır ve giriş, predicate(hdr) doğru olmadığı sürece atlanır. Bu, yalnızca bir arşivin belirli kısımlarını yeniden yazmak, extract'in hata vermesine neden olacak girişleri atlamak veya yeniden yazma sürecinde karşılaşılan içeriği kaydetmek için kullanılabilir.

predicate fonksiyonuna geçilmeden önce, Header nesnesi tarball'daki ham başlıktan biraz değiştirilir: path alanı, . girişlerini kaldıracak şekilde normalize edilir ve birden fazla ardışık eğik çizgi tek bir eğik çizgi ile değiştirilir. Eğer girişin türü :hardlink ise, bağlantı hedef yolu aynı şekilde normalize edilir, böylece hedef girişin yolu ile eşleşir; boyut alanı, hedef yolun boyutuna (bu, daha önce görülmüş bir dosya olmalıdır) ayarlanır.

Eğer taşınabilir bayrağı doğruysa, o zaman yol adları Windows'ta geçerlilik açısından kontrol edilir, bu da bunların yasaklı karakterler içermediğinden veya rezerve edilmiş adlar olmadığından emin olur. Detaylar için bkz. https://stackoverflow.com/a/31976060/659248.

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

Bir tarball'ın içerdiği dosya ağacı için bir ağaç hash değeri hesaplayın. Varsayılan olarak, bu, git'in ağaç hashleme algoritmasını ve SHA1 güvenli hash fonksiyonunu kullanır (mevcut git sürümleri gibi). Bu, git'in temsil edebileceği herhangi bir tarball için—yani yalnızca dosyalar, sembolik bağlantılar ve boş olmayan dizinler içeren bir tarball için—bu işlev tarafından hesaplanan hash değerinin, o dosya ağacı için git'in hesaplayacağı hash değeriyle aynı olacağı anlamına gelir. Tarball'ların, git'in depolayamayacağı boş dizinler içeren dosya ağaçlarını temsil edebileceğini unutmayın ve bu işlev, varsayılan olarak (aşağıda skip_empty'e bakın, bu davranışı nasıl değiştireceğiniz hakkında), bu boş dizinleri hariç tutan bir tarball'ın hash'inden farklı olacak hash'ler üretebilir. Kısacası, hash fonksiyonu, git'in temsil edebileceği tüm ağaçlarla git ile aynı fikirde, ancak git'in temsil edemediği diğer ağaçlar için hashlenebilir ağaçların alanını (tutarlı bir şekilde) genişletir.

Bir predicate işlevi geçildiğinde, bu işlev, tarball işlenirken karşılaşılan her Header nesnesi üzerinde çağrılır ve yalnızca predicate(hdr) doğruysa bir giriş hashlenir. Bu, bir arşivin yalnızca belirli kısımlarını seçerek hashlemek, extract'in bir hata fırlatmasına neden olan girişleri atlamak veya hashleme sürecinde neyin çıkarıldığını kaydetmek için kullanılabilir.

Header nesnesi, predicate işlevine geçilmeden önce, tarball'daki ham başlıktan biraz değiştirilmiştir: path alanı, . girişlerini kaldıracak şekilde normalize edilir ve birden fazla ardışık eğik çizgi, tek bir eğik çizgi ile değiştirilir. Girişin türü :hardlink ise, bağlantı hedef yolu aynı şekilde normalize edilir, böylece hedef girişin yolu ile eşleşir; boyut alanı, hedef yolun boyutuna (zaten görülmüş bir dosya olmalıdır) ayarlanır.

Şu anda desteklenen algorithm değerleri git-sha1 (varsayılan) ve git-sha256'dır; bu, git-sha1 ile aynı temel algoritmayı kullanır, ancak SHA1 hash fonksiyonunu SHA2-256 ile değiştirir; bu, git'in gelecekte kullanmaya geçeceği hash fonksiyonudur (SHA1 üzerindeki bilinen saldırılar nedeniyle). Gelecekte diğer dosya ağacı hashleme algoritmaları için destek eklenebilir.

skip_empty seçeneği, tarball'daki dosya veya sembolik bağlantı içermeyen dizinlerin hash'e dahil edilip edilmeyeceğini veya göz ardı edilip edilmeyeceğini kontrol eder. Genel olarak, bir tarball'ın içeriğini veya bir dosya ağacını hashliyorsanız, tüm dizinlerle ilgilenirsiniz, yalnızca boş olmayanlarla değil, bu nedenle bunların hesaplanan hash'e dahil edilmesi varsayılandır. Peki, bu işlev neden boş dizinleri atlama seçeneği sunuyor? Çünkü git, boş dizinleri depolamayı reddeder ve bunları bir repo'ya eklemeye çalıştığınızda göz ardı eder. Bu nedenle, bir git repo'suna dosyalar ekleyerek bir referans ağaç hash'i hesapladığınızda ve ardından git'ten ağaç hash'ini istediğinizde, elde ettiğiniz hash değeri, skip_empty=true ile tree_hash tarafından hesaplanan hash değeriyle eşleşecektir. Diğer bir deyişle, bu seçenek, tree_hash'ın boş dizinlere sahip bir ağacı nasıl hashleyeceğini taklit etmesine olanak tanır. Ancak, boş dizinler içerebilecek ağaçları hashliyorsanız (yani bir git repo'sundan gelmiyorlarsa), bunları boş dizinleri göz ardı etmeyen bir araç (bu gibi) kullanarak hashlemeniz önerilir.

Header türü, bir tar dosyasındaki tek bir kaydın temel meta verilerini temsil eden bir yapıdır ve tanımı şu şekildedir:

struct Header
    path :: String # kök ile ilgili yol
    type :: Symbol # tür göstergesi (aşağıya bakınız)
    mode :: UInt16 # mod/izinler (en iyi sekizli olarak görüntülenir)
    size :: Int64  # kayıt verisinin boyutu bayt cinsinden
    link :: String # bir sembolik bağlantının hedef yolu
end

Türler aşağıdaki sembollerle temsil edilir: file, hardlink, symlink, chardev, blockdev, directory, fifo, veya bilinmeyen türler için, sembol olarak typeflag karakteri. Not edin ki extract file, symlink ve directory dışındaki kayıt türlerini çıkarmayı reddeder; list ise yalnızca strict=false ile çağrıldığında diğer türdeki kayıtları listeleyecektir.

Tar formatı, kullanıcı ve grup kimlikleri, kullanıcı ve grup adları ve zaman damgaları da dahil olmak üzere kayıtlar hakkında çeşitli diğer meta verileri içerir. Tar paketi, tasarımı gereği, bunları tamamen göz ardı eder. Tar dosyaları oluştururken, bu alanlar her zaman sıfır/boş olarak ayarlanır. Tar dosyaları okunurken, bu alanlar yalnızca her bir başlık kaydı için başlık kontrol toplamlarını doğrulamak dışında göz ardı edilir.