edit-file-usage

edit_file Usage

The QBAgent edit_file tool performs a surgical, in-place change to a single file by replacing an exact oldString with a newString. Edits are not raw filesystem writes: they route through the QBrain.AI RepoFileService (interface IRepoFileService, src/QBrainAi.Services/Services/RepoFileService.cs) and are wrapped by TransactionGatedRepoFileService (src/QBrainAi.Support.Mcp/Services/TransactionGatedRepoFileService.cs), which enforces the path allowlist (FR-SUPPORT-010, TR-PLANNED-CORE-013) and transactional rollback compensation via IRepoFileCompensation (TR-MCP-TXN-001).

When to Use

• Changing a known region of an existing file: one function, one config key, a few lines.
• Renaming or retargeting a symbol where you can pin a unique surrounding context.
• Any edit where most of the file should stay byte-for-byte unchanged.

When Not to Use

• Creating a brand new file, or replacing essentially all of a file's content: use write_file (backed by RepoFileService.WriteAsync) instead.
• The target path is outside the workspace allowlist: the write will be rejected.
• You cannot read the file first to obtain an exact oldString. Never guess at content.

Inputs

• filePath (or relativePath): path to the existing file, relative to the repo root.
• oldString: exact text to find, including original indentation and line breaks.
• newString: replacement text. Must differ from oldString.
• replaceAll (optional, default false): replace every occurrence instead of one.
• expectedOccurrences (optional): assert the number of matches before applying; the edit fails if the actual count differs. Use this as a guard when replaceAll is true.

Critical Rules

• Read the file first. oldString must match the on-disk bytes exactly, including leading whitespace. Strip any line-number or cat -n prefixes before matching.
• oldString must be unique within the file unless replaceAll is set. A non-unique oldString without replaceAll is an error; widen the surrounding context to a unique span rather than forcing it.
• oldString and newString must differ. A no-op edit is an error.
• Prefer edit_file over write_file for partial changes. Rewriting a whole file discards unrelated content, defeats the diff, and risks clobbering concurrent edits.
• Edits are transactional. On a failed turn transaction, IRepoFileCompensation restores the prior file state, so a rejected edit leaves the file unchanged. Do not add your own manual rollback logic.
• Do not chase path-safety or rollback yourself: the server owns both. Treat a rejected edit as a signal to fix the path or the oldString, not to retry blindly.