From 70222ac5b5f64c954c4b977605b74497476a255f Mon Sep 17 00:00:00 2001
From: Shutong Wu <51266340+Scriptwonder@users.noreply.github.com>
Date: Wed, 2 Sep 2026 20:01:27 -0400
Subject: [PATCH 1/2] feat(setup): show git status in the setup window and
 explain the Git-URL failure

Adding the package from a Git URL makes the Package Manager shell out to git, and
two failures look identical to the user: git missing from PATH, or git refusing a
folder owned by another account ('fatal: not in a git directory'). Issue #1216 and
its duplicates are all one of those two, and the setup window gave no signal either
way because it only checks Python and uv.

Detect git as an OPTIONAL dependency so a missing git can never block setup, show
it as its own row, and put the safe.directory remedy in the row details and in the
troubleshooting guide. Missing optional dependencies now render in the neutral
colour rather than the red reserved for required ones.

Closes #1216
---
 .../Editor/Dependencies/DependencyManager.cs  |  3 +
 .../PlatformDetectors/IPlatformDetector.cs    |  5 ++
 .../PlatformDetectors/PlatformDetectorBase.cs | 61 +++++++++++++++++
 MCPForUnity/Editor/Windows/MCPSetupWindow.cs  | 21 +++++-
 .../Editor/Windows/MCPSetupWindow.uxml        | 12 +++-
 .../Tests/EditMode/GitDetectionTests.cs       | 66 +++++++++++++++++++
 .../Tests/EditMode/GitDetectionTests.cs.meta  | 11 ++++
 website/docs/getting-started/install.md       |  2 +
 website/docs/guides/troubleshooting.md        | 17 +++++
 9 files changed, 195 insertions(+), 3 deletions(-)
 create mode 100644 TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs
 create mode 100644 TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs.meta

diff --git a/MCPForUnity/Editor/Dependencies/DependencyManager.cs b/MCPForUnity/Editor/Dependencies/DependencyManager.cs
index c3802c475..79c4156e0 100644
--- a/MCPForUnity/Editor/Dependencies/DependencyManager.cs
+++ b/MCPForUnity/Editor/Dependencies/DependencyManager.cs
@@ -60,6 +60,9 @@ public static DependencyCheckResult CheckAllDependencies()
                 var uvStatus = detector.DetectUv();
                 result.Dependencies.Add(uvStatus);
 
+                // Check git (optional: Package Manager Git-URL installs only)
+                result.Dependencies.Add(detector.DetectGit());
+
                 // Generate summary and recommendations
                 result.GenerateSummary();
                 GenerateRecommendations(result, detector);
diff --git a/MCPForUnity/Editor/Dependencies/PlatformDetectors/IPlatformDetector.cs b/MCPForUnity/Editor/Dependencies/PlatformDetectors/IPlatformDetector.cs
index 3231105e9..08a3c221e 100644
--- a/MCPForUnity/Editor/Dependencies/PlatformDetectors/IPlatformDetector.cs
+++ b/MCPForUnity/Editor/Dependencies/PlatformDetectors/IPlatformDetector.cs
@@ -27,6 +27,11 @@ public interface IPlatformDetector
         /// </summary>
         DependencyStatus DetectUv();
 
+        /// <summary>
+        /// Detect git on this platform. Optional: only the Package Manager's Git-URL install path needs it.
+        /// </summary>
+        DependencyStatus DetectGit();
+
         /// <summary>
         /// Get platform-specific installation recommendations
         /// </summary>
diff --git a/MCPForUnity/Editor/Dependencies/PlatformDetectors/PlatformDetectorBase.cs b/MCPForUnity/Editor/Dependencies/PlatformDetectors/PlatformDetectorBase.cs
index c955381d1..73693f2a4 100644
--- a/MCPForUnity/Editor/Dependencies/PlatformDetectors/PlatformDetectorBase.cs
+++ b/MCPForUnity/Editor/Dependencies/PlatformDetectors/PlatformDetectorBase.cs
@@ -64,6 +64,67 @@ public virtual DependencyStatus DetectUv()
         }
 
 
