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

@@ -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))
 

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

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.