Metadata-Version: 2.4
Name: ZipIgnore
Version: 0.1.1
Summary: Create clean ZIP archives that respect .zipignore patterns (gitignore-style).
License: MIT
Keywords: zip,archive,gitignore,cli,developer-tools
Author: Suraj Yadav
Requires-Python: >=3.12,<3.15
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Archiving :: Compression
Requires-Dist: customtkinter (>=5.2,<6.0)
Requires-Dist: pathspec (>=0.12,<0.13)
Requires-Dist: pillow (>=10.0,<11.0)
Requires-Dist: rich (>=13,<14)
Requires-Dist: typer[all] (>=0.12)
Project-URL: Homepage, https://github.com/TheSuraj01/SafeZip
Project-URL: Repository, https://github.com/TheSuraj01/SafeZip
Description-Content-Type: text/markdown

# ZipIgnore

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

[![CI](https://github.com/TheSuraj01/SafeZip/actions/workflows/ci.yml/badge.svg)](https://github.com/TheSuraj01/SafeZip/actions)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 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

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

```bash
zipignore ./my-project
# → Creates my-project.zip with clean, intentional contents
```

---

## Installation

### Recommended: pipx (isolated global install)

```bash
pipx install ZipIgnore
```

### pip

```bash
pip install ZipIgnore
```

### From source (contributors)

```bash
git clone https://github.com/TheSuraj01/SafeZip.git
cd smartzip
poetry install
```

---

## Quick Start

**1. Create a `.zipignore` file in your project:**

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

**2. Run ZipIgnore:**

```bash
zipignore ./my-project
```

**Output:**

```
─────────────── ZIPIGNORE 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

```bash
zipignore <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

```bash
# Archive ./project → creates ./project.zip
zipignore ./project

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

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

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

# Overwrite existing archive
zipignore ./project --force

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

---

## `.zipignore` Reference

`.zipignore` uses the same syntax as `.gitignore` (powered by [pathspec](https://github.com/cpburnz/python-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`

```gitignore
# 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

ZipIgnore 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

ZipIgnore can also be used as a Python library:

```python
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](docs/contributing.md) for guidelines.

---

## License

MIT — see [LICENSE](LICENSE).
