gitsuite.nvim · Project & repos · vimdoc

:help gitsuite

One :Git command tree for everything git

doc/gitsuite.txt — rendered from the plugin's own vimdoc

*gitsuite.txt*  One :Git command tree for everything git             *gitsuite.nvim*

Author:   Stefan Bartl
Version:  0.1.0

CONTENTS *gitsuite-contents*

  1. Introduction .............. |gitsuite-intro|
  2. Requirements ............... |gitsuite-requirements|
  3. Installation ............... |gitsuite-installation|
  4. Commands .................... |gitsuite-commands|
  5. Configuration ............... |gitsuite-config|
  6. Adapters ..................... |gitsuite-adapters|
  7. Events ....................... |gitsuite-events|
  8. Statusline ................... |gitsuite-statusline|
  9. Health check ................. |gitsuite-health|

1. INTRODUCTION *gitsuite-intro*

gitsuite.nvim collects every git-related user command this config used to
spread across seven external plugins into one :Git <scope> <action> tree
(see |gitsuite-commands|). It follows the filetree.nvim pattern: its own
implementation where that pays off (merge-conflict resolution, blame,
browse), and a thin adapter where an external plugin has already done years
of edge-case work (gitsigns' hunk engine, neogit's staging UI, diffview, the
real lazygit TUI run in a floating terminal).

This is an alpha-stage, actively-growing plugin -- every subcommand listed
in docs/BINDINGS.md is a real implementation, but the surface is not
frozen yet: breaking changes are still possible.

2. REQUIREMENTS *gitsuite-requirements*

- Neovim >= 0.11
- git on $PATH
- WKDSteve/lib.nvim (hard dependency)
- WKDSteve/diff.nvim (hard dependency, used by :Git diff */:Git hunk *)
- WKDSteve/ui.nvim (hard dependency, used by :Git dashboard and the picker of
  :Git plugins log)

See docs/requirements.md for the optional tools (gitsigns, diffview,
neogit, lazygit, nvr, open.nvim, pickers.nvim) and exactly what each one
backs versus what falls back without it.

3. INSTALLATION *gitsuite-installation*

  {
    "WKDSteve/gitsuite.nvim",
    dependencies = { "WKDSteve/lib.nvim", "WKDSteve/diff.nvim", "WKDSteve/ui.nvim" },
    cmd = "Git",
    config = function(_, opts)
      require("gitsuite").setup(opts)
    end,
  }
See docs/installation.md for packer.nvim, vim-plug and mini.deps variants.

4. COMMANDS *gitsuite-commands*

                                                                        *:Git*
:Git {scope} {action} [args]

Compound command tree with <Tab> completion at every level. See
docs/BINDINGS.md for the full, generated list of {scope} {action} pairs --
that file is generated from the same route tree that drives dispatch, so it
never drifts from what :Git <Tab> actually offers.

:Git ui lazygit [dir] opens lazygit for the repository containing dir (any
directory inside its work tree) instead of the one of the current working
directory; from Lua: require("gitsuite.features.ui").lazygit(dir). A dir
that does not exist or is not inside a git repository is reported, no float
is opened.

Blame without a buffer (for other plugins): `require("gitsuite.features.blame")
.for_location(dir, path, lnum) returns { line, sha, author, author_time,
summary } for one line of path (relative to dir`, or absolute); an
uncommitted line has an all-zero sha. It blocks without a callback; with a
cb(entry, err) as fourth argument it runs asynchronously and returns a
{ stop } handle. Failures (not a repo, untracked file, line past the end) are
nil, err.

                                                          *gitsuite-conflict*
:Git conflict {ours|theirs|both|base|none} resolves the conflict under the
cursor. Markers are matched by their exact length (<<<<<<< opens a conflict,
and every other marker of it has as many characters): git writes a conflict
nested in the base section -- the conflicting virtual ancestor of a criss-cross
merge -- with longer markers, and the conflict-marker-size git attribute
raises the length for a file.

A line that is exactly ======= can be text (the underline of a Markdown
setext heading). In a merge-style conflict that makes the separator
impossible to tell from the text: the region is still highlighted (markers and
every candidate line only), found by :Git conflict next|prev and counted by
has_conflicts(). With more than one candidate, `:Git conflict
ours|theirs|both|base|none asks which =======` is the real one via
vim.ui.select (a line-before/line-after preview per candidate) instead of
guessing where our side ends -- the parser itself still never guesses, only
the user does, with the buffer content in front of them. With exactly one
candidate the base marker itself is what is ambiguous instead (two or more
||||||| before it), which no separator choice can resolve -- that case still
refuses with a message; *.md conflict-marker-size=10 in .gitattributes
avoids either case for the next merge. diff3/zdiff3 are otherwise affected
only if the base section itself holds a =======-looking line (the
||||||| marker otherwise tells the sides apart, and git keeps conflicts
around an unchanged underline apart).

                                                        *gitsuite-dashboard*
