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
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.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 reallazygitTUI 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
- Neovim >= 0.11 -giton$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 dashboardand 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
{
"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
*: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 containingdir(any directory inside its work tree) instead of the one of the current working directory; from Lua:require("gitsuite.features.ui").lazygit(dir). Adirthat 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 ofpath(relative todir`, or absolute); an uncommitted line has an all-zerosha. It blocks without a callback; with acb(entry, err)as fourth argument it runs asynchronously and returns a{ stop }handle. Failures (not a repo, untracked file, line past the end) arenil, 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 theconflict-marker-sizegit 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|prevand counted byhas_conflicts(). With more than one candidate, `:Git conflict ours|theirs|both|base|noneasks which=======` is the real one viavim.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 thebasemarker 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=10in.gitattributesavoids 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,dashboardreads the git status of every repository indir/dashboard.base_dir($REPOS_DIR by default), or a configureddashboard.groupspage. 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 fordashboard.*, 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.packor your plugin folders without starting a process. It only reads -- onegit 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 -- andpendingwhat the next update would bring, against the target lazy.nvim itself would check out, as of the last fetch (:Lazy checkfetches; gitsuite only with--fetch).--mode=pending --fetchfirst runsgit fetch --all --prunein every clone -- the one network access of gitsuite, never a default: it asks fromplugins.fetch_confirmclones on (--yesskips that), runsplugins.fetch_jobsat a time without any credential prompt, kills each fetch and its child processes afterplugins.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/Mmark commits as seen, kept in plugins_seen.json across reports (keys: docs/BINDINGS.md, "Plugins report keys").qcloses it;:Git pluginsopens 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 instdpath("state")/gitsuite/plugins_reports.jsonandUser GitsuitePluginsReportedfires after each. It reads local state only -- no install, update, pin or clean.--no-openstores the report and opens no buffer, only a one-line summary (--out=clipboard/--out=pathstill copy or write it). Withplugins.after_sync = "toast"(or"open") theupdatedreport is built after every:Lazy syncthat 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 withevent = "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)!:, aBREAKING CHANGE:footer, a subject starting withBREAKING), "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 repeatedplugins.breaking.collapse_repeatstimes 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
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 akeymaps.*entry tofalseto disable that default mapping without disabling the underlying feature.dashboardhas nofeatures.dashboardflag -- the scope is always registered, see |gitsuite-dashboard|. See docs/configuration.md for every key explained individually.
6. ADAPTERS
Each feature family resolves its own backend independently throughgitsuite.adapter(gitsigns,diffview,neogit,lazygit,native).nativeneeds nothing butgititself 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.nvim fires plainUserautocmd events after certain actions so a sister plugin can react without gitsuite knowing it exists (D-2: events, not a directrequire()from gitsuite into a consumer --gitsuite.eventsis 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,branchthe ref now checked out. *GitsuiteConflictsResolved*GitsuiteConflictsResolved{ bufnr }-- after `gitsuite.features.conflict .choose()` resolves the last remaining conflict region in a buffer, not on everychoose()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 reporthas built a report:idnames it in the report store,modeis "updated" or "pending",atthe Unix time,pluginshow many plugins changed,commitshow many commits that came to,errorshow many sources could not be listed plus plugins that could not be checked (unreadable clone, missing old state, unknown target),savedwhether the report reached the store. gitsuite has no consumer of its own; a notifier or statusline chip subscribes.
8. 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.conflictis off, orbufnris invalid. Cached per buffer bynvim_buf_get_changedtick, safe to call unconditionally on every statusline redraw -- no process runs in the render path.lualine_componentisstatusunder another name, forsections = { lualine_x = { require("gitsuite.statusline").lualine_component } }. ui.nvim ships a ready-made adapter,ui.statusline.modules.gitsuite_conflict(addgitsuite_conflictto yourorder). See docs/statusline.md for the full wiring (heirline, the native statusline) and why the cache is keyed bychangedtickrather than |GitsuiteConflictsResolved|.
9. HEALTH CHECK
:checkhealth gitsuitereports: - lib.nvim / diff.nvim / ui.nvim presence (hard dependencies -- error if missing) -giton$PATH- each adapter's availability (info, not warn/error -- see |gitsuite-adapters|) - the plugin sources:Git pluginsreads (lazy, pack, clones) - the stored:Git plugins reportreports (readable? from this machine?) - plugin state (vim.g.loaded_gitsuite) -dashboard.extra_pathsentries (are they git repositories?) - rejectedsetup()options, if any - the composer's own route-tree check for:Git