Skip to content

docs: Clarify setup reload, persistence, stack view and marks behavior - #55

Merged
mhiro2 merged 5 commits into
mainfrom
docs/clarify-setup-persist-and-panels
Oct 5, 2026
Merged

docs: Clarify setup reload, persistence, stack view and marks behavior#55
mhiro2 merged 5 commits into
mainfrom
docs/clarify-setup-persist-and-panels

Conversation

@mhiro2

@mhiro2 mhiro2 commented Oct 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

  • Align the setup reload docs with the implementation: commands are created once and read the latest config when run
  • Report which session items were skipped on restore and why, and skip entries whose file was deleted instead of opening empty popups
  • Document what a session stores, per-repository storage, empty stacks, the synchronous save on leave and unreadable storage
  • Explain stack view focus/zoom behavior, the read-only panel, and what happens to edits in copy and source popups
  • Explain when numbered and special marks are listed by the marks providers

Changes

  • dc50e18 : docs: describe how re-running setup reuses commands
    • The reload section now lists what is rebuilt for the new config and states that user commands are reused and always read the current config
  • 84d2cd5 : fix(persist): report which session items were skipped on restore
    • Session entries pointing to a file that no longer exists are skipped instead of restored as empty popups
    • The restore warning lists up to five skipped files with their reasons, and PeekstackRestore carries every skipped item as skipped
    • URIs without a scheme no longer break the report, and restore tests use real files
  • 9d94eb3 : docs(persist): describe what a session stores and how edge cases behave
    • Describes which stack a session holds, that restore adds to the current stack, and that storage is per repository/worktree as seen from the window cwd
    • Covers saving an empty stack, clearing the auto session by closing every popup, the synchronous save on leave, unreadable storage and skipped items
  • 87f626d : docs: explain stack view focus and zoom and popup edit behavior
    • The stack view closes when focus leaves it (so <CR> closes it), z zooms the top popup rather than the selected entry, and the panel is read-only
    • Copy popups are snapshots whose edits are never written and are dropped on close; source popups edit the real buffer and keep unsaved changes after closing
  • 61efe4a : docs(marks): explain when numbered and special marks are listed
    • Numbered marks need to be added to include, and special marks need both include_special and their character in include
    • A test locks down that include_special alone does not add special marks

@mhiro2 mhiro2 self-assigned this Oct 5, 2026
@mhiro2 mhiro2 added the documentation Improvements or additions to documentation label Oct 5, 2026
mhiro2 added 5 commits October 5, 2026 21:42
@mhiro2
docs: describe how re-running setup reuses commands
dc50e18 
The docs said a second setup() call re-registers the user commands, but
they are created once and reused, reading the config each time they run.
The reload section now says which parts are rebuilt for the new config
and that the commands always use the latest settings.
@mhiro2
fix(persist): report which session items were skipped on restore
84d2cd5 
A restore only warned with the number of skipped items, so there was no
way to tell which entries failed or why, and an entry whose file had
been deleted came back as an empty popup. Missing files are now skipped,
the warning lists each skipped file with its reason, and the
PeekstackRestore event carries the same list as `skipped`.
@mhiro2
docs(persist): describe what a session stores and how edge cases behave
9d94eb3 
The persist docs did not say which stack a session holds, that restoring
adds to the current stack, or that storage is kept per repository or
worktree as seen from the window's cwd. They now also cover saving an
empty stack, the synchronous save on leave, unreadable storage, and the
list of skipped items reported on restore.
@mhiro2
docs: explain stack view focus and zoom and popup edit behavior
87f626d 
It was unclear that the stack view closes whenever focus leaves it, so
<CR> on an entry also closes the panel, and that z zooms the top popup
rather than the selected one. The panel is now described as read-only,
and the buffer mode docs say what happens to edits in copy and source
popups on save, close, history, sessions and promote.
@mhiro2
docs(marks): explain when numbered and special marks are listed
61efe4a 
The marks options did not say that the default include only covers
letters, that numbered marks must be added to include, or that special
marks need both include_special and their character in include. The
docs now spell this out with an example, and a test locks down that
include_special alone does not add special marks.
@mhiro2
mhiro2 force-pushed the docs/clarify-setup-persist-and-panels branch from 9f2c659 to 61efe4a Compare October 5, 2026 12:42
@mhiro2
mhiro2 merged commit 383744c into main Oct 5, 2026
3 checks passed
@mhiro2
mhiro2 deleted the docs/clarify-setup-persist-and-panels branch October 5, 2026 12:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@mhiro2 mhiro2

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mhiro2