checkout
Switch branches, commit hashes, or restore working tree files in a Git repository. Force checkout, create new branches, detach commits, or manage upstream configuration directly.
Instructions
Switch branches, commits, or restore working tree files.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| createBranch | No | Create a new branch and start it at <start-point> (-b <new-branch>) | |
| createBranchForce | No | Create or reset a branch and start it at <start-point> (-B <new-branch>) | |
| detach | No | Check out a commit for inspection rather than switching to a branch (--detach) | |
| force | No | Force checkout, throw away local modifications (-f, --force) | |
| merge | No | When switching branches, proceed even if index/working tree differs from HEAD (-m, --merge) | |
| noTrack | No | Do not set up upstream configuration (--no-track) | |
| orphan | No | Create a new orphan branch (--orphan <new-branch>) | |
| pathspec | No | Limit checkout to specific paths | |
| repoPath | Yes | Absolute path to the git repository | |
| target | Yes | Branch name, commit hash, or tag to checkout | |
| track | No | Set up upstream configuration (--track) |
Implementation Reference
- The private #handle method implements the core logic: validates it's a git repo, transforms input to options, executes simple-git checkout, and returns success or error.
readonly #handle: ToolCallback<typeof GIT_CHECKOUT_INPUT_SCHEMA> = async (input) => { const sg = simpleGit(input.repoPath); const isRepo = await sg.checkIsRepo(); if (!isRepo) { return { isError: true, content: [ { type: 'text', text: 'Not a git repository', }, ], }; } // Execute checkout with transformed options and target await sg.checkout(input.target, this.inputToOptions(input)); return { content: [ { type: 'text', text: 'Checkout completed successfully', }, ], }; }; - Zod input schema defining parameters for repoPath, target, force, merge, detach, branch creation options, tracking, and pathspec.
// Git checkout input schema constant synced with git-checkout documentation export const GIT_CHECKOUT_INPUT_SCHEMA = { repoPath: z.string().describe('Absolute path to the git repository'), target: z.string().describe('Branch name, commit hash, or tag to checkout'), force: z.boolean().optional().describe('Force checkout, throw away local modifications (-f, --force)'), merge: z .boolean() .optional() .describe('When switching branches, proceed even if index/working tree differs from HEAD (-m, --merge)'), detach: z .boolean() .optional() .describe('Check out a commit for inspection rather than switching to a branch (--detach)'), createBranch: z.string().optional().describe('Create a new branch and start it at <start-point> (-b <new-branch>)'), createBranchForce: z .string() .optional() .describe('Create or reset a branch and start it at <start-point> (-B <new-branch>)'), orphan: z.string().optional().describe('Create a new orphan branch (--orphan <new-branch>)'), track: z.boolean().optional().describe('Set up upstream configuration (--track)'), noTrack: z.boolean().optional().describe('Do not set up upstream configuration (--no-track)'), pathspec: z.array(z.string()).optional().describe('Limit checkout to specific paths'), }; - packages/mcp-git/src/index.ts:25-25 (registration)Registers the checkout tool instance with the MCP server in the main index file.
new GitCheckoutTool().register(server);