Skip to content

Dry Run Mode Structure Preview

Jump to bottom
github-actions[bot] edited this page Mar 14, 2026 · 1 revision

Dry-Run Mode & Structure Preview

Dry-run mode (-dry-run flag) enables validation of wiki structure and page planning without consuming time and resources to generate actual page content. This feature is valuable for previewing the analysis results, validating repository structure detection, confirming page count, and verifying that wikigen correctly understands the codebase before committing to full generation.

Overview

Dry-run mode executes the first phase of the wiki generation pipeline—repository analysis and structure determination—then exits before phase two (content generation). The mode stops after Claude analyzes the codebase and returns a planned wiki structure as XML, avoiding the expensive page generation step.

This page covers:

  • How dry-run mode works within the wiki generation pipeline
  • Invoking dry-run with flags and options
  • Output format and where to find results
  • When to use dry-run for validation
  • Integration with the broader Architecture & Design workflow

Activation & Usage

Flag Definition

Dry-run mode is activated via the -dry-run boolean flag:

wikigen -dry-run -r owner/repo
wikigen -dry-run -f repos.txt
wikigen -dry-run -r project:owner/repo1 project:owner/repo2

Sources: wikigen/main.go:903

Positional Arguments

Dry-run mode respects the same repository input formats as normal generation:

  • Single repository: wikigen -dry-run -r owner/repo
  • Multiple repositories via flag: wikigen -dry-run -r owner/repo1,owner/repo2
  • File-based input: wikigen -dry-run -f repos.txt (one repository per line)
  • Grouped repositories: wikigen -dry-run -r project:owner/repo1 project:owner/repo2 (multiple repos into single wiki)

Sources: wikigen/main.go:907, 919-925

Combining with Other Flags

Dry-run can be combined with other flags to customize validation behavior:

Flag Effect Default
-r Repository list (comma-separated) None
-f File containing repository list None
-o Output directory for structure files ./wiki-output
-clone-dir Directory for cloned repositories ./.repos
-local Use local directory instead of cloning None
-lang Output language for structure ja (Japanese)
-model Claude model to use for analysis Default (configurable)
-p Parallel repository processing 1
-json Output results as JSON False

Sources: wikigen/main.go:902-916

Workflow & Execution

Two-Phase Pipeline Overview

Wikigen follows a two-phase approach described in Architecture & Design:

Phase 1: Structure Determination → This is where dry-run stops Phase 2: Content Generation → Skipped in dry-run mode

Dry-Run Execution Steps

The dry-run mode executes the following sequence and then exits:

graph TD
    A["Start: -dry-run flag activated"] --> B["Load environment & configuration"]
    B --> C["Validate repository inputs"]
    C --> D["Step 0: Clone or locate repositories"]
    D --> E["Create output directory"]
    E --> F["Step 1: Determine wiki structure<br/>(Claude analyzes codebase)"]
    F --> G["Parse XML structure response"]
    G --> H["Calculate total pages<br/>(len allPages)"]
    H --> I["Write Home.md & Sidebar.md<br/>(navigation structure)"]
    I --> J["Report: 'Dry run: N pages planned'"]
    J --> K["Exit with status: dry-run"]
Loading

Sources: wikigen/main.go:474-563

Step 0: Repository Access

If not using local mode (-local flag), wikigen clones repositories at depth 1:

  • With GitHub PAT token: Uses HTTPS with token substitution
  • Without token: Falls back to SSH key authentication
  • Already cloned: Performs git pull --ff-only to update existing clones

Sources: wikigen/main.go:147-171, 492-517

Step 1: Structure Determination

Wikigen invokes Claude with the structure analysis prompt, which instructs Claude to:

  1. Examine the codebase using available tools (Read, Grep, Glob, Bash)
  2. Identify documentation categories that apply to the repositories
  3. Return a planned wiki structure as XML
  4. The structure includes page titles, filenames, descriptions, and relationships

The structure prompt specifies:

  • Core documentation categories (System Overview, Architecture, API Specification, Data Model, etc.)
  • Inferred documentation categories (Processing Flows, Security Design, Performance Considerations)
  • Rules for multi-repository projects (cross-repository documentation)
  • Requirements: pages must map to actual code evidence

