gitlab_compare_refs
Compare two Git references to review changes between branches, tags, or commits before merging. Shows commits and diffs to understand what changed between two points in a GitLab project.
Instructions
Compare two git references Returns: Commits and diffs between refs Use when: Reviewing changes before merge Shows: What changed between two points
Example: Compare feature branch to main
from: "main"
to: "feature/new-feature" Shows all changes in feature branch
Related tools:
gitlab_create_merge_request: Create MR from comparison
gitlab_smart_diff: Advanced diff options
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Project identifier (auto-detected if not provided) Type: integer OR string Format: numeric ID or 'namespace/project' Optional: Yes - auto-detects from current git repository Examples: - 12345 (numeric ID) - 'gitlab-org/gitlab' (namespace/project path) - 'my-group/my-subgroup/my-project' (nested groups) Note: If in a git repo with GitLab remote, this can be omitted | |
| from_ref | Yes | Source reference for comparison Type: string Required: Yes Format: Branch, tag, or commit SHA Examples: - 'feature/new-api' (branch) - 'v1.0.0' (tag) - 'abc123def' (commit) Use case: Starting point for comparison | |
| to_ref | Yes | Target reference for comparison Type: string Required: Yes Format: Branch, tag, or commit SHA Examples: - 'main' (branch) - 'v2.0.0' (tag) - '456789abc' (commit) Use case: Ending point for comparison | |
| straight | No | Diff type Type: boolean Default: false Options: - true: Direct comparison (A..B) - false: Three-dot comparison (A...B) Explanation: - Direct: All changes between two points - Three-dot: Changes in B since common ancestor Use case: false for MR-style diffs, true for direct comparison |
Implementation Reference
- src/mcp_gitlab/tool_handlers.py:387-394 (handler)Main handler function that implements the core logic for the gitlab_compare_refs tool. Extracts parameters, validates project, and delegates to GitLabClient.compare_refs().
def handle_compare_refs(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]: """Handle comparing two refs""" project_id = require_project_id(client, arguments) from_ref = require_argument(arguments, "from_ref") to_ref = require_argument(arguments, "to_ref") straight = get_argument(arguments, "straight", False) return client.compare_refs(project_id, from_ref, to_ref, straight) - Pydantic/MCP tool schema definition specifying input parameters, types, descriptions, and requirements for gitlab_compare_refs.
name=TOOL_COMPARE_REFS, description=desc.DESC_COMPARE_REFS, inputSchema={ "type": "object", "properties": { "project_id": {"type": "string", "description": desc.DESC_PROJECT_ID}, "from_ref": {"type": "string", "description": desc.DESC_FROM_REF}, "to_ref": {"type": "string", "description": desc.DESC_TO_REF}, "straight": {"type": "boolean", "description": desc.DESC_STRAIGHT, "default": False} }, "required": ["from_ref", "to_ref"] } - src/mcp_gitlab/tool_handlers.py:1053-1054 (registration)Registration of the handler function in the central TOOL_HANDLERS dictionary, mapping tool name to its executor. Used by server.call_tool().
TOOL_COMPARE_REFS: handle_compare_refs, - src/mcp_gitlab/constants.py:240-240 (helper)Constant defining the canonical tool name string used throughout the codebase for consistency.
TOOL_COMPARE_REFS = "gitlab_compare_refs" - src/mcp_gitlab/server.py:691-702 (registration)Tool schema registration in the server's list_tools() method, exposing it to MCP clients.
name="gitlab_compare_refs", description=desc.DESC_COMPARE_REFS, inputSchema={ "type": "object", "properties": { "project_id": {"type": "string", "description": desc.DESC_PROJECT_ID}, "from_ref": {"type": "string", "description": desc.DESC_FROM_REF}, "to_ref": {"type": "string", "description": desc.DESC_TO_REF}, "straight": {"type": "boolean", "description": desc.DESC_STRAIGHT, "default": False} }, "required": ["from_ref", "to_ref"] }