gitflash 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86ac16bd9cd3c64cd98305a6423e67c05187040d8caba798d132a4f985ee28df
-  data.tar.gz: 8da24e90611e20296f70ca3cadab5a77f697c97ff43cf535b9f51b1bd40a66be
+  metadata.gz: 5a9dbc4a8ff348766f4e0a7911d451f372a4ab4b355e55d9f260d453a668948f
+  data.tar.gz: 687787d41cf614c244512ac27a105bc34cf1d75a169d6eec14f56c80a3ab1c88
 SHA512:
-  metadata.gz: c573a9265e4558a9d502840cb7b65b0c07c6e6f640c74bde499ed1b4ff160fd8aeb101a9ecd95b692a2170c812d0a6afd14d8abe8629d46b8e65732a7622384c
-  data.tar.gz: 53e55b8afcc5f32cd1b0fa238e0f7db356b4e919d57f606ebec37ee3a86539fff2dd0afaef3b5bf6f295f235e9f4452ec1b5bb3dee5dc7fd1df964cb3e6f3d85
+  metadata.gz: d7f50c47a77e7efe0410f287dfe6c7a447187300c3974512aeb17a52806bc4e139148a45f9499118cc6286c7a636f4209f476eea8e3e0eb23cb13a5c75eac3a0
+  data.tar.gz: 271acb28eabeb2ffa6efb6e9bc9449d90dc02ab650c8d57f8f54b1330bc164f921f7bd18b9ebdc7db0094e07347e05a631708f42c4e9eff4b09d73607bf3d09f

data/CHANGELOG.md

@@ -62,3 +62,14 @@ Security fixes for names and text that come from the repository:
 - Branch and default-branch detection use full ref names. A tag named like `origin/<default>` could change the short name of `origin/HEAD`, so the default branch lost its deletion protection and its merge status; `origin/HEAD` must now point inside `refs/remotes/origin/`
 - `delete` passes `--` before the branch name; `resolve_commit` refuses references that start with a dash
 - Text output shows terminal control characters of repository-controlled text (commit subjects, git errors) as escapes such as `\x1B`, so a crafted commit subject cannot move the cursor, rewrite output or set the clipboard (OSC 52). JSON output keeps the original text
+
+## [0.6.0] - 2026-10-05
+
+- Snapshots: gitflash saves branches, HEAD, tracked, staged and untracked files and stash entries before every change it makes, as git objects under `refs/gitflash/snapshots/` (the working tree is never touched; untracked files over 50 MB are skipped)
+- Add `undo [SNAPSHOT]`: restores the parts a snapshot saved (the latest by default), after saving the current state so the undo can be undone
+- Add `snapshot` (save on request, `--scope`, `--message`), `snapshots` (list) and `gc --older-than DAYS`
+- Every `done` result of `checkout`, `delete` and `reset` includes `undo` with the snapshot id; human output ends with `Undo with: gitflash undo ID`
+- Add `hook claude`: a Claude Code `PreToolUse` hook that saves a snapshot before destructive git commands an agent runs itself (`reset`, `checkout -- .`, `restore`, `clean -f`, `branch -D`, `stash drop`, `rebase`, `worktree remove --force`, ...). Modes: `snapshot` (default), `ask`, `deny`. It never blocks a command because of its own errors
+- Add `hook install [--scope local|project|user] [--mode ...]` to register the hook in Claude Code settings; it reports which sessions the file applies to, and the local scope uses the main checkout's root inside a worktree, as Claude Code does
+- Add `hook status` to show whether the hook protects Claude Code sessions in the current directory
+- JSON schema: new `undo` field, commands `undo`, `snapshots`, `snapshot`, `gc`, `hook`, error codes `unknown_snapshot`, `wrong_worktree`, `invalid_settings`

data/README.md

@@ -1,6 +1,6 @@
 # GitFlash
 
