Documentation

Overview

m1f ("Make One File") and s1f ("Split One File") are specialized utilities designed to:

1. Combine multiple project files into a single reference file - perfect for providing context to LLMs
2. Extract individual files from a combined file - restore original files with their structure intact

These tools help solve a core challenge when working with AI assistants: providing comprehensive context efficiently.

Setup

# Create and activate a virtual environment
python -m venv .venv
# On Windows
.venv\Scripts\activate
# On macOS/Linux
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
        

m1f (Make One File)

Combines multiple files into a single file with rich metadata and customizable formatting.

Key Features

• Multiple input sources (directories or file lists)
• Smart file filtering and deduplication
• Customizable separator styles for different use cases
• Token counting for LLM context planning
• Comprehensive metadata for each file
• Versioning support through content hashing

Basic Usage

# Combine files from a source directory
python tools/m1f.py --source-directory /path/to/your/code --output-file /path/to/combined_output.txt

# Using an input file containing paths to process
python tools/m1f.py -i filelist.txt -o combined_output.txt

# Using MachineReadable style with verbose logging
python tools/m1f.py -s ./my_project -o ./output/bundle.m1f.txt --separator-style MachineReadable --force --verbose
        

s1f (Split One File)

Extracts individual files from a combined file, recreating the original directory structure.

Key Features

• Preserves original file paths and timestamps
• Verifies file integrity with SHA256 checksums
• Supports all m1f separator styles
• Simple and secure extraction process

Basic Usage

# Basic command
python tools/s1f.py --input-file /path/to/combined_output.txt --destination-directory /path/to/output_folder

# Splitting a MachineReadable file with force overwrite and verbose output
python tools/s1f.py -i ./output/bundle.m1f.txt -d ./extracted_project -f -v

# Using current system time for timestamps
python tools/s1f.py -i ./combined_file.txt -d ./extracted_files --timestamp-mode current
        

Best Practices for LLM Context

• Be selective: Choose only the most important 20-50 files for your current task
• Include structure files: Add README.md, configuration files, and key interfaces
• Group related files: Organize files by related functionality
• Refresh context files: Create new context files for different tasks
• Comment your file lists: Add comments to explain why files are included

Common Use Cases

# Create a complete documentation bundle from all markdown files
python tools/m1f.py -s ./docs -o ./doc_bundle.m1f.txt --include-extensions .md
            

# Bundle specific components for code review
python tools/m1f.py -i code_review_files.txt -o ./review_bundle.m1f.txt
            

# Create a searchable knowledge base from project documentation
python tools/m1f.py -s ./project -o ./knowledge_base.m1f.txt \
  --include-extensions .md .txt .rst --minimal-output
            

Further Reading

For complete documentation including all command-line options, please visit:

• GitHub Repository