diff --git a/cli/commands.mdx b/cli/commands.mdx
index c2f5d3f165..bca986c092 100644
--- a/cli/commands.mdx
+++ b/cli/commands.mdx
@@ -2,7 +2,12 @@
 title: "Mintlify CLI command reference"
 sidebarTitle: "Commands"
 description: "Complete reference for Mintlify CLI commands and flags, including mint index, mint dev, mint validate, mint broken-links, and more."
-keywords: ["CLI", "mint", "commands", "flags", "reference"]
+keywords:
+  - "CLI"
+  - "mint"
+  - "commands"
+  - "flags"
+  - "reference"
 boost: 3
 ---
 
@@ -633,6 +638,10 @@ The overall score uses weighted scoring, so higher-impact checks contribute more
 
 ## `mint format`
 
+<Warning>
+  `mint format` rewrites files in place. Commit or stash your changes before running it so you can review the diff.
+</Warning>
+
 Format every `.mdx` file in the current directory to Mintlify's canonical style. The command parses each file with the same MDX parser the web editor uses, then rewrites it in place if the canonical output differs.
 
 ```bash
@@ -641,9 +650,9 @@ mint format
 
 Run the command from the root of your docs project. It walks every subdirectory, skipping paths matched by `.gitignore` and any Mintlify ignore rules. Files that already match the canonical output are left untouched.
 
-<Warning>
-  `mint format` rewrites files in place. Commit or stash your changes before running it so you can review the diff.
-</Warning>
+<Tip>
+  Running `mint format` can result in many changes depending on the size of your project. To avoid merge conflicts and introducing changes to other in progress work, first resolve all important pending branches. Then create a new branch for formatting changes and run `mint format` on that branch.
+</Tip>
 
 When it finishes, the command prints how many MDX files were reformatted and how many failed to parse. If any file fails, the command exits with code `1` and prints the file path and error, so you can run it in CI to enforce consistent formatting.