A powerful bidirectional converter between project files and human-readable YAML representations. Perfect for LLM-driven development workflows, code analysis, and project templating.

• Generate full project snapshots in YAML format with human-readable formatting
• Apply YAML files to recreate or modify projects elsewhere
• Generate incremental updates with unified diffs between project states
• Filter files by extension, gitignore rules, and custom patterns
• Human-readable output - no more escaped newlines in code files
• Configurable via YAML configuration files
• Global CLI tool - can be run from anywhere after installation
• Test integration - Run tests after applying changes
• Markdown export - Convert YAML to readable Markdown for LLM analysis

# Clone the repository
git clone <repository-url>
cd yaml_project

# Install dependencies
poetry install

# Install as global command
ln -sf $(pwd)/create-project-yaml /usr/local/bin/create-project-yaml

The tool is installed as create-project-yaml and can be run from any directory.

# Generate YAML of current directory (default behavior)
create-project-yaml

# Generate YAML of specific directory
create-project-yaml --project-dir /path/to/project

# Use custom output filename
create-project-yaml --outfile my-snapshot.yaml

# Generate full project snapshot
create-project-yaml generate full --project-dir /path/to/project --outfile project.yaml

# Generate diff between base and current state  
create-project-yaml generate diff --base previous.yaml --output changes.yaml --project-dir /path/to/project

# Apply YAML to create new project
create-project-yaml apply create project.yaml --output-dir /new/location

# Update existing project from YAML
create-project-yaml apply update project.yaml --output-dir /existing/project

# Apply only patches/diffs from YAML
create-project-yaml apply patch changes.yaml --output-dir /project

# Run tests defined in YAML
create-project-yaml test run tests.yaml --project-dir /project

# Convert YAML to Markdown for LLM analysis
create-project-yaml convert to-markdown --input project.yaml --output project.md

The tool creates a configuration file at .yamlproject/config.yaml with sensible defaults:

# Default output filename
outfile: project.yaml

# File extensions to include (40+ supported)
supported_extensions:
  .py: python
  .js: javascript
  .md: markdown
  .yaml: yaml
  # ... many more

# Directories to ignore
forbidden_dirs:
  - __pycache__
  - node_modules
  - .git
  - dist
  # ... and more

# Maximum file size (in bytes)
max_file_size: 204800

# YAML formatting options
yaml_format:
  indent: 2
  width: 120

You can customize any of these settings by editing the config file.

The tool generates human-readable YAML with the following structure:

metadata:
  version: 1.0.0
  timestamp: 2025-06-04 17:28:16.276713
  description: YAML snapshot of /path/to/project
  generator: yaml-project
  generator_version: 0.1.0

config:
  # Configuration used to generate this snapshot
  supported_extensions: {...}
  forbidden_dirs: [...]
  outfile: project.yaml
  # ... other config

content:
  files:
    README.md:
      content: |-
        # My Project
        
        This is a sample project demonstrating
        the YAML Project tool.
      metadata:
        extension: .md
        size_bytes: 153
        language: markdown
    
    src/main.py:
      content: |-
        #!/usr/bin/env python3
        """
        Main module for the project.
        """
        
        def main():
            print("Hello, World!")
        
        if __name__ == "__main__":
            main()
      metadata:
        extension: .py
        size_bytes: 234
        language: python

• Human-readable multiline strings - All code files use literal YAML style (|-) instead of escaped newlines
• Complete metadata - File extensions, sizes, detected languages
• Reproducible - Contains all configuration used to generate the snapshot
• Filterable - Only includes relevant files based on configuration

# Export project for LLM analysis
create-project-yaml --project-dir /my/project --outfile analysis.yaml

# Convert to Markdown for easier LLM reading
create-project-yaml convert to-markdown --input analysis.yaml --output analysis.md

# Apply LLM suggestions back to project
create-project-yaml apply update suggestions.yaml --output-dir /my/project

# Create template from existing project
create-project-yaml --project-dir /template/source --outfile template.yaml

# Create new project from template
create-project-yaml apply create template.yaml --output-dir /new/project

# Generate snapshot before changes
create-project-yaml --outfile before.yaml

# Make changes, then generate diff
create-project-yaml generate diff --base before.yaml --output changes.yaml

# Share the diff for review

# Apply changes and run tests
create-project-yaml apply update changes.yaml --output-dir /project
create-project-yaml test run tests.yaml --project-dir /project

# Generate test report
create-project-yaml test report --report-format html --output test-report.html

The tool supports 40+ file extensions including:

Programming Languages:

• Python (.py), JavaScript (.js, .jsx), TypeScript (.ts, .tsx)
• Java (.java), C/C++ (.c, .cpp, .h, .hpp), C# (.cs)
• Go (.go), Rust (.rs), Ruby (.rb), PHP (.php)
• Swift (.swift), Kotlin (.kt), Scala (.scala)
• Shell scripts (.sh), Perl (.pl), Lua (.lua)

Configuration & Data:

• YAML (.yaml, .yml), JSON (.json), TOML (.toml)
• XML (.xml), HTML (.html), CSS (.css)
• INI (.ini, .cfg), Properties (.properties)

Documentation:

• Markdown (.md), Text (.txt)

And more! The configuration is easily extensible.

The project follows a modular architecture:

• CLI Layer (cli.py): Command-line interface and argument parsing
• Configuration (config/): Configuration management and validation
• Core Logic (core/):
  • generator/: YAML generation and directory scanning
  • diff_handler/: Diff creation and application
  • yamilizer.py: Legacy compatibility layer
• Models (models/): Pydantic data models for validation
• Utilities (utils/):
  • test_runner/: Test execution and reporting
  • markdown_exporter/: YAML to Markdown conversion

• FullContentYAML: Complete project snapshots
• UpdateYAML: Incremental updates and patches
• TestCommand: Test execution configuration
• Config: Tool configuration

• Python 3.12+
• Poetry for dependency management
• Dependencies: pydantic, pyyaml, ruamel.yaml, pathspec, patch

# Set up development environment
poetry install

# Run tests
poetry run pytest

# Run specific test
poetry run pytest tests/unit/config/test_config_model.py

# Format code
poetry run black src tests
poetry run isort src tests

# Type checking
poetry run mypy src

The project includes comprehensive test coverage:

• Unit tests: Test individual components in isolation
• Integration tests: Test component interactions
• End-to-end tests: Test complete workflows

Run all tests:

poetry run pytest

Run with coverage:

poetry run pytest --cov=yaml_project --cov-report=html

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run the test suite
5. Submit a pull request

MIT License - see LICENSE file for details

Permission denied when installing globally:

sudo ln -sf $(pwd)/create-project-yaml /usr/local/bin/create-project-yaml

Large files being excluded: Increase max_file_size in .yamlproject/config.yaml

Unwanted files being included: Add patterns to forbidden_dirs or use --exclude flag

YAML files too large: Enable chunking in configuration:

chunking_enabled: true
chunk_size: 1048576  # 1MB chunks

For more issues, see the troubleshooting guide in the documentation.