archiver

README

archiver

Package archiver makes it trivially easy to make and extract common archive formats such as .zip, and .tar.gz. Simply name the input and output file(s).

Files are put into the root of the archive; directories are recursively added, preserving structure.

The archiver command runs the same cross-platform and has no external dependencies (not even libc); powered by the Go standard library, dsnet/compress, nwaples/rardecode, and ulikunitz/xz. Enjoy!

Supported formats/extensions:

• .zip
• .tar
• .tar.gz & .tgz
• .tar.bz2 & .tbz2
• .tar.xz & .txz
• .tar.lz4 & .tlz4
• .tar.sz & .tsz
• .rar (open only)

Install

go get github.com/mholt/archiver/cmd/archiver

Or download binaries from the releases page.

Command Use

Make a new archive:

$ archiver make [archive name] [input files...]

(At least one input file is required.)

To extract an archive:

$ archiver open [archive name] [destination]

(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 archiver -h for more help.

Library Use

import "github.com/mholt/archiver"

Create a .zip file:

err := archiver.Zip.Make("output.zip", []string{"file.txt", "folder"})

Extract a .zip file:

err := archiver.Zip.Open("input.zip", "output_folder")

Working with other file formats is exactly the same, but with their own Archiver implementations.

FAQ

Can I list a file in one folder to go into a different folder in the archive?

No. This works just like your OS would make an archive in the file explorer: organize your input files to mirror the structure you want in the archive.

Can it add files to an existing archive?

Nope. This is a simple tool; it just makes new archives or extracts existing ones.

Project Values

This project has a few principle-based goals that guide its development:

• Do one thing really well. That is creating and opening 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 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.

• 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 makes it super easy to create and open .zip, .tar.gz, and .tar.bz2 files.

Index

• Variables
• func RegisterFormat(name string, format Archiver)
• type Archiver
  • func MatchingFormat(fpath string) Archiver
• type PreservableArchiver

Variables

var Rar rarFormat

Rar is for RAR archive format

var SupportedFormats = map[string]Archiver{}

SupportedFormats contains all supported archive formats

var Tar tarFormat

Tar is for Tar format

var TarBz2 tarBz2Format

TarBz2 is for TarBz2 format

var TarGz tarGzFormat

TarGz is for TarGz format

var TarLz4 tarLz4Format

TarLz4 is for TarLz4 format

var TarSz tarSzFormat

TarSz is for TarSz format

var TarXZ xzFormat

TarXZ is for TarXZ format

var Zip zipFormat

Zip is for Zip format

Functions

func RegisterFormat

func RegisterFormat(name string, format Archiver)

RegisterFormat adds a supported archive format

Types

type Archiver

type Archiver interface {
	// Match checks supported files
	Match(filename string) bool
	// Make makes an archive file on disk.
	Make(destination string, sources []string) error
	// Open extracts an archive file on disk.
	Open(source, destination string) error
	// Write writes an archive to a Writer.
	Write(output io.Writer, sources []string) error
	// Read reads an archive from a Reader.
	Read(input io.Reader, destination string) error
}

Archiver represent a archive format

func MatchingFormat

func MatchingFormat(fpath string) Archiver

MatchingFormat returns the first archive format that matches the given file, or nil if there is no match

type PreservableArchiver

type PreservableArchiver interface {
	// Match checks supported files
	Match(filename string) bool
	// Make makes an archive file on disk.
	Make(destination string, sources []string) error
	// Open extracts an archive file on disk.
	Open(source, destination string) error
	// Write writes an archive to a Writer.
	Write(output io.Writer, sources []string) error
	// Read reads an archive from a Reader.
	Read(input io.Reader, destination string) error
	// Open extracts an archive file on disk while preserving uid/gid.
	OpenPreserve(source, destination string) error
	// Read reads an archive from a Reader while preserving uid/gid.
	ReadPreserve(input io.Reader, destination string) error
}

PreservableArchiver represent a archive format