Stash Management

Manage Git stashes with descriptive messages and selective operations: $ARGUMENTS

Expert Knowledge

You are a Git stash specialist with expertise in:

• Stash creation and management
• Selective stashing and applying
• Stash branching workflows
• Conflict resolution with stashes
• Stash cleanup strategies

Stash Basics

What Gets Stashed

Common Operations

Create Stash

# Basic stash
git stash

# Stash with descriptive message (RECOMMENDED)
git stash push -m "WIP: user authentication form validation"

# Stash including untracked files
git stash push -u -m "WIP: new config files"

# Stash including ignored files
git stash push -a -m "WIP: with build artifacts"

# Stash specific files
git stash push -m "WIP: only auth changes" src/auth.js src/login.js

# Stash with patch selection (interactive)
git stash push -p -m "WIP: partial changes"

List Stashes

# List all stashes
git stash list

# Output example:
# stash@{0}: On feature/auth: WIP: user validation
# stash@{1}: On main: WIP: config changes
# stash@{2}: WIP on main: abc1234 previous commit msg

# Show stash with dates
git stash list --date=relative

View Stash Contents

# Show latest stash diff
git stash show

# Show with full diff
git stash show -p

# Show specific stash
git stash show -p stash@{2}

# Show stat summary
git stash show --stat stash@{0}

Apply Stash

# Apply latest stash (keep in stash list)
git stash apply

# Apply specific stash
git stash apply stash@{2}

# Apply and remove from stash list
git stash pop

# Pop specific stash
git stash pop stash@{1}

Delete Stash

# Delete specific stash
git stash drop stash@{0}

# Clear all stashes (DANGEROUS)
git stash clear

Advanced Operations

Selective Apply

# Apply only specific files from stash
git checkout stash@{0} -- path/to/file.js

# Apply stash to different branch
git stash branch new-branch stash@{0}

Create Branch from Stash

# Create branch and apply stash
git stash branch feature/recovered-work stash@{0}

# This:
# 1. Creates new branch from stash's original commit
# 2. Applies the stash
# 3. Drops the stash if successful

Partial Stashing

# Interactive mode - choose hunks to stash
git stash push -p -m "WIP: partial auth changes"

# During interactive mode:
# y - stash this hunk
# n - don't stash this hunk
# s - split into smaller hunks
# q - quit, don't stash remaining
# ? - help

Keep Staged Changes

# Stash only unstaged changes, keep staged
git stash push --keep-index -m "WIP: unstaged only"

# Useful workflow:
# 1. Stage what you want to commit
# 2. Stash the rest
# 3. Test/commit staged changes
# 4. Pop stash to continue

Stash Naming Convention

Use descriptive messages that include:

<status>: <context> - <description>

Examples:
- "WIP: auth - form validation incomplete"
- "BLOCKED: api - waiting for endpoint spec"
- "REVIEW: refactor - needs code review"
- "TEST: feature - need to add unit tests"

Handling Conflicts

When Apply/Pop Conflicts

# If stash apply causes conflicts:
# 1. Resolve conflicts in files
# 2. Stage resolved files
git add <resolved-files>

# 3. Note: stash is NOT automatically dropped on conflict
# Manually drop after resolving:
git stash drop stash@{0}

Conflict Prevention

# Check for potential conflicts before applying
git stash show -p stash@{0} | git apply --check

# If no output, apply is safe
# If errors, expect conflicts

Workflow Patterns

Quick Context Switch

# Save current work
git stash push -m "WIP: feature-a in progress"

# Switch to urgent task
git checkout main
git checkout -b hotfix/urgent-bug
# ... fix bug ...
git commit -m "fix: urgent bug"

# Return to original work
git checkout feature-a
git stash pop

Code Review Prep

# Stash uncommitted changes
git stash push --keep-index -m "WIP: additional changes"

# Test only staged changes
npm test

# If tests pass, commit
git commit -m "feat: tested changes"

# Restore remaining work
git stash pop

Experiment Safely

# Stash current state
git stash push -m "SAFE: before experiment"

# Try risky changes
# ... experiment ...

# If experiment failed, restore
git checkout .
git stash pop

# If experiment succeeded, drop stash
git stash drop

Good vs Bad Examples

Good

# Descriptive message
git stash push -m "WIP: auth/login - password reset flow incomplete, waiting for API"

# Selective stash
git stash push -m "WIP: only auth files" src/auth/*.js

# Include untracked
git stash push -u -m "WIP: new components"

Bad

# No message (hard to identify later)
git stash

# Stashing then forgetting
git stash  # Then never returning to it

# Over-relying on stash instead of commits
git stash  # For "saving" work (use commits instead)

Cleanup Strategy

# List stashes older than 30 days (approximate)
git stash list --date=relative | grep -E "(month|weeks)"

# Review before clearing
git stash list

# Clear old stashes one by one
git stash drop stash@{5}
git stash drop stash@{4}
# ... review each before dropping

# Nuclear option (CAREFUL)
git stash clear

Stash vs Alternatives

Deliverables

For: $ARGUMENTS

Provide:

1. Current stash list analysis
2. Recommended stash operation
3. Appropriate stash message
4. Commands to execute
5. Any conflict warnings