diff --git a/Library/Homebrew/cmd/linkapps.rb b/Library/Homebrew/cmd/linkapps.rb
index bd88409aaaa0c2ddd6638fa3ae3c5d2daaa4609f..7dd1a6b939dd4242a7d4e6ca3f9a806d0f6722bb 100644
--- a/Library/Homebrew/cmd/linkapps.rb
+++ b/Library/Homebrew/cmd/linkapps.rb
@@ -1,6 +1,11 @@
 #:  * `linkapps` [`--local`] [<formulae>]:
 #:    Find installed formulae that provide `.app`-style macOS apps and symlink them
-#:    into `/Applications`, allowing for easier access.
+#:    into `/Applications`, allowing for easier access (deprecated).
+#:
+#:    Unfortunately `brew linkapps` cannot behave nicely with e.g. Spotlight using
+#:    either aliases or symlinks and Homebrew formulae do not build "proper" `.app`
+#:    bundles that can be relocated. Instead, please consider using `brew cask` and
+#:    migrate formulae using `.app`s to casks.
 #:
 #:    If no <formulae> are provided, all of them will have their apps symlinked.
 #:
@@ -14,6 +19,15 @@ module Homebrew
   module_function
 
   def linkapps
+    opoo <<-EOS.undent
+      `brew linkapps` has been deprecated and will eventually be removed!
+
+      Unfortunately `brew linkapps` cannot behave nicely with e.g. Spotlight using
+      either aliases or symlinks and Homebrew formulae do not build "proper" `.app`
+      bundles that can be relocated. Instead, please consider using `brew cask` and
+      migrate formulae using `.app`s to casks.
+    EOS
+
     target_dir = linkapps_target(local: ARGV.include?("--local"))
 
     unless target_dir.directory?
diff --git a/Library/Homebrew/cmd/unlinkapps.rb b/Library/Homebrew/cmd/unlinkapps.rb
index d04ef9ee40e3d017b03954dbdcf8cf157a17fa91..b2ba458bf61bf1230496a8f6bf31d619687ee3f7 100644
--- a/Library/Homebrew/cmd/unlinkapps.rb
+++ b/Library/Homebrew/cmd/unlinkapps.rb
@@ -1,5 +1,10 @@
 #:  * `unlinkapps` [`--local`] [`--dry-run`] [<formulae>]:
-#:    Remove symlinks created by `brew linkapps` from `/Applications`.
+#:    Remove symlinks created by `brew linkapps` from `/Applications` (deprecated).
+#:
+#:    Unfortunately `brew linkapps` cannot behave nicely with e.g. Spotlight using
+#:    either aliases or symlinks and Homebrew formulae do not build "proper" `.app`
+#:    bundles that can be relocated. Instead, please consider using `brew cask` and
+#:    migrate formulae using `.app`s to casks.
 #:
 #:    If no <formulae> are provided, all linked apps will be removed.
 #:
@@ -15,6 +20,12 @@ module Homebrew
   module_function
 
   def unlinkapps
+    opoo <<-EOS.undent
+      `brew unlinkapps` has been deprecated and will eventually be removed!
+
+      Unfortunately `brew linkapps` cannot behave nicely with e.g. Spotlight using either aliases or symlinks and Homebrew formulae do not build "proper" `.app` bundles that can be relocated. Instead, please consider using `brew cask` and migrate formulae using `.app`s to casks.
+    EOS
+
     target_dir = linkapps_target(local: ARGV.include?("--local"))
 
     unlinkapps_from_dir(target_dir, dry_run: ARGV.dry_run?)
diff --git a/docs/brew.1.html b/docs/brew.1.html
index 8c81b1ddb0db1ada9984a6e64c2d357a49bf05c4..ba65157cb96639b8471bd3cdf8c46ecc63cf19d6 100644
--- a/docs/brew.1.html
+++ b/docs/brew.1.html
@@ -223,7 +223,12 @@ actually link or delete any files.</p>
 
 <p>If <code>--force</code> is passed, Homebrew will allow keg-only formulae to be linked.</p></dd>
 <dt><code>linkapps</code> [<code>--local</code>] [<var>formulae</var>]</dt><dd><p>Find installed formulae that provide <code>.app</code>-style macOS apps and symlink them
