docs: give README some paint

lewis6991 · Feb 6, 2025 · fc56fc2 · fc56fc2
1 parent 8974fd3
commit fc56fc2
Showing 1 changed file with 140 additions and 53 deletions.
diff --git a/README.md b/README.md
@@ -4,46 +4,149 @@
 [![Version](https://img.shields.io/github/v/release/lewis6991/gitsigns.nvim)](https://github.com/lewis6991/gitsigns.nvim/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Gitter](https://badges.gitter.im/gitsigns-nvim/community.svg)](https://gitter.im/gitsigns-nvim/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
-<a href="https://dotfyle.com/plugins/lewis6991/gitsigns.nvim">
-  <img src="https://dotfyle.com/plugins/lewis6991/gitsigns.nvim/shield" />
-</a>
+[![Dotfyle](https://dotfyle.com/plugins/lewis6991/gitsigns.nvim/shield)](https://dotfyle.com/plugins/lewis6991/gitsigns.nvim)
 
 
-Super fast git decorations implemented purely in Lua.
+Deep buffer integration for Git
 
-## Preview
+## 👀 Preview
 
 | Hunk Actions | Line Blame |
 | --- | ----------- |
 | <img src="https://raw.githubusercontent.com/lewis6991/media/main/gitsigns_actions.gif" width="450em"/> | <img src="https://raw.githubusercontent.com/lewis6991/media/main/gitsigns_blame.gif" width="450em"/> |
 
-## Features
+## ✨ Features
 
-- Signs for added, removed, and changed lines
-- Asynchronous using [luv]
-- Navigation between hunks
-- Stage hunks (with undo)
-- Preview diffs of hunks (with word diff)
-- Customizable (signs, highlights, mappings, etc)
-- Status bar integration
-- Git blame a whole buffer or a specific line.
-- Hunk text object
-- Automatically follow files moved in the index.
-- Live intra-line word diff
-- Ability to display deleted/changed lines via virtual lines.
-- Support for detached working trees.
+<details>
+  <summary><strong>Signs</strong></summary>
 
-## Requirements
+  - Adds signs to the sign column to indicate added, changed, and deleted lines.
+
+    ![image](https://github.com/user-attachments/assets/e49ea0bf-c427-41fb-a67f-77c2d413a7cf)
+
+  - Supports different signs for staged changes.
+
+    ![image](https://github.com/user-attachments/assets/28a3e286-96fa-478c-93a3-8028f9bd7123)
+
+  - Add counts to signs.
+
+    ![image](https://github.com/user-attachments/assets/d007b924-6811-44ea-b936-d8da4dc00b68)
+
+
+</details>
+
+<details>
+  <summary><strong>Hunk Actions</strong></summary>
+
+  - Stage/unstage hunks with `:Gitsigns stage_hunk`.
+  - Reset hunks with `:Gitsigns reset_hunk`.
+  - Also works on partial hunks in visual mode.
+  - Preview hunks inline with `:Gitsigns preview_hunk_inline`
+
+    ![image](https://github.com/user-attachments/assets/60acd664-f4a8-4737-ba65-969f1efa7971)
+
+  - Preview hunks in popup with `:Gitsigns preview_hunk`
+
+    ![image](https://github.com/user-attachments/assets/d2a9b801-5857-4054-80a8-195d111f4e8c)
+
+  - Navigate between hunks with `:Gitsigns nav_hunk next/prev`.
+
+</details>
+
+<details>
+  <summary><strong>Blame</strong></summary>
+
+  - Show blame of current buffer using `:Gitsigns blame`.
+
+    ![image](https://github.com/user-attachments/assets/7d881e94-6e16-4f98-a526-7e785b11acf9)
+
+  - Show blame information for the current line in popup with `:Gitsigns blame_line`.
+
+    ![image](https://github.com/user-attachments/assets/03ff7557-b538-4cd1-9478-f893bf7e616e)
+
+  - Show blame information for the current line in virtual text.
+
+    ![image](https://github.com/user-attachments/assets/0c79e880-6a6d-4c3f-aa62-33f734725cfd)
+
+    - Enable with `setup({ current_line_blame = true })`.
+    - Toggle with `:Gitsigns toggle_current_line_blame`
+
+</details>
+
+<details>
+  <summary><strong>Diff</strong></summary>
+
+  - Change the revision for the signs with `:Gitsigns change_base <REVISION>`.
+  - Show the diff of the current buffer with the index or any revision
+    with `:Gitsigns diffthis <REVISION>`.
+  - Show intra-line word-diff in the buffer.
+
+    ![image](https://github.com/user-attachments/assets/409a1f91-5cee-404b-8b12-66b7db3ecac7)
+
+    - Enable with `setup({ word_diff = true })`.
+    - Toggle with `:Gitsigns toggle_word_diff`.
+
+</details>
+
+<details>
+  <summary><strong>Show hunks Quickfix/Location List</strong></summary>
+
+  - Set the quickfix/location list with changes with `:Gitsign setqflist/setloclist`.
+
+    ![image](https://github.com/user-attachments/assets/c17001a5-b9cf-4a00-9891-5b130c0b4745)
+
+    Can show hunks for:
+    - whole repository (`target=all`)
+    - attached buffers (`target=attached`)
+    - a specific buffer (`target=[integer]`).
+
+</details>
+
+<details>
+  <summary><strong>Text Object</strong></summary>
+
+  - Select hunks as a text object.
+  - Can use `vim.keymap.set({'o', 'x'}, 'ih', '<Cmd>Gitsigns select_hunk<CR>')`
+
+</details>
+
+<details>
+  <summary><strong>Status Line Integration</strong></summary>
+
+  Use `b:gitsigns_status` or `b:gitsigns_status_dict`. `b:gitsigns_status` is
+  formatted using `config.status_formatter`. `b:gitsigns_status_dict` is a
+  dictionary with the keys `added`, `removed`, `changed` and `head`.
+
+  Example:
+  ```viml
+  set statusline+=%{get(b:,'gitsigns_status','')}
+  ```
+
+  For the current branch use the variable `b:gitsigns_head`.
+
+</details>
+
+<details>
+  <summary><strong>Show different revisions of buffers</strong></summary>
+
+  - Use `:Gitsigns show <REVISION>` to `:edit` the current buffer at `<REVISION>`
+
+</details>
+
+## 📋 Requirements
 
 - Neovim >= 0.9.0
 
-  **Note:** If your version of Neovim is too old, then you can use a past [release].
+> [!TIP]
+> If your version of Neovim is too old, then you can use a past [release].
 
-  **Note:** If you are running a development version of Neovim (aka `master`), then breakage may occur if your build is behind latest.
+> [!WARNING]
+> If you are running a development version of Neovim (aka `master`), then
+> breakage may occur if your build is behind latest.
 
 - Newish version of git. Older versions may not work with some features.
 
-## Installation & Usage
+## 🛠️ Installation & Usage
 
 Install using your package manager of choice.
 
@@ -110,7 +213,7 @@ require('gitsigns').setup {
 
 For information on configuring Neovim via lua please see [nvim-lua-guide].
 
-### Keymaps
+### 🎹 Keymaps
 
 Gitsigns provides an `on_attach` callback which can be used to setup buffer mappings.
 
@@ -181,35 +284,11 @@ require('gitsigns').setup{
     map('n', '<leader>tw', gitsigns.toggle_word_diff)
 
     -- Text object
-    map({'o', 'x'}, 'ih', '<cmd>Gitsigns select_hunk<CR>')
+    map({'o', 'x'}, 'ih', gitsigns.select_hunk)
   end
 }
 ```
-
-## Non-Goals
-
-### Implement every feature in [vim-fugitive]
-
-This plugin is actively developed and by one of the most well regarded vim plugin developers.
-Gitsigns will only implement features of this plugin if: it is simple, or, the technologies leveraged by Gitsigns (LuaJIT, Libuv, Neovim's API, etc) can provide a better experience.
-
-### Support for other VCS
-
-There aren't any active developers of this plugin who use other kinds of VCS, so adding support for them isn't feasible.
-However a well written PR with a commitment of future support could change this.
-
-## Status Line
-
-Use `b:gitsigns_status` or `b:gitsigns_status_dict`. `b:gitsigns_status` is
-formatted using `config.status_formatter`. `b:gitsigns_status_dict` is a
-dictionary with the keys `added`, `removed`, `changed` and `head`.
-
-Example:
-```viml
-set statusline+=%{get(b:,'gitsigns_status','')}
-```
-
-For the current branch use the variable `b:gitsigns_head`.
+## 🔗 Plugin Integrations
 
 ### [vim-fugitive]
 
@@ -220,11 +299,19 @@ This means the signs placed in the buffer reflect the changes introduced by that
 
 If installed and enabled (via `config.trouble`; defaults to true if installed), `:Gitsigns setqflist` or `:Gitsigns setloclist` will open Trouble instead of Neovim's built-in quickfix or location list windows.
 
-### [lspsaga.nvim]
+## 🚫 Non-Goals
 
-If you are using lspsaga.nvim you can config `code_action.extend_gitsigns` (default is false) to show the gitsigns action in lspsaga codeaction.
+### Implement every feature in [vim-fugitive]
+
+This plugin is actively developed and by one of the most well regarded vim plugin developers.
+Gitsigns will only implement features of this plugin if: it is simple, or, the technologies leveraged by Gitsigns (LuaJIT, Libuv, Neovim's API, etc) can provide a better experience.
+
+### Support for other VCS
+
+There aren't any active developers of this plugin who use other kinds of VCS, so adding support for them isn't feasible.
+However a well written PR with a commitment of future support could change this.
 
-## Similar plugins
+## 🔌 Similar plugins
 
 - [mini.diff]
 - [coc-git]