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

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.