Skip to main content

​
Quick Start

This guide will help you start using gitsw to switch branches with automatic stash management.

​
Prerequisites

Make sure you have:

​
Basic Usage

1

Interactive Branch Selection

Run gitsw without arguments to launch the interactive branch picker:
gitsw
This opens a fuzzy-search interface showing all your branches with recent ones listed first. Use:
  • Arrow keys to navigate
  • Type to filter branches
  • Enter to select and switch
Example output:
Select branch:
> main
  feature-auth
  develop
  feature-api
2

Direct Branch Switch

Switch to a specific branch by name:
gitsw main
If you have uncommitted changes, gitsw will prompt you:
warning: You have uncommitted changes (3 modified, 1 untracked)

What would you like to do?
> Stash changes
  Discard changes
  Abort switch
Choose “Stash changes” and gitsw will:
  • Automatically stash your changes with a branch-specific identifier
  • Switch to the target branch
  • Restore the changes when you return to the original branch
3

Return to Previous Branch

When you switch back to a branch with stashed changes:
gitsw feature-auth
gitsw automatically restores your work:
info: Switching to 'feature-auth'...
done: Switched to 'feature-auth'
info: Found stashed changes for this branch
done: Restored stashed changes.

​
Common Workflows

​
Create a New Branch

Create and switch to a new branch in one command: 
gitsw -c new-feature

​
Pull Latest Changes

Switch to a branch and pull the latest changes: 
gitsw main -p

​
Track a Remote Branch

Fetch and track a remote branch: 
gitsw -t origin/feature-api
This will:
  • Fetch from the remote
  • Create a local tracking branch
  • Switch to the new branch

​
View Recent Branches

See your recently used branches with timestamps: 
gitsw -r
Example output: 
Recent branches:

* [1] feature-auth (current)
  [2] main (2 hours ago)
  [3] develop [stash] (yesterday)
  [4] feature-api (3 days ago)
The [stash] indicator shows branches with saved changes.

​
Check Current Status

View your current branch status including changes and stashes: 
gitsw -s
Example output: 
Branch: feature-auth
Changes: 3 modified, 1 untracked
Stash: present
Package manager: npm
Tracking: origin/feature-auth

​
Package Manager Detection

When you switch branches, gitsw automatically detects changes to lock files and prompts you to install dependencies: 
info: Lock file has changed
Run npm install? (y/n)
Supported package managers:
  • npm (package-lock.json)
  • yarn (yarn.lock)
  • pnpm (pnpm-lock.yaml)
Use --no-install to skip the automatic install prompt if needed.

​
Skip Automatic Features

You can disable automatic stashing or installation when needed: 
# Skip automatic stash
gitsw main --no-stash

# Skip automatic install prompt
gitsw feature --no-install

​
List All Branches with Stashes

See which branches have saved stashes: 
gitsw -l
Example output: 
Branches with stashed changes:

  feature-auth (stash present, last visited 2 hours ago)
  develop (stash present, last visited yesterday)

​
Delete a Branch

Delete a branch and automatically clean up its stash: 
gitsw -d old-feature
If the branch has a stash, gitsw will warn you and ask for confirmation before deleting both the branch and its stash.

​
Next Steps

Now that you know the basics:

Configuration Options

Explore all available command-line options and flags

Command Reference

Learn about all commands and advanced features

​
Getting Help

For a complete list of options: 
gitsw --help
To check your installed version: 
gitsw --version

Build docs developers (and LLMs) love

Get started for freeTalk to us