Git Presented

Transform Git commits into presentation slides automatically. This skill helps you work with Git Presented, a Jigsaw-based static site generator that reads Git history and renders commits tagged with `#presentation` as navigable slides.

What This Skill Does

This skill provides expert guidance for developing, modifying, and debugging the Git Presented codebase. It understands the architecture, build process, and key patterns used in the project.

Instructions

Understanding the Architecture

When working with this codebase, recognize the two-layer architecture:

1. **Git Domain Layer** (`app/Git/`):

- `Model/` contains value objects: `Commit`, `Branch`, `Presentation`, `Step`, `SubSlide`, `Author`, `FileChange`

- `Parser/` contains Git CLI wrappers: `GitCommandRunner`, `CommitParser`, `BranchParser`, `PresentationBuilder`

- `Repository.php` is the main facade

- `Provider/GitDataProvider.php` exposes data to Jigsaw

2. **Jigsaw Layer** (`source/`, `config.php`, `helpers.php`, `bootstrap.php`):

- `config.php` builds collections from Git data

- `helpers.php` provides Git configuration helpers

- `bootstrap.php` handles Jigsaw events

- `source/_layouts/` contains Blade layout templates

- `source/_partials/` contains reusable Blade components

Data Flow

Understand the data pipeline:

```

Git Repository → GitCommandRunner → Parsers → PresentationBuilder → Repository → config.php → Blade templates → Static site

```

Key Concepts

Build Commands

Use these commands for development:

```bash

composer install # Install dependencies

php jigsaw build # Build for development (build_local/)

php jigsaw build production # Build for production (build_production/)

php jigsaw serve # Start dev server on localhost:8000

composer dump-autoload # Regenerate autoload after adding classes

```

Adding New Git Models

When adding a new Git model:

1. Create class in `app/Git/Model/`

2. Add parsing logic in appropriate parser (`app/Git/Parser/`)

3. Expose via `Repository.php`

4. Add to collection in `config.php` (store ID only, not the object)

5. Create layout in `source/_layouts/` that looks up the object

6. Run `composer dump-autoload`

Working with Collections

**CRITICAL**: Jigsaw collections must contain only primitive data (IDs, titles) because they're serialized to YAML. Never store:

Instead:

Git Command Execution

Always use `GitCommandRunner` for Git commands. **Shell escaping is critical**:

```php

$runner = new GitCommandRunner('/path/to/repo');

// Use escapeshellarg for format strings with special chars (<, >, %, etc.)

$format = escapeshellarg('--format=%H %an <%ae>');

$output = $runner->runRaw("log {$format} -10");

```

Modifying Templates

When editing Blade templates:

Configuration

Environment variables in `.env`:

File Structure

```

├── app/Git/ # PHP domain layer

│ ├── Model/ # Value objects

│ ├── Parser/ # Git CLI wrappers

│ ├── Provider/ # Jigsaw data provider

│ └── Repository.php # Main facade

├── source/ # Blade templates

│ ├── _layouts/ # Page layouts

│ ├── _partials/ # Reusable components

│ └── index.blade.php # Home page

├── config.php # Jigsaw configuration

├── helpers.php # Git config helpers

├── bootstrap.php # Jigsaw event handlers

├── .env # Environment config (gitignored)

└── .env.example # Example configuration

```

Important Notes

1. **Never store objects in collections** - Only primitives (IDs, strings, numbers)

2. **Always escape Git format strings** - Use `escapeshellarg()` for strings with `<>()%`

3. **Load large data on-demand** - Diffs and file trees should be loaded in templates, not collections

4. **Run `composer dump-autoload`** - Required after adding new PHP classes

5. **Presentations come from `#presentation` tags** - Commits must be tagged to appear as slides

Examples

Creating a new slide

Tag a commit with `#presentation` in the commit message:

```bash

git commit -m "Add authentication #presentation"

```

Adding subslides

Use `## Heading` in commit body:

```

Add authentication #presentation

Overview

This step adds user authentication.

Implementation

Uses JWT tokens for session management.

```

Referencing code

Use `[filename:start-end]` syntax in commit body:

```

[src/auth.php:10-25]

```