Docs: explain browsing and restoring local history in the dashboard

Open Beginner friendly
  • Is something wrong?
#798 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@Mohamedajab is already working on this.

Since Nov 5, 2026.

  • #811 by @Mohamedajab — open

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
88/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown, rust
Domain
documentation

Research direction

The dashboard history dialogue keys are in crates/cli/src/tui/events.rs, and the open and restore behaviour is in crates/cli/src/tui/app.rs; the local and server history commands are in crates/cli/src/commands.rs. Read those, then add a short history subsection to the README's interactive-dashboard section that links to the existing server-history guide. Done means the README covers the h shortcut, the keys, the local-only scope and the restore semantics, with synthetic secret names, and scripts/check-readme-i18n passes.

Written by the indexing model from the issue text.

Description

documentation good first issue help wanted

The problem

The README explains sotto history and sotto rollback, which use server history, but does not explain the dashboard's local version-history dialogue. Its dashboard section omits the h shortcut entirely.

These are different recovery sources: the dashboard reads versions present in the local store, whereas the named CLI commands fetch history from the server. Users should be able to discover local history without assuming it requires login or contains every remotely retained version.

Proposed approach

Add a short history subsection to the existing README dashboard guidance, and cross-link it with the existing server-history walkthrough. Document current behaviour without changing the TUI or sync implementation.

Acceptance criteria
  • Explain selecting a secret in the dashboard and pressing h to open its local version history. The dashboard needs the existing local identity/project and an unlocked store, but viewing local history does not require server login or a network request.
  • Explain that only versions present on that device are available. Do not promise complete server history or recovery of versions never held locally; link to the existing server-backed history guide for that workflow.
  • Describe navigation with arrows or j/k, revealing/concealing with r or Space, copying with c, and closing with Escape or q. Values start masked. Copying requires a readable UTF-8 value and a working clipboard.
  • Clearly distinguish navigation from mutation: Enter or b restores the selected version immediately as a new local version; it is not merely a preview or a confirmation prompt. Use synthetic secret names in examples.
  • Explain that successful restoration closes the dialogue and reports the new version. It does not rewrite older history or automatically push to the server; synchronise separately using the same environment if desired.
  • Explain briefly that an unreadable historical version cannot be restored; avoid promising that a retry or pull will always recover it.
  • Follow the repository's README translation conventions and run scripts/check-readme-i18n when changing READMEs. Record link/content checks and any hands-on validation in the PR.

Keep this a concise user guide, not a new recovery feature or a description of internal storage/cryptography.

Starting points

Evidence and scope

Source and README inspected on clean main e8ef823cedae31a1b4e435752bcb5e7485ecc69a. This is a documentation gap: no Rust build, terminal session or restoration was performed for this report.

Checked open and closed issues and open PRs. #449 documents launching and navigating the dashboard; #591 documents the server-backed commands. This issue covers the local history dialogue and its distinct data source.

Suitable for a first contribution: documentation only, with concrete implementation references. Use British English and plain hyphens, follow CONTRIBUTING.md, and sign off commits with git commit -s.

Dominant language
Rust
Stars
31
Forks
42
Avg merge
3d 21m
Merged PRs (30d)
147

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from getsotto/sotto

All issues in getsotto/sotto

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.