113 lines
3.7 KiB
Markdown
113 lines
3.7 KiB
Markdown
# Tarballer
|
|
|
|
A utility to create tarballs with a specific directory structure and built-in MD5 integrity verification.
|
|
|
|
## Features
|
|
|
|
- Creates compressed tar archives (.tar.gz) with files under a specified prefix directory
|
|
- Preserves file permissions and directory structure
|
|
- Handles symbolic links correctly
|
|
- Cross-platform compatibility (FreeBSD, macOS, Linux)
|
|
- Compatible with standard tar tools
|
|
- Built-in MD5 hash verification
|
|
- Automatic file integrity checks during extraction
|
|
- Pattern-based file exclusion for creating targeted archives
|
|
|
|
## Building
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
This builds the project and creates binaries in the `./bin` directory:
|
|
- `tarballer-freebsd` - FreeBSD AMD64
|
|
- `tarballer-darwin` - macOS ARM64
|
|
- `tarballer-linux` - Linux AMD64
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
docker compose up --build
|
|
|
|
# Run specific test type
|
|
docker compose run tarballer /bin/test.sh basic
|
|
docker compose run tarballer /bin/test.sh tar
|
|
```
|
|
|
|
All tests run in the container's `/tmp` directory with no files written to the host filesystem.
|
|
|
|
Tests verify:
|
|
1. Creating and extracting tarballs with nested directories and symlinks
|
|
2. File content preservation and structure integrity
|
|
3. Symlink functionality after extraction
|
|
4. Compatibility with standard tar tools
|
|
5. MD5 hash verification
|
|
|
|
See `test/README.md` for detailed test information.
|
|
|
|
## Usage
|
|
|
|
### Create Mode
|
|
```bash
|
|
./bin/tarballer-<platform> -source /path/to/directory -output myarchive.tar.gz -prefix myprefix
|
|
```
|
|
|
|
Options:
|
|
- `-source`: Source directory to compress (required)
|
|
- `-output`: Output tarball filename (default: "output.tar.gz")
|
|
- `-prefix`: Directory name that will contain all files in the tarball (default: "myapp")
|
|
- `-exclude`: Comma-separated list of patterns to exclude (e.g. "*.log,*.tmp,temp/")
|
|
- `-verbose`: Enable detailed output during operation
|
|
|
|
### Extract Mode
|
|
```bash
|
|
./bin/tarballer-<platform> -extract -output myarchive.tar.gz -extractdir /path/to/extract
|
|
```
|
|
|
|
Options:
|
|
- `-extract`: Enables extraction mode
|
|
- `-output`: Tarball to extract (required)
|
|
- `-extractdir`: Extraction directory (default: current directory)
|
|
- `-verify`: Only verify hash integrity without extraction
|
|
- `-verbose`: Enable detailed output during operation
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Create a tarball (macOS)
|
|
./bin/tarballer-darwin -source ./myproject -output release.tar.gz -prefix app
|
|
|
|
# Create a tarball excluding specific files
|
|
./bin/tarballer-darwin -source ./myproject -output release.tar.gz -prefix app -exclude "*.log,bin/,temp/"
|
|
|
|
# Extract and verify (Linux)
|
|
./bin/tarballer-linux -extract -output release.tar.gz -extractdir /path/to/extract
|
|
|
|
# Extract with verbose output
|
|
./bin/tarballer-linux -extract -output release.tar.gz -extractdir /path/to/extract -verbose
|
|
|
|
# Only verify integrity
|
|
./bin/tarballer-linux -extract -verify -output release.tar.gz
|
|
```
|
|
|
|
## MD5 Hash Verification
|
|
|
|
1. During creation, MD5 hashes are calculated for all files and stored in `.md5-manifest.txt`
|
|
2. During extraction, file hashes are verified against the manifest
|
|
3. The manifest file is removed after successful extraction
|
|
4. Extraction aborts with an error if verification fails
|
|
|
|
## Exclude Patterns
|
|
|
|
The `-exclude` flag accepts a comma-separated list of patterns to exclude from the tarball:
|
|
|
|
- Simple wildcards using `*` (matches any sequence of characters) and `?` (matches any single character)
|
|
- Directory patterns (ending with `/`) exclude entire directory trees
|
|
- File patterns can match by extension (e.g., `*.log`) or name
|
|
|
|
Examples:
|
|
- `*.log` - Excludes all files with the .log extension
|
|
- `bin/` - Excludes the bin directory and all its contents
|
|
- `temp/,*.tmp` - Excludes the temp directory and all .tmp files
|
|
- `cache/*,*.bak` - Excludes all contents of the cache directory and all .bak files |