tools/magit: gate forge behind flag & add README #1166

docs/modules.org

@@ -168,7 +168,7 @@ Small modules that give Emacs access to external tools & services.
   backend
 + [[file:../modules/tools/lsp/README.org][lsp]] =+peek= - TODO
 + macos - TODO
-+ magit - TODO
++ [[file:../modules/tools/magit/README.org][magit]] =+forge= - TODO
 + make - TODO
 + pass - TODO
 + pdf - TODO

modules/tools/magit/README.org

@@ -0,0 +1,60 @@
+#+TITLE:   tools/magit
+#+DATE:    March 14, 2018
+#+SINCE:   v2.0.0
+#+STARTUP: inlineimages nofold
+
+* Table of Contents :TOC_3:noexport:
+- [[#description][Description]]
+  - [[#maintainers][Maintainers]]
+  - [[#module-flags][Module Flags]]
+  - [[#plugins][Plugins]]
+  - [[#hacks][Hacks]]
+- [[#prerequisites][Prerequisites]]
+- [[#features][Features]]
+- [[#configuration][Configuration]]
+- [[#troubleshooting][Troubleshooting]]
+
+* Description
+This module provides Magit, an interface to the Git version control system.
+
+If you are new to Magit, see the [[https://github.com/magit/magit#getting-started][Getting Started]] section of its project readme.
+
+** Maintainers
+This module has no dedicated maintainers.
+
+** Module Flags
++ =+forge= Enable Forge; a porcelain for managing issues and PRs from within
+  Emacs. Will take a while on first run to build emacsql-sqlite.
+
+** Plugins
++ [[https://github.com/magit/magit][magit]]
++ [[https://github.com/magit/forge][forge]]* (=+forge=)
++ [[https://github.com/jtatarik/magit-gitflow][magit-gitflow]]
++ [[https://github.com/alphapapa/magit-todos][magit-todos]]
++ [[https://github.com/charignon/github-review][github-review]]
++ [[https://github.com/emacs-evil/evil-magit][evil-magit]]* (=:editor evil +everywhere=)
+
+** Hacks
++ =forge= was modified to defer compilation of emacsql-sqlite until you try to
+  use forge, rather than when magit first loads (which could be as soon as
+  startup).
++ =magit= has been modified to recognize
+  =$XDG_CACHE_HOME/git/credential/socket=.
++ =magit= has been modified to invalidate the projectile cache when you check
+  out a new branch or commit.
++ =magit= has been modified to revert repo buffers (e.g. after changing
+  branches) when you later switch to them, rather than all at once.
+
+* Prerequisites
+This module requires ~git~.
+
+Forge will require [[https://magit.vc/manual/forge/Token-Creation.html#Token-Creation][a Github API token]] the first time you run =forge-pull=.
+
+* TODO Features
+# An in-depth list of features, how to use them, and their dependencies.
+
+* TODO Configuration
+# How to configure this module, including common problems and how to address them.
+
+* TODO Troubleshooting
+# Common issues and their solution, or places to look for help.

modules/tools/magit/config.el

@@ -1,8 +1,5 @@
 ;;; tools/magit/config.el -*- lexical-binding: t; -*-
 
-;;
-;;; Packages
-
 (use-package! magit
   :commands magit-file-delete
   :defer-incrementally (dash f s with-editor git-commit package eieio lv transient)
@@ -92,11 +89,12 @@
 
 
 (use-package! forge
+  :when (featurep! +forge)
   ;; We defer loading even further because forge's dependencies will try to
   ;; compile emacsql, which is a slow and blocking operation.
   :after-call magit-status
   :commands forge-create-pullreq forge-create-issue
-  :init
+  :preface
   (setq forge-database-file (concat doom-etc-dir "forge/forge-database.sqlite"))
   :config
   ;; All forge list modes are derived from `forge-topic-list-mode'
@@ -123,8 +121,8 @@ ensure it is built when we actually use Forge."
           (message (concat "Failed to build emacsql; forge may not work correctly.\n"
                            "See *Compile-Log* buffer for details"))
         ;; HACK Due to changes upstream, forge doesn't initialize completely if
-        ;; it doesn't find `emacsql-sqlite-executable', so we have to do it
-        ;; manually after installing it.
+        ;;      it doesn't find `emacsql-sqlite-executable', so we have to do it
+        ;;      manually after installing it.
         (setq forge--sqlite-available-p t)
         (magit-add-section-hook 'magit-status-sections-hook 'forge-insert-pullreqs nil t)
         (magit-add-section-hook 'magit-status-sections-hook 'forge-insert-issues   nil t)

modules/tools/magit/packages.el

@@ -2,7 +2,8 @@
 ;;; tools/magit/packages.el
 
 (when (package! magit :pin "0f1234e785")
-  (package! forge :pin "2e2d26cf42")
+  (when (featurep! +forge)
+    (package! forge :pin "2e2d26cf42"))
   (package! magit-gitflow :pin "cc41b561ec")
   (package! magit-todos :pin "a0e5d1f3c7")
   (package! github-review :pin "50c6bcc7cf")