dirmd/README.md

# dirmd

Generate markdown documentation from directory structure. Optimized for LLM ingestion.

<video src="./docs/videos/dirmd.webm" autoplay loop muted playsinline></video>

## Features

- Recursive directory traversal
- ASCII tree visualization (LLM-friendly, minimal token overhead)
- Full file contents with explicit delimiters and metadata
- Filters dotfiles, binaries, and blacklisted extensions
- Vertical slices mode: root file + one markdown per top-level directory
- Append mode for single files or directories
- Force overwrite of existing output files
- Configurable depth, file size limits, ignore patterns
- Optional upload to Proton Drive after generating output
- Skip frontend files (`.html`, `.css`, `.js`, etc.)
- Frontend only mode (include only frontend files and `README.md`)
- Omit test files and inline test blocks (Go, Java, Rust)

## Installation
Only for linux.  
Download binary from release page or install with go 
```bash
go install git.flo.fo/FLO/dirmd@latest
```

## Use with Git Post Hook
combine with git post hook to sync with proton drive on each commit

add something like this in ./.git/hooks/post-commit

```bash
#!/bin/bash

set -euo pipefail

if ! command -v dirmd &>/dev/null; then
    exit 0
fi

REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename "$REPO_ROOT")

dirmd -o "/tmp/${REPO_NAME}" "$REPO_ROOT" -f --vertical-slices --proton-drive
```


## Build

    go build -o dirmd .

## Usage

    # Create new documentation
    dirmd -o output.md ~/repos/myproject

    # Overwrite existing output file
    dirmd -o output.md ~/repos/myproject -f

    # Append a single file
    dirmd -a -i README.md -o existing.md

    # Append another directory
    dirmd -a ~/repos/anotherproject -o existing.md

    # Generate with vertical slices
    dirmd -o output.md ~/repos/myproject --vertical-slices

    # Skip frontend files (.html, .css, .js, etc.)
    dirmd -o output.md ~/repos/myproject --skip-frontend

    # Frontend only (include only frontend files and README.md)
    dirmd -o output.md ~/repos/myproject --frontend-only

    # Omit test files and inline test blocks
    # Go: excludes *_test.go
    # Java: excludes *Test.java, *Tests.java, src/test/java/*
    # Rust: strips #[cfg(test)] mod tests { ... } blocks
    dirmd -o output.md ~/repos/myproject --omit-test

    # Combine filters
    dirmd -o output.md ~/repos/myproject --frontend-only --omit-test

    # Generate and upload to Proton Drive (default: /my-files/md/<filename>)
    dirmd -o output.md ~/repos/myproject --proton-drive

    # Generate and upload to a specific remote path
    dirmd -o output.md ~/repos/myproject --proton-drive --drive-path /my-files/docs/api.md

## Test File Omission

The `--omit-test` flag removes test files and inline test blocks to reduce token overhead in LLM context windows. Behavior varies by language:

| Language | Exclusion Strategy | What Gets Removed |
|----------|-------------------|-------------------|
| **Go** | File exclusion | All `*_test.go` files |
| **Java** | File exclusion | `*Test.java`, `*Tests.java`, files under `src/test/java/` |
| **Rust** | Content stripping | Entire `#[cfg(test)] mod tests { ... }` blocks removed from `.rs` files |

The Rust stripping works by detecting the `#[cfg(test)]` attribute, then tracking brace depth until the module closes. Nested braces in string literals may occasionally throw off the count, but this is acceptable for RAG use cases.

## Frontend Filtering

Two complementary flags control frontend file inclusion:

| Flag | Effect |
|------|--------|
| `--skip-frontend` | Exclude frontend files, keep everything else |
| `--frontend-only` | Include only frontend files and `README.md`, exclude everything else |

Frontend extensions covered:

| Type | Extensions |
|------|------------|
| Templates | `.html`, `.htm`, `.gohtml`, `.tmpl` |
| Stylesheets | `.css`, `.scss`, `.sass`, `.less` |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |
| TypeScript | `.ts`, `.tsx` |
| Frameworks | `.vue`, `.svelte` |

`--skip-frontend` and `--frontend-only` are mutually exclusive. Both can be combined with `--omit-test`.

## Vertical Slices Mode

When `--vertical-slices` is passed, dirmd splits output into multiple files instead of one monolithic document:

- **Root file** (`-o output.md`): Full directory tree with cross-references to slice files, a vertical slices index table (file counts, total bytes per directory), and full contents of all root-level files.
- **Slice files** (`cmd.md`, `internal.md`, etc.): One per top-level directory, placed alongside the root file. Each contains its own tree, a back-reference to the root document, and full recursive file contents for that directory.

This mode cannot be combined with `--append` or `--input-file`.

Example output with `dirmd -o docs.md ~/repos/myproject --vertical-slices`:

    docs/
    ├── docs.md          ← root: tree + slices index + root file contents
    ├── cmd.md           ← slice: tree + contents of cmd/
    └── internal.md      ← slice: tree + contents of internal/

## Instructions File (`.dirmd`)

If a file named `.dirmd` exists in the root of the input directory, you can include its contents as metadata in the generated output by passing the `--instructions` flag.

This is useful for injecting specific context, constraints, or instructions for LLMs processing the snapshot.

- **File Name**: `.dirmd`
- **Location**: Root of the input directory.
- **Format**: Plain text or Markdown.
- **Output**: Rendered as a quoted block (`> Instructions: ...`) immediately after the timestamp and commit info.
- **Opt-in**: The file is **ignored** unless `--instructions` is explicitly passed.