+        // Git is not needed to run the bridge, only to add or update the package from a Git URL
+        // in the Package Manager, which is the install path most users take (issue #1216). It is
+        // reported as optional so a missing git never blocks setup, but the row tells the user why
+        // "Error when executing git command" appeared and how to clear it.
+        public const string GitInstallUrl = "https://git-scm.com/downloads";
+
+        public virtual DependencyStatus DetectGit()
+        {
+            var status = new DependencyStatus("Git", isRequired: false)
+            {
+                InstallationHint = GitInstallUrl
+            };
+
+            try
+            {
+                if (!TryFindInPath("git", out string gitPath))
+                {
+                    status.ErrorMessage = "git not found";
+                    status.Details = "Only needed to add or update MCP for Unity from a Git URL in the Package Manager.";
+                    return status;
+                }
+
+                if (ExecPath.TryRun(gitPath, "--version", null, out string stdout, out string stderr, 5000)
+                    && TryParseGitVersion(string.IsNullOrWhiteSpace(stdout) ? stderr : stdout, out string version))
+                {
+                    status.IsAvailable = true;
+                    status.Version = version;
+                    status.Path = gitPath;
+                    status.Details = "If the Package Manager still reports 'not in a git directory', git is refusing a folder "
+                        + "owned by another user: run  git config --global --add safe.directory <project folder>";
+                    return status;
+                }
+
+                status.ErrorMessage = "git found but did not report a version";
+                status.Path = gitPath;
+            }
+            catch (Exception ex)
+            {
+                status.ErrorMessage = $"Error detecting git: {ex.Message}";
+            }
+
+            return status;
+        }
+
+        /// <summary>Parses "git version 2.45.1.windows.1" or "git version 2.39.5 (Apple Git-154)" into "2.45.1.windows.1" / "2.39.5".</summary>
+        internal static bool TryParseGitVersion(string output, out string version)
+        {
+            version = null;
+            string line = (output ?? string.Empty).Trim();
+            const string prefix = "git version ";
+            if (!line.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+            {
+                return false;
+            }
+
+            string rest = line.Substring(prefix.Length).Trim();
+            int end = rest.IndexOfAny(new[] { ' ', '\r', '\n' });
+            version = end >= 0 ? rest.Substring(0, end) : rest;
+            return version.Length > 0 && char.IsDigit(version[0]);
+        }
+
         protected bool TryParseVersion(string version, out int major, out int minor)
         {
             major = 0;
diff --git a/MCPForUnity/Editor/Windows/MCPSetupWindow.cs b/MCPForUnity/Editor/Windows/MCPSetupWindow.cs
index efbee14e8..d8ee58879 100644
--- a/MCPForUnity/Editor/Windows/MCPSetupWindow.cs
+++ b/MCPForUnity/Editor/Windows/MCPSetupWindow.cs
@@ -25,6 +25,9 @@ public class MCPSetupWindow : EditorWindow
         private VisualElement uvIndicator;
         private Label uvVersion;
         private Label uvDetails;
+        private VisualElement gitIndicator;
+        private Label gitVersion;
+        private Label gitDetails;
         private Label statusMessage;
         private VisualElement installationSection;
         private Label installationInstructions;
@@ -88,6 +91,9 @@ public void CreateGUI()
             uvIndicator = rootVisualElement.Q<VisualElement>("uv-indicator");
             uvVersion = rootVisualElement.Q<Label>("uv-version");
             uvDetails = rootVisualElement.Q<Label>("uv-details");
+            gitIndicator = rootVisualElement.Q<VisualElement>("git-indicator");
+            gitVersion = rootVisualElement.Q<Label>("git-version");
+            gitDetails = rootVisualElement.Q<Label>("git-details");
             statusMessage = rootVisualElement.Q<Label>("status-message");
             installationSection = rootVisualElement.Q<VisualElement>("installation-section");
             installationInstructions = rootVisualElement.Q<Label>("installation-instructions");
@@ -328,6 +334,13 @@ private void UpdateUI()
                 UpdateDependencyStatus(uvIndicator, uvVersion, uvDetails, uvDep);
             }
 
+            // Update git status (optional dependency: never blocks readiness)
+            var gitDep = _dependencyResult.Dependencies.Find(d => d.Name == "Git");
+            if (gitDep != null)
+            {
+                UpdateDependencyStatus(gitIndicator, gitVersion, gitDetails, gitDep);
+            }
+
             // Offer the one-click uv installer only when uv is actually missing
             bool uvMissing = uvDep != null && !uvDep.IsAvailable;
             if (installUvButton != null)
@@ -367,8 +380,12 @@ private void UpdateDependencyStatus(VisualElement indicator, Label versionLabel,
                 indicator.RemoveFromClassList("valid");
                 indicator.AddToClassList("invalid");
                 versionLabel.text = "Not Found";
-                detailsLabel.text = dep.ErrorMessage ?? "Not available";
-                detailsLabel.style.color = new StyleColor(Color.red);
+                // A missing optional dependency is information, not a blocker: show what it is
+                // for in the neutral colour instead of the red used for required ones.
+                detailsLabel.text = dep.IsRequired
+                    ? dep.ErrorMessage ?? "Not available"
+                    : dep.Details ?? dep.ErrorMessage ?? "Not available";
+                detailsLabel.style.color = new StyleColor(dep.IsRequired ? Color.red : Color.gray);
             }
         }
     }