:Git dashboard [dir] [--out=...] [--to=...] and `:Git dashboard update
[dir]` are the one multi-repo exception -- every other scope above
operates on the current buffer's repository, dashboard reads the git
status of every repository in dir/dashboard.base_dir ($REPOS_DIR by
default), or a configured dashboard.groups page. Row/marked-set/whole-
page push, pull, fetch and sync (p/P/f/gp/gP/gf/gu/gS/gs), page
navigation (<C-l>/<C-h>), and per-page path add/remove (a/x) --
moved here from reposcope.nvim's former :Reposcope dashboard/update.
See docs/BINDINGS.md for the full key table, docs/configuration.md for
dashboard.*, and docs/scope.md for why this one scope is different.

                                                          *gitsuite-plugins*
:Git plugins log [plugin|owner/repo|path] [n] [--count=n] [--out=picker|buffer|clipboard]
shows the newest commits of an installed plugin or of any clone: a picker with
a preview of the message and changed files (<CR> opens the commit on its web
host, <M-o> the same without closing, <M-y> copies the hash), a read-only
buffer, or the clipboard. <Tab> completes the
plugin names of lazy.nvim, vim.pack or your plugin folders without starting a
process. It only reads -- one git log, never a fetch -- and works offline in a
blobless clone. See docs/commands.md and docs/configuration.md (plugins.*).

`:Git plugins report [--mode=updated|pending] [--all] [--last] [--out=tab|buffer|clipboard|path]
[--to=path] [--no-open] [--fetch [--yes]] says what changed across ALL installed plugins: updated` (default) is what
the last update changed -- each clone's own HEAD reflog, so it survives a restart --
and pending what the next update would bring, against the target lazy.nvim itself
would check out, as of the last fetch (:Lazy check fetches; gitsuite only with
--fetch). --mode=pending --fetch first runs git fetch --all --prune in every
clone -- the one network access of gitsuite, never a default: it asks from
plugins.fetch_confirm clones on (--yes skips that), runs plugins.fetch_jobs
at a time without any credential prompt, kills each fetch and its child
processes after plugins.fetch_timeout_ms, and names every failed or skipped
clone in the report (a failed one never counts as fetched).
By default the report opens in a tab of its own (--out=tab): an overview of the
changed plugins, a breaking digest (D), a detail per plugin (<CR>) and a preview
of the commit under the cursor, with the files it changed (line counts only in a full
clone: lazy.nvim's blobless clones have no old contents, and gitsuite never fetches
them); m/M mark commits as seen, kept in plugins_seen.json across reports
(keys: docs/BINDINGS.md, "Plugins report keys"). q
closes it; :Git plugins opens it again where it was, or after a restart the newest
stored report, without a scan. The other outputs are Markdown (a buffer, the
clipboard or a file); a rollback, a diverged
branch and a force-pushed-away old state are named as such. Reports are kept in
stdpath("state")/gitsuite/plugins_reports.json and User GitsuitePluginsReported
fires after each. It reads local state only -- no install, update, pin or clean.
--no-open stores the report and opens no buffer, only a one-line summary
(--out=clipboard/--out=path still copy or write it). With
plugins.after_sync = "toast" (or "open") the updated report is built after
every :Lazy sync that updated something and summed up in a toast that never
takes focus; a sync that updated nothing stores nothing and only says so
(default "off": no listener). A lazy-loaded gitsuite with
event = "User LazySync" reports the sync that loads it too. See
docs/commands.md and docs/integrations.md.

                                                 *gitsuite-plugins-breaking*
Each changed plugin of a report gets a deterministic summary (no AI): counts
per conventional type, top scopes, authors and the share of bots, the changed
directories, the releases of the range ("MAJOR v1.9.1 -> v2.0.0", or "no
release tag in this update (last v0.9.3)", pre-releases left out) -- and a
breaking-change digest from the commit messages: "breaking" (type(scope)!:,
a BREAKING CHANGE: footer, a subject starting with BREAKING), "probably
breaking" ("drop support", "requires Neovim x", a lower-case footer, "by
default", a misplaced !), folded "hints" (remove/rename/deprecate, a
removed Lua module) and one group for tree-sitter parser bumps; a subject
repeated plugins.breaking.collapse_repeats times is folded too, except a
commit with a breaking footer. Every flagged commit says where it sits in the
update ("17/86") and whether it concerns you (a dropped older Neovim, a parser
you have not installed). It is a heuristic: about half of what a person calls
breaking is found, and 0 hits does not mean there is none -- the report says
so. A plugin whose recent subjects are mostly not conventional commits is
marked "no marker convention recognized".

