update: each changed file lives on one shared row, and stage hunks the index holds part of

CHANGELOG.md

@@ -8,6 +8,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- `dw` in the diff or the panel shows a partly staged file's changes since staging, works as a toggle
+- `ds` in the panel or the diff previews the commit: only the staged changes, each diffed against `HEAD`, also works as a toggle
+- `s` and `u` act on a hunk the index holds only part of, and the diff winbar tallies staged and partial hunks
+- `X` in the diff reverts a file whose only change is its mode, and a binary file
+
+### Changed
+
+- A file changed in both the index and the worktree lists once now, under a new `Partial` section, and its diff shows the whole change with the staged lines shaded
+- Staged content that can't be shown in the standard diff is marked `!`, openable by `dw`
+- `X` on a hunk discards it from the index and the file together, instead of asking you to unstage it first
+- `s` and `u` walk the change set once and end with what is left, and `s` stops on a file whose remaining change only `dw` shows until you finish it there or leave it with `]f`
+- `s`, `S`, `u` and `U` ask before dropping staged content that neither `HEAD` nor the file on disk holds
+- Prompts and notices say plainly what an action loses, or why it did nothing and where to do it instead
+- `X` in the panel on a staged edit whose file was then deleted brings it back as staged, instead of resetting it to `HEAD`
+
+### Fixed
+
+- A change to a file's final newline showed only a notice. It now shows as a hunk on the last line, with a `¬` in the gutter on whichever side ends without one
+- A file whose name holds glob characters, or starts with a digit and a colon, could stage or diff the wrong content, and a symlink diffed the content it points at
+- Staging a renamed file from the panel reported "stage failed" although the rename was staged
+- Discarding a staged rename or add whose file had been deleted from disk failed
+- A file swapped for a symlink refused every staging key in the diff
+- `s` in the panel on a staged deletion reported "stage failed"
+- `X` in the panel on a submodule asked to discard it and then did nothing. It now says why
+- A sidecar that failed to start or kept crashing reported the error twice
+- Submitting a review after the PR head moved showed two warnings
+- `gh` errors that already said to run `gh auth login` repeated the advice
+- Git errors in notices ended with a blank line
+
+## [0.1.45] — 2026-09-12
+
+### Added
+
 - `context` accepts `"full"` in config, matching `:Differ context full`, and it is now the default (`math.huge` still works)
 - A fold you open in the diff view stays open for the rest of the session, including when you come back to its file
 

README.md