Example `.dirmd`:

```text
Focus on the `internal/` package for business logic.
Ignore `cmd/` unless explicitly asked.
Prioritize Go files over Python.
```

## LLM-Optimized Output

Output is designed for RAG ingestion and LLM context windows, not human presentation:

- **ISO 8601 Timestamp**: Added as a metadata line (`> Generated: ...`) immediately after the H1 header for every new file created.
- **Git Commit Info**: If the source directory is a Git repository, a second metadata line (`> Commit: <sha> (<message>)`) is added below the timestamp.
- **ASCII tree format** (`+-` instead of Unicode box-drawing) to reduce token overhead
- **Explicit file delimiters**: `--- FILE: ./path (bytes, lines) ---` and `--- END FILE ---`
- **Document type markers**: `[ROOT]` and `[SLICE]` in H1 headers
- **Cross-references**: Directory entries in root tree show `-> see cmd.md`; slice files reference their root document
- **Slices index table**: File counts and total bytes per slice for informed retrieval decisions
- **Tilde fences** (`~~~`) to avoid conflicts with backticks in source files

## Flags

| Flag | Description | Default |
|------|-------------|---------|
| `-o`, `--output` | Output markdown file path (required) | |
| `-a`, `--append` | Append to existing output file | false |
| `-f`, `--force` | Overwrite existing output file (non-append mode) | false |
| `-i`, `--input-file` | Single file input (append mode only) | |
| `--vertical-slices` | Split output into root file + one markdown per top-level directory | false |
| `--max-size` | Max file size in bytes | 524288 |
| `--max-depth` | Max directory recursion depth | 20 |
| `--ignore` | Additional ignore patterns (glob) | |
| `--extensions` | Additional file extensions to skip | |
| `--proton-drive` | Upload output to Proton Drive after writing locally | false |
| `--drive-path` | Full remote path on Proton Drive (e.g. /my-files/md/report.md) | /my-files/md/<filename> |
| `--skip-frontend` | Omit frontend file types (.html, .css, .js, .ts, .vue, .svelte, etc.) | false |
| `--frontend-only` | Include only frontend file types and README.md | false |
| `--omit-test` | Exclude test files (Go *_test.go, Java *Test.java) and strip #[cfg(test)] blocks from Rust | false |

## Proton Drive Integration

dirmd can optionally upload the generated markdown file(s) to Proton Drive using the [Proton Drive CLI](https://proton.me/support/drive-cli). The upload is performed only when `--proton-drive` is passed. Without it, dirmd behaves exactly as before — no Proton Drive dependency is required.

In vertical slices mode, all generated files (root + slices) are uploaded to `/my-files/md/`. The `--drive-path` flag is ignored in slices mode ; each file is uploaded by its basename.

### Prerequisites

1. Install the Proton Drive CLI — see the [official guide](https://proton.me/support/drive-cli) for download and installation instructions.
2. Authenticate by running `proton-drive auth login`.
3. Ensure `proton-drive` is in your PATH.

If the CLI is not installed or you are not logged in, dirmd will report the error to stderr and exit with a non-zero code. Local files are always written successfully before the upload is attempted.

For full documentation on the Proton Drive CLI, including installation, authentication, and troubleshooting, refer to the [official Proton Drive CLI support page](https://proton.me/support/drive-cli).

## Examples

    # Custom depth and size limit
    dirmd -o output.md ~/repos/project --max-depth 5 --max-size 262144

    # Ignore specific directories
    dirmd -o output.md ~/repos/project --ignore __pycache__ --ignore .venv

    # Skip additional file extensions
    dirmd -o output.md ~/repos/project --extensions .log --extensions .tmp

    # Vertical slices with overwrite
    dirmd -o docs.md ~/repos/project -f --vertical-slices

    # Skip frontend and omit tests
    dirmd -o docs.md ~/repos/project -f --skip-frontend --omit-test

    # Frontend only with test omission
    dirmd -o docs.md ~/repos/project -f --frontend-only --omit-test

    # Generate, then upload to default remote location
    dirmd -o docs.md ~/repos/project --proton-drive

    # Generate, then upload to a custom remote location
    dirmd -o docs.md ~/repos/project --proton-drive --drive-path /my-files/projects/docs.md

    # Overwrite existing local file and upload to Drive
    dirmd -o docs.md ~/repos/project -f --proton-drive

## Output Format

Produces markdown with:

1. Absolute path as H1 header with `[ROOT]` or `[SLICE]` marker
2. **Timestamp metadata line** (ISO 8601) immediately after the H1 header (only for new files)
3. ASCII directory tree (indented with `+-` and `|` characters)
4. Vertical slices index table (sliced mode only)
5. All text files with content in fenced code blocks
6. Explicit `--- FILE: ---` and `--- END FILE ---` delimiters with byte and line counts
7. Language detection from file extensions

Example output structure (non-sliced mode):

    # /home/user/repos/myproject [ROOT]
    > Generated: 2026-09-02T14:30:00Z
    > Commit: a1b2c3d (Fix login bug)

    ## Directory Tree

    ~~~
    myproject/
    +- cmd/
    |   +- main.go
    +- internal/
    |   +- config.go
    ~~~

    ## Contents

    --- FILE: ./cmd/main.go (45 bytes, 3 lines) ---
    ~~~go
    package main

    func main() {}
    ~~~
    --- END FILE ---

Note: Uses tilde fences (~~~) internally to avoid conflicts with nested backticks in source files.