v2.3.5 - A Python tool to consolidate textual content from any mix of files and folders into a single document.
Combination is a cross-platform GUI application that helps you create unified text documents from multiple source files and directories. Perfect for consolidating codebases, documentation, or any collection of text files into a single, organized document.
- Select any combination of individual files and entire folders
- Multi-select support with native OS dialogs (especially enhanced on macOS)
- Smart base detection: Automatically discovers the common ancestor directory from your selections, so you can pick files from
/project/src/main.pyand/project/docs/readme.mdand it intelligently uses/project/as the base
- Text extraction: Reads various text-based file formats
- PDF support: Extracts text from PDFs (requires PyPDF2)
- Binary detection: Automatically skips images, videos, executables, etc.
- Encoding safety: Handles text encoding issues gracefully
- Auto-exclusion: Skips common hidden directories (
.git,node_modules,__pycache__, etc.) - Visual exclusion picker (macOS): Native Finder dialog where you can ⌘-click to select any mix of files AND folders to exclude - this is the neat trick! Want to exclude just one config file? Select it. Want to exclude an entire
tests/directory? Select that instead. Want both? ⌘-click them together! - Manual exclusions: Text-based exclusion entry for cross-platform support
- Multiple formats: Generate
.txtor.mdfiles - Table of contents: Auto-generated with navigation links (Markdown)
- Structured layout: Clear file separation with headers
- Timestamped output: Prevents accidental overwrites
- macOS: Native Finder dialogs with ⌘-click multi-select
- Windows/Linux: Standard file dialogs with folder integration
- Auto-reveal: Opens destination folder when complete
- Python 3.9 or higher
- tkinter (usually included with Python)
# Install from requirements file (recommended)
pip install -r requirements.txt
# Or install manually:
pip install PyPDF2 # For PDF text extraction
pip install pyobjc # For enhanced macOS integration (usually pre-installed)-
Clone this repository:
git clone https://github.com/DSado88/combination.git cd combination -
Create a virtual environment (recommended):
python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install optional dependencies:
pip install -r requirements.txt
python3 combination.pyOr use the included launch script (macOS/Linux):
chmod +x open_combination.sh
./open_combination.sh- Select Sources: Choose files and/or folders to consolidate (can be from different directories!)
- Smart Base Detection: Tool automatically finds the common ancestor directory
- Visual Exclusions (macOS): Use the native Finder picker to ⌘-click and exclude any mix of specific files, entire folders, or both
- Choose Format: Select
.txtor.mdoutput with auto-generated table of contents - Save: Pick destination and filename - smart defaults: if you selected a single folder, it defaults to that folder's name (e.g., "MyProject.txt"), otherwise "consolidated_project.txt" (gets timestamped automatically)
- Review: The tool opens the output folder automatically
Consolidated Project Files
Generated: 2024-01-15 14:30:22
Base: /Users/username/myproject
--- TABLE OF CONTENTS ---
1. src/main.py
2. src/utils.py
3. docs/README.md
--- END OF TABLE OF CONTENTS ---
--- FILE: src/main.py ---
#!/usr/bin/env python3
...
--- FILE: src/utils.py ---
def helper_function():
...
The tool automatically skips these common items:
- Hidden directories:
.git,.hg,.svn,.DS_Store - Build artifacts:
__pycache__,node_modules,dist,build - IDE files:
.vscode,.idea - Virtual environments:
venv,.env
Automatically skipped file types include:
- Images:
.png,.jpg,.gif, etc. - Media:
.mp3,.mp4,.mov, etc. - Archives:
.zip,.tar,.gz, etc. - Executables:
.exe,.dll,.so, etc.
These are always treated as text files:
.svg,.ipynb,.csv
- Repository consolidation for AI tools: Perfect for feeding entire codebases to ChatGPT, Claude, or other AI assistants for analysis, code review, or documentation generation
- Context preparation: Create comprehensive text dumps that fit within AI token limits while preserving project structure
- Code analysis: Consolidate repos for AI-powered code auditing, refactoring suggestions, or architectural reviews
- Project archives: Create comprehensive project snapshots for backup or sharing
- Content migration: Merge multiple documentation sources into unified documents
- Research: Combine academic papers, notes, and references
- Documentation: Generate readable project overviews with complete source visibility
- Smart filename defaults: When consolidating a single folder, the Save-As dialog automatically defaults to that folder's name (e.g., select "MyProject" folder → defaults to "MyProject.txt")
- Improved UX: Falls back to "consolidated_project.txt" for multi-selection scenarios
- Multi-source support: Select any mix of files and folders
- Common ancestor detection: Smart base directory calculation
- Enhanced macOS integration: Native Finder multi-select dialogs
- PDF extraction: PyPDF2 integration for PDF text content
- Cross-platform compatibility: Improved Windows/Linux support
- Binary detection: Enhanced file type recognition
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is open source. Feel free to use, modify, and distribute as needed.
If you encounter issues or have suggestions:
- Check the Issues page
- Create a new issue with detailed information about your problem
- Include your Python version and operating system
Note: This tool is designed for text-based content consolidation. While it handles various file types safely, it's optimized for source code, documentation, and other textual materials.