feat(git): add NEW MODULE

CHANGELOG.md

@@ -25,6 +25,10 @@
 
 - FEATURE: add new `MiniFilesExplorerOpen` and `MiniFilesExplorerClose` events.
 
+## mini.git
+
+- Introduction of a new module.
+
 ## mini.hues
 
 - BREAKING FEATURE: update some highlight groups for better usability:

README.md

@@ -98,6 +98,7 @@ If you are browsing without particular objective and don't know which module to
 | mini.extra       | Extra 'mini.nvim' functionality          | [README](readmes/mini-extra.md)       | [Help file](doc/mini-extra.txt)       |
 | mini.files       | Navigate and manipulate file system      | [README](readmes/mini-files.md)       | [Help file](doc/mini-files.txt)       |
 | mini.fuzzy       | Fuzzy matching                           | [README](readmes/mini-fuzzy.md)       | [Help file](doc/mini-fuzzy.txt)       |
+| mini.git         | Git integration                          | [README](readmes/mini-git.md)         | [Help file](doc/mini-git.txt)         |
 | mini.hipatterns  | Highlight patterns in text               | [README](readmes/mini-hipatterns.md)  | [Help file](doc/mini-hipatterns.txt)  |
 | mini.hues        | Generate configurable color scheme       | [README](readmes/mini-hues.md)        | [Help file](doc/mini-hues.txt)        |
 | mini.indentscope | Visualize and work with indent scope     | [README](readmes/mini-indentscope.md) | [Help file](doc/mini-indentscope.txt) |

doc/mini.txt

@@ -31,6 +31,7 @@ Table of contents:
   Extra 'mini.nvim' functionality ............................... |mini.extra|
   Navigate and manipulate file system............................ |mini.files|
   Fuzzy matching ................................................ |mini.fuzzy|
+  Git integration ................................................. |mini.git|
   Highlight patterns in text ............................... |mini.hipatterns|
   Generate configurable color scheme ............................. |mini.hues|
   Visualize and work with indent scope .................... |mini.indentscope|
@@ -199,6 +200,10 @@ Table of contents:
   not only functions to perform fuzzy matching of one string to others, but
   also a sorter for |telescope.nvim|.
 
