Skip to content

worktree.inspect

The canonical path of a branch, derived from its name alone, whether the branch exists, whether something occupies that path, the worktree holding the branch when one does, and what stands in the way of creating or migrating it. The answer for a branch that does not exist yet is the path `worktree create` would use.

The canonical path of a branch, derived from its name alone, whether the branch exists, whether something occupies that path, the worktree holding the branch when one does, and what stands in the way of creating or migrating it. The answer for a branch that does not exist yet is the path `worktree create` would use.

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surfaceas
MCPtool majordomus_worktree_inspect
HTTPGET /api/v1/worktrees/inspect operationId worktree.inspect
command linemajordomus worktree inspect

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · InspectInput

A branch to inspect.

propertytyperequireddescription
branch string yes The branch, full name (`feature/improve-cli`). It need not exist: the canonical path derives from the name alone.
JSON Schema 
{
  "additionalProperties": false,
  "description": "A branch to inspect.",
  "properties": {
    "branch": {
      "description": "The branch, full name (`feature/improve-cli`). It need not exist: the canonical path\nderives from the name alone.",
      "type": "string"
    }
  },
  "required": [
    "branch"
  ],
  "title": "InspectInput",
  "type": "object"
}

output · InspectReport

One branch, inspected: where its work tree belongs and what is there.

