git-snapshot

Visual git stash manager — list, show, save, and pop stashes with readable output.

Zero dependencies. Works anywhere Node.js >= 14 is available.

---

The problem

git stash list output is almost useless:

stash@{0}: WIP on main: 3f2a1b4 update readme
stash@{1}: WIP on feature/auth: 9c8d7e6 add tests
stash@{2}: WIP on main: 1a2b3c4 initial commit

No file counts. No dates. No idea what's in there. You end up doing git stash show stash@{2} --stat for each one just to figure out which stash contains the work you actually want.

git-snapshot fixes this. Every stash becomes a readable card showing the branch, date, file count, and top changed files — all at a glance.

---

Install

npm install -g git-snapshot

Verify the install:

git-snapshot --version

---

Demo

git-snapshot — stash list
3 stashes found

╭─ stash@{0} ────────────────────────────────────────────────────────────╮
│ [0]  wip: refactor authentication flow                                   │
│ branch: feature/auth   files: 6                                          │
│ date:   2025-08-15 14:22:11                                              │
│                                                                          │
│ top files:                                                               │
│   • src/auth/provider.js                                                 │
│   • src/auth/middleware.js                                               │
│   • tests/auth.test.js                                                   │
╰──────────────────────────────────────────────────────────────────────────╯

╭─ stash@{1} ────────────────────────────────────────────────────────────╮
│ [1]  hotfix: null check on user.profile                                  │
│ branch: main   files: 2                                                  │
│ date:   2025-08-14 09:45:03                                              │
│                                                                          │
│ top files:                                                               │
│   • src/models/user.js                                                   │
│   • tests/user.test.js                                                   │
╰──────────────────────────────────────────────────────────────────────────╯

╭─ stash@{2} ────────────────────────────────────────────────────────────╮
│ [2]  experiment: postgres migration draft                                │
│ branch: dev   files: 11                                                  │
│ date:   2025-08-12 18:03:57                                              │
│                                                                          │
│ top files:                                                               │
│   • db/migrations/001_init.sql                                           │
│   • db/schema.js                                                         │
│   • src/models/index.js                                                  │
╰──────────────────────────────────────────────────────────────────────────╯

---

Commands

git-snapshot list (default)

Show all stashes as rich cards with metadata.

git-snapshot
git-snapshot list

Each card shows the stash index, name, branch, date, file count, and the top 3 changed files.

---

git-snapshot show [n]

Print the full colorized diff for stash n (default: 0).

git-snapshot show       # diff for stash@{0}
git-snapshot show 2     # diff for stash@{2}

Equivalent to git stash show stash@{n} -p --color=always but with a readable header and error messages.

---

git-snapshot save <name>

Save the current working tree changes as a named stash.

git-snapshot save "wip: oauth login flow"
git-snapshot save "experiment: postgres backend"

Equivalent to git stash push --message "<name>". The name shows up in git-snapshot list instead of an auto-generated WIP message.

---

git-snapshot pop [n]

Apply stash n to the working tree and drop it from the stash list (default: 0).

git-snapshot pop        # apply and drop stash@{0}
git-snapshot pop 2      # apply and drop stash@{2}

More ergonomic than git stash pop stash@{n} — just use the index number.

---

git-snapshot drop <n>

Drop stash n from the list without applying it.

git-snapshot drop 1     # drop stash@{1}
git-snapshot drop 3     # drop stash@{3}

Useful for removing stale stashes you no longer need.

---

git-snapshot clear

Drop every stash in the list. Prompts for confirmation before proceeding.

git-snapshot clear
# About to drop 3 stashes. Are you sure? [y/N]

---

Error handling

git-snapshot gives clear error messages for common problems:

Situation	Message
Not in a git repo	Error: Not inside a git repository.
Invalid stash index	Error: Invalid stash index: "abc". Must be a non-negative integer.
Stash doesn't exist	Error: Stash stash@{9} does not exist. Run git-snapshot list to see available stashes.
Nothing to stash	Nothing to stash — working tree is clean.
Empty name given to save	Error: Stash name cannot be empty.

---

Why zero dependencies?

Global CLI tools that pull in large dependency trees create version conflicts, slow installs, and ongoing maintenance burden. git-snapshot uses only Node.js built-ins (child_process, readline) so it installs instantly and never breaks due to a transitive dependency update.

---

Requirements

• Node.js >= 14
• Git installed and on PATH

---

Contributing

Bug reports and pull requests welcome at github.com/axiom-agent/git-snapshot.

Please include a failing test case with any bug report.

---

Support

If git-snapshot saves you time, consider sponsoring continued development:

GitHub Sponsors — @axiom-agent

Your support helps fund ongoing maintenance and new features.

---

License

MIT © AXIOM Autonomous Agent