Minor refactors & comment/message revision

README.md

@@ -120,10 +120,10 @@ installing, configuring and maintaining Doom Emacs.
 It's a good idea to add `~/.emacs.d/bin` to your `PATH`! Other `bin/doom`
 commands you should know about:
 
-+ `doom sync` to synchronize your private config with Doom. Installs new
++ `doom sync` to synchronize your private config with Doom by installing missing
-  packages, removes orphaned packages and regenerates caches. Run this whenever
+  packages, removing orphaned packages, and regenerating caches. Run this
-  you modify your private `init.el` or `packages.el`, or install/remove an Emacs
+  whenever you modify your private `init.el` or `packages.el`, or install/remove
-  package through your OS package manager (e.g. mu4e or agda).
+  an Emacs package through your OS package manager (e.g. mu4e or agda).
 + `doom upgrade` to update Doom to the latest release & all installed packages.
 + `doom doctor` to diagnose common issues with your system and config.
 + `doom env` to dump a snapshot of your shell environment to a file that Doom

core/autoload/debug.el

@@ -154,13 +154,13 @@ branch and commit."
   (interactive)
   (require 'vc-git)
   (let ((default-directory doom-core-dir))
-    (print! "Doom v%s (Emacs v%s)\nBranch: %s\nCommit: %s\nBuild date: %s"
+    (print! "Doom v%s (%s)\nEmacs v%s\nBranch: %s\nBuild date: %s"
             doom-version
+            (or (vc-git-working-revision doom-core-dir)
+                "n/a")
             emacs-version
             (or (vc-git--symbolic-ref doom-core-dir)
                 "n/a")
-            (or (vc-git-working-revision doom-core-dir)
-                "n/a")
             (or (cdr (doom-call-process "git" "log" "-1" "--format=%ci"))
                 "n/a"))))
 

core/autoload/packages.el

@@ -89,7 +89,7 @@ Grabs the latest commit id of the package using 'git'."
                            "git" "ls-remote" url
                            (unless select
                              (or branch straight-vc-git-default-branch)))))
-                   (user-error "%s: no id from %s" package url)))
+                   (user-error "Couldn't find a recipe for %s" package)))
            (id (car (split-string
                      (if select
                          (completing-read "Commit: " (split-string id "\n" t))

core/core-modules.el

@@ -111,7 +111,7 @@ non-nil."
     (unless no-config-p
       (doom-log "Initializing core modules")
       (doom-initialize-core-modules))
-    (when-let (init-p (load! "init" doom-private-dir t))
+    (when-let (init-p (load! doom-module-init-file doom-private-dir t))
       (doom-log "Initializing user config")
       (maphash (doom-module-loader doom-module-init-file) doom-modules)
       (run-hook-wrapped 'doom-before-init-modules-hook #'doom-try-run-hook)

core/core.el

@@ -19,7 +19,7 @@
 (defconst IS-WINDOWS (memq system-type '(cygwin windows-nt ms-dos)))
 (defconst IS-BSD     (or IS-MAC (eq system-type 'berkeley-unix)))
 
-;; Unix tools looks for HOME, but this is normally not defined on Windows.
+;; Unix tools look for HOME, but this is normally not defined on Windows.
 (when (and IS-WINDOWS (null (getenv "HOME")))
   (setenv "HOME" (getenv "USERPROFILE")))
 
@@ -448,10 +448,10 @@ If RETURN-P, return the message as a string instead of displaying it."
 (defun doom-initialize (&optional force-p)
   "Bootstrap Doom, if it hasn't already (or if FORCE-P is non-nil).
 
-The bootstrap process ensures that the essential directories exist, all core
+The bootstrap process ensures that everything Doom needs to run is set up;
-packages are installed, `doom-autoload-file' and `doom-package-autoload-file'
+essential directories exist, core packages are installed, `doom-autoload-file'
-exist and are loaded, and that `core-packages' is auto-loaded when `package' or
+is loaded (failing if it isn't), that all the needed hooks are in place, and
-`straight' are.
+that `core-packages' will load when `package' or `straight' is used.
 
 The overall load order of Doom is as follows:
 

core/templates/packages.example.el

@@ -1,25 +1,16 @@
 ;; -*- no-byte-compile: t; -*-
 ;;; $DOOMDIR/packages.el
 
-;; To install a package with Doom you must declare them here, run 'doom sync' on
+;; To install a package with Doom you must declare them here and run 'doom sync'
-;; the command line, then restart Emacs for the changes to take effect.
+;; on the command line, then restart Emacs for the changes to take effect -- or
-;; Alternatively, use M-x doom/reload.
+;; use 'M-x doom/reload'.
-
-
-;; Doom's packages are pinned to a specific commit and updated from release to
-;; release. The `unpin!' macro allows you to unpin single packages...
-;(unpin! pinned-package)
-;; ...or multiple packages
-;(unpin! pinned-package another-pinned-package)
-;; ...Or *all* packages (NOT RECOMMENDED; will likely break things)
-;(unpin! t)
 
 
 ;; To install SOME-PACKAGE from MELPA, ELPA or emacsmirror:
 ;(package! some-package)
 
-;; To install a package directly from a particular repo, you'll need to specify
+;; To install a package directly from a remote git repo, you must specify a
-;; a `:recipe'. You'll find documentation on what `:recipe' accepts here:
+;; `:recipe'. You'll find documentation on what `:recipe' accepts here:
 ;; https://github.com/raxod502/straight.el#the-recipe-format
 ;(package! another-package
 ;  :recipe (:host github :repo "username/repo"))
@@ -31,8 +22,8 @@
 ;  :recipe (:host github :repo "username/repo"
 ;           :files ("some-file.el" "src/lisp/*.el")))
 
-;; If you'd like to disable a package included with Doom, for whatever reason,
+;; If you'd like to disable a package included with Doom, you can do so here
-;; you can do so here with the `:disable' property:
+;; with the `:disable' property:
 ;(package! builtin-package :disable t)
 
 ;; You can override the recipe of a built in package without having to specify
@@ -45,3 +36,15 @@
 ;; This is required for some packages whose default branch isn't 'master' (which
 ;; our package manager can't deal with; see raxod502/straight.el#279)
 ;(package! builtin-package :recipe (:branch "develop"))
+
+;; Use `:pin' to specify a particular commit to install.
+;(package! builtin-package :pin "1a2b3c4d5e")
+
+
+;; Doom's packages are pinned to a specific commit and updated from release to
+;; release. The `unpin!' macro allows you to unpin single packages...
+;(unpin! pinned-package)
+;; ...or multiple packages
+;(unpin! pinned-package another-pinned-package)
+;; ...Or *all* packages (NOT RECOMMENDED; will likely break things)
+;(unpin! t)