@@ -165,6 +165,8 @@ require("differ").setup({
 
     -- diffs
     toggle_layout = "dl",        -- flip between stacked / split
+    toggle_local = "dw",         -- diff/panel: a partly staged file's changes since staging, and back
+    commit_preview = "ds",       -- panel/diff: only the staged changes, each as HEAD↔index, and back
     more_context = "d=", less_context = "d-",
     stage = "s", unstage = "u",  -- stage/unstage[all] work on hunks/files (diff buffer/panel)
     stage_all = "S", unstage_all = "U",
@@ -224,6 +226,14 @@ The highlight groups differ defines are listed in [recipes](RECIPES.md#highlight
 
 Sources with worktree on the new side (`:Differ`, `:Differ <rev>`, `:Differ <a>...`) also list untracked files. `git diff` can't see them whatever refs you pass it, so differ unions in `git ls-files --others --exclude-standard` to bring them in with the other changes.
 
+### Staging
+
+Every changed path takes only one row. Its diff spans `HEAD` to the worktree, with the lines already in the index shaded, and each row can either be `Conflicts`, `Staged`, `Unstaged`, `Partial` (not fully staged file) or `Untracked`. In the diff, `s` and `u` stage and unstage a hunk respectively, with repeated presses walking through/back your hunks; `X` discards a hunk on both sides (effectively hard resetting the hunk). Similarly in the panel, `s` and `u` stage and unstage entire rows/files (works on sections, directories and individual rows). `S` and `U` are available in both contexts as stage/unstage-all.
+
+Certain changes can't be displayed in that span, e.g. a change staged and then put back on disk, or a staged and then further modified hunk. Those hunks carry a `!` in the gutter and the winbar says how many exist in the current file. `dw` opens a view to show what changed since staging, where they show as hunks of their own. `ds` opens a view of **only** the files with staged changes, each diffed against the index, i.e. what is about to be committed, where `u` takes one back out.
+
+A hunk on a file's last line whose final newline differs between the two sides carries a `¬` in the gutter on the side that ends without one, since the two lines otherwise read the same.
+
 ### Runtime controls
 
 | Command | Effect |

RECIPES.md

@@ -78,6 +78,8 @@ Every group is defined with `default = true`, so a `:highlight` of your own wins
 | `differStagedWordAdd` / `differStagedWordDelete` | the word patch inside a staged line |
 | `differStagedLine` | a staged line with no add/delete kind (links `CursorLine`) |
 | `differStagedSign` | the staged-hunk gutter glyph |
+| `differHiddenSign` | the `!` gutter glyph on a hunk holding staged content the diff can't show |
+| `differNoEol` | the `¬` gutter glyph on a line its side ends on with no newline |
 
 ### File panel
 

doc/differ-recipes.txt

@@ -137,6 +137,13 @@ STAGING                              *differ-recipes-highlight-groups-staging*
                                       kind (links CursorLine)
 
   differStagedSign                    the staged-hunk gutter glyph
+
+  differHiddenSign                    the ! gutter glyph on a hunk
+                                      holding staged content the diff
+                                      can’t show
+
+  differNoEol                         the ¬ gutter glyph on a line its
+                                      side ends on with no newline
   -----------------------------------------------------------------------
 
 FILE PANEL                        *differ-recipes-highlight-groups-file-panel*

doc/differ.txt

@@ -12,6 +12,7 @@ Table of Contents                                   *differ-table-of-contents*
   - Other managers                        |differ-installation-other-managers|
 4. Configuration                                        |differ-configuration|
 5. Usage                                                        |differ-usage|
+  - Staging                                             |differ-usage-staging|
   - Runtime controls                           |differ-usage-runtime-controls|
   - PR review                                         |differ-usage-pr-review|
   - Session and sidecar commands   |differ-usage-session-and-sidecar-commands|
@@ -200,6 +201,8 @@ you’re in doubt, `:Differ sidecar` reports which one is actually running.
 
         -- diffs
         toggle_layout = "dl",        -- flip between stacked / split
+        toggle_local = "dw",         -- diff/panel: a partly staged file's changes since staging, and back
+        commit_preview = "ds",       -- panel/diff: only the staged changes, each as HEAD↔index, and back
         more_context = "d=", less_context = "d-",
         stage = "s", unstage = "u",  -- stage/unstage[all] work on hunks/files (diff buffer/panel)
         stage_all = "S", unstage_all = "U",
@@ -286,6 +289,31 @@ you pass it, so differ unions in `git ls-files --others --exclude-standard` to
 bring them in with the other changes.
 
 
+STAGING                                                 *differ-usage-staging*
+
+Every changed path takes only one row. Its diff spans `HEAD` to the worktree,
+with the lines already in the index shaded, and each row can either be
+`Conflicts`, `Staged`, `Unstaged`, `Partial` (not fully staged file) or
+`Untracked`. In the diff, `s` and `u` stage and unstage a hunk respectively,
+with repeated presses walking through/back your hunks; `X` discards a hunk on
+both sides (effectively hard resetting the hunk). Similarly in the panel, `s`
+and `u` stage and unstage entire rows/files (works on sections, directories and
+individual rows). `S` and `U` are available in both contexts as
+stage/unstage-all.
+
+Certain changes can’t be displayed in that span, e.g. a change staged and
+then put back on disk, or a staged and then further modified hunk. Those hunks
+carry a `!` in the gutter and the winbar says how many exist in the current
+file. `dw` opens a view to show what changed since staging, where they show as
+hunks of their own. `ds` opens a view of **only** the files with staged
+changes, each diffed against the index, i.e. what is about to be committed,
+where `u` takes one back out.
+
+A hunk on a file’s last line whose final newline differs between the two
+sides carries a `¬` in the gutter on the side that ends without one, since the
+two lines otherwise read the same.
+
+
 RUNTIME CONTROLS                               *differ-usage-runtime-controls*
 
   ------------------------------------------------------------------------------

lua/differ/command.lua

@@ -14,14 +14,14 @@ end
 function M.layout(arg)
     local view = require("differ").active_view()
     if not view then
-        return notify("no diff view here", vim.log.levels.WARN)
+        return notify("no differ view open", vim.log.levels.WARN)
     end
     if arg == nil or arg == "" then
         view:toggle_layout()
     elseif arg == "stacked" or arg == "split" then
         view:set_layout(arg)
     else
-        notify("layout: expected 'stacked' or 'split'", vim.log.levels.ERROR)
+        notify("layout: expected 'stacked' or 'split'", vim.log.levels.WARN)
     end
 end
 
@@ -30,7 +30,7 @@ end
 function M.context(arg)
     local view = require("differ").active_view()
     if not view then
-        return notify("no diff view here", vim.log.levels.WARN)
+        return notify("no differ view open", vim.log.levels.WARN)
     end
     if arg == "full" then
         view:set_context(math.huge)
@@ -41,7 +41,7 @@ function M.context(arg)
     else
         local n = tonumber(arg)
         if not n then
-            return notify("context: expected a number, 'full', '+' or '-'", vim.log.levels.ERROR)
+            return notify("context: expected a number, 'full', '+' or '-'", vim.log.levels.WARN)
         end
         view:set_context(math.max(0, math.floor(n)))
     end
@@ -270,15 +270,18 @@ function M.sidecar(arg)
         if err then
             -- a spawn/handshake failure already carries the binary's own stderr; a
             -- protocol-level one doesn't, so fall back to whatever it last said
-            local msg = "sidecar: " .. (err.message or err.code)
+            local msg = err.message or err.code
+            if not vim.startswith(msg, "sidecar") then -- transport errors already say so
+                msg = "sidecar: " .. msg
+            end
             local exit = sidecar.last_exit()
             if not msg:find("\n", 1, true) and exit then
                 msg = sidecar.with_tail(msg, exit.stderr)
             end
             return notify(msg, vim.log.levels.ERROR)
         end
         notify(
-            ("sidecar ok — binary %s, protocol %d"):format(info.binary or "?", info.protocol or 0)
+            ("sidecar ok: binary %s, protocol %d"):format(info.binary or "?", info.protocol or 0)
         )
     end)
 end
@@ -287,7 +290,7 @@ end
 ---@param arg string|nil
 function M.cache(arg)
     if arg ~= "clear" then
-        return notify("cache: expected 'clear'", vim.log.levels.ERROR)
+        return notify("cache: expected 'clear'", vim.log.levels.WARN)
     end
     require("differ.sidecar").request("cache_clear", nil, function(err)
         if err then

lua/differ/config.lua

@@ -162,6 +162,8 @@ M.defaults = {
         close = "dc", -- diff/panel/history: end the session (merge, pr or local)
         toggle_panel = "dd", -- diff/panel: hide/show the file panel sidebar
         toggle_layout = "dl", -- diff: flip stacked / split
+        toggle_local = "dw", -- diff/panel: a partly staged file's changes since staging, and back
+        commit_preview = "ds", -- panel/diff: list only what a commit would take, HEAD↔index rows
         -- merge tool, bound on the result buffer. nav + take-this resolution,
         -- the result buffer is the real worktree
         -- file and stays editable, so the whole choose family sits behind <leader>

lua/differ/git/exec.lua

@@ -0,0 +1,128 @@
+-- spawning git, and telling the user (or a stale buffer) about it. every git module
+-- runs through here, so the argv prefix and the message shape sit in one place
+
+local M = {}
+
+-- every path differ hands git is a real file name, never a glob
+M.GIT = { "git", "--literal-pathspecs" }
+
+---@param msg string
+---@param level integer|nil
+function M.notify(msg, level)
+    vim.notify("differ: " .. msg, level or vim.log.levels.INFO)
+end
+
+-- spawn git and wait. vim.system raises when the process can't start, so that comes
+-- back as `err`; a nil res with no err is wait() answering nothing at all
+---@param cmd string[]
+---@param opts table
+---@return { code: integer, stdout: string|nil, stderr: string|nil }|nil res, string|nil err
+local function run(cmd, opts)
+    local ok, obj = pcall(vim.system, cmd, opts)
+    if not ok then
+        return nil, tostring(obj)
+    end
+    return obj:wait()
+end
+
+-- run git in `cwd`: stdout on success, nil + stderr on failure. `text = true`
+-- normalises `\r\n`, which is right for plumbing output but would corrupt file content
+-- read via `git show`; content reads use git_raw instead
+---@param args string[]
+---@param cwd string
+---@param opts? { timeout?: integer, env?: table<string, string> }
+---@return string|nil stdout, string|nil stderr
+function M.git(args, cwd, opts)
+    local cmd = vim.list_extend({}, M.GIT)
+    vim.list_extend(cmd, args)
+    opts = opts or {}
+    local res, err = run(cmd, {
+        cwd = cwd,
+        text = true,
+        timeout = opts.timeout,
+        env = opts.env,
+    })
+    if err then
+        return nil, err -- never started
+    end
+    -- a killed process exits 124 with an empty stderr, or answers nothing at all when a
+    -- child outlives it holding the pipes. both are the budget, and neither says so
+    if opts.timeout and (not res or res.code == 124) then
+        return nil, ("git %s timed out after %ds"):format(args[1], opts.timeout / 1000)
+    end
+    if not res then
+        return nil, "git exited without a result"
+    end
+    if res.code ~= 0 then
+        return nil, res.stderr
+    end
+    return res.stdout
+end
+
+-- like `git`, but byte-true stdout (CRLF kept): for content reads (`git show` on the
+-- index, a rev, a conflict stage), never for plumbing output
+---@param args string[]
+---@param cwd string
+---@return string|nil stdout, string|nil stderr
+function M.git_raw(args, cwd)
+    local cmd = vim.list_extend({}, M.GIT)
+    vim.list_extend(cmd, args)
+    local res, err = run(cmd, { cwd = cwd })
+    if not res then
+        return nil, err
+    end
+    if res.code ~= 0 then
+        return nil, res.stderr
+    end
+    return res.stdout
+end
+
+-- run git and report a failure where the user can see it. the wrapper owns the message,
+-- so a caller branching on the boolean alone can't swallow one
+---@param args string[]
+---@param cwd string
+---@param what string  -- names the operation in the message
+---@return boolean ok
+function M.git_ok(args, cwd, what)
+    local out, err = M.git(args, cwd) -- nil out is exactly a non-zero exit; stderr can be empty
+    if not out then
+        M.notify(M.with_stderr(what .. " failed", err), vim.log.levels.ERROR)
+        return false
+    end
+    return true
+end
+
+-- `lead`, followed by what git said when it said anything
+---@param lead string
+---@param stderr string|nil
+---@return string
+function M.with_stderr(lead, stderr)
+    local said = vim.trim(stderr or "")
+    if said == "" then
+        return lead
+    end
+    return lead .. ": " .. said
+end
+
+-- strip trailing whitespace from a git output line (e.g. rev-parse, show, log)
+---@param s string
+---@return string
+function M.chomp(s)
+    return (s:gsub("%s+$", ""))
+end
+
+-- a buffer on a file differ just rewrote keeps the old content until something checks,
+-- and a window switch doesn't. checktime leaves unsaved edits alone, so fire it always
+---@param root string
+---@param relpath string
+function M.reload_buffer(root, relpath)
+    local buf = require("differ.util.buf").find(root .. "/" .. relpath)
+    if buf and vim.api.nvim_buf_is_loaded(buf) then
+        -- silent!: the file may be gone entirely (a discarded untracked file)
+        pcall(vim.api.nvim_buf_call, buf, function()
+            vim.cmd("silent! checktime")
+        end)
+    end
+end
+
+return M