diff --git a/MCPForUnity/Editor/Windows/MCPSetupWindow.uxml b/MCPForUnity/Editor/Windows/MCPSetupWindow.uxml
index 1f69286bd..35cbf0b41 100644
--- a/MCPForUnity/Editor/Windows/MCPSetupWindow.uxml
+++ b/MCPForUnity/Editor/Windows/MCPSetupWindow.uxml
@@ -11,7 +11,7 @@
             <ui:VisualElement class="section">
                 <ui:Label text="System Requirements" class="section-title" />
                 <ui:VisualElement class="section-content">
-                    <ui:Label text="MCP for Unity requires Python 3.10+ and UV package manager to function." class="help-text description-text" />
+                    <ui:Label text="MCP for Unity requires Python 3.10+ and UV package manager to function. Git is only needed to install or update the package from a Git URL." class="help-text description-text" />
 
                     <!-- Dependency Status -->
                     <ui:VisualElement name="dependency-list">
@@ -34,6 +34,16 @@
                             </ui:VisualElement>
                             <ui:Label name="uv-details" class="help-text dependency-details" />
                         </ui:VisualElement>
+
+                        <!-- Git Status (optional) -->
+                        <ui:VisualElement class="dependency-item">
+                            <ui:VisualElement class="dependency-row">
+                                <ui:Label text="Git (optional)" class="dependency-name" />
+                                <ui:Label name="git-version" text="..." class="setting-value" />
+                                <ui:VisualElement name="git-indicator" class="status-indicator-small" />
+                            </ui:VisualElement>
+                            <ui:Label name="git-details" class="help-text dependency-details" />
+                        </ui:VisualElement>
                     </ui:VisualElement>
 
                     <!-- Overall Status Message -->
diff --git a/TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs b/TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs
new file mode 100644
index 000000000..2c60ea78d
--- /dev/null
+++ b/TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs
@@ -0,0 +1,66 @@
+using System.Linq;
+using MCPForUnity.Editor.Dependencies;
+using MCPForUnity.Editor.Dependencies.Models;
+using MCPForUnity.Editor.Dependencies.PlatformDetectors;
+using NUnit.Framework;
+
+namespace MCPForUnityTests.Editor
+{
+    public class GitDetectionTests
+    {
+        [TestCase("git version 2.45.1.windows.1", "2.45.1.windows.1")]
+        [TestCase("git version 2.39.5 (Apple Git-154)", "2.39.5")]
+        [TestCase("  git version 2.43.0\n", "2.43.0")]
+        public void TryParseGitVersion_ExtractsTheVersionToken(string output, string expected)
+        {
+            Assert.IsTrue(PlatformDetectorBase.TryParseGitVersion(output, out string version));
+            Assert.AreEqual(expected, version);
+        }
+
+        [TestCase("")]
+        [TestCase(null)]
+        [TestCase("'git' is not recognized as an internal or external command")]
+        [TestCase("git version ")]
+        [TestCase("git version beta")]
+        public void TryParseGitVersion_RejectsAnythingThatIsNotAGitVersionLine(string output)
+        {
+            Assert.IsFalse(PlatformDetectorBase.TryParseGitVersion(output, out _));
+        }
+
+        [Test]
+        public void CheckAllDependencies_ReportsGitAsOptional()
+        {
+            var result = DependencyManager.CheckAllDependencies();
+            var git = result.Dependencies.FirstOrDefault(d => d.Name == "Git");
+
+            Assert.IsNotNull(git, "The dependency check should always include a Git row");
+            Assert.IsFalse(git.IsRequired, "Git must never block setup; only Git-URL installs need it");
+            Assert.AreEqual(PlatformDetectorBase.GitInstallUrl, git.InstallationHint);
+            if (git.IsAvailable)
+            {
+                Assert.IsFalse(string.IsNullOrEmpty(git.Version));
+                Assert.IsFalse(string.IsNullOrEmpty(git.Path));
+            }
+            else
+            {
+                Assert.IsFalse(string.IsNullOrEmpty(git.ErrorMessage));
+            }
+        }
+
+        [Test]
+        public void MissingGit_DoesNotMakeTheSystemNotReady()
+        {
+            // Mirrors what the setup window computes: Python and uv present, git absent.
+            var result = new DependencyCheckResult();
+            result.Dependencies.Add(new DependencyStatus("Python") { IsAvailable = true, Version = "3.12.0" });
+            result.Dependencies.Add(new DependencyStatus("uv Package Manager") { IsAvailable = true, Version = "0.8.0" });
+            result.Dependencies.Add(new DependencyStatus("Git", isRequired: false) { IsAvailable = false, ErrorMessage = "git not found" });
+
+            result.GenerateSummary();
+
+            Assert.IsTrue(result.IsSystemReady);
+            Assert.IsTrue(result.HasMissingOptional);
+            Assert.IsEmpty(result.GetMissingRequired());
+        }
+    }
+}
diff --git a/TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs.meta b/TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs.meta
new file mode 100644
index 000000000..3b0aab0ea
--- /dev/null
+++ b/TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 48a82ca94d9e4cd0ac61182d8ae86f74
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
diff --git a/website/docs/getting-started/install.md b/website/docs/getting-started/install.md
index fa4159468..ba28b5225 100644
--- a/website/docs/getting-started/install.md
+++ b/website/docs/getting-started/install.md
@@ -18,6 +18,8 @@ Three install paths are supported. Pick one. **Git URL** is the fastest if you j
 
 ## Option 1 — Git URL (fastest)
 
