github.com/mholt/archiver/v3
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.
Readme
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 platform-specific or format-specific archive utilities.
Package archiver makes it trivially easy to make and extract common archive formats such as tarball (and its compressed variants) and zip. 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.
Tar files can optionally be compressed using any of the above compression formats.
See https://pkg.go.dev/github.com/mholt/archiver/v3
webi will install webi and arc to ~/.local/bin/ and update your PATH.
curl -fsS https://webinstall.dev/arc | bash
curl.exe -fsS -A MS https://webinstall.dev/arc | powershell
To install the runnable binary to your $GOPATH/bin:
go install github.com/mholt/archiver/v3/cmd/arc@latest
To install manually
sudo:
chmod a+x ~/Downloads/arc_*
mkdir -p ~/.local/bin
mv ~/Downloads/arc_* ~/.local/bin/arc
root:
chmod a+x ~/Downloads/arc_*
sudo mkdir -p /usr/local/bin
sudo mv ~/Downloads/arc_* /usr/local/bin/arc
~/.bashrc or ~/.profile to include add arc in your PATH, for example:
echo 'PATH="$HOME:/.local/bin:$PATH"' >> ~/.bashrc
You can successfully build arc with just the go tooling, or with goreleaser.
gogo build cmd/arc/*.go
goreleaserBuilds with goreleaser will also include version info.
goreleaser --snapshot --skip-publish --rm-dist
# 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.)
# 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.
# 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
...
# Syntax: arc extract [archive name] [path in archive] [destination on disk]
arc extract test.tar.gz foo/hello.txt extracted/hello.txt
# 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.
# 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 are specified before the subcommand. Use arc help or arc -h to get usage help and a description of flags with their default values.
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.
To use as a dependency in your project:
go get github.com/mholt/archiver/v3
import "github.com/mholt/archiver/v3"
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.
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!
FAQs
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.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Cyber extortion in the US and Canada hit record levels in 2023, with ransomware attacks surging and median ransom demands skyrocketing, though fewer companies are choosing to pay ransoms.
Security News
Ecma TC39 is meeting this week and has moved key ECMAScript proposals forward, advancing Deferred Import Evaluation, Error.isError(), RegExp Escaping, and Promise.try to the next stages.
Security News
Researchers have demonstrated that teams of LLM agents can exploit zero-day vulnerabilities with a 53% success rate, and the costs of using AI to do so are rapidly becoming more affordable than hiring a human penetration tester.