Skip to main content
The moon debug command provides utilities for inspecting and debugging moon’s internal state, loaded configuration, and VCS integration. 
moon debug <subcommand>

​
Subcommands

​
config

Debug all loaded configuration files and settings. 
moon debug config
This outputs detailed debug information for:
  • Workspace configuration (workspace.yml)
  • Extensions configuration (extensions.yml)
  • Toolchains configuration (toolchains.yml)
  • Tasks configuration (tasks.yml and inherited task configs)
The output uses Rust’s dbg! macro, providing deeply nested structure inspection with file locations and line numbers.

​
vcs

Debug the Version Control System (VCS) integration. 
moon debug vcs
This outputs:
  • VCS configuration - Settings from workspace.yml
  • VCS adapter details - Active VCS provider and settings
  • Branch information:
    • Default branch name
    • Default branch revision/commit
    • Current local branch name
    • Current local branch revision/commit
  • Changed files - Files modified in the working directory
  • Changed files against previous revision - Files changed compared to HEAD

​
How it works

  1. Loads the moon session with full workspace context
  2. Accesses internal configuration and state objects
  3. Outputs debug information using Rust’s debug formatting
  4. For VCS debugging, queries the VCS adapter for real-time information
The output is designed for:
  • Troubleshooting configuration issues
  • Understanding how moon loads and merges configuration
  • Debugging VCS integration problems
  • Reporting issues with detailed environment information

​
Examples

​
Debug configuration

moon debug config
Example output: 
&session.workspace_config = WorkspaceConfig {
    projects: ProjectsConfig {
        sources: [
            "packages/*",
            "apps/*",
        ],
        ...
    },
    vcs: VcsConfig {
        client: Git,
        default_branch: "main",
        ...
    },
    ...
}

&session.extensions_config = ExtensionsConfig {
    ...
}

&session.toolchains_config = ToolchainsConfig {
    node: Some(NodeToolchainConfig {
        version: Some("20.11.0"),
        ...
    }),
    ...
}

&session.tasks_config = TasksConfig {
    tasks: {
        "build": TaskConfig {
            command: Some("tsc"),
            ...
        },
        ...
    },
}

​
Debug VCS

moon debug vcs
Example output: 
config
&session.workspace_config.vcs = VcsConfig {
    client: Git,
    default_branch: "main",
    sync: true,
    ...
}

vcs
&vcs = GitAdapter {
    repository: "/Users/username/projects/my-workspace",
    ...
}

default_branch = main
default_branch_revision = abc123def456...
local_branch = feature/new-feature
local_branch_revision = 789ghi012jkl...

changed_files
[
    "packages/api/src/handler.ts",
    "apps/web/src/App.tsx",
]

changed_files_against_previous_revision
[
    "packages/api/src/handler.ts",
    "apps/web/src/App.tsx",
    "packages/shared/src/utils.ts",
]

​
Common debugging scenarios

​
Configuration not loading correctly

# Check if configuration is being parsed properly
moon debug config | grep -A 20 "workspace_config"

​
VCS integration issues

# Verify VCS is detecting the repository and branches
moon debug vcs

​
Task inheritance problems

# See what tasks are loaded at the workspace level
moon debug config | grep -A 50 "tasks_config"

​
Toolchain configuration

# Check toolchain settings
moon debug config | grep -A 30 "toolchains_config"

​
Output format

The debug output uses Rust’s debug format ({:#?}), which:
  • Shows nested structures with indentation
  • Includes type information
  • Displays all fields, including defaults
  • Uses multi-line formatting for readability
  • Shows enum variants explicitly
This format is optimized for developers to understand the exact state of moon’s internal data structures.

​
Use cases

​
Troubleshooting configuration

When tasks aren’t inheriting properly or configuration seems incorrect: 
moon debug config > config-dump.txt
# Review the file to see exact loaded values

​
Reporting bugs

When filing bug reports, include debug output: 
moon debug config > moon-debug.txt
moon debug vcs >> moon-debug.txt
# Attach moon-debug.txt to your bug report

​
Understanding configuration merging

To see how workspace, tasks, and project configs merge: 
moon debug config | less
# Search for specific settings to see their final values

​
VCS debugging

When experiencing issues with:
  • Branch detection
  • Changed file tracking
  • Hook synchronization
  • Remote operations
moon debug vcs

​
Notes

The debug output format may change between moon versions as internal data structures evolve. Don’t rely on parsing this output programmatically.
For production environments, avoid using debug commands as they expose internal implementation details. Use them primarily for development and troubleshooting.

​
Exit codes

  • 0 - Debug information displayed successfully
  • Non-zero - Error accessing configuration or VCS information

Build docs developers (and LLMs) love

Get started for freeTalk to us