Folder to Text Converter

A powerful Node.js tool that converts folder contents to text format and can regenerate folders from text. Perfect for sharing code snippets, creating backups, copying project structures, and working with AI models.

✨ Features

• 🗂️ Convert entire folders to single text files
• 📁 Regenerate folder structures from text files
• 📋 Copy files to clipboard (interactive or automatic)
• 🔧 Generate touch/creation commands for cross-platform compatibility
• 🚫 Smart filtering with customizable ignore patterns
• 💻 Cross-platform support (Mac, Windows, Linux)
• ⚡ Configurable file size limits and output splitting
• 📊 Metadata tracking for complete conversion history
• 🔄 File splitting for large outputs (text_1, text_2, etc.)
• ✂️ Large file splitting - automatically splits individual large files into manageable parts
• 🎯 ES Module support with modern JavaScript

🚀 Installation

npm install -g folder-to-text

Or use without installing:

npx folder-to-text

📖 Usage

Basic Commands

# Convert current directory
ftt convert

# Convert specific folder
ftt convert ./my-project -o project.txt

# Quick convert current directory
ftt quick

# Show help
ftt --help

Advanced Features

# Convert with custom ignore patterns
ftt convert ./my-project --ignore "*.log,test/**,*.tmp"

# Convert with custom file size limit
ftt convert -s 5000

# Convert with custom large file splitting (max 2000 lines per split file)
ftt convert -s 3000 -p 2000

# Auto-copy all files to clipboard (macOS friendly)
ftt clipboard project.txt --auto

# Show conversion metadata
ftt info project.txt

# Combine split files
ftt combine project.txt -o combined.txt

📋 Commands Reference

| Command | Alias | Description | |---------|-------|-------------| | convert | c | Convert folder to text file | | regenerate | r | Recreate folder from text file | | clipboard | clip | Copy files to clipboard | | quick | q | Quick convert current directory | | combine | comb | Combine split text files | | info | i | Show metadata information | | test-clipboard | test | Test clipboard functionality |

🎯 Command Options

Convert Command

ftt convert [folder] [options]

Options:
  -o, --output <file>      Output text file (default: folder_contents.txt)
  -s, --max-size <size>    Maximum file size in bytes (default: 3000)
  -l, --min-lines <lines>  Minimum lines before splitting (default: 4000)
  -m, --max-lines <lines>  Maximum lines per file (default: 2000)
  -p, --max-lines-per-split <lines>  Maximum lines per split file for large files (default: 4000)
  -i, --ignore <patterns>  Comma-separated ignore patterns

Clipboard Command

ftt clipboard <textfile> [options]

Options:
  -a, --auto               Copy all files automatically (recommended for macOS)
  --all                    Same as --auto

Regenerate Command

ftt regenerate <textfile> [options]

Options:
  -o, --output <folder>    Output folder name (default: regenerated_folder)

Combine Command

ftt combine <basefile> [options]

Options:
  -o, --output <file>      Output combined file (default: folder_contents_combined.txt)

📁 File Types Supported

• JavaScript/TypeScript: .js, .ts, .jsx, .tsx
• Python: .py
• Web: .html, .css, .scss, .less
• Configuration: .json, .xml, .yml, .yaml, .env, .gitignore
• Documentation: .md, .txt
• Scripts: .sh, .bat, .ps1
• Other Languages: .java, .cpp, .c, .cs, .php, .rb, .go, .rs, .swift, .kt, .scala, .sql
• Docker: Dockerfile*

🚫 Default Ignore Patterns

The tool automatically ignores common directories and files:

