zsh-snap-new

snapper create is powerful but unforgiving. Two silent mistakes break your safety net:

• Omitting --cleanup-algorithm timeline → the snapshot is never cleaned up automatically, filling your disk over time
• Omitting --userdata important=yes on a critical snapshot → it gets silently rotated away by snapper's number/timeline policies

snap-new makes both mistakes impossible. It replaces the raw command with a guided flow: a 14-scenario table pre-fills the description and suggests the right type (standard vs important) based on what you are about to do. Before executing, it checks disk usage, shows existing snapshot context, and asks for confirmation. --cleanup-algorithm timeline is always set — you cannot forget it.

Deployed and validated on a live openSUSE Tumbleweed system.

---

Architecture

_{⚠️ If the diagram is not visible, refresh the page — Mermaid rendering may take a moment.}

flowchart TD
    classDef plugin  fill:#1e3a5f,stroke:#93c5fd,stroke-width:2px,color:#ffffff
    classDef step    fill:#14532d,stroke:#86efac,stroke-width:2px,color:#ffffff
    classDef confirm fill:#7f1d1d,stroke:#fca5a5,stroke-width:2px,color:#ffffff
    classDef output  fill:#78350f,stroke:#fcd34d,stroke-width:2px,color:#ffffff
    classDef note    fill:#1f2937,stroke:#4b5563,stroke-width:1px,color:#9ca3af

    P[zsh-snap-new]:::plugin
    P --> R[Reason]:::step
    R --> C[Config]:::step
    C --> T[Type]:::step
    T --> S[Summary]:::confirm
    S --> CR[snapper create]:::output
    CR --> FB[Feedback]:::output

    P  -.-> NP[Oh My Zsh plugin — entry point]:::note
    R  -.-> NR[Mandatory free-text — describes the purpose of the snapshot]:::note
    C  -.-> NC[root / home — auto-detected, home shown only if config exists]:::note
    T  -.-> NT[standard: timeline cleanup / important: protected from auto-cleanup]:::note
    S  -.-> NS[Colored recap before execution — confirm or abort]:::note
    CR -.-> NCR[--cleanup-algorithm timeline always set, important=yes if applicable]:::note
    FB -.-> NFB[Green confirmation with snapshot ID — red on error]:::note

---

Features

14-scenario table with smart type suggestion

Instead of typing a free description, choose from a pre-built table of 14 common scenarios split into two columns — Important and Standard. The type (standard vs important) is automatically pre-selected based on the scenario. Choosing "Before system update" defaults to important; "Routine checkpoint" defaults to standard. For custom free-text reasons, keywords like update, kernel, downgrade, security, migration trigger the important default automatically.

Dual-config support — root, home, or both in one command

If a home snapper config is detected on the system, a third option appears: both — creating snapshots for root and home in a single command. If no home config exists, the prompt is skipped entirely. No manual -c flag required.

Disk space check before creation

Before any snapshot is created, snap-new checks filesystem usage on /. If usage exceeds 85%, a warning is displayed with the exact percentage and a confirmation is required to proceed. Prevents silently worsening space pressure on a nearly full system.

Snapshot context display

Before the type and confirmation prompts, snap-new shows the current state of each target config: total snapshot count, last snapshot ID, description, type, and date. You know exactly what exists before adding a new snapshot.

Forced --cleanup-algorithm timeline

Every snapshot created by snap-new includes --cleanup-algorithm timeline. This ensures snapper's automatic rotation policies apply — the snapshot will be cleaned up according to your configured timeline rules. Omitting this flag with raw snapper create leaves orphan snapshots that accumulate indefinitely.

Protected snapshots with important=yes

When type important is selected, --userdata important=yes is added. Snapper's number and timeline cleanup algorithms skip snapshots carrying this flag — they are protected from automatic rotation until explicitly deleted. Critical snapshots before major changes are never silently removed.

Colored confirmation summary before execution

Before calling snapper, a recap is displayed: config, type (color-coded green/yellow), and reason. The user confirms with y or aborts with N. Nothing is created until explicit confirmation.

Feedback with previous and new snapshot IDs

After creation, the output shows both the new snapshot ID and the previous snapshot ID, for each config. Makes it immediately clear what was created and what the rollback reference point is.

---

Requirements

• openSUSE Tumbleweed
• zsh 5.9+
• Oh My Zsh
• snapper — sudo zypper install snapper
• Snapper configured with at least one config (root, optionally home)

---

Installation

git clone https://github.com/crisis1er/zsh-snap-new \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/snap-new

Add snap-new to the plugins list in ~/.zshrc:

plugins=(... snap-new)

Reload:

source ~/.zshrc

---

Usage

snap-new

Step 1 — Banner + scenario table

On launch, a banner explains the context. A 2-column table lists 14 pre-defined scenarios (7 Important / 7 Standard). Option 0 lets you type a custom reason.

Step 2 — Context, smart type suggestion, summary, confirmation

After selecting a scenario, snap-new displays the current snapshot state (count + last snapshot). The type is pre-selected based on the scenario — here, scenario 1 "Before system update" triggers the important suggestion automatically. A colored summary is shown before execution, and the result confirms the new snapshot ID alongside the previous one.

---

Design decisions

• No argument — fully interactive, no risk of forgetting the description
• --cleanup-algorithm timeline always set — snapshots are managed automatically unless marked important=yes
• important=yes userdata protects the snapshot from automatic cleanup by snapper's number/timeline algorithms
• function name { } syntax — prevents zsh alias/function conflicts on shell reload
• Config home prompt appears only if the config actually exists on the system