+This path needs `git` on your PATH (the Package Manager runs it). If it reports `Error when executing git command`, see [troubleshooting](../guides/troubleshooting.md#package-manager-error-when-executing-git-command--not-in-a-git-directory).
+
 In Unity, open **Window → Package Manager**, click the **`+`** button, choose **Add package from git URL...**, and paste:
 
 ```text
diff --git a/website/docs/guides/troubleshooting.md b/website/docs/guides/troubleshooting.md
index 76ac65bb5..e573c7cce 100644
--- a/website/docs/guides/troubleshooting.md
+++ b/website/docs/guides/troubleshooting.md
@@ -165,6 +165,23 @@ This is a Unity bug (UUM-132096), not an MCP for Unity one.
 
 ---
 
+## Package Manager: "Error when executing git command" / "not in a git directory"
+
+Adding the package from a Git URL makes the Package Manager shell out to `git`. Two things make that fail:
+
+1. **git is not installed or not on PATH.** Install it from [git-scm.com](https://git-scm.com/downloads) and restart Unity so the Editor picks up the new PATH. The setup window (**Window → MCP for Unity → Local Setup Window**) shows a **Git (optional)** row so you can confirm the Editor sees it.
+2. **git refuses the folder.** Newer git versions decline to run inside a directory owned by a different user account (external drives, shared folders, projects created by another account). The Package Manager surfaces this as `fatal: not in a git directory`. Tell git the folder is yours:
+
+```bash
+git config --global --add safe.directory "/path/to/the/parent/folder"
+```
+
+Trusting the parent folder covers every project inside it. Restart Unity and add the package again.
+
+Git is only needed for this install path; the bridge itself does not use it, so a missing git never blocks setup.
+
+*Reported by [@Cherrymocha](https://github.com/CoplayDev/unity-mcp/issues/1216).*
+
 ## Codex: `resources/read failed: unknown MCP server`
 
 The `mcpforunity://` URI names the *resource*, not the server. Some clients take a separate server key on a resource read.

From dfe6795c91e9e64b21ec4d82971581d3210e1602 Mon Sep 17 00:00:00 2001
From: Shutong Wu <shutong@ramenvr.com>
Date: Sat, 5 Sep 2026 13:47:06 -0400
Subject: [PATCH 2/2] fix(setup): keep the optional row neutral and correct the
 safe.directory advice

Addresses the review on #1383.

The missing-optional branch still added the `invalid` class to the indicator,
and `.status-indicator-small.invalid` is red in Components/Common.uss, which
MCPSetupWindow.uxml loads. Only the details text was made conditional, so a
machine without git showed a red dot next to grey "only needed for Git-URL
installs" text - the opposite of what the row is for. The branch now drops both
state classes, leaving the plain grey of the base class. Split into three cases
rather than one branch with two ternaries, since that pairing is what let the
indicator and the text disagree.

UpdateDependencyStatus becomes internal static - it touched no instance state -
so the three new tests can drive it directly through the InternalsVisibleTo the
test assembly already has.

The safe.directory line was wrong in both places it appeared. Git's own docs:
"Giving a directory with /* appended to it will allow access to all repositories
under the named directory." A plain parent path trusts only that exact
repository, so "Trusting the parent folder covers every project inside it" was
untrue. The docs now give both forms and say which is which; the reporter on
#1216 used the parent-folder one, so it stays rather than being dropped. The
in-editor hint also loses a double space and gains quotes around the path, which
Windows project paths need.
---
 .../PlatformDetectors/PlatformDetectorBase.cs |  2 +-
 MCPForUnity/Editor/Windows/MCPSetupWindow.cs  | 23 ++++---
 .../Tests/EditMode/GitDetectionTests.cs       | 67 +++++++++++++++++++
 website/docs/guides/troubleshooting.md        |  8 ++-
 4 files changed, 89 insertions(+), 11 deletions(-)

diff --git a/MCPForUnity/Editor/Dependencies/PlatformDetectors/PlatformDetectorBase.cs b/MCPForUnity/Editor/Dependencies/PlatformDetectors/PlatformDetectorBase.cs
index 73693f2a4..c2ae4f948 100644
--- a/MCPForUnity/Editor/Dependencies/PlatformDetectors/PlatformDetectorBase.cs
+++ b/MCPForUnity/Editor/Dependencies/PlatformDetectors/PlatformDetectorBase.cs
@@ -93,7 +93,7 @@ public virtual DependencyStatus DetectGit()
                     status.Version = version;
                     status.Path = gitPath;
                     status.Details = "If the Package Manager still reports 'not in a git directory', git is refusing a folder "
-                        + "owned by another user: run  git config --global --add safe.directory <project folder>";
+                        + "owned by another user: run git config --global --add safe.directory \"<your Unity project folder>\"";
                     return status;
                 }
 
