feat(explorer): Git stats + Explorer Keymaps + Explorer line renderer - #448
Closed
richardgill wants to merge 8 commits into
Closed
feat(explorer): Git stats + Explorer Keymaps + Explorer line renderer#448richardgill wants to merge 8 commits into
richardgill wants to merge 8 commits into
Conversation
richardgill
marked this pull request as ready for review
July 20, 2026 16:20
…to review-deverts-commits
# Conflicts: # README.md # doc/tags
# Conflicts: # tests/ui/highlights_spec.lua
Owner
|
Thanks for the many fancy new features! I indeed would like it be multiple smaller PRs for easier review, and better risk management if there is a need for revert, thanks |
Collaborator
Author
|
@esmuellert No problem 👍, here is a PR which just adds the explorer formatters: #472 |
esmuellert
added a commit
that referenced
this pull request
Jul 29, 2026
- Add `explorer.formatters.{file,folder,group}`callbacks.
- Support styled left/right regions with display-width-aware truncation.
- Add `explorer.ellipsis` to customize truncated-region markers,
defaulting to `…`.
- Provide row metadata for files, folders, and groups while preserving
selected-row backgrounds.
- Passing `nil` to the formatters uses the default formatters from
`formatters.lua`
- New default formatter includes `...` truncation (this is a change).
This extracts only the Explorer line formatter functionality from #448.
Git line statistics and custom Explorer keymaps are intentionally
excluded.
## Demo
All three recordings use the same repository fixture, window dimensions,
cursor position, and inputs. The Explorer is resized to demonstrate
display-width-aware truncation and right-aligned regions.
### Before - upstream `main`
Default Explorer rendering:
https://github.com/user-attachments/assets/c106ba3e-e130-4265-8d32-95e8aa613b7e
### After - default formatters
- No formatter configuration is provided.
- Normal-width rendering remains unchanged;
- narrowing demonstrates the new built-in formatter truncation:
https://github.com/user-attachments/assets/7a1c8908-c2b2-4cae-be3c-98391dc88dbc
### After - custom formatters with `mini.icons`
Configuration: [custom Explorer formatters using
`mini.icons`](https://gist.github.com/richardgill/050a30e1c253dd8a20413f614b563ed0)
- This example replaces file, folder, and group rows with custom
function.
- Uses metadata such as file counts and Git groups
- Demonstrates using `mini.icons` for file and directory icons.
https://github.com/user-attachments/assets/d3766882-7233-43e2-a66c-f040285228b8
esmuellert
added a commit
that referenced
this pull request
Jul 29, 2026
- Add `explorer.formatters.{file,folder,group}`callbacks.
- Support styled left/right regions with display-width-aware truncation.
- Add `explorer.ellipsis` to customize truncated-region markers,
defaulting to `…`.
- Provide row metadata for files, folders, and groups while preserving
selected-row backgrounds.
- Passing `nil` to the formatters uses the default formatters from
`formatters.lua`
- New default formatter includes `...` truncation (this is a change).
This extracts only the Explorer line formatter functionality from #448.
Git line statistics and custom Explorer keymaps are intentionally
excluded.
## Demo
All three recordings use the same repository fixture, window dimensions,
cursor position, and inputs. The Explorer is resized to demonstrate
display-width-aware truncation and right-aligned regions.
### Before - upstream `main`
Default Explorer rendering:
https://github.com/user-attachments/assets/c106ba3e-e130-4265-8d32-95e8aa613b7e
### After - default formatters
- No formatter configuration is provided.
- Normal-width rendering remains unchanged;
- narrowing demonstrates the new built-in formatter truncation:
https://github.com/user-attachments/assets/7a1c8908-c2b2-4cae-be3c-98391dc88dbc
### After - custom formatters with `mini.icons`
Configuration: [custom Explorer formatters using
`mini.icons`](https://gist.github.com/richardgill/050a30e1c253dd8a20413f614b563ed0)
- This example replaces file, folder, and group rows with custom
function.
- Uses metadata such as file counts and Git groups
- Demonstrates using `mini.icons` for file and directory icons.
https://github.com/user-attachments/assets/d3766882-7233-43e2-a66c-f040285228b8
This was referenced Jul 29, 2026
Collaborator
Author
|
This has now been split into three focused PRs:
Closing this combined PR in favor of those replacements. |
esmuellert
added a commit
that referenced
this pull request
Aug 1, 2026
Adds opt-in Git line statistics to the Explorer.
- works across all Explorer comparison modes:
- working tree status
- a revision against the working tree
- two revisions against each other
- handles staged, unstaged, renamed, deleted, binary, conflicting, and
optionally bounded untracked files
- preserves path filtering when calculating statistics
- exposes per-file and aggregate folder/group statistics to the `file`,
`folder`, and `group` formatter functions
- includes sensible default formatter functions:
- right-aligned, truncatable file statistics
- aggregate group totals
### Screenshots
#### Before
```lua
require("codediff").setup({
explorer = {
width = 56,
view_mode = "tree",
flatten_dirs = false,
},
})
```

#### After - disabled by default
```lua
require("codediff").setup({
explorer = {
width = 56,
view_mode = "tree",
flatten_dirs = false,
-- line_stats is omitted because it is disabled by default.
},
})
```

#### After - enabled with default formatters
```lua
require("codediff").setup({
explorer = {
width = 56,
view_mode = "tree",
flatten_dirs = false,
line_stats = {
enabled = true,
count_untracked = true,
max_untracked_bytes = 1024 * 1024,
},
},
})
```

#### After - custom file, folder, and group formatters
```lua
local default_formatters = require("codediff.ui.explorer.formatters")
require("codediff").setup({
explorer = {
width = 56,
view_mode = "tree",
flatten_dirs = false,
line_stats = {
enabled = true,
count_untracked = true,
max_untracked_bytes = 1024 * 1024,
},
formatters = {
file = function(ctx)
local layout = default_formatters.file(ctx)
local right = {}
if ctx.stats then
local segments = ctx.stats.binary and {
{ text = "binary ", hl = "CodeDiffExplorerStatBinary" },
} or {
{ text = "↑" .. ctx.stats.insertions, hl = "CodeDiffExplorerStatInsertions" },
{ text = " ↓" .. ctx.stats.deletions .. " ", hl = "CodeDiffExplorerStatDeletions" },
}
right[#right + 1] = {
segments = segments,
truncate_priority = 3,
}
end
right[#right + 1] = {
segments = {
{ text = ctx.status, hl = ctx.status_hl },
{ text = string.rep(" ", ctx.status_right_margin), hl = "Normal" },
},
}
layout.right = right
return layout
end,
folder = function(ctx)
local layout = default_formatters.folder(ctx)
if not ctx.stats then
return layout
end
layout.right = {
{
segments = {
{ text = "↑" .. ctx.stats.insertions, hl = "CodeDiffExplorerStatInsertions" },
{ text = " ↓" .. ctx.stats.deletions, hl = "CodeDiffExplorerStatDeletions" },
},
},
}
return layout
end,
group = function(ctx)
return {
left = {
{
segments = { { text = " " .. ctx.label, hl = "CodeDiffExplorerTreeGroup" } },
truncate_priority = 1,
},
},
right = {
{
segments = {
{ text = ctx.file_count .. " files · ", hl = "CodeDiffExplorerStatFiles" },
{ text = "↑" .. ctx.stats.insertions, hl = "CodeDiffExplorerStatInsertions" },
{ text = " ↓" .. ctx.stats.deletions, hl = "CodeDiffExplorerStatDeletions" },
},
},
},
min_gap = 2,
}
end,
},
},
})
```

Supercedes part of #448.
Fixes #181
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR adds three related explorer features. They can be split into separate PRs if preferred.
Git line statistics
Optionally show per-file and aggregate insertion/deletion counts:
Files display
+12 -4orbin; folders and groups show aggregate totals. Statistics are disabled by default because they require additional Git queries.Explorer line formatters
Replace complete file, folder, or group rows:
Formatters receive metadata for the represented files and return styled, left/right-aligned regions with display-width-aware truncation.
Custom explorer keymaps
Add buffer-local explorer actions:
Callbacks receive the selected file, directory, or group, plus
redraw()andrefresh(). Custom mappings can override built-in explorer mappings.Fixes #181
Fixes #455
Fixes #456