ZipIgnore 0.1.0

Create clean ZIP archives that respect .zipignore patterns (gitignore-style).

SmartZip

Create clean ZIP archives that respect .zipignore patterns (gitignore-style).

---

The Problem

Standard zip tools have no concept of project-specific exclusions. Every time you archive a project you manually exclude node_modules/, build artifacts, .env secrets, and log files — or you accidentally include them.

The Solution

SmartZip reads a .zipignore file from your project (same syntax as .gitignore) and automatically excludes matching files when creating the ZIP archive.

smartzip ./my-project
# → Creates my-project.zip with clean, intentional contents

---

Installation

Recommended: pipx (isolated global install)

pipx install smartzip

pip

pip install smartzip

From source (contributors)

git clone https://github.com/your-org/smartzip.git
cd smartzip
poetry install

---

Quick Start

1. Create a .zipignore file in your project:

# .zipignore
node_modules/
dist/
build/
*.log
.env
.env.local
**/__pycache__/
**/*.pyc

2. Run SmartZip:

smartzip ./my-project

Output:

─────────────── SMARTZIP REPORT ───────────────

Excluded:
  ✗ node_modules/lodash/lodash.js
  ✗ .env
  ✗ error.log

Included:
  ✓ src/app.py
  ✓ src/utils.py
  ✓ README.md

Statistics:
  Included Files   3
  Excluded Files   312
  Archive Size     4.2 MB
  Archive Path     /home/user/my-project.zip

──────────── ✓ Archive created: my-project.zip ────────────

---

CLI Reference

Basic Usage

smartzip <FOLDER> [OPTIONS]

Options

Flag	Short	Description
--output PATH	-o	Custom output ZIP path (default: {folder}.zip in CWD)
--dry-run		Preview inclusions/exclusions without creating an archive
--verbose	-v	Print each file's include/exclude decision in real time
--force	-f	Overwrite the output file if it already exists
--version		Print version and exit
--help		Show help and exit

Examples

# Archive ./project → creates ./project.zip
smartzip ./project

# Custom output path
smartzip ./project -o release-v1.0.zip

# Dry run — preview only, no archive created
smartzip ./project --dry-run

# Verbose — see every include/exclude decision
smartzip ./project --verbose

# Overwrite existing archive
smartzip ./project --force

# Combine flags
smartzip ./project -o dist/release.zip --verbose --force

---

.zipignore Reference

.zipignore uses the same syntax as .gitignore (powered by pathspec).

Pattern Syntax

Pattern	Description	Example Match
node_modules/	Directory and all contents	node_modules/lodash/index.js
*.log	Wildcard by extension	error.log, logs/access.log
.env	Exact filename	.env, config/.env
temp/*	Single-level glob	temp/cache.db (not temp/sub/file)
**/*.pyc	Recursive wildcard	a/b/c/module.pyc
!important.log	Negation — re-include	important.log (if previously matched)
# comment	Comment line	(ignored)

Example .zipignore

# Dependencies
node_modules/
vendor/

# Build artifacts
dist/
build/
*.egg-info/

# Environment & secrets
.env
.env.*
!.env.example

# Logs
*.log
logs/

# Python cache
**/__pycache__/
**/*.pyc
**/*.pyo

# Temporary files
*.tmp
*.temp
temp/
.cache/

# IDE
.idea/
.vscode/
*.swp

# OS
.DS_Store
Thumbs.db

# Test artifacts
.pytest_cache/
htmlcov/
.coverage

Always Excluded

The following are always excluded regardless of .zipignore contents:

• .zipignore itself (tooling artifact, not project content)

---

Exit Codes

SmartZip follows standard UNIX exit code conventions for use in CI/CD pipelines:

Code	Meaning
0	Success — archive created (or dry run completed)
1	User error — bad path, output exists, all files excluded
2	Internal error — unexpected failure

---

Python API

SmartZip can also be used as a Python library:

from pathlib import Path
from smartzip import run, ArchiveRequest

request = ArchiveRequest(
    target=Path("./my-project"),
    output=Path("./my-project.zip"),
    dry_run=False,
    verbose=False,
    force=False,
)

result = run(request)
print(f"Archived {result.file_count} files ({result.size_human})")

---

Platform Support

Platform	Status
Linux	✅ Fully supported
macOS	✅ Fully supported
Windows	✅ Fully supported

ZIP archives created on any platform use POSIX / path separators internally, ensuring consistent extraction on all systems.

---

Contributing

See docs/contributing.md for guidelines.

---

License

MIT — see LICENSE.