diff --git a/MCPForUnity/Editor/Windows/MCPSetupWindow.cs b/MCPForUnity/Editor/Windows/MCPSetupWindow.cs
index d8ee58879..8594a68d6 100644
--- a/MCPForUnity/Editor/Windows/MCPSetupWindow.cs
+++ b/MCPForUnity/Editor/Windows/MCPSetupWindow.cs
@@ -365,7 +365,7 @@ private void UpdateUI()
             }
         }
 
-        private void UpdateDependencyStatus(VisualElement indicator, Label versionLabel, Label detailsLabel, DependencyStatus dep)
+        internal static void UpdateDependencyStatus(VisualElement indicator, Label versionLabel, Label detailsLabel, DependencyStatus dep)
         {
             if (dep.IsAvailable)
             {
@@ -375,17 +375,24 @@ private void UpdateDependencyStatus(VisualElement indicator, Label versionLabel,
                 detailsLabel.text = dep.Details ?? "Available";
                 detailsLabel.style.color = new StyleColor(Color.gray);
             }
-            else
+            else if (dep.IsRequired)
             {
                 indicator.RemoveFromClassList("valid");
                 indicator.AddToClassList("invalid");
                 versionLabel.text = "Not Found";
-                // A missing optional dependency is information, not a blocker: show what it is
-                // for in the neutral colour instead of the red used for required ones.
-                detailsLabel.text = dep.IsRequired
-                    ? dep.ErrorMessage ?? "Not available"
-                    : dep.Details ?? dep.ErrorMessage ?? "Not available";
-                detailsLabel.style.color = new StyleColor(dep.IsRequired ? Color.red : Color.gray);
+                detailsLabel.text = dep.ErrorMessage ?? "Not available";
+                detailsLabel.style.color = new StyleColor(Color.red);
+            }
+            else
+            {
+                // A missing optional dependency is information, not a blocker. Drop both state
+                // classes so the dot keeps the neutral grey of .status-indicator-small instead of
+                // the red .invalid reserved for required ones, and say what it is for.
+                indicator.RemoveFromClassList("valid");
+                indicator.RemoveFromClassList("invalid");
+                versionLabel.text = "Not Found";
+                detailsLabel.text = dep.Details ?? dep.ErrorMessage ?? "Not available";
+                detailsLabel.style.color = new StyleColor(Color.gray);
             }
         }
     }
diff --git a/TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs b/TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs
index 2c60ea78d..67a8d5fa0 100644
--- a/TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs
+++ b/TestProjects/UnityMCPTests/Assets/Tests/EditMode/GitDetectionTests.cs
@@ -2,7 +2,10 @@
 using MCPForUnity.Editor.Dependencies;
 using MCPForUnity.Editor.Dependencies.Models;
 using MCPForUnity.Editor.Dependencies.PlatformDetectors;