5. CONFIGURATION *gitsuite-config*

  require("gitsuite").setup({
    features = { conflict = true, hunk = true, blame = true, diff = true,
      browse = true, branch = true, ui = true, status = true },
    commands = { git = "Git" },
    keymaps = { blame_full = "<leader>gb", ui_lazygit = "<leader>lg" },
    browse = { hosts = {} },
    dashboard = { base_dir = "", extra_paths = {}, groups = {}, pull_scope = "behind", fetch_jobs = 4,
      fetch_on_open = false },
    plugins = { sources = "auto", roots = {}, log_limit = 50, timeout_ms = 30000,
      include_local = false, mode = "updated", max_commits = 1000, parallel = 4,
      fetch_jobs = 2, fetch_timeout_ms = 60000, fetch_confirm = 5,
      run_window_s = 300, merges = false, keep_reports = 20, max_age_days = 365,
      seen_ttl_days = 180, ascii = false,
      after_sync = "off",
      breaking = { collapse_repeats = 5, ignore = {}, plugins = {} } },
    progress_style = "auto",
  })
Set a keymaps.* entry to false to disable that default mapping without
disabling the underlying feature. dashboard has no features.dashboard
flag -- the scope is always registered, see |gitsuite-dashboard|. See
docs/configuration.md for every key explained individually.

6. ADAPTERS *gitsuite-adapters*

Each feature family resolves its own backend independently through
gitsuite.adapter (gitsigns, diffview, neogit, lazygit, native).
native needs nothing but git itself and is always available inside a git
repo; every other adapter is only available once its own plugin/binary is
present -- an unavailable adapter is never an error by itself, only the
family it would have served falling back further, or refusing with a clear
message when nothing is left to fall back to.

7. EVENTS *gitsuite-events*

gitsuite.nvim fires plain User autocmd events after certain actions so a
sister plugin can react without gitsuite knowing it exists (D-2: events, not
a direct require() from gitsuite into a consumer -- gitsuite.events is
the one place they are fired from). Subscribe the usual way:
  vim.api.nvim_create_autocmd("User", {
    pattern = "GitsuiteBranchSwitched",
    callback = function(event) vim.print(event.data) end,
  })
                                                       *GitsuiteBranchSwitched*
GitsuiteBranchSwitched  { dir, branch } -- after `gitsuite.features.branch
.switch() checks out a different branch. dir` is the repo root the checkout
ran in, branch the ref now checked out.

                                                    *GitsuiteConflictsResolved*
GitsuiteConflictsResolved  { bufnr } -- after `gitsuite.features.conflict
.choose()` resolves the last remaining conflict region in a buffer, not on
every choose() call -- only once the buffer has none left.

                                                        *GitsuiteStatusChanged*
GitsuiteStatusChanged  { dir } -- after a hunk stage (single hunk or whole
buffer) actually writes to the git index, fired from gitsigns' own
completion callback rather than merely after the (async) action was
requested. Not fired for a hunk reset: gitsigns' reset only rewrites the
buffer's in-memory lines, never the index or the file on disk.

                                                     *GitsuitePluginsReported*
GitsuitePluginsReported  { id, mode, at, plugins, commits, errors, saved }
-- after :Git plugins report has built a report: id names it in the report
store, mode is "updated" or "pending", at the Unix time, plugins how many
plugins changed, commits how many commits that came to, errors how many
sources could not be listed plus plugins that could not be checked (unreadable
clone, missing old state, unknown target), saved whether the report reached the
store. gitsuite has no consumer of its own; a notifier or statusline chip
subscribes.

8. STATUSLINE *gitsuite-statusline*

require("gitsuite.statusline").status(bufnr?) returns an ambient
merge-conflict indicator for the current (or given) buffer, e.g. "MERGE 2"
-- "" when the buffer has no conflicts, features.conflict is off, or
bufnr is invalid. Cached per buffer by nvim_buf_get_changedtick, safe to
call unconditionally on every statusline redraw -- no process runs in the
render path. lualine_component is status under another name, for
sections = { lualine_x = { require("gitsuite.statusline").lualine_component } }.
ui.nvim ships a ready-made adapter, ui.statusline.modules.gitsuite_conflict
(add gitsuite_conflict to your order). See docs/statusline.md for the
full wiring (heirline, the native statusline) and why the cache is keyed by
changedtick rather than |GitsuiteConflictsResolved|.

9. HEALTH CHECK *gitsuite-health*

:checkhealth gitsuite reports:
  - lib.nvim / diff.nvim / ui.nvim presence (hard dependencies -- error if missing)
  - git on $PATH
  - each adapter's availability (info, not warn/error -- see |gitsuite-adapters|)
  - the plugin sources :Git plugins reads (lazy, pack, clones)
  - the stored :Git plugins report reports (readable? from this machine?)
  - plugin state (vim.g.loaded_gitsuite)
  - dashboard.extra_paths entries (are they git repositories?)
  - rejected setup() options, if any
  - the composer's own route-tree check for :Git