Sources: wikigen/main.go:183-273

Step 1b: XML Parsing & Home/Sidebar Generation

After structure determination, wikigen:

  1. Cleans the XML response (removes markdown code fences if present)
  2. Parses the XML to extract page metadata:
    • Page title, filename, description, importance, relevant files
    • Related pages and cross-references
  3. Populates result object with calculated total page count
  4. Writes navigation files:
    • Home.md — Table of contents with project description and page list
    • _Sidebar.md — Navigation sidebar with page links

Sources: wikigen/main.go:533-548, 640-667

Step 2: Skipped in Dry-Run

Content generation (the expensive operation) is completely skipped. This phase normally:

  • Generates individual wiki pages
  • Implements parallel page generation (with -pp flag)
  • Manages retry logic for failed pages
  • Logs errors to _errors.log

Sources: wikigen/main.go:558-563

Output & Results

Stderr Output

During execution, dry-run prints real-time progress to stderr:

🚀 Processing 1 wikis (parallel: 1, pages: 3, model: default, dry-run)

[project] 📋 structure...
[project] 📋 structure...
[project] Dry run: 12 pages planned in ./wiki-output/project/

The progress line shows:

  • Repository name/project name
  • Current phase (📋 structure analysis)
  • Completion message with page count and output path

Sources: wikigen/main.go:560, 1007-1017

File Output

Dry-run generates the following files in the output directory:

