From c363791da0031f36ab3713184ce5c158b03468a4 Mon Sep 17 00:00:00 2001
From: Henrik Lissner <henrik@lissner.net>
Date: Sat, 16 Nov 2019 20:41:46 -0500
Subject: [PATCH] Made -f the default for 'doom refresh' #2065

-f is necessary when there are changes to your system that Doom needs to
pick up when running 'doom refresh'. It won't do anything if your doom
dotfiles haven't visibly changed, which won't be the case if you are
installing, say, mu4e or vterm, through your system package manager.

What was initially a time-saving mechanic has become a trap for
beginners, so I've made -f its default behavior and its previous
behavior opt-in with the -n / --if-necessary switches.
---
 core/core-cli.el      |  6 +++---
 docs/contributing.org |  4 ++--
 docs/faq.org          | 12 +++++++-----
 3 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/core/core-cli.el b/core/core-cli.el
index 5cde55b4b..e1ca98b87 100644
--- a/core/core-cli.el
+++ b/core/core-cli.el
@@ -216,7 +216,7 @@ BODY will be run when this dispatcher is called."
 (load! "cli/install")
 
 (defcli! (refresh re)
-    ((force-p ["-f" "--force"] "Regenerate autoloads files, whether or not they're stale"))
+    ((if-necessary-p ["-n" "--if-necessary"] "Only regenerate autoloads files if necessary"))
   "Ensure Doom is properly set up.
 
 This is the equivalent of running autoremove, install, autoloads, then
@@ -234,7 +234,7 @@ stale."
   (let (success)
     (when (file-exists-p doom-env-file)
       (doom-cli-reload-env-file 'force))
-    (doom-cli-reload-core-autoloads force-p)
+    (doom-cli-reload-core-autoloads (not if-necessary-p))
     (unwind-protect
         (progn
           (and (doom-cli-packages-install)
@@ -243,7 +243,7 @@ stale."
                (setq success t))
           (and (doom-cli-packages-purge nil 'builds-p nil)
                (setq success t)))
-      (doom-cli-reload-package-autoloads (or success force-p))
+      (doom-cli-reload-package-autoloads (or success (not if-necessary-p)))
       (doom-cli-byte-compile nil 'recompile))
     t))
 
diff --git a/docs/contributing.org b/docs/contributing.org
index e8850ecf7..46feb468f 100644
--- a/docs/contributing.org
+++ b/docs/contributing.org
@@ -59,8 +59,8 @@ things you should try first:
 
 + Make sure your configuration (or Doom Emacs) is *not* byte-compiled. Run ~doom
   clean~ to ensure it isn't. *Byte-compilation interferes with debugging!*
-+ Run ~bin/doom refresh -f~ to ensure all plugins are installed and autoload
-  files generated.
++ Run ~bin/doom refresh~ to ensure all plugins are installed and autoload files
+  generated.
 + Run ~bin/doom doctor~ to diagnose common issues with your system.
 + Check [[file:faq.org::*Common%20Issues][Common Issues]] in the FAQ to see if yours is a known issue.
 + If you happen to know what module(s) are relevant to your issue, check their
diff --git a/docs/faq.org b/docs/faq.org
index 56b4b6990..695ee890c 100644
--- a/docs/faq.org
+++ b/docs/faq.org
@@ -813,10 +813,12 @@ commands that you may find particularly useful:
 ** When to run ~doom refresh~
 As a rule of thumb you should run ~doom refresh~ whenever you:
 
-+ Update Doom (with ~git pull~),
++ Update Doom with ~git pull~ instead of ~doom upgrade~,
 + Change your ~doom!~ block in =$DOOMDIR/init.el=,
-+ Change the autoload files in any module (or =$DOOMDIR=),
++ Change autoload files in any module (or =$DOOMDIR=),
 + Or change the packages.el file in any module (or =$DOOMDIR=).
++ Install an Emacs package or dependency outside of Emacs (i.e. through your OS
+  package manager).
 
 If anything is misbehaving, it's a good idea to run ~doom refresh~ first. ~doom
 refresh~ is responsible for regenerating your autoloads file (which tells Doom
@@ -985,12 +987,12 @@ manually (e.g. by double-clicking each file in explorer).
 ** ~void-variable~ and ~void-function~ errors on startup
 The most common culprit for these types of errors are:
 
-1. An out-of-date autoloads file. To regenerate it, run ~doom refresh -f~.
+1. An out-of-date autoloads file. To regenerate it, run ~doom refresh~.
 
    To avoid this issue, remember to run ~doom refresh~ whenever you modify your
    ~doom!~ block in =~/.doom.d/init.el=, or add ~package!~ declarations to
-   =~/.doom.d/packages.el=. If you modify =~/.emacs.d/.local= by hand, for
-   whatever reason, run ~doom refresh -f~ to bypass caches and modify-checks.
+   =~/.doom.d/packages.el=. Or if you modify =~/.emacs.d/.local= by hand, for
+   whatever reason.
 
    See ~doom help refresh~ for details on what this command does and when you
    should use it.