Skip to content

Branch

branch

GitBranchTool — create or checkout git branches.

GitBranchTool

Bases: AXMTool

Create or checkout a git branch in one call.

Registered as git_branch via axm.tools entry point.

Source code in packages/axm-git/src/axm_git/tools/branch.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
class GitBranchTool(AXMTool):
    """Create or checkout a git branch in one call.

    Registered as ``git_branch`` via axm.tools entry point.
    """

    @property
    def name(self) -> str:
        """Tool name used for MCP registration."""
        return "git_branch"

    def execute(  # type: ignore[override]
        self,
        *,
        name: str,
        from_ref: str | None = None,
        checkout_only: bool = False,
        path: str = ".",
        **kwargs: Any,
    ) -> ToolResult:
        """Create or checkout a git branch.

        Args:
            name: Branch name (required).
            from_ref: Optional ref to branch from (tag, commit, branch).
            checkout_only: If True, checkout existing branch without creating.
            path: Project root directory.

        Returns:
            ToolResult with branch name on success.
        """
        resolved = Path(path).resolve()

        # Verify this is a git repo.
        check = run_git(["rev-parse", "--git-dir"], resolved)
        if check.returncode != 0:
            return not_a_repo_error(check.stderr, resolved)

        # Build the checkout command.
        if checkout_only:
            cmd = ["checkout", name]
        else:
            cmd = ["checkout", "-b", name]
            if from_ref is not None:
                cmd.append(from_ref)

        result = run_git(cmd, resolved)
        if result.returncode != 0:
            return ToolResult(
                success=False,
                error=result.stderr.strip() or result.stdout.strip(),
            )

        # Confirm the current branch.
        current = run_git(["branch", "--show-current"], resolved)
        branch = current.stdout.strip()

        return ToolResult(
            success=True,
            data={"branch": branch},
        )
name property

Tool name used for MCP registration.

execute(*, name, from_ref=None, checkout_only=False, path='.', **kwargs)

Create or checkout a git branch.

Parameters:

Name Type Description Default
name str

Branch name (required).

 required
from_ref str | None

Optional ref to branch from (tag, commit, branch).

 None
checkout_only bool

If True, checkout existing branch without creating.

 False
path str

Project root directory.

 '.'

Returns:

Type Description
ToolResult

ToolResult with branch name on success.
Source code in packages/axm-git/src/axm_git/tools/branch.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def execute(  # type: ignore[override]
    self,
    *,
    name: str,
    from_ref: str | None = None,
    checkout_only: bool = False,
    path: str = ".",
    **kwargs: Any,
) -> ToolResult:
    """Create or checkout a git branch.

    Args:
        name: Branch name (required).
        from_ref: Optional ref to branch from (tag, commit, branch).
        checkout_only: If True, checkout existing branch without creating.
        path: Project root directory.

    Returns:
        ToolResult with branch name on success.
    """
    resolved = Path(path).resolve()

    # Verify this is a git repo.
    check = run_git(["rev-parse", "--git-dir"], resolved)
    if check.returncode != 0:
        return not_a_repo_error(check.stderr, resolved)

    # Build the checkout command.
    if checkout_only:
        cmd = ["checkout", name]
    else:
        cmd = ["checkout", "-b", name]
        if from_ref is not None:
            cmd.append(from_ref)

    result = run_git(cmd, resolved)
    if result.returncode != 0:
        return ToolResult(
            success=False,
            error=result.stderr.strip() or result.stdout.strip(),
        )

    # Confirm the current branch.
    current = run_git(["branch", "--show-current"], resolved)
    branch = current.stdout.strip()

    return ToolResult(
        success=True,
        data={"branch": branch},
    )