Merge pull request #20416 from Homebrew/copilot/fix-18036

Add brew doctor warning for symlinked /home directories on Linux

Library/Homebrew/extend/os/linux/diagnostic.rb

@@ -10,6 +10,7 @@ require "os/linux/kernel"
 module OS
   module Linux
     module Diagnostic
+      # Linux-specific diagnostic checks for Homebrew.
       module Checks
         extend T::Helpers
 
@@ -28,6 +29,7 @@ module OS
             check_glibc_minimum_version
             check_kernel_minimum_version
             check_supported_architecture
+            check_for_symlinked_home
           ].freeze
         end
 
@@ -154,6 +156,27 @@ module OS
           EOS
         end
 
+        def check_for_symlinked_home
+          return unless File.symlink?("/home")
+
+          <<~EOS
+            Your /home directory is a symlink.
+            This is known to cause issues with formula linking, particularly when installing
+            multiple formulae that create symlinks in shared directories.
+
+            While this may be a standard directory structure in some distributions
+            (e.g. Fedora Silverblue) there are known issues as-is.
+
+            If you encounter linking issues, you may need to manually create conflicting
+            directories or use `brew link --overwrite` as a workaround.
+
+            We'd welcome a PR to fix this functionality.
+            See https://github.com/Homebrew/brew/issues/18036 for more context.
+
+            #{support_tier_message(tier: 2)}
+          EOS
+        end
+
         def check_gcc_dependent_linkage
           gcc_dependents = ::Formula.installed.select do |formula|
             next false unless formula.tap&.core_tap?

Library/Homebrew/test/os/linux/diagnostic_spec.rb

@@ -25,4 +25,11 @@ RSpec.describe Homebrew::Diagnostic::Checks do
     expect(checks.check_kernel_minimum_version)
       .to match(/Your Linux kernel .+ is too old/)
   end
+
+  specify "#check_for_symlinked_home" do
+    allow(File).to receive(:symlink?).with("/home").and_return(true)
+
+    expect(checks.check_for_symlinked_home)
+      .to match(%r{Your /home directory is a symlink})
+  end
 end