Documentation
¶
Overview ¶
Package tgz lets you work with gzip tar streams.
It defines interfaces for reading and writing tar streams, provides a modular implementation of them and exports some high-level functions for common tasks like recursively writing all the files in a directory to a gzip tar archive stream, creating or extracting a tarball.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractTarball ¶
ExtractTarball extracts the files in the given tarball to the specified directory, taking care of creating intermediate directories as needed.
If you pass the empty string for destDirPath, ExtractTarball preserves the original archive paths, even if they're absolute. For example, if "/d/f" is the path of file f in the archive, ExtractTarball will try creating a directory "/d" if it doesn't exist and then put f in there. With an empty destDirPath, ExtractTarball resolves relative archive paths with respect to the current directory. For example, if "d/f" is the path of file f in the archive, ExtractTarball will try creating a directory "./d" if it doesn't exist and then put f in there.
On the other hand, if you specify a destDirPath (either absolute or relative to the current directory), ExtractTarball recreates the directory structure of the archived files entirely in destDirPath by interpreting all archive paths (even absolute ones) relative to destDirPath. For example, if "/d/f" is the path of file f in the archive, ExtractTarball will try creating a directory "destDirPath/d" if it doesn't exist and then put f in there. The same happens to relative paths. For example, if "d/f" is the path of file f in the archive, ExtractTarball will try creating a directory "destDirPath/d" if it doesn't exist and then put f in there.
func MakeTarball ¶
MakeTarball collects all the files in sourceDir (and its sub-dirs) and writes them to a gzip tar archive file. The archive file is created with 0644 permissions at the path specified by tarballPath. Each file in sourceDir gets written to the archive at path "b/r" where b is sourceDir's base name and r is the file's path relative to sourceDir. For example, if sourceDir = "my/source" contains a file "my/source/d/f", that file gets archived at "source/d/f".
func WriteFileArchive ¶
func WriteFileArchive(sourceDir file.AbsPath, sink io.WriteCloser) error
WriteFileArchive collects all the files in sourceDir (and its sub-dirs) and writes them to a gzip tar archive. Each file gets written to the archive at path "b/r" where b is sourceDir's base name and r is the file's path relative to sourceDir. For example, if sourceDir = "my/source" contains a file "my/source/d/f", that file gets archived at "source/d/f". The archive bytes get written to the give sink stream.
Types ¶
type ClosedHandle ¶
type ClosedHandle string
An attempt to access a closed resource handle, like a file or a stream.
type EntryReader ¶
EntryReader processes an entry in a tar archive. The entry is at archivePath and has an associated file metadata whereas the content should only be read if the entry is a regular file.
type Reader ¶
type Reader interface {
// IterateEntries calls process on each tar entry.
// Regardless of errors, IterateEntries closes the archive stream,
// making the Reader unusable.
IterateEntries(process EntryReader) error
// Close releases all archive stream resources, making the Reader
// unusable. Subsequent calls have no effect.
Close()
}
Reader calls an EntryReader on each entry in a tar archive.
type Writer ¶
type Writer interface {
// AddEntry writes the given content to the archive at the specified
// path, relative to the archive base directory.
AddEntry(archivePath string, content io.Reader) error
// AddFile writes the given file to the archive at the specified path,
// relative to the archive base directory.
AddFile(archivePath string, filePath string, fi os.FileInfo) error
// Visitor returns a function you can use with a file.TreeScanner to
// collect all the files in a directory (including sub-directories)
// and add them to the archive.
Visitor() file.Visitor
// Close finalises the writing to the archive and closes the underlying
// sink stream.
Close()
}
Writer writes data to a compressed tar stream. The tar format is PAX and the compression is gzip. You create a Writer with a sink stream where the compressed tar data gets written.
Example. Archiving all the files in "some/dir" and its sub-directories.
sourceDir, _ := file.ParseAbsPath("some/dir")
sink, _ := os.OpenFile("my.tgz", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
archiveBaseDirName := "my-root"
scanner := file.NewTreeScanner(sourceDir)
writer, _ := NewWriter(archiveBaseDirName, sink)
defer writer.Close()
scanner.Visit(writer.Visitor())
If "some/dir/d1/f1" is a file, then it'll be archived at "my-root/d1/f1". Use an empty string for archive base directory name if you don't want to prefix archived paths---e.g. the above file would be archived at "d1/f1". The above example uses a file.Visitor to collect files from a directory, but you can also call directly the AddEntry and AddFile methods for finer control over what gets written to the archive. Also, there's a couple of convenience functions to archive directory contents to a stream or a file, see: WriteFileArchive and MakeTarball.
func NewWriter ¶
func NewWriter(archiveBaseDirName string, sink io.WriteCloser, opts ...WriterOption) (Writer, error)
type WriterOption ¶
type WriterOption func(opts *writerOpts)
func WithBestCompression ¶
func WithBestCompression() WriterOption
Use the highest gzip compression level when writing the archive.
func WithBestSpeed ¶
func WithBestSpeed() WriterOption
Use the lowest gzip compression level when writing the archive.
func WithDefaultCompression ¶
func WithDefaultCompression() WriterOption
Use gzip's default compression level when writing the archive.
func WithEntryTime ¶
func WithEntryTime(when time.Time) WriterOption
Set the access, change and mod time of each tar header to the specified time point.
Source Files