Initialize a new git repository in repo_path, creating the directory if missing. Use this when starting a brand-new project, when the working directory is not yet version-controlled, or when a repo needs a non-standard initial branch or bare layout. Does NOT clone existing projects — use git_clone to fetch a remote repository instead. Best for: creating a fresh repository before first commit. Returns: confirmation text with the repository path; refuses non-empty directories, so pass an empty or missing target. More direct than raw git init because it validates the target directory first.

Clone a remote repository from url into local_path, optionally pinning a branch or shallow depth. Use this when starting work on an existing project, when a full history is not needed (depth), or when a local copy must be created from a remote. Does NOT initialize a new empty repository — use git_init for that. Best for: fetching an existing repository to work on locally. Returns: confirmation text with the local path; refuses non-empty destinations, so the target must be missing or empty.

Show the repository's working tree state: current branch, staged, modified and untracked files. Use this at the start of any edit task to answer 'what changed?', and before committing to verify what will be staged. Best for: inspecting repository state before starting edits or after a change. Returns: 'On branch .' first line, then non-empty sections 'Staged changes (N): ' / 'Modified (N): ' / 'Untracked (N): ' with file lists capped at 10 plus ', and N more', or 'Working tree clean on .' when nothing changed; short=True gives compact '--short --branch' output, include_untracked=False omits untracked files. Does NOT show file contents or diffs — use git_diff for those; does NOT list commit history — use git_log. More direct than raw git status because output is returned as text with no shell.

Delete untracked files, or preview them first with dry_run. Use this to remove build artifacts and other untracked clutter, and to answer 'what junk is in this repo?' before deleting. DESTRUCTIVE: requires confirmed=True to delete; dry_run=True previews without deleting, so preview first. Does NOT touch tracked files, ignored files, or stashes — untracked files only; use git_status to see untracked files before deciding what to clean. Best for: removing build artifacts and other untracked clutter. Returns: list of removed or would-be-removed files, or 'No untracked files to clean.'

Stage files into the index, ready for committing. Use this to prepare modified or new files before a commit: select specific files, stage everything (all=True), or tracked changes only (update=True). Does NOT commit — use git_commit for that; review first with git_status and git_diff. Best for: preparing modified or new files before a commit. Returns: 'Staged files:' followed by the staged paths, or 'All changes staged'.

Create a commit with the given message, or amend the last one. Use this when staged changes are ready to record, to fix the previous commit's message or contents (amend=True), or to skip pre-commit hooks (no_verify=True). Does NOT stage files — run git_add first; check git_status if nothing appears staged. Best for: recording staged changes after git_add. Returns: confirmation with the new commit hash, or 'No changes to commit' with a staging hint when untracked files are present.

Read git configuration values from the repository, either one key or the full list. Use this to verify settings like user.name, user.email, core options, or remote URLs before operating, and to answer 'what is this repo configured to?'. Does NOT modify configuration — it is read-only; use git_remote for a friendlier view of remote URLs. Best for: checking settings like user.name, user.email, remote URLs or core options before operating. Returns: the value of the requested config key, or the full 'git config --list' output when key is omitted; an unset key returns 'Config key ... is not set.' without error.

Show differences between the working tree, the index, and commits. Defaults to a diffstat summary; pass stat=False for the full diff. Use this to review what a change actually contains before staging or committing, to compare two commits with source and target, or to check what would be committed with staged=True. Best for: reviewing changes before staging or committing. Returns: 'Diff output:' followed by the diff, or 'No changes'; stat=True shows a summary only. Does NOT show file status or history — use git_status for the file list and git_log for commits; use git_show to see one commit's full patch.

Show recent commits as ' - ' lines, filtered by author, date range, or message grep. Use this to answer 'what changed recently?', to review history before branching or merging, and to find a commit by author or message text. Best for: reviewing commit history and filtering by author, date or message. Returns: one formatted line per commit, or 'No commits found.' Does NOT show commit patches or file contents — use git_show for a single commit's details and git_grep to search file contents; use git_reflog to see HEAD movements.

Render a commit's metadata and patch, defaulting to HEAD. Use this to inspect exactly what a specific commit changed — answering 'what did this commit do?' — or to view the latest change by omitting object. Best for: inspecting what a specific commit changed. Returns: a summary line ' , : ', followed by the commit header and its diff; stat defaults to True and shows a diffstat summary only. Does NOT list history — use git_log to find commits; does NOT compare working tree changes — use git_diff for that.

