{"id":29906795,"url":"https://github.com/atkntepe/dir2txt","last_synced_at":"2025-08-01T21:13:36.550Z","repository":{"id":306123553,"uuid":"1025115418","full_name":"atkntepe/dir2txt","owner":"atkntepe","description":"Convert project directories to LLM-friendly text format. Perfect for ChatGPT, Claude \u0026 AI code analysis. Features clipboard integration, project templates \u0026 smart filtering.","archived":false,"fork":false,"pushed_at":"2025-08-01T14:36:58.000Z","size":301,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-01T14:53:48.689Z","etag":null,"topics":["ai-tools","cli","code-analysis","developer-tools","llm","npm-package","text-export"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atkntepe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-23T18:42:23.000Z","updated_at":"2025-08-01T14:31:48.000Z","dependencies_parsed_at":"2025-07-23T20:58:08.637Z","dependency_job_id":"5018390c-d65d-4df8-a83b-2a87e59c39f9","html_url":"https://github.com/atkntepe/dir2txt","commit_stats":null,"previous_names":["atkntepe/dir2txt"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/atkntepe/dir2txt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atkntepe%2Fdir2txt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atkntepe%2Fdir2txt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atkntepe%2Fdir2txt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atkntepe%2Fdir2txt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atkntepe","download_url":"https://codeload.github.com/atkntepe/dir2txt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atkntepe%2Fdir2txt/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268297608,"owners_count":24228127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","cli","code-analysis","developer-tools","llm","npm-package","text-export"],"created_at":"2025-08-01T21:13:31.801Z","updated_at":"2025-08-01T21:13:36.524Z","avatar_url":"https://github.com/atkntepe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dir2txt\n\nA powerful CLI tool that converts your project's directory structure and file contents into clean, LLM-friendly text format. Perfect for sharing codebases with AI assistants, creating documentation, or analyzing project structures.\n\n## ✨ Key Features\n\n### 🚀 **Core Functionality**\n- **LLM-Optimized Output**: Clean, structured text perfect for AI analysis\n- **Multiple Output Formats**: Plain text, Markdown with syntax highlighting\n- **Flexible File Discovery**: Smart scanning with configurable ignore patterns\n- **Binary File Detection**: Automatically skips binary files and images  \n- **Size Filtering**: Configurable file size limits to avoid huge files\n- **Performance Optimized**: Concurrent processing with timing metrics\n\n### 🔗 **Smart Relationship Analysis**\n- **Import/Export Tracking**: Analyze dependencies between files\n- **File Summaries**: Pattern-based file purpose identification\n- **Dependency Graphs**: Visualize project structure and relationships\n- **Functional Grouping**: Organize files by functionality instead of directories\n\n### ⚡ **Incremental Processing \u0026 Caching**\n- **Lightning Fast Updates**: Only process changed files on subsequent runs\n- **Smart Change Detection**: SHA256-based content comparison with mtime optimization\n- **Watch Mode Integration**: Real-time updates with minimal processing overhead\n- **Cache Management**: Built-in cache statistics and cleanup tools\n- **Perfect for Large Projects**: Massive speed improvements for repeated analysis\n\n### 🎮 **Interactive Experience**\n- **Interactive Mode**: Guided interface for exploring your project\n- **Live File Browser**: Navigate and analyze files interactively\n- **Real-time Search**: Find patterns across your codebase instantly\n- **Project Statistics**: Detailed analysis and metrics\n- **Watch Mode**: Auto-regenerate output when files change\n\n### 🛠️ **Advanced Search \u0026 Filtering**\n- **Content Search**: Find patterns within file contents with regex support\n- **Date Filtering**: Process only files modified within specific time ranges\n- **TODO/FIXME Detection**: Automatically find technical debt markers\n- **Function Pattern Matching**: Extract function definitions across languages\n- **Context-Aware Results**: Show surrounding lines for search matches\n\n### 📋 **Project Management**\n- **Project Templates**: Pre-configured settings for Node.js, Python, Java, Web, C++\n- **Flexible Configuration**: JSON config files with inheritance\n- **Template System**: Quick setup for common project types\n\n## 📦 Installation\n\n### Global Installation (Recommended)\n```bash\nnpm install -g dir2txt\n```\n\n### Local Installation\n```bash\nnpm install dir2txt\nnpx dir2txt --help\n```\n\n## 🏃 Quick Start\n\n### Basic Usage\n```bash\n# Generate text to directory-output.txt (default)\ndir2txt run\n\n# Copy directly to clipboard for AI tools\ndir2txt run --clipboard\n\n# Only show directory structure (no file content)\ndir2txt run --dry\n\n# Generate in markdown format  \ndir2txt run --markdown --output docs/codebase.md\n```\n\n### Smart Analysis Features\n```bash\n# Include file relationships and summaries\ndir2txt run --include-relationships --file-summaries --clipboard\n\n# Show dependency graph and group by functionality\ndir2txt run --include-dependencies --group-by-feature --output analysis.txt\n\n# Fast incremental processing (only changed files)\ndir2txt run --incremental --show-changes --clipboard\n```\n\n### Interactive Mode\n```bash\n# Start interactive mode with guided interface\ndir2txt interactive\n\n# Quick alias\ndir2txt i\n```\n\n### Watch Mode (Live Updates)\n```bash\n# Watch for changes and auto-update\ndir2txt watch --clipboard\n\n# Watch with change analysis (incremental by default)\ndir2txt watch --show-changes --output live.txt\n```\n\n## ⚡ Incremental Processing\n\nPerfect for large projects and active development:\n\n```bash\n# First run: processes all files, builds cache\ndir2txt run --incremental --clipboard\n\n# Subsequent runs: only processes changed files (lightning fast!)\ndir2txt run --incremental --show-changes\n\n# Clear cache and start fresh\ndir2txt run --clear-cache --incremental\n\n# Check cache statistics\ndir2txt cache --stats\n\n# Manual cache management\ndir2txt cache --clear\n```\n\n## 🔍 Advanced Search \u0026 Analysis\n\n### Content Search\n```bash\n# Search for patterns in file contents\ndir2txt run --search \"TODO|FIXME\" --context 3\n\n# Find all TODO/FIXME comments\ndir2txt run --find-todos --output tech-debt.txt\n\n# Regex search with case sensitivity\ndir2txt run --search \"async.*function\" --regex --case-sensitive\n```\n\n### Date-Based Filtering\n```bash\n# Files modified since specific date\ndir2txt run --since \"2024-01-01\" --clipboard\n\n# Files modified in date range\ndir2txt run --since \"2024-01-01\" --before \"2024-02-01\"\n\n# Recent changes with search\ndir2txt run --since \"2024-01-01\" --search \"async\" --context 2\n```\n\n### Function Analysis\n```bash\n# Extract function definitions\ndir2txt run --find-functions --output functions.txt\n\n# Combine with content filtering\ndir2txt run --content-filter \"async\" --find-functions\n```\n\n## ⚙️ Configuration\n\n### Create Default Config\n```bash\ndir2txt config\n```\n\nThis creates `.dir2txt.json` with intelligent defaults:\n\n```json\n{\n  \"ignorePatterns\": [\n    \"node_modules/**\",\n    \"dist/**\", \n    \"build/**\",\n    \"coverage/**\",\n    \".dir2txt-cache/**\"\n  ],\n  \"includeExtensions\": [\n    \".js\", \".ts\", \".jsx\", \".tsx\",\n    \".json\", \".md\", \".py\", \".java\",\n    \".css\", \".html\", \".vue\", \".svelte\"\n  ],\n  \"maxFileSize\": 1048576,\n  \"concurrency\": 10,\n  \"excludeLarge\": true\n}\n```\n\n### Dynamic Configuration Updates\n```bash\n# Add/remove ignore patterns\ndir2txt update --add \"*.test.js\" --add \"docs/**\"\ndir2txt update --remove \"dist/**\"\n\n# Manage file extensions\ndir2txt update --add-ext .go --add-ext .rs\ndir2txt update --remove-ext .xml\n\n# Update settings\ndir2txt update --max-size 2097152\ndir2txt config --show\n```\n\n### Project Templates\n```bash\n# List available templates\ndir2txt templates --list\n\n# Apply template for your project type\ndir2txt templates --apply node    # Node.js/TypeScript\ndir2txt templates --apply python  # Python\ndir2txt templates --apply web     # Web Frontend\ndir2txt templates --apply java    # Java\ndir2txt templates --apply cpp     # C/C++\n```\n\n## 📋 Complete Command Reference\n\n| Command | Description | Key Options |\n|---------|-------------|-------------|\n| `run` | Generate text output | `--incremental`, `--include-relationships`, `--file-summaries`, `--clipboard`, `--dry`, `--markdown` |\n| `interactive` | Interactive mode | Guided interface with all features |\n| `watch` | Live file watching | `--incremental` (default), `--show-changes`, `--clipboard`, `--output` |\n| `cache` | Cache management | `--stats`, `--clear` |\n| `config` | Configuration | `--show` |\n| `update` | Update config | `--add`, `--remove`, `--add-ext`, `--remove-ext` |\n| `templates` | Project templates | `--list`, `--apply` |\n| `status` | Directory status | Show current directory and config status |\n\n## 📖 Output Examples\n\n### With Relationship Analysis\n```\n=== PROJECT ANALYSIS ===\n\nTotal Files Analyzed: 45\nTotal Imports: 127\nTotal Exports: 89\n\n=== FILE CONTENTS ===\n\n--- src/components/Button.jsx ---\nPurpose: Component module - Button\nImports: react, ./styles.css, ../utils/helpers\nLanguage: javascript\n\nimport React from 'react';\nimport './styles.css';\nimport { formatLabel } from '../utils/helpers';\n\nexport const Button = ({ label, onClick, variant = 'primary' }) =\u003e {\n  return (\n    \u003cbutton \n      className={`btn btn-${variant}`}\n      onClick={onClick}\n    \u003e\n      {formatLabel(label)}\n    \u003c/button\u003e\n  );\n};\n```\n\n### Incremental Processing Output\n```\n🔍 Starting dir2txt...\n📦 Cache initialized at: .dir2txt-cache\n📁 Scanning directory...\n✅ Found 156 files\n\n📊 Change Analysis:\n   📄 Total files: 156\n   🔄 Changed: 3\n   ✨ New: 1  \n   🗑️  Deleted: 0\n   📝 New files: src/components/Modal.jsx\n\n🚀 Processing 3 changed files\n💾 Cache updated: 156 files cached\n🎉 Generation complete!\n```\n\n## 🎯 Common Use Cases\n\n### For AI/LLM Analysis\n```bash\n# Complete codebase with context\ndir2txt run --include-relationships --file-summaries --clipboard\n\n# Fast incremental updates during development\ndir2txt run --incremental --show-changes --clipboard\n\n# Focus on specific functionality\ndir2txt run --group-by-feature --include-dependencies --output analysis.txt\n```\n\n### For Documentation\n```bash\n# Project structure overview\ndir2txt run --dry --markdown \u003e project-structure.md\n\n# Comprehensive code documentation\ndir2txt run --markdown --include-relationships --file-summaries --output docs/codebase.md\n\n# API documentation focus\ndir2txt run --search \"export.*function|export.*class\" --context 5 --markdown\n```\n\n### For Code Review \u0026 Analysis\n```bash\n# Recent changes analysis\ndir2txt run --since \"2024-01-01\" --include-relationships --output recent-changes.txt\n\n# Technical debt analysis\ndir2txt run --find-todos --find-functions --output tech-debt-analysis.txt\n\n# Dependency analysis\ndir2txt run --include-dependencies --group-by-feature --markdown\n```\n\n### For Active Development\n```bash\n# Live development with watch mode\ndir2txt watch --incremental --show-changes --clipboard\n\n# Interactive exploration\ndir2txt interactive\n\n# Quick previews\ndir2txt run --preview 10 --include-relationships\n```\n\n## 🏗️ Architecture\n\n```\ndir2txt/\n├── bin/cli.js              # CLI entry point and commands\n├── lib/\n│   ├── config.js           # Configuration management\n│   ├── traverse.js         # Directory traversal and filtering  \n│   ├── generate.js         # Text generation and formatting\n│   ├── relationships.js    # Import/export analysis \u0026 file summaries\n│   ├── search.js          # Content search and pattern matching\n│   ├── interactive.js     # Interactive mode interface\n│   ├── watcher.js         # File watching and live updates\n│   ├── cache.js           # Incremental processing and caching\n│   └── validation.js      # Configuration validation\n└── test/                  # Comprehensive test suite\n```\n\n## 📊 Performance\n\n### Speed Optimizations\n- **Incremental Processing**: 10-100x faster on subsequent runs\n- **Concurrent Processing**: Configurable parallelism (default: 10 files)\n- **Smart Caching**: SHA256-based change detection with mtime optimization\n- **Efficient Scanning**: Fast-glob for optimal file discovery\n- **Memory Efficient**: Streaming output for large projects\n\n### Benchmarks\n- **First Run**: ~100-500ms for typical projects\n- **Incremental Run**: ~10-50ms (only changed files)\n- **Watch Mode**: ~5-20ms updates (near-instantaneous)\n- **Large Projects**: 500+ files processed in \u003c2 seconds\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Setup\n```bash\ngit clone https://github.com/yourusername/dir2txt.git\ncd dir2txt\nnpm install\n\n# Run tests\nnpm test\n\n# Test locally\nnode bin/cli.js run --dry\nnode bin/cli.js interactive\n```\n\n## 📄 License\n\nThis project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [fast-glob](https://github.com/mrmlnc/fast-glob) - Fast and efficient glob matching\n- [chokidar](https://github.com/paulmillr/chokidar) - Efficient file watching\n- [ignore](https://github.com/kaelzhang/node-ignore) - .gitignore parsing\n- [commander](https://github.com/tj/commander.js) - Command-line interface framework\n- [clipboardy](https://github.com/sindresorhus/clipboardy) - Cross-platform clipboard access\n\n---\n\n**Made with ❤️ for developers and AI enthusiasts**\n\n*Transform your codebase into AI-friendly text with intelligent analysis, lightning-fast incremental processing, and comprehensive project insights.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatkntepe%2Fdir2txt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatkntepe%2Fdir2txt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatkntepe%2Fdir2txt/lists"}