doomemacs/modules/ui/vc-gutter/README.org

#+title:    :ui vc-gutter
#+subtitle: Get your diff out of the gutter
#+created:  June 26, 2018
#+since:    21.12.0

* Description :unfold:
This module displays a diff of the current file (against HEAD) in the fringe.
Supports Git, Svn, Hg, and Bzr.

** Maintainers
- [[doom-user:][@hlissner]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +diff-hl ::
  Use [[doom-package:][diff-hl]] instead of git-gutter to power the VC gutter. It is a little
  faster, but is slightly more prone to visual glitching. [[doom-package:][diff-hl]] is intended to
  replace git-gutter at some point in the future.
- +pretty ::
  Apply some stylistic defaults to the fringe, enabling thin bars in the fringe.
  This look takes after the modern look of git-gutter in VSCode and Sublime
  Text, without sacrificing on fringe width (which squeeze other indicators,
  like flycheck's, flymake's, or flyspell's). However, this will look bad with
  themes that invert the foreground/background of either git-gutter's or
  diff-hl's faces (like modus-themes does).

** Packages
- [[doom-package:][git-gutter-fringe]] unless [[doom-module:][+diff-hl]]
- [[doom-package:][diff-hl]] if [[doom-module:][+diff-hl]]

** TODO Hacks
#+begin_quote
 🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module requires any of Git, Svn, Hg, and/or Bazaar to get gutter diffs in
projects version controlled by them.

* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote

* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote

* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote
docs: use lowercase keywords As per Org's new defaults, which we're adopting elsewhere, so may as well adopt it here. 2022-03-28 15:03:21 +02:00			`#+title: :ui vc-gutter`
			`#+subtitle: Get your diff out of the gutter`
			`#+created: June 26, 2018`
			`#+since: 21.12.0`
docs(:ui): update READMEs to new format 2021-10-16 01:29:57 +02:00
			`* Description :unfold:`
			`This module displays a diff of the current file (against HEAD) in the fringe.`
			`Supports Git, Svn, Hg, and Bzr.`

			`** Maintainers`
			`- [[doom-user:][@hlissner]]`

			`[[doom-contrib-maintainer:][Become a maintainer?]]`

			`** Module flags`
feat(vc-gutter): add +diff-hl backend This adds an alternative backend to the :ui vc-gutter module, enabled with the +diff-hl flag. In the future, I intend for diff-hl to replace git-gutter, as it is slightly faster and depends on more native functionality (vc.el), but it's still a little buggy. It will remain opt-in until those issues are sorted out. 2022-08-08 17:46:31 +02:00			`- +diff-hl ::`
			`Use [[doom-package:][diff-hl]] instead of git-gutter to power the VC gutter. It is a little`
			`faster, but is slightly more prone to visual glitching. [[doom-package:][diff-hl]] is intended to`
			`replace git-gutter at some point in the future.`
refactor!(vc-gutter): move style defaults behind +pretty BREAKING CHANGE: This changes moves its default configuration of the fringe behind a +pretty flag. This won't cause breakage, but will cause a (possibly unwanted) visual change: git-gutter will use its default indicators (e.g. + and - symbols) instead of the continuous bars from before. To get back the old look, enable `+pretty` on the `:ui vc-gutter` module. This was done to make the defaults toggleable, to standardize +pretty, to document issues with this customization that have been brought up by members of the Emacs community, and to better document it in comments for posterity. 2022-08-08 17:36:23 +02:00			`- +pretty ::`
			`Apply some stylistic defaults to the fringe, enabling thin bars in the fringe.`
			`This look takes after the modern look of git-gutter in VSCode and Sublime`
			`Text, without sacrificing on fringe width (which squeeze other indicators,`
			`like flycheck's, flymake's, or flyspell's). However, this will look bad with`
			`themes that invert the foreground/background of either git-gutter's or`
			`diff-hl's faces (like modus-themes does).`
docs(:ui): update READMEs to new format 2021-10-16 01:29:57 +02:00
			`** Packages`
feat(vc-gutter): add +diff-hl backend This adds an alternative backend to the :ui vc-gutter module, enabled with the +diff-hl flag. In the future, I intend for diff-hl to replace git-gutter, as it is slightly faster and depends on more native functionality (vc.el), but it's still a little buggy. It will remain opt-in until those issues are sorted out. 2022-08-08 17:46:31 +02:00			`- [[doom-package:][git-gutter-fringe]] unless [[doom-module:][+diff-hl]]`
			`- [[doom-package:][diff-hl]] if [[doom-module:][+diff-hl]]`
docs(:ui): update READMEs to new format 2021-10-16 01:29:57 +02:00
			`** TODO Hacks`
			`#+begin_quote`
			`🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]`
			`#+end_quote`

			`** TODO Changelog`
			`# This section will be machine generated. Don't edit it by hand.`
			`/This module does not have a changelog yet./`

			`* Installation`
			`[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]`

			`This module requires any of Git, Svn, Hg, and/or Bazaar to get gutter diffs in`
			`projects version controlled by them.`

			`* TODO Usage`
			`#+begin_quote`
			`🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]`
			`#+end_quote`

			`* TODO Configuration`
			`#+begin_quote`
			`🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]`
			`#+end_quote`

			`* Troubleshooting`
			`/There are no known problems with this module./ [[doom-report:][Report one?]]`

			`* Frequently asked questions`
			`/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]`

			`* TODO Appendix`
			`#+begin_quote`
			`🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]`
			`#+end_quote`