archives

README

archives

A Go library for reading and browsing archive files in memory. Supports ZIP, TAR (with gzip, bzip2, xz compression), and Ruby gem formats.

Installation

go get github.com/git-pkgs/archives

Usage

package main

import (
	"fmt"
	"os"

	"github.com/git-pkgs/archives"
)

func main() {
	f, _ := os.Open("package.tar.gz")
	defer f.Close()

	reader, _ := archives.Open("package.tar.gz", f)
	defer reader.Close()

	// List all files
	files, _ := reader.List()
	for _, fi := range files {
		fmt.Println(fi.Path, fi.Size)
	}

	// List a specific directory
	dirFiles, _ := reader.ListDir("src")
	for _, fi := range dirFiles {
		fmt.Println(fi.Name, fi.IsDir)
	}

	// Extract a file
	rc, _ := reader.Extract("README.md")
	defer rc.Close()
	// read from rc...
}

Prefix stripping

Some package formats wrap content in a directory (npm uses package/). OpenWithPrefix strips a path prefix from all entries:

reader, _ := archives.OpenWithPrefix("pkg.tgz", f, "package/")
// files are now accessible without the package/ prefix

Comparing versions

The diff subpackage compares two archives and produces unified diffs. It classifies each file as added, deleted, modified, or binary, and includes line-level diff output for text files.

import "github.com/git-pkgs/archives/diff"

result, _ := diff.Compare(oldReader, newReader)
for _, f := range result.Files {
	fmt.Printf("%s %s (+%d -%d)\n", f.Type, f.Path, f.LinesAdded, f.LinesDeleted)
	if f.Diff != "" {
		fmt.Println(f.Diff)
	}
}

Supported formats

• .zip, .jar, .whl, .nupkg, .egg (ZIP-based)
• .tar, .tar.gz, .tgz, .tar.bz2, .tar.xz
• .gem (Ruby gems with nested data.tar.gz)

License

MIT

Documentation

Overview

Package archives provides in-memory archive reading and browsing capabilities.

It supports multiple archive formats including:

• ZIP (.zip, .jar, .whl, .nupkg)
• TAR (.tar, .tar.gz, .tgz, .tar.bz2, .tar.xz)
• GEM (.gem - Ruby gems with nested tar structure)

The package is designed to work entirely in memory without writing to disk, making it suitable for browsing cached artifacts on-demand.

Index

• type FileInfo
• type Reader
  • func Open(filename string, content io.Reader) (Reader, error)
  • func OpenWithPrefix(filename string, content io.Reader, stripPrefix string) (Reader, error)

Types

type FileInfo

type FileInfo struct {
	Path           string    // Full path within archive
	Name           string    // Base name
	Size           int64     // Uncompressed size in bytes
	ModTime        time.Time // Modification time
	IsDir          bool      // Whether this is a directory
	Mode           uint32    // File mode/permissions
	CompressedSize int64     // Compressed size (if available)
}

FileInfo represents metadata about a file in an archive.

type Reader

type Reader interface {
	// List returns all files in the archive.
	List() ([]FileInfo, error)

	// ListDir returns files in a specific directory path.
	// Use "" or "/" for root directory.
	ListDir(dirPath string) ([]FileInfo, error)

	// Extract reads a specific file from the archive.
	// Returns io.ReadCloser for the file content.
	Extract(filePath string) (io.ReadCloser, error)

	// Close releases resources associated with the reader.
	Close() error
}

Reader provides methods to browse and extract files from archives.

func Open

func Open(filename string, content io.Reader) (Reader, error)

Open creates an archive reader for the given content. The filename is used to detect the archive format. The content reader will be read entirely into memory.

func OpenWithPrefix

func OpenWithPrefix(filename string, content io.Reader, stripPrefix string) (Reader, error)

OpenWithPrefix opens an archive and strips the given prefix from all paths. This is useful for npm packages which wrap content in a "package/" directory.