aggr

README

aggr

A tool to aggregate and unpack files from directories

---

aggr is a command-line utility that recursively aggregates files from specified paths into a single file and unpacks them back to their original directory structure.

Features

• Pack multiple files and directories into a single text archive.
• Unpack archives, restoring the original directory structure.
• Filter files by size, extension, and path using glob + .gitignore-style patterns.
• Supports loading of a .aggrignore following gitignore conventions.
• Skips binary files automatically and, by default, hidden files and common VCS/build dirs.

Installation

curl -sSL https://raw.githubusercontent.com/idelchi/aggr/refs/heads/main/install.sh | sh -s -- -d ~/.local/bin

Usage

# Pack the current directory (excluding ignored files) into `pack.aggr`
aggr

# Pack specific paths
aggr src/ docs/

# Pack using glob patterns
aggr '**/folder/**/*.go'

# Unpack an archive to a specific directory
aggr --unpack -o __extracted__ pack.aggr

Format

Archives are plain text files with simple markers to delimit file content.

// === AGGR: BEGIN: src/main.go ===
package main

import "fmt"

func main() {
    fmt.Println("Hello, world!")
}

// === AGGR: END: src/main.go ===

// === AGGR: BEGIN: README.md ===
# Project

Description here.
// === AGGR: END: README.md ===

Marker escaping

If a line in your file content starts with the marker prefix (after optional spaces/tabs), it gets escaped on pack and unescaped on unpack. Lines that contain the marker elsewhere are left alone. This keeps the archive parseable without mutating normal content.

Path semantics (important)

• Root directory: By default the root is the current working directory. Use --root DIR or -C DIR to change it.
• Patterns: Input patterns must be relative to the root and cannot contain absolute paths or any .. segment. If you want to work outside CWD, use -C.
• Normalization:
  • . becomes ** (current dir + all subdirs).
  • A directory path with no glob meta (e.g. foo/) is treated as recursive: foo/**.
  • If your pattern already has meta (*?[{), it's passed through.
• Glob engine: Uses doublestar. Examples:
  • **/*.go
  • pkg/**/testdata/**
  • **/Dockerfile

Filtering

Create an .aggrignore with .gitignore-style patterns:

# Ignore logs and build artifacts
*.log
build/
dist/

You can also provide additional ignore patterns via CLI:

aggr -i "*.tmp" -i "node_modules/"

Defaults (always applied unless you override with your own patterns):

• Common VCS/build dirs: .git/, vendor/, node_modules/, etc.
• Hidden files/dirs (those starting with .) are excluded by default. Use -a/--hidden to include them.
• The output file itself (when -o is used).
• The aggr executable.
• Binary files are skipped automatically.

Extensions include list

You can use -x/--extensions to "invert" selection by extension, e.g.:

# Only include .go and .md (plus anything force-included by your own patterns)
aggr -x go -x md

This is implemented as an "allow-list" layer using ignore patterns under the hood.

Flags

• --unpack, -u – Unpack from a packed file
• --output, -o – Specify output file/folder. For --unpack, defaults to $(pwd)/aggr-[hash of <file>]
• --root, -C – Root directory to use
• --file, -f - Path to the .aggrignore file. Set to an empty string to completely ignore. When not passed, uses defaults.
• --extensions, -x – File extensions to include (repeatable)
• --ignore, -i – Additional .aggrignore patterns (repeatable)
• --hidden, -a – Include hidden files and directories
• --binary, -b – Include binary files
• --size, -s – Maximum size of file to include
• --max, -m – Maximum number of files to include
• --dry-run, -d – Show which files would be processed without reading contents
• --parallel, -j – Number of parallel workers to use

When --file is not set, it defaults to the first found of .aggrignore, ~/.config/aggr/.aggrignore and .gitignore.

Note: If the output directory already exists, you'll be prompted to confirm before potentially overwriting files.

Peculiarities & gotchas

• No absolute paths, no ..: Any absolute path or pattern containing a .. segment is rejected. Use -C if you need to work elsewhere.
• Pattern normalization is opinionated: . becomes **, and a plain directory becomes recursive. If you want exact matching behaviour, use explicit globs.
• Binary detection is conservative: Files that look binary are skipped. If you need to force-include something unusual, use --binary/-b to disable the check.

Documentation

Overview

Package main provides the aggr command-line tool for aggregating and unpacking files.

The aggr tool recursively aggregates files from specified paths into a single file and can unpack them back to their original directory structure. It supports various filtering options including file size limits, ignore patterns, and file type filtering.