README ¶
archiver
Introducing Archiver 3.1 - a cross-platform, multi-format archive utility and Go library. A powerful and flexible library meets an elegant CLI in this generic replacement for several of platform-specific, format-specific archive utilities.
Features
Package archiver makes it trivially easy to make and extract common archive formats such as zip and tarball (and its compressed variants). Simply name the input and output file(s). The arc
command runs the same on all platforms and has no external dependencies (not even libc). It is powered by the Go standard library and several third-party, pure-Go libraries.
Files are put into the root of the archive; directories are recursively added, preserving structure.
- Make whole archives from a list of files
- Open whole archives to a folder
- Extract specific files/folders from archives
- Stream files in and out of archives without needing actual files on disk
- Traverse archive contents without loading them
- Compress files
- Decompress files
- Streaming compression and decompression
- Several archive and compression formats supported
Format-dependent features
- Optionally create a top-level folder to avoid littering a directory or archive root with files
- Toggle overwrite existing files
- Adjust compression level
- Zip: store (not compress) already-compressed files
- Make all necessary directories
- Open password-protected RAR archives
- Optionally continue with other files after an error
Supported archive formats
- .zip
- .tar
- .tar.gz or .tgz
- .tar.bz2 or .tbz2
- .tar.xz or .txz
- .tar.lz4 or .tlz4
- .tar.sz or .tsz
- .rar (open only)
Supported compression formats
- bzip2
- gzip
- lz4
- snappy (sz)
- xz
Install
go get -u github.com/mholt/archiver/cmd/arc
Or download binaries from the releases page.
Command Use
Make new archive
# Syntax: arc archive [archive name] [input files...]
$ arc archive test.tar.gz file1.txt images/file2.jpg folder/subfolder
(At least one input file is required.)
Extract entire archive
# Syntax: arc unarchive [archive name] [destination]
$ arc unarchive test.tar.gz
(The destination path is optional; default is current directory.)
The archive name must end with a supported file extension—this is how it knows what kind of archive to make. Run arc help
for more help.
List archive contents
# Syntax: arc ls [archive name]
$ arc ls caddy_dist.tar.gz
drwxr-xr-x matt staff 0 2018-09-19 15:47:18 -0600 MDT dist/
-rw-r--r-- matt staff 6148 2017-08-07 18:34:22 -0600 MDT dist/.DS_Store
-rw-r--r-- matt staff 22481 2018-09-19 15:47:18 -0600 MDT dist/CHANGES.txt
-rw-r--r-- matt staff 17189 2018-09-19 15:47:18 -0600 MDT dist/EULA.txt
-rw-r--r-- matt staff 25261 2016-03-07 16:32:00 -0700 MST dist/LICENSES.txt
-rw-r--r-- matt staff 1017 2018-09-19 15:47:18 -0600 MDT dist/README.txt
-rw-r--r-- matt staff 288 2016-03-21 11:52:38 -0600 MDT dist/gitcookie.sh.enc
...
Extract a specific file or folder from an archive
# Syntax: arc extract [archive name] [path in archive] [destination on disk]
$ arc extract test.tar.gz foo/hello.txt extracted/hello.txt
Compress a single file
# Syntax: arc compress [input file] [output file]
$ arc compress test.txt compressed_test.txt.gz
$ arc compress test.txt gz
For convenience, the output file (second argument) may simply be a compression format (without leading dot), in which case the output filename will be the same as the input filename but with the format extension appended, and the input file will be deleted if successful.
Decompress a single file
# Syntax: arc decompress [input file] [output file]
$ arc decompress test.txt.gz original_test.txt
$ arc decompress test.txt.gz
For convenience, the output file (second argument) may be omitted. In that case, the output filename will have the same name as the input filename, but with the compression extension stripped from the end; and the input file will be deleted if successful.
Flags
Flags are specified before the subcommand. Use arc help
or arc -h
to get usage help and a description of flags with their default values.
Library Use
The archiver package allows you to easily create and open archives, walk their contents, extract specific files, compress and decompress files, and even stream archives in and out using pure io.Reader and io.Writer interfaces, without ever needing to touch the disk.
import "github.com/mholt/archiver"
See the package's GoDoc for full API documentation.
For example, creating or unpacking an archive file:
err := archiver.Archive([]string{"testdata", "other/file.txt"}, "test.zip")
// ...
err = archiver.Unarchive("test.tar.gz", "test")
The archive format is determined by file extension. (There are several functions in this package which perform a task by inferring the format from file extension or file header, including Archive()
, Unarchive()
, CompressFile()
, and DecompressFile()
.)
To configure the archiver used or perform, create an instance of the format's type:
z := archiver.Zip{
CompressionLevel: flate.DefaultCompression,
MkdirAll: true,
SelectiveCompression: true,
ContinueOnError: false,
OverwriteExisting: false,
ImplicitTopLevelFolder: false,
}
err := z.Archive([]string{"testdata", "other/file.txt"}, "/Users/matt/Desktop/test.zip")
Inspecting an archive:
err = z.Walk("/Users/matt/Desktop/test.zip", func(f archiver.File) error {
zfh, ok := f.Header.(zip.FileHeader)
if ok {
fmt.Println("Filename:", zfh.Name)
}
return nil
})
Streaming files into an archive that is being written to the HTTP response:
err = z.Create(responseWriter)
if err != nil {
return err
}
defer z.Close()
for _, fname := range filenames {
info, err := os.Stat(fname)
if err != nil {
return err
}
// get file's name for the inside of the archive
internalName, err := archiver.NameInArchive(info, fname, fname)
if err != nil {
return err
}
// open the file
file, err := os.Open(f)
if err != nil {
return err
}
// write it to the archive
err = z.Write(archiver.File{
FileInfo: archiver.FileInfo{
FileInfo: info,
CustomName: internalName,
},
ReadCloser: file,
})
file.Close()
if err != nil {
return err
}
}
The archiver.File
type allows you to use actual files with archives, or to mimic files when you only have streams.
There's a lot more that can be done, too. See the GoDoc for full API documentation.
Security note: This package does NOT attempt to mitigate zip-slip attacks. It is extremely difficult to do properly and seemingly impossible to mitigate effectively across platforms. Attempted fixes have broken processing of legitimate files in production, rendering the program unusable. Our recommendation instead is to inspect the contents of an untrusted archive before extracting it (this package provides Walkers
) and decide if you want to proceed with extraction.
Project Values
This project has a few principle-based goals that guide its development:
-
Do our thing really well. Our thing is creating, opening, inspecting, compressing, and streaming archive files. It is not meant to be a replacement for specific archive format tools like tar, zip, etc. that have lots of features and customizability. (Some customizability is OK, but not to the extent that it becomes overly complicated or error-prone.)
-
Have good tests. Changes should be covered by tests.
-
Limit dependencies. Keep the package lightweight.
-
Pure Go. This means no cgo or other external/system dependencies. This package should be able to stand on its own and cross-compile easily to any platform -- and that includes its library dependencies.
-
Idiomatic Go. Keep interfaces small, variable names semantic, vet shows no errors, the linter is generally quiet, etc.
-
Be elegant. This package should be elegant to use and its code should be elegant when reading and testing. If it doesn't feel good, fix it up.
-
Well-documented. Use comments prudently; explain why non-obvious code is necessary (and use tests to enforce it). Keep the docs updated, and have examples where helpful.
-
Keep it efficient. This often means keep it simple. Fast code is valuable.
-
Consensus. Contributions should ideally be approved by multiple reviewers before being merged. Generally, avoid merging multi-chunk changes that do not go through at least one or two iterations/reviews. Except for trivial changes, PRs are seldom ready to merge right away.
-
Have fun contributing. Coding is awesome!
We welcome contributions and appreciate your efforts! However, please open issues to discuss any changes before spending the time preparing a pull request. This will save time, reduce frustration, and help coordinate the work. Thank you!
Documentation ¶
Overview ¶
Package archiver facilitates convenient, cross-platform, high-level archival and compression operations for a variety of formats and compression algorithms.
This package and its dependencies are written in pure Go (not cgo) and have no external dependencies, so they should run on all major platforms. (It also comes with a command for CLI use in the cmd/arc folder.)
Each supported format or algorithm has a unique type definition that implements the interfaces corresponding to the tasks they perform. For example, the Tar type implements Reader, Writer, Archiver, Unarchiver, Walker, and several other interfaces.
The most common functions are implemented at the package level for convenience: Archive, Unarchive, Walk, Extract, CompressFile, and DecompressFile. With these, the format type is chosen implicitly, and a sane default configuration is used.
To customize a format's configuration, create an instance of its struct with its fields set to the desired values. You can also use and customize the handy Default* (replace the wildcard with the format's type name) for a quick, one-off instance of the format's type.
To obtain a new instance of a format's struct with the default config, use the provided New*() functions. This is not required, however. An empty struct of any type, for example &Zip{} is perfectly valid, so you may create the structs manually, too. The examples on this page show how either may be done.
See the examples in this package for an idea of how to wield this package for common tasks. Most of the examples which are specific to a certain format type, for example Zip, can be applied to other types that implement the same interfaces. For example, using Zip is very similar to using Tar or TarGz (etc), and using Gz is very similar to using Sz or Xz (etc).
When creating archives or compressing files using a specific instance of the format's type, the name of the output file MUST match that of the format, to prevent confusion later on. If you absolutely need a different file extension, you may rename the file afterward.
Values in this package are NOT safe for concurrent use. There is no performance benefit of reusing them, and since they may contain important state (especially while walking, reading, or writing), it is NOT recommended to reuse values from this package or change their configuration after they are in use.
Index ¶
- Variables
- func Archive(sources []string, destination string) error
- func ByExtension(filename string) (interface{}, error)
- func CompressFile(source, destination string) error
- func DecompressFile(source, destination string) error
- func Extract(source, target, destination string) error
- func NameInArchive(sourceInfo os.FileInfo, source, fpath string) (string, error)
- func Unarchive(source, destination string) error
- func Walk(archive string, walkFn WalkFunc) error
- type Archiver
- type Bz2
- type Compressor
- type Decompressor
- type ExtensionChecker
- type Extractor
- type File
- type FileCompressor
- type FileInfo
- type Gz
- type Lz4
- type Matcher
- type Rar
- func (*Rar) CheckExt(filename string) error
- func (r *Rar) Close() error
- func (r *Rar) Extract(source, target, destination string) error
- func (*Rar) Match(file io.ReadSeeker) (bool, error)
- func (r *Rar) Open(in io.Reader, size int64) error
- func (r *Rar) OpenFile(filename string) error
- func (r *Rar) Read() (File, error)
- func (r *Rar) String() string
- func (r *Rar) Unarchive(source, destination string) error
- func (r *Rar) Walk(archive string, walkFn WalkFunc) error
- type ReadFakeCloser
- type Reader
- type Snappy
- type Tar
- func (t *Tar) Archive(sources []string, destination string) error
- func (*Tar) CheckExt(filename string) error
- func (t *Tar) Close() error
- func (t *Tar) Create(out io.Writer) error
- func (t *Tar) Extract(source, target, destination string) error
- func (*Tar) Match(file io.ReadSeeker) (bool, error)
- func (t *Tar) Open(in io.Reader, size int64) error
- func (t *Tar) Read() (File, error)
- func (t *Tar) String() string
- func (t *Tar) Unarchive(source, destination string) error
- func (t *Tar) Walk(archive string, walkFn WalkFunc) error
- func (t *Tar) Write(f File) error
- type TarBz2
- func (tbz2 *TarBz2) Archive(sources []string, destination string) error
- func (*TarBz2) CheckExt(filename string) error
- func (tbz2 *TarBz2) Create(out io.Writer) error
- func (tbz2 *TarBz2) Extract(source, target, destination string) error
- func (tbz2 *TarBz2) Open(in io.Reader, size int64) error
- func (tbz2 *TarBz2) String() string
- func (tbz2 *TarBz2) Unarchive(source, destination string) error
- func (tbz2 *TarBz2) Walk(archive string, walkFn WalkFunc) error
- type TarGz
- func (tgz *TarGz) Archive(sources []string, destination string) error
- func (*TarGz) CheckExt(filename string) error
- func (tgz *TarGz) Create(out io.Writer) error
- func (tgz *TarGz) Extract(source, target, destination string) error
- func (tgz *TarGz) Open(in io.Reader, size int64) error
- func (tgz *TarGz) String() string
- func (tgz *TarGz) Unarchive(source, destination string) error
- func (tgz *TarGz) Walk(archive string, walkFn WalkFunc) error
- type TarLz4
- func (tlz4 *TarLz4) Archive(sources []string, destination string) error
- func (*TarLz4) CheckExt(filename string) error
- func (tlz4 *TarLz4) Create(out io.Writer) error
- func (tlz4 *TarLz4) Extract(source, target, destination string) error
- func (tlz4 *TarLz4) Open(in io.Reader, size int64) error
- func (tlz4 *TarLz4) String() string
- func (tlz4 *TarLz4) Unarchive(source, destination string) error
- func (tlz4 *TarLz4) Walk(archive string, walkFn WalkFunc) error
- type TarSz
- func (tsz *TarSz) Archive(sources []string, destination string) error
- func (*TarSz) CheckExt(filename string) error
- func (tsz *TarSz) Create(out io.Writer) error
- func (tsz *TarSz) Extract(source, target, destination string) error
- func (tsz *TarSz) Open(in io.Reader, size int64) error
- func (tsz *TarSz) String() string
- func (tsz *TarSz) Unarchive(source, destination string) error
- func (tsz *TarSz) Walk(archive string, walkFn WalkFunc) error
- type TarXz
- func (txz *TarXz) Archive(sources []string, destination string) error
- func (*TarXz) CheckExt(filename string) error
- func (txz *TarXz) Create(out io.Writer) error
- func (txz *TarXz) Extract(source, target, destination string) error
- func (txz *TarXz) Open(in io.Reader, size int64) error
- func (txz *TarXz) String() string
- func (txz *TarXz) Unarchive(source, destination string) error
- func (txz *TarXz) Walk(archive string, walkFn WalkFunc) error
- type Unarchiver
- type WalkFunc
- type Walker
- type Writer
- type Xz
- type Zip
- func (z *Zip) Archive(sources []string, destination string) error
- func (*Zip) CheckExt(filename string) error
- func (z *Zip) Close() error
- func (z *Zip) Create(out io.Writer) error
- func (z *Zip) Extract(source, target, destination string) error
- func (*Zip) Match(file io.ReadSeeker) (bool, error)
- func (z *Zip) Open(in io.Reader, size int64) error
- func (z *Zip) Read() (File, error)
- func (z *Zip) String() string
- func (z *Zip) Unarchive(source, destination string) error
- func (z *Zip) Walk(archive string, walkFn WalkFunc) error
- func (z *Zip) Write(f File) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultBz2 = NewBz2()
DefaultBz2 is a default instance that is conveniently ready to use.
var DefaultGz = NewGz()
DefaultGz is a default instance that is conveniently ready to use.
var DefaultLz4 = NewLz4()
DefaultLz4 is a default instance that is conveniently ready to use.
var DefaultRar = NewRar()
DefaultRar is a default instance that is conveniently ready to use.
var DefaultSnappy = NewSnappy()
DefaultSnappy is a default instance that is conveniently ready to use.
var DefaultTar = NewTar()
DefaultTar is a default instance that is conveniently ready to use.
var DefaultTarBz2 = NewTarBz2()
DefaultTarBz2 is a convenient archiver ready to use.
var DefaultTarGz = NewTarGz()
DefaultTarGz is a convenient archiver ready to use.
var DefaultTarLz4 = NewTarLz4()
DefaultTarLz4 is a convenient archiver ready to use.
var DefaultTarSz = NewTarSz()
DefaultTarSz is a convenient archiver ready to use.
var DefaultTarXz = NewTarXz()
DefaultTarXz is a convenient archiver ready to use.
var DefaultXz = NewXz()
DefaultXz is a default instance that is conveniently ready to use.
var DefaultZip = NewZip()
DefaultZip is a default instance that is conveniently ready to use.
var ErrStopWalk = fmt.Errorf("walk stopped")
ErrStopWalk signals Walk to break without error.
Functions ¶
func Archive ¶
Archive creates an archive of the source files to a new file at destination. The archive format is chosen implicitly by file extension.
Example ¶
The simplest use of this package: create an archive file from a list of filenames. This is the recommended way to do so using a default configuration, as it guarantees the file format matches the file extension, because the format to write is determined by the given extension.
Output:
func ByExtension ¶
ByExtension returns an archiver and unarchiver, or compressor and decompressor, based on the extension of the filename.
func CompressFile ¶
CompressFile is a convenience function to simply compress a file. The compression algorithm is selected implicitly based on the destination's extension.
Example ¶
This example compresses a standard tar file into a tar.gz file. Compression formats are selected by file extension.
Output:
Example (Custom) ¶
This example changes the default configuration for the Gz compression format.
Output:
func DecompressFile ¶
DecompressFile is a convenience function to simply compress a file. The compression algorithm is selected implicitly based on the source's extension.
Example ¶
This example decompresses a gzipped tarball and writes it to an adjacent file.
Output:
func Extract ¶
Extract extracts a single file from the given source archive. If the target is a directory, the entire folder will be extracted into destination. The archive format is chosen implicitly.
Example ¶
This example extracts target.txt from inside example.rar and puts it into a folder on disk called output/dir.
Output:
func NameInArchive ¶
NameInArchive returns a name for the file at fpath suitable for the inside of an archive. The source and its associated sourceInfo is the path where walking a directory started, and if no directory was walked, source may == fpath. The returned name is essentially the components of the path between source and fpath, preserving the internal directory structure.
func Unarchive ¶
Unarchive unarchives the given archive file into the destination folder. The archive format is selected implicitly.
Example ¶
The simplest use of this package: extract all of an archive's contents to a folder on disk using the default configuration. The archive format is determined automatically.
Output:
func Walk ¶
Walk calls walkFn for each file within the given archive file. The archive format is chosen implicitly.
Example ¶
It's easy to list the items in an archive. This example prints the name and size of each file in the archive. Like other top-level functions in this package, the format is inferred automatically for you.
Output:
Types ¶
type Archiver ¶
type Archiver interface { ExtensionChecker // Archive adds all the files or folders in sources // to an archive to be created at destination. Files // are added to the root of the archive, and directories // are walked and recursively added, preserving folder // structure. Archive(sources []string, destination string) error }
Archiver is a type that can create an archive file from a list of source file names.
type Bz2 ¶
type Bz2 struct {
CompressionLevel int
}
Bz2 facilitates bzip2 compression.
func NewBz2 ¶
func NewBz2() *Bz2
NewBz2 returns a new, default instance ready to be customized and used.
func (*Bz2) Decompress ¶
Decompress reads in, decompresses it, and writes it to out.
type Compressor ¶
Compressor compresses to out what it reads from in. It also ensures a compatible or matching file extension.
type Decompressor ¶
Decompressor decompresses to out what it reads from in.
type ExtensionChecker ¶
ExtensionChecker validates file extensions
type Extractor ¶
Extractor can extract a specific file from a source archive to a specific destination folder on disk.
type File ¶
type File struct { os.FileInfo // The original header info; depends on // type of archive -- could be nil, too. Header interface{} // Allow the file contents to be read (and closed) io.ReadCloser }
File provides methods for accessing information about or contents of a file within an archive.
type FileCompressor ¶
type FileCompressor struct { Compressor Decompressor // Whether to overwrite existing files when creating files. OverwriteExisting bool }
FileCompressor can compress and decompress single files.
func (FileCompressor) CompressFile ¶
func (fc FileCompressor) CompressFile(source, destination string) error
CompressFile reads the source file and compresses it to destination. The destination must have a matching extension.
func (FileCompressor) DecompressFile ¶
func (fc FileCompressor) DecompressFile(source, destination string) error
DecompressFile reads the source file and decompresses it to destination.
type FileInfo ¶
FileInfo is an os.FileInfo but optionally with a custom name, useful if dealing with files that are not actual files on disk, or which have a different name in an archive than on disk.
type Gz ¶
type Gz struct {
CompressionLevel int
}
Gz facilitates gzip compression.
func NewGz ¶
func NewGz() *Gz
NewGz returns a new, default instance ready to be customized and used.
func (*Gz) Compress ¶
Compress reads in, compresses it, and writes it to out.
Example (Custom) ¶
This example creates a new Gz instance and uses it to compress a stream, writing to another stream. This is sometimes preferable over modifying the DefaultGz.
Output:
func (*Gz) Decompress ¶
Decompress reads in, decompresses it, and writes it to out.
type Lz4 ¶
type Lz4 struct {
CompressionLevel int
}
Lz4 facilitates LZ4 compression.
func NewLz4 ¶
func NewLz4() *Lz4
NewLz4 returns a new, default instance ready to be customized and used.
func (*Lz4) Decompress ¶
Decompress reads in, decompresses it, and writes it to out.
type Matcher ¶
type Matcher interface {
Match(io.ReadSeeker) (bool, error)
}
Matcher is a type that can return whether the given file appears to match the implementation's format. Implementations should return the file's read position to where it was when the method was called.
type Rar ¶
type Rar struct { // Whether to overwrite existing files; if false, // an error is returned if the file exists. OverwriteExisting bool // Whether to make all the directories necessary // to create a rar archive in the desired path. MkdirAll bool // A single top-level folder can be implicitly // created by the Unarchive method if the files // to be extracted from the archive do not all // have a common root. This roughly mimics the // behavior of archival tools integrated into OS // file browsers which create a subfolder to // avoid unexpectedly littering the destination // folder with potentially many files, causing a // problematic cleanup/organization situation. // This feature is available for both creation // and extraction of archives, but may be slightly // inefficient with lots and lots of files, // especially on extraction. ImplicitTopLevelFolder bool // If true, errors encountered during reading // or writing a single file will be logged and // the operation will continue on remaining files. ContinueOnError bool // The password to open archives (optional). Password string // contains filtered or unexported fields }
Rar provides facilities for reading RAR archives. See https://www.rarlab.com/technote.htm.
func NewRar ¶
func NewRar() *Rar
NewRar returns a new, default instance ready to be customized and used.
func (*Rar) Extract ¶
Extract extracts a single file from the rar archive. If the target is a directory, the entire folder will be extracted into destination.
func (*Rar) Match ¶
func (*Rar) Match(file io.ReadSeeker) (bool, error)
Match returns true if the format of file matches this type's format. It should not affect reader position.
func (*Rar) OpenFile ¶
OpenFile opens filename for reading. This method supports multi-volume archives, whereas Open does not (but Open supports any stream, not just files).
func (*Rar) Read ¶
Read reads the next file from t, which must have already been opened for reading. If there are no more files, the error is io.EOF. The File must be closed when finished reading from it.
type ReadFakeCloser ¶
ReadFakeCloser is an io.Reader that has a no-op close method to satisfy the io.ReadCloser interface.
type Snappy ¶
type Snappy struct{}
Snappy facilitates Snappy compression.
func NewSnappy ¶
func NewSnappy() *Snappy
NewSnappy returns a new, default instance ready to be customized and used.
func (*Snappy) Decompress ¶
Decompress reads in, decompresses it, and writes it to out.
type Tar ¶
type Tar struct { // Whether to overwrite existing files; if false, // an error is returned if the file exists. OverwriteExisting bool // Whether to make all the directories necessary // to create a tar archive in the desired path. MkdirAll bool // A single top-level folder can be implicitly // created by the Archive or Unarchive methods // if the files to be added to the archive // or the files to be extracted from the archive // do not all have a common root. This roughly // mimics the behavior of archival tools integrated // into OS file browsers which create a subfolder // to avoid unexpectedly littering the destination // folder with potentially many files, causing a // problematic cleanup/organization situation. // This feature is available for both creation // and extraction of archives, but may be slightly // inefficient with lots and lots of files, // especially on extraction. ImplicitTopLevelFolder bool // If true, errors encountered during reading // or writing a single file will be logged and // the operation will continue on remaining files. ContinueOnError bool // contains filtered or unexported fields }
Tar provides facilities for operating TAR archives. See http://www.gnu.org/software/tar/manual/html_node/Standard.html.
func NewTar ¶
func NewTar() *Tar
NewTar returns a new, default instance ready to be customized and used.
func (*Tar) Archive ¶
Archive creates a tarball file at destination containing the files listed in sources. The destination must end with ".tar". File paths can be those of regular files or directories; directories will be recursively added.
func (*Tar) Extract ¶
Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.
func (*Tar) Match ¶
func (*Tar) Match(file io.ReadSeeker) (bool, error)
Match returns true if the format of file matches this type's format. It should not affect reader position.
func (*Tar) Read ¶
Read reads the next file from t, which must have already been opened for reading. If there are no more files, the error is io.EOF. The File must be closed when finished reading from it.
func (*Tar) Unarchive ¶
Unarchive unpacks the .tar file at source to destination. Destination will be treated as a folder name.
type TarBz2 ¶
TarBz2 facilitates bzip2 compression (https://github.com/dsnet/compress/blob/master/doc/bzip2-format.pdf) of tarball archives.
func NewTarBz2 ¶
func NewTarBz2() *TarBz2
NewTarBz2 returns a new, default instance ready to be customized and used.
func (*TarBz2) Archive ¶
Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.bz2" or ".tbz2". File paths can be those of regular files or directories; directories will be recursively added.
func (*TarBz2) Extract ¶
Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.
func (*TarBz2) Open ¶
Open opens t for reading a compressed archive from in. The size parameter is not used.
type TarGz ¶
type TarGz struct { *Tar // The compression level to use, as described // in the compress/gzip package. CompressionLevel int }
TarGz facilitates gzip compression (RFC 1952) of tarball archives.
func NewTarGz ¶
func NewTarGz() *TarGz
NewTarGz returns a new, default instance ready to be customized and used.
func (*TarGz) Archive ¶
Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.gz" or ".tgz". File paths can be those of regular files or directories; directories will be recursively added.
func (*TarGz) Extract ¶
Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.
func (*TarGz) Open ¶
Open opens t for reading a compressed archive from in. The size parameter is not used.
type TarLz4 ¶
type TarLz4 struct { *Tar // The compression level to use when writing. // Minimum 0 (fast compression), maximum 12 // (most space savings). CompressionLevel int }
TarLz4 facilitates lz4 compression (https://github.com/lz4/lz4/tree/master/doc) of tarball archives.
func NewTarLz4 ¶
func NewTarLz4() *TarLz4
NewTarLz4 returns a new, default instance ready to be customized and used.
func (*TarLz4) Archive ¶
Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.lz4" or ".tlz4". File paths can be those of regular files or directories; directories will be recursively added.
func (*TarLz4) Extract ¶
Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.
func (*TarLz4) Open ¶
Open opens t for reading a compressed archive from in. The size parameter is not used.
type TarSz ¶
type TarSz struct {
*Tar
}
TarSz facilitates Snappy compression (https://github.com/google/snappy) of tarball archives.
func NewTarSz ¶
func NewTarSz() *TarSz
NewTarSz returns a new, default instance ready to be customized and used.
func (*TarSz) Archive ¶
Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.sz" or ".tsz". File paths can be those of regular files or directories; directories will be recursively added.
func (*TarSz) Extract ¶
Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.
func (*TarSz) Open ¶
Open opens t for reading a compressed archive from in. The size parameter is not used.
type TarXz ¶
type TarXz struct {
*Tar
}
TarXz facilitates xz compression (https://tukaani.org/xz/format.html) of tarball archives.
func NewTarXz ¶
func NewTarXz() *TarXz
NewTarXz returns a new, default instance ready to be customized and used.
func (*TarXz) Archive ¶
Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.xz" or ".txz". File paths can be those of regular files or directories; directories will be recursively added.
func (*TarXz) Extract ¶
Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.
func (*TarXz) Open ¶
Open opens t for reading a compressed archive from in. The size parameter is not used.
type Unarchiver ¶
Unarchiver is a type that can extract archive files into a folder.
func ByHeader ¶
func ByHeader(input io.ReadSeeker) (Unarchiver, error)
ByHeader returns the unarchiver value that matches the input's file header. It does not affect the current read position.
type WalkFunc ¶
WalkFunc is called at each item visited by Walk. If an error is returned, the walk may continue if the Walker is configured to continue on error. The sole exception is the error value ErrStopWalk, which stops the walk without an actual error.
type Walker ¶
Walker can walk an archive file and return information about each item in the archive.
type Xz ¶
type Xz struct{}
Xz facilitates XZ compression.
func NewXz ¶
func NewXz() *Xz
NewXz returns a new, default instance ready to be customized and used.
func (*Xz) Decompress ¶
Decompress reads in, decompresses it, and writes it to out.
type Zip ¶
type Zip struct { // The compression level to use, as described // in the compress/flate package. CompressionLevel int // Whether to overwrite existing files; if false, // an error is returned if the file exists. OverwriteExisting bool // Whether to make all the directories necessary // to create a zip archive in the desired path. MkdirAll bool // If enabled, selective compression will only // compress files which are not already in a // compressed format; this is decided based // simply on file extension. SelectiveCompression bool // A single top-level folder can be implicitly // created by the Archive or Unarchive methods // if the files to be added to the archive // or the files to be extracted from the archive // do not all have a common root. This roughly // mimics the behavior of archival tools integrated // into OS file browsers which create a subfolder // to avoid unexpectedly littering the destination // folder with potentially many files, causing a // problematic cleanup/organization situation. // This feature is available for both creation // and extraction of archives, but may be slightly // inefficient with lots and lots of files, // especially on extraction. ImplicitTopLevelFolder bool // If true, errors encountered during reading // or writing a single file will be logged and // the operation will continue on remaining files. ContinueOnError bool // contains filtered or unexported fields }
Zip provides facilities for operating ZIP archives. See https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT.
Example (Custom) ¶
Here we create our own instance of the Zip format. No need to use the constructor function (NewZip) or the default instance (DefaultZip) if we do not want to. Instantiating the type like this allows us to easily be very explicit about our configuration.
Output:
Example (Default) ¶
In this example, the DefaultZip is being customized so that all calls to its methods will use that configuration.
Output:
Example (StreamingRead) ¶
This example demonstrates how to read an archive in a streaming fashion. The idea is that you can stream the bytes of an archive from a stream, regardless of whether it is an actual file on disk. This means that you can read a huge archive file-by-file rather than having to store it all on disk first. In this example, we read a hypothetical archive from a (fake) HTTP request body and print its file names and sizes. The files can be read, of course, but they do not have to be.
Output:
Example (StreamingWrite) ¶
This example demonstrates how to write an archive in a streaming fashion. The idea is that you can stream the bytes of a new archive that is created on-the-fly from generic streams. Those streams could be actual files on disk, or they could be over a network, or standard output, or any other io.Reader/io.Writer. This example only adds one file to the archive and writes the resulting archive to standard output, but you could add as many files as needed with a loop.
Output:
func NewZip ¶
func NewZip() *Zip
NewZip returns a new, default instance ready to be customized and used.
func (*Zip) Archive ¶
Archive creates a .zip file at destination containing the files listed in sources. The destination must end with ".zip". File paths can be those of regular files or directories. Regular files are stored at the 'root' of the archive, and directories are recursively added.
Example ¶
Much like the package-level Archive function, this creates an archive using the configuration of the Zip instance it is called on. The output filename must match the format's recognized file extension(s).
Output:
func (*Zip) Extract ¶
Extract extracts a single file from the zip archive. If the target is a directory, the entire folder will be extracted into destination.
func (*Zip) Match ¶
func (*Zip) Match(file io.ReadSeeker) (bool, error)
Match returns true if the format of file matches this type's format. It should not affect reader position.
func (*Zip) Open ¶
Open opens z for reading an archive from in, which is expected to have the given size and which must be an io.ReaderAt.
func (*Zip) Read ¶
Read reads the next file from z, which must have already been opened for reading. If there are no more files, the error is io.EOF. The File must be closed when finished reading from it.
func (*Zip) Unarchive ¶
Unarchive unpacks the .zip file at source to destination. Destination will be treated as a folder name.