Generated Files

  1. Home.md — Main wiki page with:

    • Project title
    • Project description (extracted from Claude's analysis)
    • Repository list (if multi-repo)
    • Generation timestamp
    • Complete page index with descriptions

  2. _Sidebar.md — Navigation sidebar with:

    • Home page link
    • All planned pages as navigation links
    • Used by GitHub Wiki for left-side navigation

Example structure in ./wiki-output/project/:

Home.md            # Table of contents
_Sidebar.md        # Navigation sidebar
(no .md files yet)  # Content generation skipped

Sources: wikigen/main.go:640-667

JSON Output

With the -json flag, dry-run outputs structured results to stdout:

[
  {
    "project": "myproject",
    "repos": ["owner/repo"],
    "output_dir": "/absolute/path/to/wiki-output/myproject",
    "pages": [
      {
        "title": "System Overview",
        "filename": "System-Overview",
        "size": 0,
        "status": "pending"
      },
      {
        "title": "Architecture & Design",
        "filename": "Architecture-Design",
        "size": 0,
        "status": "pending"
      }
    ],
    "total_pages": 12,
    "failed": 0,
    "duration": "45s",
    "status": "dry-run"
  }
]

The JSON structure includes:

  • Project metadata (name, repositories, output path)
  • Planned pages with status: "pending" (not yet generated)
  • Total page count
  • Overall status: "dry-run"

Sources: wikigen/main.go:96-112, 552-554, 1058-1061

Result Status

The WikiResult object contains:

  • Status: Set to "dry-run" on successful completion
  • TotalPages: Calculated from the XML structure
  • Pages: Array of page metadata with status "pending"
  • Failed: Always 0 (no pages generated)

Sources: wikigen/main.go:96-112, 559-560

Use Cases & Validation Scenarios

1. Preview Wiki Structure Before Generation

Validate that wikigen correctly understands your codebase:

wikigen -dry-run -r owner/repo -lang en

Output shows:

  • How many pages wikigen plans to create
  • Page titles and descriptions
  • Where the wiki will be generated

2. Validate Multi-Repository Projects

For projects with multiple repositories, confirm correct cross-repository documentation:

wikigen -dry-run -r project:owner/repo1 project:owner/repo2 project:owner/repo3

Verify:

  • Page count is proportional to project complexity
  • Cross-repository pages are planned
  • Individual repository pages are included

3. Test Language-Specific Output

Verify structure determination in different languages:

wikigen -dry-run -r owner/repo -lang en   # English
wikigen -dry-run -r owner/repo -lang ja   # Japanese
wikigen -dry-run -r owner/repo -lang es   # Spanish

Sources: wikigen/main.go:910, 183-190

4. Validate Repository Access

Ensure wikigen can clone and analyze the repository:

wikigen -dry-run -r owner/repo -token $GITHUB_TOKEN

If the repository cannot be cloned or analyzed, the error appears immediately without wasting time on content generation.

5. Estimate Generation Scope

Use page count to estimate generation duration:

  • Small projects (3-5 pages): ~30-60 seconds generation time
  • Medium projects (10-15 pages): ~2-3 minutes generation time
  • Large projects (30+ pages): ~5-10 minutes or more

Dry-run shows page count in seconds; actual generation scales accordingly.

6. Batch Processing Validation

Before running batch generation with -f repos.txt:

wikigen -dry-run -f repos.txt

Verify all repositories in the file are valid and analyzable before committing to full wiki generation.

Progress Tracking

Dry-run displays real-time progress using the same progress tracking system as full generation:

[project] 📋 structure...
[project] 📋 structure...
[0/1 100%] [project] Dry run: 8 pages planned in ./wiki-output/project/

Progress fields:

  • [X/Y Z%] — Completed projects / Total projects / Percentage
  • Project name — Current project being analyzed
  • Status indicator — Phase emoji (📋 for structure)
  • Phase details — What phase is running (structure analysis)

Sources: wikigen/main.go:39-58, 560

Integration with Full Generation

Dry-run is a non-destructive validation step that can be followed by full generation:

# 1. Validate structure
wikigen -dry-run -r owner/repo -lang en

# 2. If satisfied, generate full wiki
wikigen -r owner/repo -lang en -o ./wiki-output

The full generation:

  • Re-analyzes the repository structure (regenerates Home.md and _Sidebar.md)
  • Generates all planned pages with content
  • Creates _errors.log if any pages fail
  • Can use -retry flag to regenerate only failed pages

For details on full generation and error handling, see Error Handling & Retry Mechanism.

Combining with Local Mode

Dry-run can validate structure without cloning:

wikigen -dry-run -local ./my-local-repo
wikigen -dry-run -local ./my-local-repo myproject

With -local:

  • No git clone is performed
  • Repository is analyzed from the local filesystem
  • Useful for offline validation or analyzing uncommitted code

Sources: wikigen/main.go:492-495, 905, 920-921

Troubleshooting & Common Issues

Issue: "no pages found in structure"

Cause: Claude analyzed the repository but returned empty structure (no documentation categories matched the codebase)

Solution:

  • Verify the repository has substantial code
  • Check repository language and structure
  • Try with -lang en for debugging

Issue: Git clone fails

Cause: Repository is private or PAT token is invalid

Solution:

# With GitHub PAT
wikigen -dry-run -r owner/repo -token $GITHUB_TOKEN

# With SSH keys (public or properly configured private repos)
wikigen -dry-run -r owner/repo

Issue: Claude CLI not found

Cause: Claude CLI is not installed or not in PATH

Solution:

# Install Claude CLI
# Then verify installation
which claude
claude --version

# Or specify explicit path
wikigen -dry-run -r owner/repo -claude /path/to/claude

Sources: wikigen/main.go:936-939

Environment Variables & Configuration

Dry-run respects all environment variables used by wikigen:

Variable Effect
GITHUB_TOKEN Used for repository authentication (if -token not specified)
WIKI_OUTPUT_DIR Output directory (default: ./wiki-output)
WIKI_CLONE_DIR Clone directory (default: ./.repos)
WIKI_LANGUAGE Default output language (default: ja)
WIKI_PARALLEL Repository-level parallelism (default: 1)
WIKI_PAGE_PARALLEL Page-level parallelism (default: 3)
CLAUDE_MODEL Claude model to use

Sources: wikigen/main.go:694-717, 909-915

These can be set in .env or .env.local files. See Configuration & Environment Variables for detailed documentation.

Performance Characteristics

Dry-run mode is significantly faster than full generation:

Dry-run (structure only):

  • Duration: 30-60 seconds typical
  • What happens: Repository clone (if needed) + structure analysis
  • Output: Page plan and navigation files

Full generation:

  • Duration: Minutes to hours (scales with page count)
  • What happens: Repository clone + structure analysis + page generation
  • Output: Complete wiki with all pages

The speedup from dry-run allows rapid iteration on structure validation before committing to expensive content generation.

Related Pages

Home

Clone this wiki locally