node_modules/**, venv/**, .env/**, .git/**
*.log, .DS_Store, Thumbs.db
__pycache__/**, *.pyc, .pytest_cache/**
dist/**, build/**, .next/**, coverage/**, .nyc_output/**

📄 Text File Format

Generated text files use this structured format:

FILE: src/index.js
console.log('Hello World');
---END---

FILE: package.json
{
  "name": "my-project",
  "version": "1.0.0"
}
---END---

📊 Metadata System

Every conversion creates a .metadata.json file that tracks:

• Conversion details: timestamp, source folder, settings
• File information: paths, sizes, modification dates, inclusion status
• Split file mapping: tracks which files were split and where
• Ignore patterns: records what was filtered out
• Statistics: total files found vs converted

View Metadata

ftt info project.txt

Example output:

📋 Conversion Information for: project.txt
📅 Timestamp: 2025-09-09T19:38:21.298Z
📂 Source folder: /path/to/my-project
📄 Output file: project.txt
📊 Total files found: 15
✅ Files converted: 12
📏 Max file size: 3000 bytes
📏 Max output size: 1000000 bytes
📏 Max lines per split file: 4000

📁 File details:
  ✅ src/index.js (23 bytes)
  ✅ package.json (84 bytes)
  ❌ large-file.js (File too large: 5000 bytes, split into 3 parts)

📄 Split large files:
  - large-file.js → large-file_part1.js, large-file_part2.js, large-file_part3.js

🔄 File Splitting

Output Splitting

When output exceeds 1MB (configurable), files are automatically split:

project.txt          # Main file
project_1.txt        # Split file 1
project_2.txt        # Split file 2
project.metadata.json # Metadata file

Large File Splitting

When individual files exceed the size limit AND have more lines than maxLinesPerSplitFile, they are split into multiple parts:

# Original large file
large_file.js (5000 bytes, 2000 lines)

# Becomes split files
large_file_part1.js  # Lines 1-4000
large_file_part2.js  # Lines 4001-8000

# Main text file contains reference
FILE: large_file.js
[File too large: 5000 bytes, split into 2 parts]
Split files: large_file_part1.js, large_file_part2.js
---END---

The metadata system automatically handles:

• Regeneration from split files (combines parts back into original)
• Combining split files back together
• Clipboard operations with split files
• Large file reconstruction during regeneration

✂️ Large File Splitting

The tool intelligently handles large files by splitting them into manageable parts while preserving the ability to perfectly reconstruct the original files.

How It Works

1. Detection: Files exceeding the size limit (-s) AND having more lines than maxLinesPerSplitFile (-p) are candidates for splitting
2. Splitting: Large files are split into multiple parts with up to maxLinesPerSplitFile lines each
3. Reference: The main text file contains a reference to all split parts
4. Reconstruction: During regeneration, all parts are automatically combined back into the original file

Example

# Convert with large file splitting
ftt convert ./my-project -s 3000 -p 4000

# Results in:
# - main_output.txt (contains references to split files)
# - large_file_part1.js (lines 1-4000)
# - large_file_part2.js (lines 4001-8000)
# - main_output.metadata.json (tracks all split files)

# Regenerate (automatically combines parts)
ftt regenerate main_output.txt -o restored-project

Benefits

• Manageable file sizes: Large files are broken into digestible chunks
• Perfect reconstruction: Original files are exactly restored during regeneration
• Metadata tracking: Complete information about all split files
• Automatic handling: No manual intervention required during regeneration

📋 Clipboard Functionality

macOS Compatibility

The clipboard functionality is optimized for macOS:

# Test clipboard functionality
ftt test-clipboard

# Auto mode (recommended for macOS)
ftt clipboard project.txt --auto

# Interactive mode
ftt clipboard project.txt

Clipboard Features

• Auto mode: Copies all files automatically without interaction
• Interactive mode: Step-by-step copying with user confirmation
• Touch commands: Generates cross-platform file creation commands
• Error handling: Graceful handling of clipboard failures

🌍 Cross-Platform Support

File Creation Commands

• Mac/Linux: mkdir -p "dir" && touch "file"
• Windows: mkdir "dir" 2>nul && echo. > "file"

Path Handling

• Automatic path resolution for all platforms
• Interactive path input when no path specified
• Relative and absolute path support

💡 Use Cases

1. 🤖 AI Model Training: Prepare code datasets for AI models
2. 📤 Code Sharing: Convert projects to text for easy sharing
3. 💾 Backup: Create text-based backups of small projects
4. 📚 Documentation: Generate project overviews and structure
5. 🔄 Migration: Move project structures between systems
6. 👥 Code Review: Share entire project context
7. 🎓 Learning: Analyze project structures and patterns
8. 🔧 Automation: Integrate with CI/CD pipelines

🛠️ Examples

Complete Workflow

# 1. Convert project to text with metadata
ftt convert ./my-project -o backup.txt

# 2. View conversion details
ftt info backup.txt

# 3. Copy files to clipboard (auto mode)
ftt clipboard backup.txt --auto

# 4. Regenerate project elsewhere
ftt regenerate backup.txt -o restored-project

# 5. Verify regeneration
ls restored-project/

Custom Ignore Patterns

# Ignore specific file types and directories
ftt convert ./my-project --ignore "*.log,test/**,*.tmp,coverage/**"

# Ignore multiple patterns
ftt convert ./my-project --ignore "node_modules/**,dist/**,*.min.js"

Large Project Handling

# Convert large project (will auto-split if needed)
ftt convert ./large-project -o large_backup.txt

# View split files
ftt info large_backup.txt

# Combine split files
ftt combine large_backup.txt -o combined.txt

# Regenerate from split files (automatic)
ftt regenerate large_backup.txt -o restored-large-project

Large File Splitting

# Convert with custom large file splitting settings
ftt convert ./my-project -s 3000 -p 2000

# This will:
# - Split files larger than 3000 bytes into 2000-line chunks
# - Create part files: file_part1.js, file_part2.js, etc.
# - Reference split files in main output
# - Automatically combine parts during regeneration

# Regenerate (automatically handles split files)
ftt regenerate project.txt -o restored-project

🔧 Configuration

Environment Variables

# Set default max file size
export FTT_MAX_SIZE=5000

# Set default max output size
export FTT_MAX_OUTPUT_SIZE=2000000

Programmatic Usage

import FolderToText from 'folder-to-text';

const converter = new FolderToText({
  maxSize: 5000,
  maxOutputSize: 2000000,
  maxLinesPerSplitFile: 4000,
  customIgnorePatterns: ['*.log', 'test/**']
});

// Convert folder
const result = await converter.convertFolderToText('./my-project', 'output.txt');

// Regenerate folder
await converter.regenerateFolder('output.txt', 'restored-project');

// Copy to clipboard
await converter.copyToClipboard('output.txt', { auto: true });

🐛 Troubleshooting

Clipboard Issues on macOS

# Test clipboard functionality
ftt test-clipboard

# Use auto mode if interactive mode fails
ftt clipboard project.txt --auto

Large File Handling

# Increase file size limit
ftt convert -s 10000

# Adjust large file splitting
ftt convert -s 3000 -p 2000

# Check metadata for file details
ftt info project.txt

Permission Issues

# Ensure write permissions for output directory
chmod 755 ./output-directory

🔧 Quick File Recreation

After converting a folder to text, the tool automatically generates cross-platform commands that allow you to quickly recreate the file structure. This is perfect for setting up project scaffolding or sharing file structures.

How It Works

When you run a conversion command, the tool automatically prints touch commands for both Windows and macOS/Linux:

ftt convert ./my-project -o project.txt

Output:

✅ Converted 5 files to project.txt
📋 Metadata saved to: project.metadata.json

🔧 Quick file recreation commands:
Copy and paste these commands to quickly recreate the file structure:

Windows:

echo. > "src/index.js" && echo. > "src/utils.js" && mkdir "tests" 2>nul || echo Directory exists && echo. > "tests/test.js" && echo. > "package.json" && echo. > "README.md" && echo. > "project.txt" && echo. > "project.metadata.json"

macOS/Linux:

touch "src/index.js" && touch "src/utils.js" && mkdir -p "tests" && touch "tests/test.js" && touch "package.json" && touch "README.md" && touch "project.txt" && touch "project.metadata.json"

💡 Tip: You can also use the regenerate command: ftt regenerate project.txt

What's Included

The touch commands include:

1. All converted files - Every file that was successfully converted
2. Directory creation - Commands to create necessary directories
3. Main output file - The text file containing all the content
4. Metadata file - The .metadata.json file with conversion details

Usage Examples

Windows (Command Prompt/PowerShell)

echo. > "src/index.js" && echo. > "src/utils.js" && mkdir "tests" 2>nul || echo Directory exists && echo. > "tests/test.js" && echo. > "package.json" && echo. > "README.md" && echo. > "project.txt" && echo. > "project.metadata.json"

macOS/Linux (Terminal)

touch "src/index.js" && touch "src/utils.js" && mkdir -p "tests" && touch "tests/test.js" && touch "package.json" && touch "README.md" && touch "project.txt" && touch "project.metadata.json"

Benefits

• Quick Setup: Instantly recreate project structure
• Cross-Platform: Works on Windows, macOS, and Linux
• Complete: Includes all files and directories
• Copy-Paste Ready: Single command that can be copied and pasted
• No Dependencies: Uses built-in OS commands

Use Cases

1. Project Scaffolding: Quickly set up new projects with the same structure
2. Team Collaboration: Share file structures with team members
3. Template Creation: Create project templates from existing projects
4. Documentation: Show project structure in documentation
5. CI/CD: Use in build scripts to create required directories

Advanced Usage

Custom Output File

ftt convert ./my-project -o custom_output.txt

The touch commands will include custom_output.txt and custom_output.metadata.json.

With Split Files

When files are split due to size limits, the touch commands still work:

ftt convert ./large-project -o large_project.txt

Commands will include all split files and the main output file.

Troubleshooting

Windows Issues

• Use Command Prompt or PowerShell
• Ensure you have write permissions in the target directory
• If echo. doesn't work, try echo. > "filename"

macOS/Linux Issues

• Ensure you have write permissions in the target directory
• Use chmod +x if needed for script execution
• Some systems may require mkdir -p for nested directories

Permission Issues

# Make sure you have write permissions
chmod 755 ./target-directory

# Or run with appropriate permissions
sudo ftt convert ./my-project

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

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

📞 Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Discussions: GitHub Discussions

Made with ❤️ for developers who love clean, efficient tools.