-into <code>/Applications</code>, allowing for easier access.</p>
+into <code>/Applications</code>, allowing for easier access (deprecated).</p>
+
+<p>Unfortunately <code>brew linkapps</code> cannot behave nicely with e.g. Spotlight using
+either aliases or symlinks and Homebrew formulae do not build "proper" <code>.app</code>
+bundles that can be relocated. Instead, please consider using <code>brew cask</code> and
+migrate formulae using <code>.app</code>s to casks.</p>
 
 <p>If no <var>formulae</var> are provided, all of them will have their apps symlinked.</p>
 
@@ -369,7 +374,12 @@ for temporarily disabling a formula:
 
 <p>If <code>--dry-run</code> or <code>-n</code> is passed, Homebrew will list all files which would
 be unlinked, but will not actually unlink or delete any files.</p></dd>
-<dt><code>unlinkapps</code> [<code>--local</code>] [<code>--dry-run</code>] [<var>formulae</var>]</dt><dd><p>Remove symlinks created by <code>brew linkapps</code> from <code>/Applications</code>.</p>
+<dt><code>unlinkapps</code> [<code>--local</code>] [<code>--dry-run</code>] [<var>formulae</var>]</dt><dd><p>Remove symlinks created by <code>brew linkapps</code> from <code>/Applications</code> (deprecated).</p>
+
+<p>Unfortunately <code>brew linkapps</code> cannot behave nicely with e.g. Spotlight using
+either aliases or symlinks and Homebrew formulae do not build "proper" <code>.app</code>
+bundles that can be relocated. Instead, please consider using <code>brew cask</code> and
+migrate formulae using <code>.app</code>s to casks.</p>
 
 <p>If no <var>formulae</var> are provided, all linked apps will be removed.</p>
 
diff --git a/manpages/brew.1 b/manpages/brew.1
index c9269e7b3919020a03546085f63e4c17489ccefb..aa1d1c1d00fde78ea806e1ef409cc170a49c3270 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -294,7 +294,10 @@ If \fB\-\-force\fR is passed, Homebrew will allow keg\-only formulae to be linke
 .
 .TP
 \fBlinkapps\fR [\fB\-\-local\fR] [\fIformulae\fR]
-Find installed formulae that provide \fB\.app\fR\-style macOS apps and symlink them into \fB/Applications\fR, allowing for easier access\.
+Find installed formulae that provide \fB\.app\fR\-style macOS apps and symlink them into \fB/Applications\fR, allowing for easier access (deprecated)\.
+.
+.IP
+Unfortunately \fBbrew linkapps\fR cannot behave nicely with e\.g\. Spotlight using either aliases or symlinks and Homebrew formulae do not build "proper" \fB\.app\fR bundles that can be relocated\. Instead, please consider using \fBbrew cask\fR and migrate formulae using \fB\.app\fRs to casks\.
 .
 .IP
 If no \fIformulae\fR are provided, all of them will have their apps symlinked\.
@@ -508,7 +511,10 @@ If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, Homebrew will list all files which
 .
 .TP
 \fBunlinkapps\fR [\fB\-\-local\fR] [\fB\-\-dry\-run\fR] [\fIformulae\fR]
-Remove symlinks created by \fBbrew linkapps\fR from \fB/Applications\fR\.
+Remove symlinks created by \fBbrew linkapps\fR from \fB/Applications\fR (deprecated)\.
+.
+.IP
+Unfortunately \fBbrew linkapps\fR cannot behave nicely with e\.g\. Spotlight using either aliases or symlinks and Homebrew formulae do not build "proper" \fB\.app\fR bundles that can be relocated\. Instead, please consider using \fBbrew cask\fR and migrate formulae using \fB\.app\fRs to casks\.
 .
 .IP
 If no \fIformulae\fR are provided, all linked apps will be removed\.