Render per-line attribution for a tracked file, optionally restricted to a line range, showing which commit last touched each line. Use this when investigating who changed a line or when a regression was introduced, and to trace how a file evolved. Best for: finding which commit last touched each line of a file. Returns: a line count summary 'Blame for : lines' followed by git blame output with commit hashes, authors and line content; start_line and end_line must be provided together and the file must be tracked by git. Does NOT show current file content or whole-history log — use git_show or git_log for context.

Show the reflog for a ref (default HEAD), recording every local HEAD movement even after branch deletions or resets. Use this to recover lost commits after a reset or branch delete, and to answer 'where was HEAD before?'. Best for: recovering lost commits and understanding HEAD history. Returns: 'Showing reflog entries for .' followed by reflog text, or 'No reflog entries found.'; pass ref to inspect a specific branch. Does NOT show regular commit history — use git_log for that; pair with git_reset to restore a commit found here.

Search tracked files for a pattern, returning 'file:line:content' matches. Use this to find where a string or symbol appears in the codebase — answering 'where is X used?' — without a shell. Best for: finding where a string appears in the codebase. Returns: 'file:line:content' matches, or 'No matches'. Pattern must not start with '-'; does NOT search commit messages or untracked files — use git_log with its grep filter for commit messages.

List, create, or delete branches, marking the current branch with '*'. Use this to review existing branches before choosing where to work, to start a feature branch, or to remove a merged one; in detached HEAD state no branch is current. Does NOT switch branches — use git_checkout for that; does NOT manage release markers — use git_tag. Best for: managing feature branches and listing local or remote branches. Returns: branch listing lines, or confirmation text for create/delete; delete requires confirmed=True and refuses the current branch; force=True replaces an existing branch on create; 'list' with all=True also shows remote branches.

Switch to an existing branch, tag, or commit, optionally creating a branch first. Use this to move between branches for different features, to jump to a tag or historical commit, or to start a new branch with create_branch. Does NOT discard local changes without confirmation: force=True discards them and requires confirmed=True — run preview=True first to see what would be discarded, or git_stash to keep changes. Best for: moving between branches to work on different features. Returns: 'Switched to branch ' on success, or an impact preview when preview=True; use git_branch to list what is available to switch to.

Merge a branch into the current branch, integrating its commits with or without a merge commit. Use this to bring a feature branch back into its base when histories have diverged, or to squash a branch's work into one commit with squash=True. Does NOT rewrite the current branch's history — use git_rebase for that; use git_cherry_pick to port specific commits instead of a whole branch. Best for: integrating a feature branch back into the base branch. Returns: git merge output text; conflicts raise a ValueError with details — resolve them and retry.

Rebase the current branch onto an upstream, or manage an in-progress rebase with mode='continue', 'abort', or 'skip'. Use this to keep a feature branch up to date with its base and produce a linear history. Does NOT create a merge commit — use git_merge to record integration; on conflict, resolve and call with mode='continue', or mode='abort' to cancel. Best for: keeping a feature branch up to date with its base. Returns: confirmation text or git rebase output; use git_log afterwards to see the rewritten history.

Apply the changes of one or more commits onto the current branch, optionally without committing (no_commit=True). Use this to port a specific fix or feature from another branch when a full merge is too broad — answering 'how do I copy just this commit?'. Does NOT integrate a whole branch — use git_merge or git_rebase for that; use git_revert to undo a commit instead of applying it. Best for: porting specific commits to another branch. Returns: 'Cherry-picked ' on success; conflicts are reported as errors — resolve them and continue.

Manage remotes: list, add, remove or rename them. Use this to answer 'where does this repo sync to?', to configure a new upstream, or to fix a remote URL. Best for: configuring where the repository syncs to and from. Returns: one 'name -> url' line per remote, or operation confirmation; 'No remotes configured.' when none exist; add needs both name and url, remove/rename operate on existing remotes. Does NOT transfer data — use git_fetch, git_pull, or git_push to move commits. More readable than raw git config --list when looking for remote URLs.

