diff --git a/codex-rs/config.md b/codex-rs/config.md
index 1a407a239b..c7dfe42a75 100644
--- a/codex-rs/config.md
+++ b/codex-rs/config.md
@@ -259,6 +259,8 @@ disk, but attempts to write a file or access the network will be blocked.
 
 A more relaxed policy is `workspace-write`. When specified, the current working directory for the Codex task will be writable (as well as `$TMPDIR` on macOS). Note that the CLI defaults to using the directory where it was spawned as `cwd`, though this can be overridden using `--cwd/-C`.
 
+On macOS (and soon Linux), all writable roots (including `cwd`) that contain a `.git/` folder _as an immediate child_ will configure the `.git/` folder to be read-only while the rest of the Git repository will be writable. This means that commands like `git commit` will fail, by default (as it entails writing to `.git/`), and will require Codex to ask for permission.
+
 ```toml
 # same as `--sandbox workspace-write`
 sandbox_mode = "workspace-write"