propertytyperequireddescription
branch string yes The branch asked about.
branch_exists boolean yes The branch exists locally.
canonical boolean yes The branch is checked out at its canonical path.
destination_exists boolean yes Something exists at that path.
diagnostics array yes What stands in the way, if anything.
expected_path string yes Where its work tree belongs.
worktree one of 2 no The work tree that holds the branch, when one does.
JSON Schema 
{
  "$defs": {
    "DiagnosticCode": {
      "description": "The stable machine name of everything that can be wrong with the topology. One code per\ncondition, reused by the command line, the API, MCP, the Cockpit, the tests and the\ndocumentation; the prose beside a code is rendered from the typed state.",
      "oneOf": [
        {
          "const": "worktree.path_mismatch",
          "description": "A linked work tree is not at its branch's canonical path.",
          "type": "string"
        },
        {
          "const": "worktree.container_occupied",
          "description": "A linked work tree occupies the container path itself.",
          "type": "string"
        },
        {
          "const": "worktree.nested",
          "description": "A linked work tree sits inside the primary checkout or inside another work tree.",
          "type": "string"
        },
        {
          "const": "worktree.destination_conflict",
          "description": "The canonical path of a branch is occupied by something that is not its work tree.",
          "type": "string"
        },
        {
          "const": "worktree.missing",
          "description": "A registered work tree's directory does not exist.",
          "type": "string"
        },
        {
          "const": "worktree.stale_registration",
          "description": "Git reports the registration as prunable.",
          "type": "string"
        },
        {
          "const": "worktree.branch_already_checked_out",
          "description": "A branch is checked out somewhere other than its canonical path.",
          "type": "string"
        },
        {
          "const": "worktree.detached",
          "description": "A linked work tree has no branch.",
          "type": "string"
        },
        {
          "const": "worktree.ephemeral",
          "description": "A linked work tree is a session's scratch checkout: under the temporary directory or\nunder the primary checkout's `.claude/worktrees/`.",
          "type": "string"
        },
        {
          "const": "worktree.primary_on_non_trunk",
          "description": "The primary checkout holds a branch that is not the trunk.",
          "type": "string"
        },
        {
          "const": "worktree.trunk_in_linked_worktree",
          "description": "The trunk is checked out in a linked work tree rather than the primary checkout.",
          "type": "string"
        },
        {
          "const": "worktree.path_escape",
          "description": "A derived path would leave the container. Cannot happen for a valid branch name.",
          "type": "string"
        },
        {
          "const": "worktree.invalid_branch_name",
          "description": "A branch name git accepted that this executable cannot derive a path for.",
          "type": "string"
        },
        {
          "const": "worktree.locked",
          "description": "A work tree is locked, so it cannot be moved until it is unlocked.",
          "type": "string"
        },
        {
          "const": "worktree.migration_verification_failed",
          "description": "A move happened and the fingerprint after it differs from the one before.",
          "type": "string"
        },
        {
          "const": "worktree.trunk_unknown",
          "description": "The trunk could not be determined.",
          "type": "string"
        },
        {
          "const": "worktree.case_collision",
          "description": "Two branch names map to one directory on a case-insensitive filesystem.",
          "type": "string"
        },
        {
          "const": "worktree.cross_device",
          "description": "A move crossed devices and was made by copy, repair and verification.",
          "type": "string"
        }
      ]
    },
    "DirtyState": {
      "description": "Uncommitted work in a work tree, counted from `git status --porcelain`. Untracked\ncontent counts: it is exactly what a careless move loses.",
      "properties": {
        "clean": {
          "description": "Nothing above is non-zero.",
          "type": "boolean"
        },
        "conflicted": {
          "description": "Entries with an unresolved merge conflict.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "in_progress": {
          "description": "A merge, rebase, cherry-pick, revert or bisect is in progress here.",
          "type": [
            "string",
            "null"
          ]
        },
        "staged": {
          "description": "Entries with a change in the index.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "unstaged": {
          "description": "Entries with a change in the work tree that is not in the index.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "untracked": {
          "description": "Untracked, not ignored, files.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "staged",
        "unstaged",
        "untracked",
        "conflicted",
        "clean"
      ],
      "type": "object"
    },
    "Severity": {
      "description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither.",
      "oneOf": [
        {
          "const": "info",
          "description": "Worth knowing; changes nothing.",
          "type": "string"
        },
        {
          "const": "warning",
          "description": "Something to look at; the object is still served.",
          "type": "string"
        },
        {
          "const": "error",
          "description": "The file is excluded and the index is degraded.",
          "type": "string"
        }
      ]
    },
    "Standing": {
      "description": "Where a work tree stands against the topology.",
      "oneOf": [
        {
          "const": "primary",
          "description": "The primary checkout: exempt from the path rule, held to the trunk rule.",
          "type": "string"
        },
        {
          "const": "canonical",
          "description": "A linked work tree at exactly its branch's canonical path.",
          "type": "string"
        },
        {
          "const": "misplaced",
          "description": "A linked work tree somewhere else. Migration brings it home.",
          "type": "string"
        },
        {
          "const": "detached",
          "description": "A linked work tree with no branch. It has no canonical path and is never moved.",
          "type": "string"
        },
        {
          "const": "ephemeral",
          "description": "A linked work tree under the operating system's temporary directory or under the\nprimary checkout's `.claude/worktrees/`: a session's scratch checkout, owned and\nremoved by the harness that made it. Reported; migrated only on request.",
          "type": "string"
        },
        {
          "const": "missing",
          "description": "A registration whose directory is gone. Repair drops it.",
          "type": "string"
        }
      ]
    },
    "TopologyDiagnostic": {
      "description": "One thing wrong with, or worth knowing about, the topology.",
      "properties": {
        "branch": {
          "description": "The branch involved.",
          "type": [
            "string",
            "null"
          ]
        },
        "code": {
          "$ref": "#/$defs/DiagnosticCode",
          "description": "The stable code."
        },
        "expected": {
          "description": "Where the work tree belongs.",
          "type": [
            "string",
            "null"
          ]
        },
        "message": {
          "description": "What is wrong, in one line.",
          "type": "string"
        },
        "path": {
          "description": "The work tree involved.",
          "type": [
            "string",
            "null"
          ]
        },
        "remedy": {
          "description": "The command that addresses it.",
          "type": "string"
        },
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How serious it is."
        }
      },
      "required": [
        "code",
        "severity",
        "message",
        "remedy"
      ],
      "type": "object"
    },
    "UpstreamState": {
      "description": "A branch's upstream and how far the two have moved apart, from `for-each-ref` in one\nsubprocess for every branch, never a fetch.",
      "properties": {
        "ahead": {
          "description": "Commits here that the upstream lacks.",
          "format": "uint",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "behind": {
          "description": "Commits upstream that this branch lacks.",
          "format": "uint",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "gone": {
          "description": "The upstream ref no longer exists.",
          "type": "boolean"
        },
        "name": {
          "description": "The upstream ref, short (`origin/master`).",
          "type": "string"
        }
      },
      "required": [
        "name",
        "gone"
      ],
      "type": "object"
    },
    "WorktreeKind": {
      "description": "Whether a work tree is the repository's own checkout or one linked to it.",
      "oneOf": [
        {
          "const": "primary",
          "description": "The main work tree. It hosts the trunk, is never moved and is never removed.",
          "type": "string"
        },
        {
          "const": "linked",
          "description": "A linked work tree. Belongs at its branch's canonical path.",
          "type": "string"
        }
      ]
    },
    "WorktreeState": {
      "description": "One work tree, as the topology sees it.",
      "properties": {
        "branch": {
          "description": "The branch checked out here, short. Absent when detached.",
          "type": [
            "string",
            "null"
          ]
        },
        "current": {
          "description": "The call came from inside this work tree.",
          "type": "boolean"
        },
        "detached": {
          "description": "HEAD is detached here.",
          "type": "boolean"
        },
        "diagnostics": {
          "description": "What is wrong with this work tree, if anything.",
          "items": {
            "$ref": "#/$defs/TopologyDiagnostic"
          },
          "type": "array"
        },
        "dirty": {
          "anyOf": [
            {
              "$ref": "#/$defs/DirtyState"
            },
            {
              "type": "null"
            }
          ],
          "description": "Uncommitted work here. Absent when it was not asked for: it costs one subprocess per\nwork tree, and a topology check does not need it."
        },
        "exists": {
          "description": "The directory git registered still exists on disk.",
          "type": "boolean"
        },
        "expected_path": {
          "description": "Where this branch's work tree belongs. Absent when detached, or for the primary\ncheckout on the trunk.",
          "type": [
            "string",
            "null"
          ]
        },
        "head": {
          "description": "The commit checked out here.",
          "type": [
            "string",
            "null"
          ]
        },
        "issue": {
          "description": "The issue this branch provably names: a path component of the branch equal to an\nissue id of `.ai/repo/project/issues/`, or beginning with it and a hyphen. Nothing\nis inferred from similarity.",
          "type": [
            "string",
            "null"
          ]
        },
        "kind": {
          "$ref": "#/$defs/WorktreeKind",
          "description": "Primary or linked."
        },
        "label": {
          "description": "The name it is shown under: the branch, or `detached/<short commit>`.",
          "type": "string"
        },
        "locked": {
          "description": "Locked, with git's reason; an empty string when it recorded none.",
          "type": [
            "string",
            "null"
          ]
        },
        "path": {
          "description": "Absolute, as git holds it.",
          "type": "string"
        },
        "prunable": {
          "description": "Prunable, with git's reason.",
          "type": [
            "string",
            "null"
          ]
        },
        "standing": {
          "$ref": "#/$defs/Standing",
          "description": "Where it stands against the topology."
        },
        "upstream": {
          "anyOf": [
            {
              "$ref": "#/$defs/UpstreamState"
            },
            {
              "type": "null"
            }
          ],
          "description": "The branch's upstream and its distance from it."
        }
      },
      "required": [
        "path",
        "kind",
        "standing",
        "label",
        "detached",
        "exists",
        "current",
        "diagnostics"
      ],
      "type": "object"
    }
  },
  "description": "One branch, inspected: where its work tree belongs and what is there.",
  "properties": {
    "branch": {
      "description": "The branch asked about.",
      "type": "string"
    },
    "branch_exists": {
      "description": "The branch exists locally.",
      "type": "boolean"
    },
    "canonical": {
      "description": "The branch is checked out at its canonical path.",
      "type": "boolean"
    },
    "destination_exists": {
      "description": "Something exists at that path.",
      "type": "boolean"
    },
    "diagnostics": {
      "description": "What stands in the way, if anything.",
      "items": {
        "$ref": "#/$defs/TopologyDiagnostic"
      },
      "type": "array"
    },
    "expected_path": {
      "description": "Where its work tree belongs.",
      "type": "string"
    },
    "worktree": {
      "anyOf": [
        {
          "$ref": "#/$defs/WorktreeState"
        },
        {
          "type": "null"
        }
      ],
      "description": "The work tree that holds the branch, when one does."
    }
  },
  "required": [
    "branch",
    "branch_exists",
    "expected_path",
    "destination_exists",
    "canonical",
    "diagnostics"
  ],
  "title": "InspectReport",
  "type": "object"
}

Policies

benchmark
required — a target on every transport the exposure declares; the cases are the input type's
cache
disabled — every call runs the handler

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transportstatecasestargets
directcovered1feature-branch
mcpcovered1feature-branch
httpcovered1feature-branch