From e8a0ec8de920ff0db3c350db4e04e3c8e2774d19 Mon Sep 17 00:00:00 2001
From: Rahul Martim Juliato <rahul.juliato@gmail.com>
Date: Wed, 30 Jul 2025 22:51:57 -0300
Subject: [PATCH] doc: add macos requirements warning (#9)

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

diff --git a/README.md b/README.md
index 15c7fef..7366edd 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,7 @@ enjoying it, you can:
 With Emacs-Kick, the goal is to empower you to explore Emacs at your
 own pace. The sky's the limit! 🌟
 
+
 ## Minimum Requirements
 
 - Emacs version **>=30.1**
@@ -64,6 +65,33 @@ emacs --version
 **Note**: floating windows on TUI are only supported from Emacs >=31 (current
 development version on Emacs master branch).
 
+
+### macOS Warning
+
+On macOS, `emacs-kick` may fail to function correctly due to missing or
+incompatible system utilities. To avoid common issues, make sure the
+following tools are installed via Homebrew:
+
+```bash
+brew install coreutils git
+```
+
+This provides:
+
+- `gls`: The GNU version of `ls`, required by Dired to avoid errors
+  like:
+
+  ```
+  Listing directory failed but 'access-file' worked.
+  ```
+
+- `git`: macOS system usually has an older version of Git, this
+  typically refers to the version installed through Apple's Command
+  Line Tools (part of Xcode). Installing from Homebrew ensures a
+  modern version of git is installed and will avoid problems with
+  `magit`.
+
+
 ## Installation Instructions
 
 1. **Clone the repository**: