Git Step Reference¶

This page is generated from the public step inventory and shows the documented workflow contract for each public step.

Status and Inspection¶

`get_status`¶

Retrieves the current git status and saves it to the context.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: get_status

Used by built-in workflows: commit-ai

Available to later steps: git_status

Requires

Name	Type	Description
`ctx.git`	-	An initialized GitClient.

Outputs (saved to ctx.data)

Name	Type	Description
`git_status`	GitStatus	The full git status object, which includes the `is_clean` flag.

Returns

Result	Saved for later steps	Description
`Success`	`git_status`	If there are changes to commit (workflow continues)
`Exit`	-	If working directory is clean (stops commit workflow; parent continues)
`Error`	-	If the GitClient is not available or the git command fails.

`get_current_branch`¶

Retrieves the current git branch name and saves it to the context.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: get_current_branch

Available to later steps: pr_head_branch

Requires

Name	Type	Description
`ctx.git`	-	An initialized GitClient.

Outputs (saved to ctx.data)

Name	Type	Description
`pr_head_branch`	str	The name of the current branch, to be used as the head branch for a PR.

Returns

Result	Saved for later steps	Description
`Success`	`pr_head_branch`	If the current branch was retrieved successfully.
`Error`	-	If the GitClient is not available or the git command fails.

`get_base_branch`¶

Retrieves the configured main/base branch name and saves it to the context.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: get_base_branch

Available to later steps: pr_base_branch

Requires

Name	Type	Description
`ctx.git`	-	An initialized GitClient.

Outputs (saved to ctx.data)

Name	Type	Description
`pr_base_branch`	str	The name of the base branch, to be used as the base branch for a PR.

Returns

Result	Saved for later steps	Description
`Success`	`pr_base_branch`	If the base branch was retrieved successfully.
`Error`	-	If the GitClient is not available or the git command fails.

Commits¶

`create_commit`¶

Creates a git commit.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: create_commit

Used by built-in workflows: commit-ai

Available to later steps: commit_hash

Requires

Name	Type	Description
`ctx.git`	-	An initialized GitClient.

Inputs (from ctx.data)

Name	Type	Description
`git_status`	GitStatus	The git status object, used to check if the working directory is clean.
`commit_message`	str	The message for the commit.
`all_files`	bool, optional	Whether to commit all modified and new files. Defaults to True.
`no_verify`	bool, optional	Skip pre-commit and commit-msg hooks. Defaults to False.
`commit_hash`	str, optional	If present, indicates a commit was already created.

Outputs (saved to ctx.data)

Name	Type	Description
`commit_hash`	str	The hash of the created commit.

Returns

Result	Saved for later steps	Description
`Success`	`commit_hash`	If the commit was created successfully.
`Error`	-	If the GitClient is not available, or the commit operation fails.
`Skip`	`commit_hash`	If there are no changes to commit or a commit was already created.

`push`¶

Pushes changes to a remote repository.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: push

Used by built-in workflows: commit-ai

Available to later steps: pr_head_branch

Requires

Name	Type	Description
`ctx.git`	-	An initialized GitClient.

Outputs (saved to ctx.data)

Name	Type	Description
`pr_head_branch`	str	The name of the branch that was pushed.

Returns

Result	Saved for later steps	Description
`Success`	`pr_head_branch`	If the push was successful.
`Error`	-	If the push operation fails.

`ai_generate_commit_message`¶

Generate a commit message using AI based on the current changes.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: ai_generate_commit_message

Used by built-in workflows: commit-ai

Available to later steps: commit_message

Requires

Name	Type	Description
`ctx.git`	-	An initialized GitClient.
`ctx.ai`	-	An initialized AIClient.

Inputs (from ctx.data)

Name	Type	Description
`git_status`	-	Current git status with changes.

Outputs (saved to ctx.data)

Name	Type	Description
`commit_message`	str	AI-generated commit message.

Returns

Result	Saved for later steps	Description
`Success`	`commit_message`	If the commit message was generated successfully.
`Error`	-	If the operation fails.
`Skip`	`commit_message`	If no changes, AI not configured, or user declined.

Branching¶

`save_current_branch`¶

Save current branch and stash uncommitted changes.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: save_current_branch

Available to later steps: original_branch, has_stashed_changes

Outputs (saved to ctx.data)

Name	Type	Description
`original_branch`	str	Name of the branch the user was on
`has_stashed_changes`	bool	Whether changes were stashed

