patch_file

Apply a lightweight, non-destructive text patch to an existing file in a Bridge Town project and commit the result. The path is project-relative (e.g. ‘README.md’, ‘model/revenue.py’). This tool only works on UTF-8 text files; binary files return a ‘patch-not-supported’ error. It performs an exact literal find/replace (find_text -> replace_text) and is intended for small, targeted edits. Specify expected_occurrences to enforce deterministic edits: the call fails if the current file does not contain find_text exactly that many times. Specify branch to commit to a non-default branch (e.g. a scenario branch). Omitting branch, passing an empty string, or passing null all resolve to the project’s default branch. Passing the branch name explicitly is equivalent. Pass expected_sha (the sha returned by read_file or a prior write tool) to enable optimistic concurrency control: if another session modified the file since you last read it the tool raises a ToolError with a structured conflict payload so you can merge and retry without an extra read_file call. If commit_message is omitted the server generates a default of the form ‘feat: patch {filename} (Bridge Town)’. Requires at least Editor access to the project. Returns: path (str) — updated file path; project (str) — project name; commit_sha (str) — git commit SHA of the change; replacements_applied (int) — number of literal replacements performed. Validation/failure behavior: rejects empty find_text, expected_occurrences < 1, ambiguous matches, or no-op patches.

Parameters

Name	Type	Required	Default	Description
project_name	str	Yes	—
path	str	Yes	—
find_text	str	Yes	—
replace_text	str	Yes	—
expected_occurrences	int	No	1
commit_message	str	No	''
branch	`str	None`	No	None
expected_sha	str	No	''

Returns

Returns a structured object. Top-level fields:

• path (string)
• project (string)
• commit_sha (string)
• replacements_applied (integer)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "patch_file",
  "arguments": {
    "project_name": "forecasts",
    "path": "model/revenue.py",
    "find_text": "growth_rate = 0.10",
    "replace_text": "growth_rate = 0.15",
    "expected_occurrences": 1,
    "commit_message": "tweak: bump growth assumption"
  }
}

Response

{
  "path": "model/revenue.py",
  "project": "forecasts",
  "commit_sha": "abc1234def5678901234567890abcdef12345678",
  "replacements_applied": 1
}

Notes

• Module: Models
• Requires authentication via API token or Auth0 JWT.