pack-src

pack-src

pack-src is a powerful tool designed for efficiently packing source code directories into clean ZIP archives. This utility is built for speed and smart handling of file exclusions, ensuring reliable and reproducible packaging of your projects. Key features include:

Features

• Smart Ignoring: Automatically respects various ignore files including .packsrcignore, .gitignore, .dockerignore, and .npmignore, along with built-in defaults.
• Streaming ZIP: Utilizes streaming methods to avoid loading entire files into memory, allowing it to scale efficiently for larger repositories.
• Deterministic Output: Ensures files are sorted for consistent and reproducible archive outputs.
• Polished CLI: User-friendly command-line interface featuring progress spinners, colored outputs, and human-readable statistics to enhance the user experience.
• Zip-Slip Safety: Validates all paths before archiving to protect against zip-slip vulnerabilities.
• Zero Configuration: Offers sensible defaults right out of the box, minimizing setup time.

Usage Examples

To pack files in a directory, execute the following commands:

# To pack the current directory
pack-src

# To pack a specific directory
pack-src ./my-project

# To specify the output file name
pack-src ./my-project -o snapshot.zip

# To include a timestamp in the filename
pack-src ./my-project --timestamp
# Example output: my-project-2026-05-21.zip

# To perform a dry run and preview files without creating the archive
pack-src ./my-project --dry-run

# To list the files that will be included
pack-src ./my-project --list-files

# To print compression statistics
pack-src ./my-project --stats

# To set the compression level (0 = store, 9 = maximum)
pack-src ./my-project -c 9

# To include .env files (excluded by default)
pack-src ./my-project --include-env

# To disable .gitignore
pack-src ./my-project --no-gitignore

# To disable all built-in exclusions
pack-src ./my-project --no-default-ignore

# To overwrite existing output files
pack-src ./my-project --overwrite

# Quiet mode (suitable for CI)
pack-src ./my-project -q

Ignore Behavior

The ignore rules are prioritized as follows:

1. .packsrcignore — project-specific overrides
2. .gitignore — standard Git ignores
3. .dockerignore — Docker ignores
4. .npmignore — npm ignores
5. Built-in Defaults — includes common directories such as node_modules, dist, and more.

Output Naming

pack-src provides predictable naming conventions for the generated ZIP files:

Benchmark Performance

pack-src has demonstrated impressive performance metrics, particularly when tested on large projects. For example:

Programmatic API

For developers looking to integrate packing functionality into their applications, pack-src provides an intuitive API:

import { runPack, collectFiles, IgnoreEngine } from 'pack-src';

// Pack a directory
await runPack({
  source: './my-project',
  output: 'snapshot.zip',
  compression: 6,
  stats: true,
});

Development and Contributions

If interested in contributing to pack-src, clone the repository and follow the established development practices. The project encourages contributions through a well-defined process.