write_file
Write full file content atomically with crash-durable writes, automatic parent directory creation, and optimistic concurrency checks to prevent overwriting concurrent changes.
Instructions
Create or overwrite a file with the given content. The write is atomic and crash-durable (temp file fsynced, renamed, parent directory fsynced before the call returns — never partially written); parent directories are created automatically and the LSP server is notified so diagnostics and symbols update immediately. Pass expected_mtime or expected_sha (from a read_file header) to reject the write if the file changed since you read it, so a full-content overwrite never silently clobbers a concurrent change. If the call fails with a transport/connection error, the atomic temp+rename guarantees the file is either fully written or untouched — never partially written; re-read to confirm which side of the rename it landed on. Use edit_file for targeted edits to an existing file.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | Full content to write to the file. | |
| dirty_ok | No | Allow writing a file that has uncommitted changes in its git repository. Default false — the write is refused if the target file is dirty. Pass true to overwrite anyway. | |
| file_path | No | Absolute path, file:// URI, or workspace-relative path of the file to write. | |
| create_dirs | No | Create parent directories if they do not exist. Default true. | |
| expected_sha | No | Optional. Hex-encoded SHA-256 previously returned by read_file. If provided, the write is rejected if the file's current content hash differs — stronger than expected_mtime, survives mtime aliasing. | |
| expected_mtime | No | Optional. RFC3339Nano mtime previously returned by read_file. If provided, the write is rejected if the file's current mtime differs — fast optimistic-concurrency check, so a full-content overwrite never silently clobbers a change made since you read it. | |
| await_diagnostics | No | When true, block up to a few seconds for the language server to finish re-analysing this file and report an authoritative post-write result — a clean fresh pass is stated explicitly. Use it for a trustworthy "did my change compile?" answer instead of shelling out to a build. Default false (fast adaptive window; the result may predate the write). | |
| overwrite_changed | No | Allow overwriting a file that changed on disk since this session read it (a peer agent or human edited it after your read). Default false — the write is refused so a stale full-content overwrite cannot silently discard that change. Re-read to merge, or pass true to overwrite anyway. Only consulted when neither expected_mtime nor expected_sha is given (those guards take precedence). |