Returns

Result	Saved for later steps	Description
`Success`	`original_branch`, `has_stashed_changes`	Branch saved and changes stashed if needed
`Error`	-	Git operation failed

`restore_original_branch`¶

Restore original branch and pop stashed changes.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: restore_original_branch

Inputs (from ctx.data)

Name	Type	Description
`original_branch`	str	Name of the branch to restore
`has_stashed_changes`	bool	Whether to pop stashed changes

Returns

Result	Saved for later steps	Description
`Success`	-	Branch restored and changes popped if needed
`Error`	-	Git operation failed

`checkout`¶

Checkout a Git branch.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: checkout

Inputs (from ctx.data)

Name	Type	Description
`branch`	str	Branch name to checkout

Returns

Result	Saved for later steps	Description
`Success`	-	Branch checked out successfully
`Error`	-	Git operation failed

`pull`¶

Pull from Git remote.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: pull

Inputs (from ctx.data)

Name	Type	Description
`remote`	str, optional	Remote name (defaults to "origin")
`branch`	str, optional	Branch name (defaults to current branch)

Returns

Result	Saved for later steps	Description
`Success`	-	Pull completed successfully
`Error`	-	Git operation failed

`create_branch`¶

Create a new Git branch.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: create_branch

Inputs (from ctx.data)

Name	Type	Description
`new_branch`	str	Name of the branch to create
`start_point`	str, optional	Starting point for the branch (defaults to HEAD)
`delete_if_exists`	bool, optional	Delete the branch if it already exists (default: False)
`checkout`	bool, optional	Checkout the new branch after creation (default: True)

Returns

Result	Saved for later steps	Description
`Success`	-	Branch created successfully
`Error`	-	Git operation failed

Diff Summaries¶

`show_uncommitted_diff_summary`¶

Show uncommitted changes and let the user select which files to include

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: show_uncommitted_diff_summary

Used by built-in workflows: commit-ai

Returns

Result	Saved for later steps	Description
`Success`	-	Files selected and saved to context
`Exit`	-	No files selected by the user
`Skip`	-	Could not retrieve diff stat

`show_branch_diff_summary`¶

Show summary of branch changes (git diff base...head --stat).

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: show_branch_diff_summary

Inputs (from ctx.data)

Name	Type	Description
`pr_head_branch`	str	Head branch name

Returns

Result	Saved for later steps	Description
`Success`	-	Always (even if no changes, for workflow continuity)

Worktrees¶

`create_worktree`¶

Create a temporary git worktree in detached HEAD mode from remote main branch.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: create_worktree

Returns

Result	Saved for later steps	Description
`Success`	-	If the worktree is created successfully.
`Error`	-	If the Git client is unavailable or worktree creation fails.

`remove_worktree`¶

Remove a git worktree.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: remove_worktree

Returns

Result	Saved for later steps	Description
`Success`	-	If the worktree is removed successfully or is already gone.
`Error`	-	If cleanup fails.

`worktree_commit`¶

Create a commit in a worktree.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: worktree_commit

Returns

Result	Saved for later steps	Description
`Success`	-	If the commit is created in the worktree.
`Error`	-	If required context is missing or the git command fails.

`worktree_push`¶

Push from a worktree.

How to read this contract

Inputs (from ctx.data) shows what the step expects before it runs.
Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: git
  step: worktree_push

Returns

Result	Saved for later steps	Description
`Success`	-	If the branch is pushed from the worktree.
`Error`	-	If required context is missing or the git command fails.

Git Step Reference¶

Status and Inspection¶

get_status¶

get_current_branch¶

get_base_branch¶

Commits¶

create_commit¶

push¶

ai_generate_commit_message¶

Branching¶

save_current_branch¶

restore_original_branch¶

checkout¶

pull¶

create_branch¶

Diff Summaries¶

show_uncommitted_diff_summary¶

show_branch_diff_summary¶

Worktrees¶

create_worktree¶

remove_worktree¶

worktree_commit¶

worktree_push¶

`get_status`¶

`get_current_branch`¶

`get_base_branch`¶

`create_commit`¶

`push`¶

`ai_generate_commit_message`¶

`save_current_branch`¶

`restore_original_branch`¶

`checkout`¶

`pull`¶

`create_branch`¶

`show_uncommitted_diff_summary`¶

`show_branch_diff_summary`¶

`create_worktree`¶

`remove_worktree`¶

`worktree_commit`¶

`worktree_push`¶