-[![Gem Version](https://badge.fury.io/rb/gitflash.svg)](https://badge.fury.io/rb/gitflash)
+[![GitHub version](https://badge.fury.io/gh/Kleanthismits%2Fgit_flash.svg)](https://badge.fury.io/gh/Kleanthismits%2Fgit_flash)
 
 ⚠️ **This project is still under development**: Use at your own risk!
 
@@ -38,9 +38,51 @@ Run `gitflash` inside a git repository to get a list with the available commands
 | `gitflash checkout [BRANCH]` | Check out a branch, or pick one from a list |
 | `gitflash delete [BRANCH...]` | Delete branches, or pick them from a list. The current, default, `main` and `master` branches are protected. Unmerged branches are kept unless you pass `--force` |
 | `gitflash reset [COMMIT]` | Reset to a commit, or pick one of the latest 100. Mixed by default; `--soft` keeps changes staged, `--hard` discards them after confirmation |
+| `gitflash undo [SNAPSHOT]` | Restore a snapshot, the latest by default: deleted branches, moved branches, HEAD, uncommitted and untracked files, dropped stashes |
+| `gitflash snapshot` | Save the current state on request (`--scope`, `--message`) |
+| `gitflash snapshots` | List snapshots, newest first |
+| `gitflash gc` | Delete snapshots older than 30 days (`--older-than DAYS`) |
+| `gitflash hook install` | Protect plain git commands run by Claude Code (see below) |
+| `gitflash hook status` | Show whether the hook protects Claude Code sessions in the current directory |
 | `gitflash schema` | Print the JSON Schema of the `--json` output |
 | `gitflash version` | Print the installed version (also `--version`, `-v`) |
 
+### Undo
+
+Before every change it makes, gitflash saves a snapshot: branches, HEAD, tracked, staged and untracked files, and stash entries. Snapshots are plain git objects under `refs/gitflash/snapshots/`; the working tree is never touched while saving. Git's own `revert` and `reflog` cover committed work; snapshots also cover what git never recorded: uncommitted and untracked files, deleted branches (git deletes their reflog) and dropped stashes.
+
+```bash
+gitflash delete old-feature --yes
+```
+
+```bash
+gitflash undo --yes
+```
+
+`gitflash undo` restores only what the snapshot saved and what differs, and saves the current state first, so an undo can itself be undone.
+
+### Protect plain git commands run by AI agents
+
+Agents often run git directly. Claude Code's own checkpoints do not cover changes made by shell commands, so a `git reset --hard` or `git clean -fd` run by an agent cannot be rewound there. Install the gitflash hook once per repository:
+
+```bash
+gitflash hook install
+```
+
+Before Claude Code runs a command that can discard work git cannot restore (`reset`, `checkout -- .`, `restore`, `clean -f`, `branch -D`, `stash drop`, `rebase`, `worktree remove --force`, ...), the hook saves a snapshot and tells the agent how to undo it. Other commands pass through; the hook adds about 0.1 s to commands that do not mention git. `--mode ask` also asks you to approve such commands, `--mode deny` blocks them.
+
+Where the hook goes, following Claude Code's own rules:
+
+| Scope | File | Applies to |
+| --- | --- | --- |
+| `local` (default) | `.claude/settings.local.json` at the repository root (the main checkout's root inside a worktree) | Sessions anywhere in the repository and its worktrees |
+| `project` | `.claude/settings.json` at the repository top level, to share with your team | Sessions started in that directory |
+| `user` | `~/.claude/settings.json` | Every session |
+
+Claude Code reloads settings files, so running sessions pick the hook up without a restart. Run `gitflash hook status` in the directory where you start Claude Code to check which files apply and whether the `gitflash` executable is found.
+
+### Scripts
+
 Without an argument, a command shows an interactive list. With arguments it runs directly, which also works in scripts.
 
 Options for every command:
@@ -76,6 +118,7 @@ With `--json`, every command prints one object in the same envelope, defined in
 
 - `status`: `done`, `planned` (`--dry-run`), `noop`, `cancelled`, `failed`, `confirmation_required` or `error`. `ok` is true for the first four.
 - `result` includes what you need to revert: the SHA of each deleted branch (`git branch NAME SHA`), the previous branch after `checkout`, the previous commit after `reset`.
+- `undo` names the snapshot saved before the change and the command that restores it (`gitflash undo ID`).
 - `error.code` is a stable identifier such as `unknown_branch`, `protected_branch` or `confirmation_required`.
 
 ```bash

data/bin/gitflash

@@ -1,6 +1,16 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# Fast path for the agent hook, which runs before every shell command: when the command does
+# not mention git there is nothing to do, so exit before loading the rest of gitflash.
+if ARGV.first(2) == %w[hook claude]
+  input = $stdin.read
+  exit 0 unless input.include?('git')
+
+  require 'stringio'
+  $stdin = StringIO.new(input)
+end
+
 require 'gitflash'
 require 'gitflash/cli'
 

data/command_descriptions.yml

@@ -46,3 +46,26 @@ reset:
     By default performs a mixed reset: your changes are kept as unstaged changes.
     Pass --soft to keep them staged, or --hard to discard them. A hard reset asks for
     confirmation; pass --yes to skip it, which is required without a terminal.
+
+undo:
+  short: 'Restore a snapshot (the latest by default)'
+  long: |
+    Restores the parts of the repository a snapshot saved: deleted or moved branches,
+    HEAD, tracked, staged and untracked files, and dropped stash entries. Only parts that
+    differ are changed; branches and files created after the snapshot are left alone.
+
+    gitflash saves a snapshot before every change it makes, and the agent hook saves one
+    before destructive git commands. List them with `gitflash snapshots`.
+
+    The current state is saved as a new snapshot first, so an undo can itself be undone.
+    Asks for confirmation; pass --yes to skip it (required without a terminal) or
+    --dry-run to only show the plan.
+
+snapshot:
+  short: 'Save the current state so it can be restored with gitflash undo'
+  long: |
+    Saves branches, HEAD, tracked, staged and untracked files (not ignored ones) and stash
+    entries as git objects under refs/gitflash/snapshots/. The working tree is not changed.
+    Untracked files larger than 50 MB are skipped and listed.
+
+    Use --scope to save only some parts, for example --scope worktree.

data/lib/gitflash/branch.rb

@@ -29,6 +29,12 @@ module Gitflash
       )
     end
 
+    # { branch name => sha } from `git for-each-ref --format=TIPS_FORMAT refs/heads/`
+    def self.parse_tips(output)
+      output.to_s.each_line(chomp: true).to_h { |line| line.split(' ', 2) }
+            .transform_keys { |ref| ref.delete_prefix(Repo::HEADS) }
+    end
+
     # The record's fields; the full ref name is shortened by removing refs/heads/ only, because
     # `refname:short` gives another name when a tag has the same name.
     def self.fields(line)
@@ -50,4 +56,5 @@ module Gitflash
       super.merge(last_commit_at: last_commit_at.iso8601)
     end
   end
+  Branch::TIPS_FORMAT = '%(refname) %(objectname)'
 end

data/lib/gitflash/cli.rb

@@ -5,6 +5,7 @@ require 'thor'
 module Gitflash
   class Cli < Thor
     extend Configuration::Descriptions
+    include CommandRunner
 
     SCHEMA_PATH = File.expand_path('../../schema/v1.json', __dir__)
 
@@ -25,13 +26,13 @@ module Gitflash
     option :gone, type: :boolean, desc: 'Branches whose upstream branch was deleted'
     option :stale, type: :numeric, banner: 'DAYS', desc: 'Branches without commits for DAYS days'
     def branches
-      run_command(Commands::Branches)
+      run_command('branches', Commands::Branches)
     end
 
     desc 'checkout [BRANCH]', descriptions.checkout.short
     long_desc descriptions.checkout.long
     def checkout(branch = nil)
-      run_command(Commands::Checkout, *[branch].compact)
+      run_command('checkout', Commands::Checkout, *[branch].compact)
     end
 
     desc 'delete [BRANCH...]', descriptions.delete.short
@@ -39,7 +40,7 @@ module Gitflash
     option :force, type: :boolean, default: false,
                    desc: 'Delete branches even if they have unmerged changes'
     def delete(*branches)
-      run_command(Commands::Delete, *branches)
+      run_command('delete', Commands::Delete, *branches)
     end
 
     desc 'reset [COMMIT]', descriptions.reset.short
@@ -47,9 +48,39 @@ module Gitflash
     option :hard, type: :boolean, default: false, desc: 'Discard all current changes'
     option :soft, type: :boolean, default: false, desc: 'Keep changes staged'
     def reset(commit = nil)
-      run_command(Commands::Reset, *[commit].compact)
+      run_command('reset', Commands::Reset, *[commit].compact)
     end
 
+    desc 'undo [SNAPSHOT]', descriptions.undo.short
+    long_desc descriptions.undo.long
+    def undo(snapshot = nil)
+      run_command('undo', Commands::Undo, *[snapshot].compact)
+    end
+
+    desc 'snapshots', 'List snapshots, newest first'
+    def snapshots
+      run_command('snapshots', Commands::SnapshotList)
+    end
+
+    desc 'snapshot', descriptions.snapshot.short
+    long_desc descriptions.snapshot.long
+    option :message, type: :string, desc: 'Why the snapshot was taken'
+    option :scope, type: :array, banner: 'PARTS',
+                   desc: 'Parts to save: branches head worktree stashes (default: all)'
+    def snapshot
+      run_command('snapshot', Commands::SnapshotCreate)
+    end
+
+    desc 'gc', 'Delete old snapshots'
+    option :older_than, type: :numeric, banner: 'DAYS',
+                        desc: 'Delete snapshots older than DAYS days (default 30)'
+    def gc
+      run_command('gc', Commands::Gc)
+    end
+
+    desc 'hook SUBCOMMAND', 'Agent hooks: claude (run the hook), install (register it)'
+    subcommand 'hook', HookCli
+
     desc 'schema', 'Print the JSON Schema of the --json output'
     def schema
       puts File.read(SCHEMA_PATH)
@@ -61,22 +92,5 @@ module Gitflash
     def version
       puts VERSION
     end
-
-    private
-
-    def run_command(command_class, *)
-      ui = build_ui(command_class.name.split('::').last.downcase)
-      repo = Repo.new
-      repo.ensure_work_tree!
-      status = command_class.new(repo: repo, ui: ui, options: options).call(*)
-      exit(status) unless status.zero?
-    rescue Error => e
-      ui.error(e)
-      exit(e.exit_code)
-    end
-
-    def build_ui(command)
-      Ui.new(command: command, json: options[:json], yes: options[:yes], dry_run: options[:dry_run])
-    end
   end
 end

data/lib/gitflash/command_runner.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Runs a command class with the parsed Thor options and turns errors into output and exit codes
+  module CommandRunner
+    private
+
+    def run_command(name, command_class, *, repo_required: true)
+      ui = build_ui(name)
+      repo = Repo.new
+      repo.ensure_work_tree! if repo_required
+      status = command_class.new(repo: repo, ui: ui, options: options).call(*)
+      exit(status) unless status.zero?
+    rescue Error => e
+      ui.error(e)
+      exit(e.exit_code)
+    end
+
+    def build_ui(name)
+      Ui.new(command: name, json: options[:json], yes: options[:yes], dry_run: options[:dry_run])
+    end
+  end
+end

data/lib/gitflash/commands/base.rb

@@ -26,6 +26,15 @@ module Gitflash
         raise Error.new("git #{command} failed:\n#{result.output}", code: 'git_failed')
       end
 
+      def snapshots
+        @snapshots ||= Gitflash::Snapshots.new
+      end
+
+      # Saves the state a change is about to modify, so `gitflash undo` can restore it
+      def take_snapshot(reason, scope:, branches: nil)
+        snapshots.create(reason: reason, scope: scope, branches: branches)
+      end
+
       def planned(plan, text)
         ui.report(status: 'planned', plan: plan, text: text)
       end

data/lib/gitflash/commands/checkout.rb

@@ -32,11 +32,12 @@ module Gitflash
         plan = { branch: name }
         return planned(plan, "Would check out '#{name}'") if ui.dry_run?
 
+        snapshot = take_snapshot("gitflash checkout #{name}", scope: %w[head])
         result = repo.checkout(name)
         git_error!('checkout', result) unless result.success?
 
         ui.report(status: 'done', plan: plan, result: { branch: name, previous_branch: current },
-                  text: "Switched to branch '#{name}'")
+                  undo: snapshot, text: "Switched to branch '#{name}'")
       end
 
       def noop(branch, text)

data/lib/gitflash/commands/delete.rb

@@ -56,8 +56,10 @@ module Gitflash
         return planned(plan, "Would delete:\n#{bullets(names)}") if ui.dry_run?
         return cancelled(plan) unless ui.confirm?(summary(names), plan: plan)
 
+        snapshot = take_snapshot("gitflash delete #{names.join(' ')}",
+                                 scope: %w[branches], branches: names)
         outcomes = names.map { |name| [name, repo.delete_branch(name, force: force?)] }
-        report_results(plan, outcomes, shas)
+        report_results(plan, outcomes, shas, snapshot)
       end
 
       def summary(names)
@@ -74,14 +76,15 @@ module Gitflash
         nil
       end
 
-      def report_results(plan, outcomes, shas)
+      def report_results(plan, outcomes, shas, snapshot)
         deleted, failed = outcomes.partition { |_name, result| result.success? }
         result = {
           deleted: deleted.map { |name, _result| { branch: name, sha: shas[name] } },
           failed: failed.map { |name, result| { branch: name, error: result.output } }
         }
         ui.report(status: failed.empty? ? 'done' : 'failed', plan: plan, result: result,
-                  error: failure(failed, outcomes), text: results_text(result))
+                  error: failure(failed, outcomes), text: results_text(result),
+                  undo: (snapshot if deleted.any?))
       end
 
       def failure(failed, outcomes)

data/lib/gitflash/commands/gc.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Deletes snapshots older than --older-than DAYS (default 30). Git frees their objects at
+    # its next garbage collection.
+    class Gc < Base
+      DEFAULT_DAYS = 30
+
+      def call
+        days = options[:older_than] || DEFAULT_DAYS
+        old = older_than(days)
+        plan = { older_than_days: days, snapshots: old.map(&:id) }
+        return nothing(plan) if old.empty?
+
+        delete(plan, "#{old.size} snapshots older than #{days} days")
+      end
+
+      private
+
+      def delete(plan, text)
+        return planned(plan, "Would delete #{text}") if ui.dry_run?
+        return cancelled(plan) unless ui.confirm?("You are about to delete #{text}", plan: plan)
+
+        plan[:snapshots].each { |id| snapshots.delete(id) }
+        ui.report(status: 'done', plan: plan, result: { deleted: plan[:snapshots] },
+                  text: "Deleted #{text}")
+      end
+
+      def older_than(days)
+        cutoff = Time.now - (days * 86_400)
+        snapshots.list.select { |snapshot| Time.iso8601(snapshot.created_at) < cutoff }
+      end
+
+      def nothing(plan)
+        ui.report(status: 'noop', plan: plan, result: { deleted: [] },
+                  text: "No snapshots older than #{plan[:older_than_days]} days")
+      end
+    end
+  end
+end

data/lib/gitflash/commands/hook_install.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Gitflash
+  module Commands
+    # Registers `gitflash hook claude` as a Claude Code PreToolUse hook for Bash commands.
+    # Merges into the settings file and keeps everything else in it.
+    class HookInstall < Base
+      SCOPES = Hook::Settings::SCOPES
+
+      def call
+        plan = build_plan
+        data = settings.read(plan[:file])
+        entry = settings.entry(data)
+        return already_installed(plan) if entry && entry['command'] == plan[:command]
+        return planned(plan, "Would add the gitflash hook to #{plan[:file]}") if ui.dry_run?
+
+        install(data, entry, plan)
+      end
+
+      private
+
+      def build_plan
+        scope = choice(:scope, SCOPES, 'local')
+        { scope: scope, file: settings.path(scope), command: hook_command,
+          applies_to: settings.applies_to(scope) }
+      end
+
+      def settings
+        @settings ||= Hook::Settings.new(options[:scope] == 'user' ? nil : repo)
+      end
+
+      def install(data, entry, plan)
+        entry ? entry['command'] = plan[:command] : add_entry(data, plan[:command])
+        FileUtils.mkdir_p(File.dirname(plan[:file]))
+        File.write(plan[:file], "#{JSON.pretty_generate(data)}\n")
+        ui.report(status: 'done', plan: plan, result: plan,
+                  text: "Installed the gitflash hook in #{plan[:file]}.\n" \
+                        "It applies to #{plan[:applies_to]}, including running ones.")
+      end
+
+      def choice(name, allowed, default)
+        value = options[name] || default
+        return value if allowed.include?(value)
+
+        usage_error!('invalid_options', "Unknown #{name} '#{value}' (use #{allowed.join(', ')})")
+      end
+
+      def hook_command
+        mode = choice(:mode, Hook::Claude::MODES, 'snapshot')
+        mode == 'snapshot' ? 'gitflash hook claude' : "gitflash hook claude --mode #{mode}"
+      end
+
+      def already_installed(plan)
+        ui.report(status: 'noop', plan: plan, result: plan,
+                  text: "Already installed in #{plan[:file]}.\nIt applies to #{plan[:applies_to]}.")
+      end
+
+      def add_entry(data, command)
+        hooks = (data['hooks'] ||= {})
+        (hooks['PreToolUse'] ||= []) << {
+          'matcher' => 'Bash',
+          'hooks' => [{ 'type' => 'command', 'command' => command, 'timeout' => 30 }]
+        }
+      end
+    end
+  end
+end

data/lib/gitflash/commands/hook_status.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Shows whether the gitflash hook protects Claude Code sessions in the current directory:
+    # which settings files hold it, which sessions each file applies to, and whether the
+    # gitflash executable the hook runs can be found.
+    class HookStatus < Base
+      def call
+        settings = Hook::Settings.new(inside_repo? ? repo : nil)
+        files = settings.scopes.map { |scope| file_status(settings, scope) }
+        executable = find_executable
+        active = executable && files.any? { |file| file[:installed] }
+        result = { active: active ? true : false, executable: executable, files: files }
+        ui.report(status: 'done', result: result, text: text(result))
+      end
+
+      private
+
+      def inside_repo?
+        repo.ensure_work_tree!
+        true
+      rescue Error
+        false
+      end
+
+      def file_status(settings, scope)
+        path = settings.path(scope)
+        entry = settings.entry(settings.read(path))
+        { scope: scope, file: path, installed: !entry.nil?, command: entry&.fetch('command', nil),
+          applies_to: settings.applies_to(scope) }
+      end
+
+      def find_executable
+        ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).map { |dir| File.join(dir, 'gitflash') }
+           .find { |path| File.file?(path) && File.executable?(path) }
+      end
+
+      def text(result)
+        lines = [headline(result)]
+        result[:files].each do |file|
+          state = file[:installed] ? "installed (#{file[:command]})" : 'not installed'
+          lines << "  #{file[:scope].ljust(8)} #{file[:file]}: #{state}"
+          lines << "           applies to #{file[:applies_to]}" if file[:installed]
+        end
+        lines << "  gitflash executable: #{result[:executable] || 'not found on PATH'}"
+        lines.join("\n")
+      end
+
+      def headline(result)
+        return 'gitflash hook: active' if result[:active]
+
+        reason = if result[:executable]
+                   'run `gitflash hook install`'
+                 else
+                   'the gitflash executable is not on PATH'
+                 end
+        "gitflash hook: not active (#{reason})"
+      end
+    end
+  end
+end

data/lib/gitflash/commands/reset.rb

@@ -48,11 +48,17 @@ module Gitflash
 
       def execute(plan, text)
         previous = repo.resolve_commit('HEAD')
+        snapshot = snapshot_before(plan)
         result = repo.reset(plan[:commit], mode: plan[:mode])
         git_error!('reset', result) unless result.success?
 
         ui.report(status: 'done', plan: plan, result: plan.merge(previous_commit: previous),
-                  text: text.capitalize)
+                  undo: snapshot, text: text.capitalize)
+      end
+
+      def snapshot_before(plan)
+        take_snapshot("gitflash reset --#{plan[:mode]} #{plan[:commit][0, 7]}",
+                      scope: %w[branches head worktree], branches: [repo.current_branch].compact)
       end
 
       def confirmed?(plan)

data/lib/gitflash/commands/snapshot_create.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Saves the current state on request, for example before a risky step
+    class SnapshotCreate < Base
+      def call
+        snapshot = take_snapshot(options[:message] || 'gitflash snapshot', scope: scope)
+        ui.report(status: 'done', result: { snapshot: snapshot.to_h }, undo: snapshot,
+                  text: text(snapshot))
+      end
+
+      private
+
+      def scope
+        scope = options[:scope] || Snapshots::SCOPES
+        invalid = scope - Snapshots::SCOPES
+        usage_error!('invalid_options', "Unknown scope: #{invalid.join(', ')}") if invalid.any?
+        scope
+      end
+
+      def text(snapshot)
+        text = "Saved snapshot #{snapshot.id}"
+        return text if snapshot.skipped_files.empty?
+
+        "#{text}\nSkipped large untracked files: #{snapshot.skipped_files.join(', ')}"
+      end
+    end
+  end
+end

data/lib/gitflash/commands/snapshot_list.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Lists snapshots, newest first
+    class SnapshotList < Base
+      def call
+        list = snapshots.list
+        text = list.empty? ? 'No snapshots' : list.map { |snapshot| row(snapshot) }.join("\n")
+        ui.report(status: 'done', result: { snapshots: list.map(&:to_h) }, text: text)
+      end
+
+      private
+
+      def row(snapshot)
+        "#{snapshot.id}  #{snapshot.scope.join(',').ljust(28)}  #{snapshot.reason}"
+      end
+    end
+  end
+end