From fc56fc25cfc3dc3f24266508aa4a7096102eb6a6 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 21 Jan 2025 11:30:34 +0000 Subject: [PATCH] docs: give README some paint --- README.md | 193 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 140 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 995357146..5935420d8 100644 --- 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) - - - +[![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 | | --- | ----------- | | | | -## 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. +
+ Signs -## 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) + + +
+ +
+ Hunk Actions + + - 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`. + +
+ +
+ Blame + + - 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` + +
+ +
+ Diff + + - Change the revision for the signs with `:Gitsigns change_base `. + - Show the diff of the current buffer with the index or any revision + with `:Gitsigns diffthis `. + - 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`. + +
+ +
+ Show hunks Quickfix/Location List + + - 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]`). + +
+ +
+ Text Object + + - Select hunks as a text object. + - Can use `vim.keymap.set({'o', 'x'}, 'ih', 'Gitsigns select_hunk')` + +
+ +
+ Status Line Integration + + 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`. + +
+ +
+ Show different revisions of buffers + + - Use `:Gitsigns show ` to `:edit` the current buffer at `` + +
+ +## 📋 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', 'tw', gitsigns.toggle_word_diff) -- Text object - map({'o', 'x'}, 'ih', 'Gitsigns select_hunk') + 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]