From 8501377980a52d98d1b51d04f60f571a7f0dc3db Mon Sep 17 00:00:00 2001
From: Duncan Horn <40036384+dunhor@users.noreply.github.com>
Date: Sat, 6 Jan 2024 21:23:45 -0800
Subject: [PATCH] Update readme to explicitly call out the difficulties
 mentioned in #417 (#424)

---
 README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/README.md b/README.md
index 5a6128a98..27e4b57aa 100644
--- a/README.md
+++ b/README.md
@@ -160,6 +160,11 @@ There are a few different ways to format your code:
 
 ### 1. Formatting with `git clang-format`
 
+> **Important!** Git integration with `clang-format` is only available through the LLVM distribution.
+You can install LLVM through their [GibHub releases page](https://github.com/llvm/llvm-project/releases), via `winget install llvm.llvm`, or through the package manager of your choice.
+
+> **Important!** The use of `git clang-format` additionally requires Python to be installed and available on your `PATH`.
+
 The simplest way to format just your changes is to use `clang-format`'s `git` integration.
 You have the option to do this continuously as you make changes, or at the very end when you're ready to submit a PR.
 To format code continuously as you make changes, you run `git clang-format` after staging your changes.
@@ -185,6 +190,11 @@ C:\wil> scripts\format-changes.cmd upstream/master
 
 ### 2. Formatting with `clang-format`
 
+> **Important!** The path to `clang-format.exe` is not added to `PATH` automatically, even when using a Visual Studio command window.
+The LLVM installer has the option to add itself to the system or user `PATH` if you'd like.
+If you would like the path to the version of `clang-format` that ships with Visual Studio added to your path, you will need to do so manually.
+Otherwise, the `run-clang-format.cmd` script mentioned below (or, equivalently, building the `format` target) will manually invoke the `clang-format.exe` under your Visual Studio install path.
+
 An alternative, and generally easier option, is to run `clang-format` either on all source files or on all source files you've modified.
 Note, however, that depending on how `clang-format` is invoked, the version used may not be the one that ships with Visual Studio.
 Some tools such as Visual Studio Code allow you to specify the path to the version of `clang-format` that you wish to use when formatting code, however this is not always the case.