m1f-init Tool

The m1f-init command provides a quick and easy way to set up m1f in any project, creating a standardized structure with pre-configured bundles.

Overview

m1f-init automatically:

Creates an m1f/ directory in your project
Generates project-specific bundles (complete and documentation)
Creates file and directory lists for analysis
Sets up a .m1f.config.yml configuration file
Optionally creates a symlink to m1f documentation

Installation

The m1f-init command is included with the m1f installation. Make sure m1f is properly installed and the alias is set up:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
alias m1f-init='python /path/to/m1f/tools/m1f_init.py'

Basic Usage

Navigate to your project directory and run:

cd /your/project
m1f-init

This creates the following structure:

m1f/
├── <project>_complete.txt          # Full project bundle
├── <project>_complete_filelist.txt # List of all included files
├── <project>_complete_dirlist.txt  # List of all directories
├── <project>_docs.txt              # Documentation bundle
├── <project>_docs_filelist.txt    # List of documentation files
├── <project>_docs_dirlist.txt     # Documentation directories
└── .m1f.config.yml                # Configuration file

Command Options

`--no-symlink`

Skip creating a symlink to m1f documentation:

m1f-init --no-symlink

`--project-name`

Specify a custom project name (default: current directory name):

m1f-init --project-name "my-awesome-project"

`--output-dir`

Specify a different output directory (default: ./m1f):

m1f-init --output-dir "./bundles"

Generated Files

Complete Bundle

The <project>_complete.txt file contains all project files (excluding common build artifacts, dependencies, etc.). This bundle:

Includes all source code files
Excludes node_modules, .git, build directories
Respects .gitignore patterns
Provides full project context for AI analysis

Documentation Bundle

The <project>_docs.txt file contains only documentation files with these extensions:

.md, .txt, .rst, .org, .tex, .info, .adoc, .asciidoc, .changelog,
.changes, .creole, .faq, .feature, .help, .history, .lhs, .litcoffee,
.ltx, .man, .markdown, .mdx, .pod, .rdoc, .readme, .release, .rmd,
.rtf, .story, .textile, .todo, .wiki, and more...

File Lists

The _filelist.txt files contain:

One file path per line
Relative paths from the project root
Can be edited and used as input for custom bundles

Example usage:

# Edit the file list
vi m1f/myproject_complete_filelist.txt

# Create custom bundle from edited list
m1f -i m1f/myproject_complete_filelist.txt -o m1f/custom_bundle.txt

Configuration File

The .m1f.config.yml file defines multiple bundle configurations:

bundles:
  <project>_complete:
    description: "Complete project bundle"
    source_directory: ".."
    output_file: "m1f/<project>_complete.txt"
    excludes:
      - "m1f/"
      - "*.pyc"
      - "__pycache__"
    exclude_paths_file: "../.gitignore"
    separator_style: "Detailed"
    
  <project>_docs:
    description: "Documentation bundle"
    source_directory: ".."
    output_file: "m1f/<project>_docs.txt"
    include_extensions:
      - ".md"
      - ".txt"
      - ".rst"
      # ... (all documentation extensions)
    excludes:
      - "m1f/"
    exclude_paths_file: "../.gitignore"
    separator_style: "Markdown"

Updating Bundles

After initial setup, update your bundles using:

# Update all bundles
m1f auto-bundle

# Or use the alias
m1f-update

# Update specific bundle
m1f-update <project>_complete

Common Workflows

Initial Project Analysis

# 1. Initialize m1f in your project
cd /path/to/project
m1f-init

# 2. Review generated file lists
cat m1f/*_filelist.txt | wc -l  # Count total files
head m1f/*_complete_filelist.txt # View included files

# 3. Update bundles after changes
m1f-update

Custom Bundle Creation

# 1. Initialize to get file lists
m1f-init

# 2. Create custom file list
grep -E '\.(js|jsx|ts|tsx)$' m1f/*_complete_filelist.txt > m1f/frontend_files.txt

# 3. Generate custom bundle
m1f -i m1f/frontend_files.txt -o m1f/frontend_bundle.txt

CI/CD Integration

# In your build script
m1f-init --no-symlink
m1f-update
# Now m1f/ contains fresh bundles for deployment/analysis

Best Practices

Run m1f-init at project root - This ensures correct relative paths
Review generated file lists - Verify included/excluded files match expectations
Customize .m1f.config.yml - Add project-specific bundles as needed
Use —no-symlink in CI/CD - Avoid filesystem dependencies in automated environments
Keep bundles updated - Run m1f-update regularly during development

Troubleshooting

Permission Errors

If you get permission errors, ensure:

You have write permissions in the current directory
The m1f installation directory is accessible

Missing Files

If expected files are missing from bundles:

Check your .gitignore patterns
Review the excludes in .m1f.config.yml
Verify file extensions are included

Large Bundle Sizes

For very large projects:

Use --max-file-size in the config to skip large files
Create focused bundles for specific components
Exclude test data and generated files

Advanced Configuration

Edit .m1f.config.yml to create specialized bundles:

bundles:
  frontend:
    description: "Frontend code only"
    source_directory: ".."
    output_file: "m1f/frontend.txt"
    include_extensions: [".js", ".jsx", ".ts", ".tsx", ".css", ".scss"]
    excludes: ["node_modules/", "dist/", "build/"]
    
  backend:
    description: "Backend code only"
    source_directory: ".."
    output_file: "m1f/backend.txt"
    include_extensions: [".py", ".go", ".java"]
    excludes: ["tests/", "__pycache__/"]
    
  config:
    description: "Configuration files"
    source_directory: ".."
    output_file: "m1f/config.txt"
    include_paths_file: "config-files.txt"
    separator_style: "Markdown"