@mustafa60x/gitpack 1.0.1 → 1.2.0

package/README.md

@@ -1,76 +1,207 @@
-# Gitpack
+# Gitpack 📦
 
-> Smart project packer that respects `.gitignore` or falls back to a sensible default exclusion list. Creates timestamped archives named after your package.
+> Pack your project smartly. No more `node_modules` or `.git` folder clutter in your zips!
 
-## Features
+**Gitpack** creates a clean, timestamped archive of your project, respecting your `.gitignore` rules automatically.
 
-- ✅ **Smart Naming**:
-  - Uses `name` and `version` from `package.json` if available (e.g., `app-v1.3.0-2026-02-09_153045.zip`)
-  - Fallback to directory name + timestamp if `package.json` is missing.
-- ✅ **Git Aware**: 
-  - Uses `git ls-files` to include only tracked and non-ignored files.
-- ✅ **Multiple Formats**: Support for `.zip` and `.tar.gz`.
-- ✅ **Custom Output**: Control where your archive goes and what it includes.
+## Why Gitpack? 🚀
 
-## Installation
+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.)
 
-You can run it directly with `npx`:
+**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
 ```
 
-Or install it globally:
+### Global Installation
+
+You can install it globally to use it from anywhere:
 
 ```bash
 npm install -g @mustafa60x/gitpack
 ```
 
-## Usage
+### Project Dependency
+
+Install it as a development dependency:
 
 ```bash
-gitpack [options]
+npm install --save-dev @mustafa60x/gitpack
 ```
 
-### Options
+Then add to your `package.json` scripts:
 
-| 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` |
+```json
+{
+  "scripts": {
+    "pack": "gitpack",
+    "pack:tar": "gitpack --format tar --out ./backups",
+    "backup": "gitpack --out ./backups"
+  }
+}
+```
 
-### Examples
 
-**Standard Zip (Parent Directory)**
+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 to a 'backups' folder**
+### Custom Output Directory
+
+Specify a different directory for the archive:
+
 ```bash
+# Save to specific folder
 gitpack --out ./backups
+
+# Save to current directory
+gitpack --out .
 ```
 
-**Generate a .tar.gz file**
+### Different Archive Format
+
+Create a tar.gz archive instead of a zip:
+
 ```bash
 gitpack --format tar
 ```
 
-**Force fallback mode and include .env files**
+### 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 --include-env
+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 Table
+## Output Example 📂
 
-| Scenario | `package.json` | Example Result |
-|----------|---------------|-----------------|
-| **Standard Zip** | `name: "app"`, `v1.3.0` | `app-v1.3.0-2026-02-09_032045.zip` |
-| **Tar Mode** | `name: "app"` | `app-2026-02-09_032045.tar.gz` |
-| **No Package** | (missing) | `folder_name-2026-02-09_032045.zip` |
+Imagine your project structure:
 
-## License
+```
+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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mustafa60x/gitpack",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "overrides": {
     "glob": "^11.0.0"
   },