+using MCPForUnity.Editor.Windows;
 using NUnit.Framework;
+using UnityEngine;
+using UnityEngine.UIElements;
 
 namespace MCPForUnityTests.Editor
 {
@@ -62,5 +65,69 @@ public void MissingGit_DoesNotMakeTheSystemNotReady()
             Assert.IsTrue(result.HasMissingOptional);
             Assert.IsEmpty(result.GetMissingRequired());
         }
+
+        [Test]
+        public void MissingOptionalRow_KeepsTheNeutralIndicatorAndExplainsWhatItIsFor()
+        {
+            var indicator = new VisualElement();
+            indicator.AddToClassList("status-indicator-small");
+            indicator.AddToClassList("valid"); // stale state from an earlier refresh
+            var version = new Label();
+            var details = new Label();
+            var dep = new DependencyStatus("Git", isRequired: false)
+            {
+                IsAvailable = false,
+                ErrorMessage = "git not found",
+                Details = "Only needed to add or update MCP for Unity from a Git URL in the Package Manager."
+            };
+
+            MCPSetupWindow.UpdateDependencyStatus(indicator, version, details, dep);
+
+            // .status-indicator-small.invalid is red in Common.uss; an optional row must keep the
+            // plain grey of the base class so it does not read as a blocker.
+            Assert.IsFalse(indicator.ClassListContains("invalid"));
+            Assert.IsFalse(indicator.ClassListContains("valid"));
+            Assert.AreEqual(dep.Details, details.text);
+            Assert.AreEqual(Color.gray, details.style.color.value);
+        }
+
+        [Test]
+        public void MissingRequiredRow_StaysRed()
+        {
+            var indicator = new VisualElement();
+            indicator.AddToClassList("status-indicator-small");
+            var version = new Label();
+            var details = new Label();
+            var dep = new DependencyStatus("Python") { IsAvailable = false, ErrorMessage = "Python not found" };
+
+            MCPSetupWindow.UpdateDependencyStatus(indicator, version, details, dep);
+
+            Assert.IsTrue(indicator.ClassListContains("invalid"));
+            Assert.AreEqual("Python not found", details.text);
+            Assert.AreEqual(Color.red, details.style.color.value);
+        }
+
+        [Test]
+        public void AvailableGitRow_ShowsTheVersionAndTheSafeDirectoryRemedy()
+        {
+            var indicator = new VisualElement();
+            indicator.AddToClassList("status-indicator-small");
+            indicator.AddToClassList("invalid"); // stale state from an earlier refresh
+            var version = new Label();
+            var details = new Label();
+            var dep = new DependencyStatus("Git", isRequired: false)
+            {
+                IsAvailable = true,
+                Version = "2.45.1",
+                Details = "run git config --global --add safe.directory \"<your Unity project folder>\""
+            };
+
+            MCPSetupWindow.UpdateDependencyStatus(indicator, version, details, dep);
+
+            Assert.IsTrue(indicator.ClassListContains("valid"));
+            Assert.IsFalse(indicator.ClassListContains("invalid"));
+            Assert.AreEqual("v2.45.1", version.text);
+            Assert.AreEqual(dep.Details, details.text);
+        }
     }
 }
diff --git a/website/docs/guides/troubleshooting.md b/website/docs/guides/troubleshooting.md
index e573c7cce..3dd425f4d 100644
--- a/website/docs/guides/troubleshooting.md
+++ b/website/docs/guides/troubleshooting.md
@@ -173,10 +173,14 @@ Adding the package from a Git URL makes the Package Manager shell out to `git`.
 2. **git refuses the folder.** Newer git versions decline to run inside a directory owned by a different user account (external drives, shared folders, projects created by another account). The Package Manager surfaces this as `fatal: not in a git directory`. Tell git the folder is yours:
 
 ```bash
-git config --global --add safe.directory "/path/to/the/parent/folder"
+# trust this one project
+git config --global --add safe.directory "/path/to/the/unity/project"
+
+# or trust every repository under a folder — the trailing /* is required
+git config --global --add safe.directory "/path/to/the/parent/folder/*"
 ```
 
-Trusting the parent folder covers every project inside it. Restart Unity and add the package again.
+A plain directory path only trusts that exact repository; the `/*` suffix is what extends it to the repositories underneath. Restart Unity and add the package again.
 
 Git is only needed for this install path; the bridge itself does not use it, so a missing git never blocks setup.