npm package: @mustafa60x/gitpack
Description: Smart project packer that respects .gitignore or falls back to a sensible default exclusion list. Creates timestamped zip archives named after your package.
Author: mustafa60x
Latest version: 1.2.0

# Gitpack 📦

> Pack your project smartly. No more `node_modules` or `.git` folder clutter in your zips!

**Gitpack** creates a clean, timestamped archive of your project, respecting your `.gitignore` rules automatically.

## Why Gitpack? 🚀

Have you ever zipped your project to send it to someone, only to realize you included:
- ❌ The massive `node_modules` folders (100s of MBs)
- ❌ Sensitive `.env` files with API keys
- ❌ The huge `.git` history
- ❌ Temporary build artifacts (`dist`, `build`, etc.)

**Gitpack solves this** by intelligently selecting only tracked and non-ignored files, giving you production-ready archives every time.

## Usage Scenarios 💡

- **Sharing Code:** Quickly send a clean source code zip to a colleague or friend.
- **Backups:** Create a "checkpoint" of your work before trying something experimental.
- **Assignments:** Submit your homework/project without unnecessary file bloat.
- **Archives:** Manually tag and archive versions of your app.

## Installation 🛠️

### npx (Recommended - No Installation)

You can run it directly with `npx`

```bash
npx @mustafa60x/gitpack
```

### Global Installation

You can install it globally to use it from anywhere:

```bash
npm install -g @mustafa60x/gitpack
```

### Project Dependency

Install it as a development dependency:

```bash
npm install --save-dev @mustafa60x/gitpack
```

Then add to your `package.json` scripts:

```json
{
  "scripts": {
    "pack": "gitpack",
    "pack:tar": "gitpack --format tar --out ./backups",
    "backup": "gitpack --out ./backups"
  }
}
```


Now run with:
```bash
npm run backup
```

## Requirements 📋

- **Node.js**: v14 or higher
- **Git**: Recommended (for smart tracking features), but not required.

## Features ✨

- 🎯 **Git-Aware Packing**: Uses git ls-files to include only tracked files
- 📛 **Smart Naming**: Auto-generates names from package.json (e.g., myapp-v1.3.0-2026-02-09_153045.zip)
- 🗜️ **Multiple Formats**: Support for .zip and .tar.gz
- 🎨 **Custom Output**: Control where archives go and what they include
- ⚡ **Zero Config**: Works out of the box with sensible defaults

## Usage Examples 🚀

### Basic Usage

Create a zip archive of your project:

```bash
# Create a zip in parent directory
gitpack

# Create a tar.gz archive
gitpack --format tar
```

### Custom Output Directory

Specify a different directory for the archive:

```bash
# Save to specific folder
gitpack --out ./backups

# Save to current directory
gitpack --out .
```

### Different Archive Format

Create a tar.gz archive instead of a zip:

```bash
gitpack --format tar
```

### Include .env Files

Include .env files in the archive (use with caution!):

```bash
gitpack --include-env
```

### No Git Data

Force fallback mode and exclude .git data:

```bash
gitpack --no-git
```

### Advanced Usage

Combine multiple options for custom backups:

```bash
# Create a timestamped backup in a specific directory
gitpack --out ./backups --format tar

# Create a clean archive without .git data
gitpack --no-git --out ./clean-backup
```

## Output Example 📂

Imagine your project structure:

```
my-app/
├── node_modules/   (ignored)
├── dist/           (ignored)
├── src/
├── package.json
└── README.md
```

Running `gitpack` produces:

```
📦 my-app-v1.0.0-2024-03-20_140000.zip (Contains only src, package.json, README.md)
```

## CLI Options ⚙️

| Flag | Description | Default |
|------|-------------|---------|
| `--format <type>` | Archive format (`zip` or `tar`). | `zip` |
| `--out <path>` | Specify output directory. | `../` (Parent directory) |
| `--include-env` | Include `.env` files (only in fallback mode). | `false` |
| `--no-git` | Force fallback mode (ignore `.git` data). | `false` |

## Naming Convention 🏷️

| Scenario | package.json | Output Name |
|----------|--------------|-------------|
| **Standard zip** | `name: "app", version: "1.3.0"` | `app-v1.3.0-2026-02-09_153045.zip` |
| **Tar format** | `name: "app", version: "2.0.1"` | `app-v2.0.1-2026-02-09_153045.tar.gz` |
| **Missing package.json** | `N/A` | `folder-name-2026-02-09_153045.zip` |
| **Missing version** | `name: "app" only` | `app-2026-02-09_153045.zip` |

## Contributing 🤝

Contributions are welcome! If you find a bug or want to add a feature:

1.  Fork the repository
2.  Create your feature branch (`git checkout -b feature/amazing-feature`)
3.  Commit your changes (`git commit -m 'Add some amazing feature'`)
4.  Push to the branch (`git push origin feature/amazing-feature`)
5.  Open a Pull Request

## Support 🌟

If you find this project useful, please consider giving it a star on GitHub! It helps others discover the project and motivates me to keep improving it.

## Connect 📬

If you have any questions or feedback, feel free to reach out:

- **GitHub:** [mustafa60x](https://github.com/mustafa60x)
- **Issues:** [Report a bug](https://github.com/mustafa60x/gitpack/issues)

## License 📄

MIT © [mustafa60x](https://github.com/mustafa60x)

<p align="center">
  Made with ❤️ by <a href="https://github.com/mustafa60x">mustafa60x</a>
</p>