Commands

gitrepoforge provides four commands: validate, apply, report, and schema.

Command Description
validate Dry-run audit. Reports drift without making changes.
apply Reports drift by default, or applies the desired state when --action selects a named action.
report Generates a markdown report of what apply would change.
schema Generates a JSON Schema for the .gitrepoforge per-repo config file.

Common Flags

Several flags are shared across commands:

Flag Used by Description
--repo <name> validate, apply, report Target a single repo by its directory name.
--json validate, apply, schema Output results as JSON instead of the default format.
--output <path> report, schema Write output to a file instead of stdout.
--action <name> apply Named action from the action config to use for Git automation.

Output

Human-Readable (default)

validate and apply print a summary per repo with status, validation errors, and findings.

JSON (--json)

validate and apply return a structured report when --json is passed:

{
  "tool": {
    "name": "gitrepoforge",
    "version": "...",
    "timestamp": "2024-01-15T10:30:00Z",
    "command": "validate"
  },
  "root_config": "/path/to/.gitrepoforge-config",
  "config_repo": "/path/to/config-repo",
  "repos": [
    {
      "name": "my-repo",
      "status": "drift",
      "validation_errors": [],
      "findings": [
        {
          "file_path": ".github/workflows/ci.yml",
          "operation": "create",
          "message": "file should exist"
        }
      ]
    }
  ]
}

Finding Operations

Operation Description
create File should exist but is missing.
update File exists but content differs from desired state.
delete File should not exist but is present.

Table of contents