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

npx @mustafa60x/gitpack

Global Installation

You can install it globally to use it from anywhere:

npm install -g @mustafa60x/gitpack

Project Dependency

Install it as a development dependency:

npm install --save-dev @mustafa60x/gitpack

Then add to your package.json scripts:

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

Now run with:

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:

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

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

gitpack --format tar

Include .env Files

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

gitpack --include-env

No Git Data

Force fallback mode and exclude .git data:

gitpack --no-git

Advanced Usage

Combine multiple options for custom backups:

# 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
• Issues: Report a bug

License 📄

MIT © mustafa60x