Merge pull request #14 from BHFock/stash

Add stash/unstash support for changelists (`git cl stash`, `git cl unstash`)

Author: BHFock

README.md

@@ -17,6 +17,7 @@ Perfect for developers who prefer to organise their work logically from the star
 - Group files logically before staging using Git changelists
 - Work on multiple features on a single branch
 - Stage and commit changes by intent
+- Stash changelists and resume work later
 - Local-only metadata (`.git/cl.json`)
 - Simple CLI: `git cl <command>`
 
@@ -62,6 +63,11 @@ git cl remove README.md
 
 # Delete a changelist
 git cl delete docs-fix
+
+# Temporarily stash a changelist and resume work on a new branch
+git cl stash docs-fix
+git checkout -b docs-fix-work
+git cl unstash docs-fix
 ```
 
 ## Example Output

docs/FUTURE.md

@@ -22,19 +22,6 @@ Combine two or more changelists into a new one.
 - Merges file assignments from multiple lists
 - Ideal for consolidating related work
 
-### `git cl stash list_name`
-Temporarily shelve changes in a changelist.
-
-- Saves file changes and changelist metadata
-- Tracks stash reference internally
-- Displays stashed state in `git cl st`
-
-### `git cl unstash list_name`
-Restore a previously stashed changelist to the working directory.
-
-- Recovers both file changes and changelist context
-- Seamless integration with ongoing work
-
 ### `git cl br list_name [branch_name]`
 Create a new Git branch for a changelist.
 

docs/tutorial.md

@@ -25,6 +25,7 @@ git-cl: A Git subcommand to manage changelists in Git. Group files by intent, ma
   - [2.5 Commit a changelist](#25-commit-a-changelist)
   - [2.6 Remove files from changelists](#26-remove-files-from-changelists)
   - [2.7 Delete changelists](#27-delete-changelists)
+  - [2.8 Stash and Unstash Changelists](#28-stash-and-unstash-changelists)
 - [3. Example Workflow: Changelists as Named Staging Areas](#3-example-workflow-changelists-as-named-staging-areas)
 - [4. FAQ & Common Pitfalls](#4-faq--common-pitfalls)
 - [5. Command Summary](#5-command-summary)
@@ -326,6 +327,55 @@ git cl delete --all
 
 Only changelist metadata is deleted — no file content or Git history is lost.
 
+### 2.8 Stash and Unstash Changelists
+
+You can temporarily shelve changelists using `stash`, then restore them later with `unstash`. This is useful when switching branches or pausing work on a feature.
+
+#### Stash a changelist
+
+```
+git cl stash <changelist-name>
+```
+
+- Saves unstaged and untracked changes from the changelist.
+- Staged changes are skipped.
+- The stash is named after the changelist and timestamped.
+
+#### Unstash a changelist
+
+```
+git cl unstash <changelist-name>
+```
+
+- Restores the previously stashed changes.
+- Warns if files conflict with current working directory.
+
+#### Stash all changelists
+
+```
+git cl stash --all
+```
+
+- Stashes all active changelists.
+- Useful before switching branches or pulling updates.
+
+#### Unstash all changelists
+
+```
+git cl unstash --all
+```
+- Restores all previously stashed changelists.
+
+#### Example
+
+```
+git cl stash docs
+git checkout feature-branch
+git cl unstash docs
+```
+
+This lets you move work-in-progress between branches without committing or losing context.
+
 [↑ Back to top](#git-cl-a-git-subcommand-for-changelist-management)
 
 ## 3. Example Workflow: Changelists as Named Staging Areas