+- |MiniGit| - Git integration (https://git-scm.com/). Implements tracking of
+  Git related data (root, branch, etc.), |:Git| command for better integration
+  with running Neovim instance, and various helpers to explore Git history.
+
 - |MiniHipatterns| - highlight patterns in text with configurable highlighters
   (pattern and/or highlight group can be string or callable).
   Works asynchronously with configurable debounce delay.

lua/mini/init.lua

@@ -31,6 +31,7 @@
 ---   Extra 'mini.nvim' functionality ............................... |mini.extra|
 ---   Navigate and manipulate file system............................ |mini.files|
 ---   Fuzzy matching ................................................ |mini.fuzzy|
+---   Git integration ................................................. |mini.git|
 ---   Highlight patterns in text ............................... |mini.hipatterns|
 ---   Generate configurable color scheme ............................. |mini.hues|
 ---   Visualize and work with indent scope .................... |mini.indentscope|
@@ -199,6 +200,10 @@
 ---   not only functions to perform fuzzy matching of one string to others, but
 ---   also a sorter for |telescope.nvim|.
 ---
+--- - |MiniGit| - Git integration (https://git-scm.com/). Implements tracking of
+---   Git related data (root, branch, etc.), |:Git| command for better integration
+---   with running Neovim instance, and various helpers to explore Git history.
+---
 --- - |MiniHipatterns| - highlight patterns in text with configurable highlighters
 ---   (pattern and/or highlight group can be string or callable).
 ---   Works asynchronously with configurable debounce delay.

readmes/mini-git.md

@@ -0,0 +1,176 @@
+<img src="https://github.com/echasnovski/media/blob/main/mini.nvim/logo/logo_git.png" style="width: 100%">
+
+<!-- badges: start -->
+[![GitHub license](https://badgen.net/github/license/echasnovski/mini.nvim)](https://github.com/echasnovski/mini.nvim/blob/main/LICENSE)
+<!-- badges: end -->
+
+### Git integration
+
+See more details in [Features](#features) and [help file](../doc/mini-git.txt).
+
+---
+
+⦿ This is a part of [mini.nvim](https://github.com/echasnovski/mini.nvim) library. Please use [this link](https://github.com/echasnovski/mini.nvim/blob/main/readmes/mini-git.md) if you want to mention this module.
+
+⦿ All contributions (issues, pull requests, discussions, etc.) are done inside of 'mini.nvim'.
+
+⦿ See the repository page to learn about common design principles and configuration recipes.
+
+---
+
+If you want to help this project grow but don't know where to start, check out [contributing guides of 'mini.nvim'](https://github.com/echasnovski/mini.nvim/blob/main/CONTRIBUTING.md) or leave a Github star for 'mini.nvim' project and/or any its standalone Git repositories.
+
+## Demo
+
+https://github.com/echasnovski/mini.nvim/assets/24854248/3c2b34cd-f04f-4e30-9ca4-1ff51e2d65a2
+
+**Note**: This demo uses custom `vim.notify()` from [mini.notify](https://github.com/echasnovski/mini.nvim/blob/main/readmes/mini-notify.md) and diff line number highlighting from [mini.diff](https://github.com/echasnovski/mini.nvim/blob/main/readmes/mini-diff.md).
+
+## Features
+
+- Automated tracking of [Git](https://git-scm.com/) related data: root path, status, HEAD, etc. Exposes buffer-local variables for convenient use in statusline.
+
+- `:Git` command for executing any `git` call inside file's repository root with deeper current instance integration (show output as notification/buffer, use to edit commit messages, etc.).
+
+- Helper functions to inspect Git history:
+    - `MiniGit.show_range_history()` shows how certain line range evolved.
+    - `MiniGit.show_diff_source()` shows file state as it was at diff entry.
+    - `MiniGit.show_at_cursor()` shows Git related data depending on context.
+
+What it doesn't do:
+
+- Replace fully featured Git client. Rule of thumb: if feature does not rely on a state of current Neovim (opened buffers, etc.), it is out of scope. For more functionality, use either ['mini.diff'](https://github.com/echasnovski/mini.nvim/blob/main/readmes/mini-diff.md) or fully featured Git client.
+
+To read more information, see these tags in help file:
+- `*:Git*`
+- `*MiniGit-examples*`
+- `*MiniGit.enable()*`
+- `*MiniGit.get_buf_data()*`
+
+## Installation
+
+This plugin can be installed as part of 'mini.nvim' library (**recommended**) or as a standalone Git repository.
+
+During beta-testing phase there is only one branch to install from:
+<!-- There are two branches to install from: -->
+
+- `main` (default, **recommended**) will have latest development version of plugin. All changes since last stable release should be perceived as being in beta testing phase (meaning they already passed alpha-testing and are moderately settled).
+<!-- - `stable` will be updated only upon releases with code tested during public beta-testing phase in `main` branch. -->
+
+Here are code snippets for some common installation methods (use only one):
+
+<details>
+<summary>With <a href="https://github.com/echasnovski/mini.nvim/blob/main/readmes/mini-deps.md">mini.deps</a></summary>
+<table>
+    <thead>
+        <tr>
+            <th>Github repo</th> <th>Branch</th> <th>Code snippet</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <!-- <td rowspan=2>'mini.nvim' library</td> <td>Main</td> <td rowspan=2><i>Follow recommended 'mini.deps' installation</i></td> -->
+            <td rowspan=1>'mini.nvim' library</td> <td>Main</td> <td rowspan=1><i>Follow recommended 'mini.deps' installation</i></td>
+        </tr>
+        <!-- <tr> -->
+        <!--     <td>Stable</td> -->
+        <!-- </tr> -->
+        <tr>
+            <!-- <td rowspan=2>Standalone plugin</td> <td>Main</td> <td><code>add('echasnovski/mini-git')</code></td> -->
+            <td rowspan=1>Standalone plugin</td> <td>Main</td> <td><code>add('echasnovski/mini-git')</code></td>
+        </tr>
+        <!-- <tr> -->
+        <!--     <td>Stable</td> <td><code>add({ source = 'echasnovski/mini-git', checkout = 'stable' })</code></td> -->
+        <!-- </tr> -->
+    </tbody>
+</table>
+</details>
+
+<details>
+<summary>With <a href="https://github.com/folke/lazy.nvim">folke/lazy.nvim</a></summary>
+<table>
+    <thead>
+        <tr>
+            <th>Github repo</th> <th>Branch</th> <th>Code snippet</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <!-- <td rowspan=2>'mini.nvim' library</td> <td>Main</td> <td><code>{ 'echasnovski/mini.nvim', version = false },</code></td> -->
+            <td rowspan=1>'mini.nvim' library</td> <td>Main</td> <td><code>{ 'echasnovski/mini.nvim', version = false },</code></td>
+        </tr>
+        <!-- <tr> -->
+        <!--     <td>Stable</td> <td><code>{ 'echasnovski/mini.nvim', version = '*' },</code></td> -->
+        <!-- </tr> -->
+        <tr>
+            <!-- <td rowspan=2>Standalone plugin</td> <td>Main</td> <td><code>{ 'echasnovski/mini-git', version = false },</code></td> -->
+            <td rowspan=1>Standalone plugin</td> <td>Main</td> <td><code>{ 'echasnovski/mini-git', version = false },</code></td>
+        </tr>
+        <!-- <tr> -->
+        <!--     <td>Stable</td> <td><code>{ 'echasnovski/mini-git', version = '*' },</code></td> -->
+        <!-- </tr> -->
+    </tbody>
+</table>
+</details>
+
+<details>
+<summary>With <a href="https://github.com/junegunn/vim-plug">junegunn/vim-plug</a></summary>
+<table>
+    <thead>
+        <tr>
+            <th>Github repo</th> <th>Branch</th> <th>Code snippet</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <!-- <td rowspan=2>'mini.nvim' library</td> <td>Main</td> <td><code>Plug 'echasnovski/mini.nvim'</code></td> -->
+            <td rowspan=1>'mini.nvim' library</td> <td>Main</td> <td><code>Plug 'echasnovski/mini.nvim'</code></td>
+        </tr>
+        <!-- <tr> -->
+        <!--     <td>Stable</td> <td><code>Plug 'echasnovski/mini.nvim', { 'branch': 'stable' }</code></td> -->
+        <!-- </tr> -->
+        <tr>
+            <!-- <td rowspan=2>Standalone plugin</td> <td>Main</td> <td><code>Plug 'echasnovski/mini-git'</code></td> -->
+            <td rowspan=1>Standalone plugin</td> <td>Main</td> <td><code>Plug 'echasnovski/mini-git'</code></td>
+        </tr>
+        <!-- <tr> -->
+        <!--     <td>Stable</td> <td><code>Plug 'echasnovski/mini-git', { 'branch': 'stable' }</code></td> -->
+        <!-- </tr> -->
+    </tbody>
+</table>
+</details>
+
+<br>
+
+**Important**: don't forget to call `require('mini.git').setup()` to enable its functionality.
+
+**Note**: if you are on Windows, there might be problems with too long file paths (like `error: unable to create file <some file name>: Filename too long`). Try doing one of the following:
+- Enable corresponding git global config value: `git config --system core.longpaths true`. Then try to reinstall.
+
+## Default config
+
+```lua
+-- No need to copy this inside `setup()`. Will be used automatically.
+{
+  -- General CLI execution
+  job = {
+    -- Path to Git executable
+    git_executable = 'git',
+
+    -- Timeout (in ms) for each job before force quit
+    timeout = 30000,
+  },
+
+  -- Options for `:Git` command
+  command = {
+    -- Default split direction
+    split = 'auto',
+  },
+}
+```
+
+## Similar plugins
+
+- [tpope/vim-fugitive](https://github.com/tpope/vim-fugitive)
+- [NeogitOrg/neogit](https://github.com/NeogitOrg/neogit)
+- [lewis6991/gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim)

scripts/basic-setup_init.lua

@@ -31,6 +31,7 @@ local test_actions = {
   ['extra']       = function() require('mini.extra').setup() end,
   ['files']       = function() require('mini.files').setup() end,
   ['fuzzy']       = function() require('mini.fuzzy').setup() end,
+  ['git']         = function() require('mini.git').setup() end,
   ['hipatterns']  = function() require('mini.hipatterns').setup() end,
   ['hues']        = function() require('mini.hues').setup({ background = '#000000', foreground = '#ffffff' }) end,
   ['indentscope'] = function() require('mini.indentscope').setup() end,

scripts/dual_sync.sh

@@ -20,7 +20,10 @@ sync_module () {
   if [[ ! -d $repo ]]
   then
     printf "Pulling\n"
-    git clone --filter=blob:none https://github.com/echasnovski/mini.$module.git $repo
+    # Handle 'mini.git' differently because GitHub repo is named 'mini-git'
+    # (".git" suffix is not allowed as repo name on GitHub)
+    if [ $module = "git" ]; then github_repo="mini-git"; else github_repo="mini.$module"; fi
+    git clone --filter=blob:none https://github.com/echasnovski/$github_repo.git $repo
   else
     printf "No pulling (already present)\n"
   fi
@@ -79,6 +82,7 @@ sync_module "doc"
 sync_module "extra"
 sync_module "files"
 sync_module "fuzzy"
+sync_module "git"
 sync_module "hipatterns"
 sync_module "hues" colors/randomhue.lua
 sync_module "indentscope"

scripts/minidoc.lua

@@ -21,6 +21,7 @@ local modules = {
   'extra',
   'files',
   'fuzzy',
+  'git',
   'hipatterns',
   'hues',
   'indentscope',

tests/dir-git/diff-output

@@ -0,0 +1,23 @@
+diff --git a/dir/file1 b/dir/file1
+index dd2b945..b81ef66 100644
+--- a/dir/file1
++++ b/dir/file1
+@@ -247,3 +247,3 @@ Hunk header 1
+       Line 1
+-      Previous line 2
++      Current line 2
+     Line 3
+@@ -317,4 +317,4 @@
+ Line 11
++Added line 12
++Added line 13
+
+diff --git a/file b/file
+index a0a225b..9f8c05f 100644
+--- a/file
++++ b/file
+@@ -283,4 +283,4 @@
+ +++
+-+++ Deleted line 112
+---- Deleted line 113
+ ---

tests/dir-git/file

@@ -0,0 +1,2 @@
+aaa
+uuu

tests/dir-git/git-repo/.git-dir/COMMIT_EDITMSG

@@ -0,0 +1,2 @@
+
+# This is a mock of Git template for its `GIT_EDITOR`

tests/dir-git/git-repo/.git-dir/HEAD

@@ -0,0 +1 @@
+ref: refs/heads/tmp

tests/dir-git/git-repo/.git-dir/refs/heads/tmp

@@ -0,0 +1 @@
+

tests/dir-git/git-repo/HEAD

@@ -0,0 +1 @@
+ref: refs/heads/tmp

tests/dir-git/git-repo/dir-in-git/file-in-dir-in-git

@@ -0,0 +1,5 @@
+Line 1
+Line 2
+Line 3
+Line 4
+Line 5

tests/dir-git/git-repo/file-in-git

@@ -0,0 +1 @@
+

tests/dir-git/help-output

@@ -0,0 +1,62 @@
+
+GIT-PUSH(1)                        Git Manual                       GIT-PUSH(1)
+
+NAME
+       git-push - Update remote refs along with associated objects
+
+SYNOPSIS
+       git push [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
+                  [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose]
+                  [-u | --set-upstream] [-o <string> | --push-option=<string>]
+                  [--[no-]signed|--signed=(true|false|if-asked)]
+                  [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]]
+                  [--no-verify] [<repository> [<refspec>...]]
+
+DESCRIPTION
+       A truncated output of `git help push` for testing purposes
+
+OPTIONS
+       <repository>
+           The "remote" repository. Should be parsed as option.
+
+       <refspec>...
+           Specify what destination ref to update with what source object.
+           Some other very important information.
+
+       --all, --branches
+           Push all branches (i.e. refs under refs/heads/); cannot be used with
+           other <refspec>.
+
+       --prune
+           Remove remote branches that don’t have a local counterpart.
+
+           This line contains --do-not-parse flag which should not be parsed.
+
+           --another-no-parse
+
+       -n, --dry-run
+           Do everything except actually send the updates.
+
+       -vv
+           A single dash flag but with two letters afterwards.
+
+       --[no-]signed, --signed=(true|false|if-asked)
+           This is some hard to parse options.
+           Should prefer '--signed' over '--signed='.
+
+       --receive-pack=<git-receive-pack>, --exec=<git-receive-pack>
+           Another hard to parse.
+
+       --[no-]force-with-lease, --force-with-lease=<refname>,
+       --force-with-lease=<refname>:<expect>
+           An entry which documents same flag several times.
+
+       -4, --ipv4
+           Use IPv4 addresses only, ignoring IPv6 addresses.
+
+       -6, --ipv6
+           Use IPv6 addresses only, ignoring IPv4 addresses.
+
+NEW SECTION
+       --not-an-option
+           Although formatted as an option, it is not in an appropriate section.