Fetch refs from a remote (default origin) without merging, updating remote-tracking branches. Use this to see upstream changes before deciding to integrate them — answering 'what is on the remote?' — and to prune stale branches with prune=True. Does NOT change the working tree — use git_pull to fetch and integrate, or git_push to send local commits. Best for: updating remote-tracking branches before reviewing upstream changes. Returns: 'Fetched N refs from 'origin'.' followed by per-ref lines; use git_log or git_diff to inspect what was fetched.

Pull from a remote and merge (or rebase) into the current branch. Use this to sync local work with upstream changes, with rebase=True to keep a linear history instead of a merge commit. Does NOT fetch only — use git_fetch to update tracking branches without touching the working tree; conflicts are reported as errors, resolve and retry. Best for: syncing local work with upstream changes. Returns: 'Pulled from 'origin'.' followed by per-ref lines.

Push commits to a remote (default origin), optionally including tags. Use this to publish local commits when work is ready to share, and to push tags for releases; force=True overwrites remote history and requires confirmed=True, tags=True also pushes tags. Does NOT integrate upstream work — if the remote has diverged, use git_fetch or git_pull first. Best for: publishing local commits to the remote repository. Returns: 'Pushed to 'origin'.' followed by per-ref lines; use git_remote to check where the push will go.

Manage tags: list them, create a new one, or delete one. Use this to mark release points in history so commits are easy to reference later, or to list existing releases. Does NOT branch or switch — tags are lightweight markers: use git_branch for branches and git_checkout to switch to a tag. Best for: marking release points in history. Returns: tag names for list, or confirmation for create/delete; delete requires confirmed=True; annotated=True needs a message.

Manage stashes: list, push changes, or pop and drop existing stashes. Use this to set aside uncommitted work before switching branches, or to restore previously stashed work. Does NOT discard changes permanently — push preserves them for later; only drop, which requires confirmed=True, removes a stash, and push needs modified tracked files. Best for: setting aside work-in-progress to switch context. Returns: stash listing, or git stash output. Use git_checkout after stashing to switch branches; use git_reset to discard changes instead of preserving them.

Reset the repository to a target commit (default HEAD) in soft, mixed, or hard mode. Use this to undo commits, unstage changes, or discard working tree changes. DESTRUCTIVE: requires confirmed=True to execute; run preview=True first to see which tracked changes would be discarded (hard/mixed modes), while soft mode only moves HEAD and touches neither the working tree nor the index. Does NOT create a new commit — use git_revert to undo a published commit safely, or git_stash to keep changes before resetting. Best for: undoing commits or unstaging changes. Returns: 'Reset () to .' on success, or an impact preview when preview=True.

Revert a commit by creating a new commit that undoes it, or apply the undo without committing (no_commit=True). Use this to safely undo a published commit without rewriting history, when other people may already have the commit. Does NOT move HEAD backwards or discard history — use git_reset for that; use git_cherry_pick to re-apply a commit instead of undoing it. Best for: safely undoing a published commit without rewriting history. Returns: confirmation with the new revert commit hash.

Manage linked worktrees: list, add, or remove them. Use this to check out multiple branches simultaneously in separate directories when switching back and forth is disruptive, or to work on a second branch without stashing. Does NOT switch the main working tree — use git_checkout for that; use git_branch to see which branches can be added. Best for: checking out multiple branches simultaneously. Returns: worktree listing, or git worktree output; remove requires confirmed=True and add refuses non-empty paths.

Drive a bisect session: start, mark good/bad commits, or reset. Use this to binary-search which commit introduced a regression by alternating 'good' and 'bad' marks until the culprit is found. Best for: binary-searching which commit introduced a regression. Returns: git bisect progress output. Start with 'start', alternate 'good'/'bad' marks, and 'reset' to end the session. Does NOT inspect history — use git_log to understand commits before bisecting; stash local changes first, because the session checks out commits automatically.

Manage submodules: show status, add a new one, or update all of them. Use this when a repository embeds external repositories, to check whether embedded repos are in sync, or to add a new dependency as a submodule. Best for: embedding and syncing external repositories. Returns: submodule status output, or git submodule output; 'No submodules found.' when none are configured. add needs both url and path; update fetches and inits all submodules. Does NOT clone the superproject — use git_clone for that.