tar_light for Rust

A simple and lightweight tar archive reader and writer library in Rust.

Features

📦 Pack and unpack TAR archives (.tar)
🗜️ Support for gzip compression (.tar.gz, .tgz)
📋 List files in archives
🚀 Simple and intuitive API
🔧 Command-line tool included

Usage

Packing files into a TAR archive

use tar_light::pack;

// List of files to include in the archive
let files = vec!["file1.txt",　"file2.txt", "dir/file3.txt"];

// Create plain TAR archive
pack("archive.tar", &files);

// Create gzip-compressed TAR archive
pack("archive.tar.gz", &files);

Unpacking files from a TAR archive

use tar_light::unpack;

// Extract plain TAR archive
unpack("archive.tar", "output_directory");

// Extract gzip-compressed TAR archive
unpack("archive.tar.gz", "output_directory");

Listing files in a TAR archive

use tar_light::list;

// Works with both .tar and .tar.gz
match list("archive.tar.gz") {
    Ok(headers) => {
        println!("Files in archive:");
        for header in headers {
            println!("  {} ({} bytes)", header.name, header.size);
        }
    }
    Err(e) => eprintln!("Error: {}", e),
}

Advanced usage with low-level API

use tar_light::{read_tar, write_tar, TarEntry, TarHeader};
use std::fs;

// Reading TAR archives
let tar_data = fs::read("archive.tar").unwrap();
let entries = read_tar(&tar_data);
// list entries
for entry in entries {
    println!("{}: {} bytes", entry.header.name, entry.header.size);
}

// Creating TAR archives
let mut entries = Vec::new();
let header = TarHeader::new("hello.txt".to_string(), 0o644, 12);
let data = b"Hello, World".to_vec();
let header_bytes = header.to_bytes();

entries.push(TarEntry { header, data, header_bytes });
let tar_data = write_tar(&entries);
fs::write("new_archive.tar", tar_data).unwrap();

Supported Formats

.tar - Plain TAR archives
.tar.gz - Gzip-compressed TAR archives
.tgz - Gzip-compressed TAR archives (alternative extension)

Installation

Add to your Cargo.toml:

[dependencies]
tar_light = "0.1"

Or use cargo:

cargo add tar_light

The format is automatically detected based on the file extension.

Command Line Tool

The library includes a command-line tool for basic tar operations:

# Pack files into TAR archive
cargo run -- pack archive.tar file1.txt file2.txt

# Pack files into gzip-compressed TAR archive
cargo run -- pack archive.tar.gz file1.txt file2.txt

# Unpack archive
cargo run -- unpack archive.tar output_dir

# Unpack gzip-compressed archive
cargo run -- unpack archive.tar.gz output_dir

# List files in archive
cargo run -- list archive.tar.gz

Easy Building with just

This project uses just as a task runner, making it easy to build and test the project with simple commands. A justfile is provided for common tasks:

# Build the project
just build

# Build in release mode
just build-release

# Pack files into TAR archive
just pack archive.tar file1.txt file2.txt

# Unpack TAR archive
just unpack archive.tar output_dir

# List files in archive
just list archive.tar

# Clean up generated files
just clean

If you don't have just installed, you can install it with:

# macOS
brew install just

# Other platforms
cargo install just

Security

This library handles untrusted TAR archives. Please review SECURITY.md for important security considerations, known vulnerabilities, and best practices when working with TAR archives from untrusted sources.

Key Security Concerns:

Path traversal vulnerabilities in unpack() function
File overwrites without confirmation
Symbolic link handling

See SECURITY.md for detailed information and mitigation strategies.

License

MIT

tar_light 0.1.5