docs: give README some paint

2025-02-20 22:47:23 +00:00 · 2025-01-21 11:30:34 +00:00 · 2025-01-21 11:30:34 +00:00 · fc56fc25cf
commit fc56fc25cf
parent 8974fd397e
1 changed files with 140 additions and 53 deletions
--- 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,12 +284,22 @@ 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
 }
 ```
+## 🔗 Plugin Integrations

-## Non-Goals
+### [vim-fugitive]
+
+When viewing revisions of a file (via `:0Gclog` for example), Gitsigns will attach to the fugitive buffer with the base set to the commit immediately before the commit of that revision.
+This means the signs placed in the buffer reflect the changes introduced by that revision of the file.
+
+### [trouble.nvim]
+
+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.
+
+## 🚫 Non-Goals

 ### Implement every feature in [vim-fugitive]

@ -198,33 +311,7 @@ Gitsigns will only implement features of this plugin if: it is simple, or, the t
 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`.
-
-### [vim-fugitive]
-
-When viewing revisions of a file (via `:0Gclog` for example), Gitsigns will attach to the fugitive buffer with the base set to the commit immediately before the commit of that revision.
-This means the signs placed in the buffer reflect the changes introduced by that revision of the file.
-
-### [trouble.nvim]
-
-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]
-
-If you are using lspsaga.nvim you can config `code_action.extend_gitsigns` (default is false) to show the gitsigns action in lspsaga codeaction.
-
-## Similar plugins
+## 🔌 Similar plugins

 - [mini.diff]
 - [coc-git]