# repomeld 🔥

> Turn your entire codebase into a single AI-ready file — in seconds.

[![npm version](https://badge.fury.io/js/repomeld.svg)](https://www.npmjs.com/package/repomeld)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Works with:

| ChatGPT | Claude | Gemini | Cursor | Windsurf |
|---------|--------|--------|--------|----------|
| ✅ | ✅ | ✅ | ✅ | ✅ |

---

## The Problem

AI tools are powerful — but they struggle with large repositories.

Copying files manually is:
- **Slow** — jumping between files, copy-pasting one by one
- **Error-prone** — missing imports, missing context, wrong versions
- **Incomplete** — AI sees fragments, not the full picture

The result? Vague suggestions. Wrong answers. Wasted time.

---

## The Solution

```bash
npx repomeld
```

repomeld scans your entire repository and produces a single, clean, AI-ready document containing:

✅ Project structure  
✅ All source code  
✅ Dependencies and config  
✅ Optional Mermaid dependency diagrams  
✅ Clean context — nothing AI doesn't need  

One file. Paste it. Ask anything.

---

## Demo

```bash
npx repomeld --style markdown --output context.md
```

Upload `context.md` to ChatGPT, Claude, or Gemini and ask:

> *"Review my project and suggest improvements."*

Or drop it into Cursor / Windsurf as project context before starting a session.

---

## Why repomeld Instead of repomix?

Many developers discover this category by searching for repomix. Here's how repomeld compares:

| Feature | repomeld | repomix |
|---|---|---|
| Auto-numbered outputs (never overwrites) | ✅ | ❌ |
| Automatic backup zip creation | ✅ | ❌ |
| `repoclean` — one-command artifact cleanup | ✅ | ❌ |
| Mermaid dependency graph | ✅ | ❌ |
| Force include support | ✅ | ✅ |
| Multiple output styles (banner/markdown/minimal) | ✅ | ✅ |
| Gitignore support | ✅ | ✅ |
| Binary file detection + caching | ✅ | ✅ |
| Cross-platform (Windows, macOS, Linux) | ✅ | ✅ |

---

## Install

```bash
npm install -g repomeld
```

Or use without installing:

```bash
npx repomeld
```

---

## Quick Start

```bash
cd your-project
repomeld
```

repomeld walks your project, respects `.gitignore`, skips binary files, and writes everything into one readable file.

---

## ✨ Features

- 🚀 **Fast & Efficient** - Async scanning with real-time progress and binary caching
- 🎨 **Multiple Styles** - Banner, Markdown, or Minimal output
- 🔍 **Smart Filtering** - Extension, pattern, and size-based filtering
- 📁 **Gitignore Support** - Respects your .gitignore rules automatically
- 💾 **Binary Detection** - Intelligent caching for binary file detection
- 📦 **Single File Output** - Perfect for AI context windows
- 🔄 **Auto-Numbering** - Never overwrites existing files
- 💿 **Zip Backup** - Creates auto-numbered backups in `repomeld_zips/` folder
- 🔔 **Update Notifications** - Non-intrusive version checking
- 🎯 **Force Include** - Override ignore rules when needed
- 📊 **Dependency Graph** - Optional Mermaid diagram of file dependencies
- 🧹 **repoclean** - One command to delete all repomeld-generated files and zips
- 🌍 **Cross-Platform** - Works perfectly on Windows, macOS, and Linux

---

## Auto-Numbered Output — No Overwriting

Every time you run repomeld it creates a **new numbered file** so previous runs are never lost:

```
repomeld_output.txt       ← first run
repomeld_output__2.txt    ← second run
repomeld_output__3.txt    ← third run
repomeld_zips/            ← backup folder
  ├── repomeld_output.zip
  ├── repomeld_output__2.zip
  └── repomeld_output__3.zip
```

All previous output files and zips are **automatically excluded** from the next run — so you'll never get repomeld's own output included inside itself.

---

## All Options

```
Usage: repomeld [options]

Options:
  -V, --version                 Show version number
  -h, --help                    Show help

Output:
  -o, --output <filename>       Output file name
                                Default: "repomeld_output.txt"
                                Auto-numbered if the file already exists.

Filtering:
  -e, --ext <exts...>           Only include files with these extensions
                                e.g.  --ext js ts jsx tsx

  --include <patterns...>       Only include files whose path matches a pattern
                                e.g.  --include src/

  --exclude <patterns...>       Skip files whose path matches a pattern
                                e.g.  --exclude test spec __tests__

  -i, --ignore <names...>       Extra folder or file names to ignore
                                e.g.  --ignore dist .next coverage

  --force-include <names...>    Force-include something that would normally be ignored
                                e.g.  --force-include vendor bootstrap

  --max-size <kb>               Skip files larger than N kilobytes
                                Default: 500

  --no-gitignore                Ignore .gitignore file (include everything)

Formatting:
  -s, --style <style>           Header style for each file block:
                                  banner   — clear dividers with file info  (default)
                                  markdown — fenced code blocks, great for AI prompts
                                  minimal  — filename only, no extra formatting

  --no-toc                      Don't include a table of contents at the top

  --no-meta                     Hide per-file metadata (line count, size, language)

  --trim                        Trim leading/trailing whitespace from each file

Advanced:
  --lines-before <n>            Skip the first N lines of every file
  --lines-after <n>             Skip the last N lines of every file
  --dry-run                     Preview which files would be included — nothing is written
  --no-backup                   Skip creating backup zip file
  --no-update-check             Skip checking for updates
```

---

## Examples

```bash
# Basic — include everything, auto-numbered output
repomeld

# Only TypeScript files
repomeld --ext ts tsx

# Only files inside src/
repomeld --include src/

# Skip test files
repomeld --exclude test spec __tests__

# Markdown style — great for pasting into AI chats
repomeld --style markdown --output context.md

# Preview what would be included without writing anything
repomeld --dry-run

# Ignore extra folders on top of defaults
repomeld --ignore coverage logs tmp

# Respect gitignore (default) or ignore it
repomeld --no-gitignore  # include everything

# Only small files — skip anything over 100 KB
repomeld --max-size 100

# Force-include a vendor file that's normally ignored
repomeld --force-include bootstrap

# No table of contents, no metadata
repomeld --no-toc --no-meta

# Combine filters
repomeld --ext php --include Controllers --exclude test --style markdown

# Skip backup creation
repomeld --no-backup
```

---

## Auto-Ignored by Default

repomeld automatically skips these so your output stays clean:

| Category        | What's skipped                                      |
|-----------------|-----------------------------------------------------|
| Dependencies    | `node_modules/`                                     |
| Version control | `.git/`                                             |
| Env / secrets   | `.env`, `.env.local`, `.env.production`             |
| Lock files      | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` |
| Build output    | `dist/`, `build/`, `.next/`, `.nuxt/`, `.cache/`   |
| OS files        | `.DS_Store`                                         |
| repomeld output | `repomeld_output.txt` and all `repomeld_output__N.txt` files |

**Note:** `package.json` and `README.md` are **NOT** ignored by default — they contain important context for AI tools and code reviews.

---

## Custom Ignore Rules

### Method 1: repomeld.ignore.json

Create a `repomeld.ignore.json` in your project root for comprehensive ignore patterns:

```json
{
  "_comment": "repomeld.ignore.json — auto-ignored files and folders",
  "ignore": [
    "coverage",
    "logs",
    "tmp",
    "*.min.js",
    "**/generated/**",
    "vendor/**/bootstrap*",
    "**/jquery*",
    "**/fontawesome*"
  ]
}
```

These are merged with the defaults every time repomeld runs.

### Method 2: .gitignore

repomeld automatically respects your `.gitignore` file. Use `--no-gitignore` to override.

### Method 3: CLI --ignore

Override on the command line:

```bash
repomeld --ignore temp logs "*.tmp"
```

---

## Backup Zip Files

When repomeld runs, it automatically creates a backup zip file in the `repomeld_zips/` folder:

```
repomeld_output.txt
repomeld_zips/
  └── repomeld_output.zip          ← contains all included files + output

repomeld_output__2.txt
repomeld_zips/
  └── repomeld_output__2.zip       ← corresponding backup

repomeld_output__3.txt
repomeld_zips/
  └── repomeld_output__3.zip       ← and so on...
```

The zip file contains:
- All source files included in the run (preserving folder structure)
- The repomeld output file itself

To disable backups: `repomeld --no-backup`

---

## 🧹 repoclean — Remove All repomeld Artifacts

After several runs, your project root can accumulate output files and zip backups. `repoclean` removes all of them in one command.

```bash
repoclean
```

It finds and deletes everything repomeld creates:

| What gets deleted | Examples |
|---|---|
| Output text files | `repomeld_output.txt`, `repomeld_output__2.txt`, ... |
| Custom-named outputs | `repomeld_myproject.txt` |
| Backup zip folder | `repomeld_zips/` (entire folder) |

### repoclean Options

```
Usage: repoclean [options]

Options:
  -V, --version        Show version number
  -h, --help           Show help
  --dry-run            Preview what would be deleted — nothing is removed
  -y, --yes            Skip confirmation prompt (useful for scripts/CI)
  -d, --dir <path>     Clean a specific directory instead of cwd
```

### repoclean Examples

```bash
# Interactive — lists items and asks for confirmation
repoclean

# Preview only — shows what would be deleted without removing anything
repoclean --dry-run

# Skip confirmation (for CI or scripts)
repoclean --yes

# Clean a specific directory
repoclean --dir /path/to/project

# Preview a different directory
repoclean --dry-run --dir ../other-project
```

### Typical repoclean session

```
╔══════════════════════════════════════════════════════╗
║ repoclean v3.1.0                                     ║
║ Remove all repomeld-generated files 🧹               ║
╠══════════════════════════════════════════════════════╣
║ 💼 susheelhbti@gmail.com — Open for work             ║
╚══════════════════════════════════════════════════════╝

 📂 Target : /your/project

 🔍 Found 4 item(s) to remove:

   📄 repomeld_output.txt
   📄 repomeld_output__2.txt
   📄 repomeld_output__3.txt
   📁 repomeld_zips\  (entire folder)

 ⚠️  Delete all 4 item(s)? This cannot be undone. [y/N] y

 ✨ repoclean complete!
 ─────────────────────────────────────────────────
 ✅ Deleted : 4 item(s)
 ─────────────────────────────────────────────────
```

---

## Performance Optimizations

repomeld is optimized for large codebases:

- **Async file scanning** - Non-blocking operations
- **Binary caching** - Extension-based detection cache
- **Real-time progress** - Shows ETA and completion percentage
- **Memory efficient** - Processes files in streams
- **Smart filtering** - Early filtering to reduce processing
- **Handles 50,000+ files** - Tested on large monorepos

Example output:
```
🔍 Scanning files...
✅ Found 2453 files in 1.2s

📝 Processing 2453 files...

  Processing: 1245/2453 files (50.7%) | 2.3s elapsed
  Processing: ✅ Completed 2453/2453 files in 4.7s
```

**Memory warning** for extremely large repos (>20,000 files):
```
⚠️ Large repository detected (~25347 files). Memory usage may be high.
```

---

## Use Cases

### 🤖 AI Context Preparation
```bash
repomeld --ext js ts jsx py --style markdown --max-size 200
```

### 📋 Code Review
```bash
repomeld --include src/ --exclude test --style minimal --no-meta
```

### 💾 Full Project Backup
```bash
repomeld --force-include . --max-size 10000 --no-toc --no-meta
```

### 📚 Documentation Generation
```bash
repomeld --ext md --include docs --style markdown --output documentation.md
```

### 🔍 Debug Specific Feature
```bash
repomeld --include feature-name --ext js css --output feature-context.txt
```

### 🗺️ Dependency Analysis
```bash
repomeld --include src --style markdown --output analysis.md
# Then render the Mermaid graph in the output
```

### 🧹 Clean Up After AI Sessions
```bash
# After multiple repomeld runs, tidy up in one shot
repoclean
```

---

## Development

```bash
# Clone the repo
git clone https://github.com/susheelhbti/repomeld.git
cd repomeld

# Install dependencies
npm install

# Run locally
npm start -- --dry-run

# Link for global testing
npm link
repomeld --help
repoclean --help

# Run tests
npm test
```

---

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

---

## License

MIT © [Susheel](mailto:susheelhbti@gmail.com)

---

## Support & Contact

- 🐛 **Issues**: [GitHub Issues](https://github.com/susheel/repomeld/issues)
- 📧 **Email**: [susheelhbti@gmail.com](mailto:susheelhbti@gmail.com)
- 💼 **Hire Me**: Available for freelance and full-time opportunities

---

> ## 💼 Open to Work
> Built by a developer available for **freelance and full-time opportunities**.
> Got a project? Let's talk — 📧 **[susheelhbti@gmail.com](mailto:susheelhbti@gmail.com)**

---

**Made with ❤️ for developers who need better context for AI tools**