Gitsy

Git commands, turbocharged

Overview

Gitsy is a set of versatile bash utilities designed to make managing Git repositories easier, faster, and more efficient. It provides user-friendly commands to automate common Git operations such as checking out branches, pushing, pulling, creating worktrees, stashing changes, and viewing git status — all enhanced with helpful prompts, color-coded outputs, and automation.

System Requirements

Requirement
Details
Node.js
>= 12.0.0
Shell
Bash
Version Control
Git
Dependencies
figlet, lolcat
Supported OS
macOS, Linux

Command Reference

Command
Description
Key Flags
g-co
Checkout branch
--target-branch, --stash-changes
g-pull
Pull changes from remote
--target-branch, --fetch
g-push
Push changes to remote
--target-branch, --force
g-wa
Create git worktree
--target-branch, --worktree-name, --stash-changes
g-wl
List all git worktrees
None
g-wr
Remove git worktree
--target-branch, --worktree-name, --all, --force
g-wh
Detect and repair bricked worktree / prune
--target-branch, --worktree-name, --all, --dry-run, --force
g-db
Delete branch
--target-branch
g-dlc
Discard last commit
--force
g-rmf
Stash working directory
--message
g-rto
Reset to remote branch
None
g-cb
Show current branch
None
g-s
Show git status
None
g-diff
Compare branches
--source-branch, --target-branch, --full, --files-only

Features

Feature
Title
Description
g-co
Checkout Branch
Checkout to a branch with optional stash, automatically handles local and remote branches.
g-pull
Pull Changes
Pull changes from a remote branch. If no branch is specified, it pulls for the current branch.
g-push
Push Changes
Push changes to a remote branch, with optional force flag for overwriting remote history.
g-wa
Create Worktree
Create a new git worktree with automatic repository restructuring. Organizes your repo into main/ and worktrees/ directories for better branch isolation.
g-wl
List Worktrees
List all active worktrees along with their branch names in an aligned table. Automatically prunes stale entries whose directories no longer exist.
g-wr
Remove Worktree
Remove a git worktree by branch or directory name, prune stale worktree records, or remove all worktrees except main using --all.
g-wh
Heal Worktree
Detect and repair bricked worktrees: fixes broken submodule gitdirs, clears stale index.lock files, and prunes orphaned worktree registrations.
g-db
Delete Branch
Delete a branch locally and optionally push the deletion to remote.
g-dlc
Discard Commit
Discard the last commit with optional force mode to hard reset.
g-rmf
Stash Changes
Stash all changes in working directory with a timestamped message.
g-rto
Reset to Remote
Reset working directory hard to the latest remote branch, stashing changes first.
g-cb
Current Branch
Display the current git branch name.
g-s
Git Status
Show the output of git status with color formatting.
g-diff
Compare Branches
Compare and show differences between two branches.

Installation

Install gitsy globally using npm. You'll also need to install the required dependencies (git, figlet, lolcat) for your platform:

bash
# Install globally via npm
npm install -g gitsy

# Install dependencies (required)
# macOS
brew install git figlet lolcat

# Ubuntu/Debian
sudo apt-get install git figlet lolcat

# Fedora/RHEL
sudo dnf install git figlet lolcat

# Verify installation
g-s --help

Once installed, all commands (g-s, g-co, g-pull, etc.) will be available globally in your terminal.

Commands

Each script corresponds to a Git-related utility. Below is a comprehensive guide on all available commands.

Checkout Branch (g-co)

Checkout to a branch, with optional stash.

bash
g-co - attempt to checkout to branch

g-co [options]

options:
-h, --help                                                          show brief help
--target-branch BRANCH, --target-branch=BRANCH, -t=BRANCH, -t BRANCH   specify the target branch
--stash-changes                                                     stash changes before proceeding

Usage examples:

bash
# Checkout to a branch
g-co -t feature/xyz

# With stash
g-co -t main --stash-changes

The command will automatically:

  • Check if the branch exists locally
  • Search for the branch on remote if not found locally
  • Prompt to create a new branch if it doesn't exist
  • Stash changes if --stash-changes flag is provided

Pull Changes (g-pull)

Pull changes from a remote branch.

bash
g-pull - pull changes from remote branch

g-pull [options]

options:
-h, --help                                                             show brief help
--target-branch BRANCH, --target-branch=BRANCH, -t=BRANCH, -t BRANCH   specify the target branch
--stash-changes                                                        stash changes before proceeding
-f, --fetch                                                            fetch changes before pulling

Usage examples:

bash
# Pull current branch
g-pull

# Pull specific branch with fetch
g-pull -t develop -f

The command will automatically:

  • Use current branch if no branch is specified
  • Fetch changes from remote if -f/--fetch flag is provided
  • Pull and merge changes from the target branch

Push Changes (g-push)

Push changes to a remote branch, optionally with force.

bash
g-push - push changes to remote branch

g-push [options]

options:
-h, --help                                                             show brief help
--target-branch BRANCH, --target-branch=BRANCH, -t=BRANCH, -t BRANCH   specify the target branch
--stash-changes                                                        stash changes before proceeding
--force                                                                force push changes to the target branch

Usage examples:

bash
# Push current branch
g-push

# Force push
g-push --force

Warning: Using --force will overwrite remote history. This can cause data loss for collaborators who have already pulled the branch. Only use force push when you're certain it's safe.

The command will automatically:

  • Use current branch if no branch is specified
  • Push changes to the remote repository
  • Force push if --force flag is provided (use with caution)

Create Git Worktree (g-wa)

Create a new git worktree with intelligent repository restructuring. On first use, automatically reorganizes your repository to support multiple worktrees. New branches are created from your current branch, preserving your branch context.

bash
g-wa - create git worktree for branch

g-wa [options]

options:
-h, --help                                                             show brief help
--target-branch BRANCH, --target-branch=BRANCH, -t=BRANCH, -t BRANCH   specify the target branch
--worktree-name NAME, --worktree-name=NAME                             specify custom worktree directory name
--stash-changes                                                        stash changes before proceeding

Usage examples:

bash
# Create worktree for branch (creates ../worktrees/feature_new_feature)
# If you're on develop, the new branch will be cut from develop
g-wa -t feature/new-feature

# With custom directory name (creates ../worktrees/my-custom-name)
g-wa -t feature/new-feature --worktree-name my-custom-name

# With stash (creates ../worktrees/develop)
g-wa -t develop --stash-changes

Repository Restructuring: On first use, g-wa will automatically reorganize your repository:

  • Moves your repository into a main/ subdirectory
  • Creates a worktrees/ directory for feature branches
  • Provides step-by-step feedback throughout the process
  • Requires confirmation before making any changes

Final structure:

text
your-repo/
├── main/           # Default branch (main/master)
└── worktrees/      # Feature branch worktrees
    ├── feature_1/
    ├── feature_2/
    └── bugfix_abc/

The command will automatically:

  • Repository restructuring (first time only):
    • Detect if restructuring is needed
    • Move repository contents to main/ subdirectory
    • Create worktrees/ directory structure
    • Checkout default branch in main directory
    • Create worktree for your original branch (if not on default branch)
    • Navigate to original branch worktree to preserve context
  • Worktree creation:
    • Check if worktree already exists for the branch
    • Use custom directory name if --worktree-name is specified, otherwise sanitize branch name (lowercase, replace special chars with _)
    • Convert to absolute path for clarity (e.g. /Users/you/projects/your-repo/worktrees/feature_name)
    • Truncate long names to 30 characters with ".." suffix (e.g. feature/this-is-a-very-long-branch-name → feature_this_is_a_very_long_br..)
    • Check if branch exists locally or remotely
    • Prompt to create new branch if it doesn't exist
    • Automatically push new branches to remote
  • Safety features:
    • New branches are created from your current branch (preserves branch context)
    • Prevents duplicate worktrees
    • Optional stashing with --stash-changes flag
    • Custom directory naming with --worktree-name flag
    • Requires confirmation before restructuring or creating worktrees
    • Clear error messages with actionable guidance

Branch Context: When creating a new branch, it will be cut from your current branch. For example, if you're on develop and run g-wa -t feature/new, the new branch will be created from develop, not from main. This ensures your new branch inherits the correct context.

List Git Worktrees (g-wl)

List all active git worktrees along with their checked out branch names in an aligned table.

bash
g-wl - list all git worktrees with their branches

g-wl [options]

options:
-h, --help          show brief help

Usage examples:

bash
# List all worktrees with their branch names
g-wl

The command will automatically:

  • Automatically prune stale worktree records whose directories were deleted on disk
  • Display directory names, branch names, and detached HEAD states in a formatted table
  • Show the total count of active worktrees

Remove Git Worktree (g-wr)

Remove a git worktree by branch name or worktree directory name, prune stale worktree registrations, or remove all worktrees except main with --all.

bash
g-wr - remove a git worktree for a specified branch or name

g-wr [options]

options:
-h, --help                                                             show brief help
--target-branch BRANCH, --target-branch=BRANCH, -t=BRANCH, -t BRANCH   specify the target branch
--worktree-name NAME, --worktree-name=NAME, -w=NAME, -w NAME           specify the worktree directory name
-a, --all                                                              remove all worktrees except for main
-s, --stash-changes                                                    stash changes before proceeding
-f, --force                                                            skip all confirmation prompts (assume yes)

Usage examples:

bash
# Remove by branch name
g-wr -t feature/old-feature

# Remove by sanitized worktree directory name
g-wr -w feature_old_feature

# Remove all worktrees except main
g-wr --all

# Remove all worktrees with auto-confirm
g-wr -a -f

The command will automatically:

  • Search for the worktree in the worktrees directory or Git's worktree records
  • Support removing all worktrees except main with -a/--all
  • Check for uncommitted changes in the worktree before removal
  • Prompt for confirmation before removal (skip with -f/--force)
  • Safely navigate your shell to main if invoked from inside a removed worktree
  • Automatically prune dead registrations from Git if the directory was deleted manually

Heal Git Worktree (g-wh)

Detect and repair bricked git worktrees, broken submodule gitdirs, stale index.lock files, and orphaned worktree registrations.

bash
g-wh - detect and repair a bricked git worktree

g-wh [options]

options:
-h, --help                                                             show brief help
--target-branch BRANCH, --target-branch=BRANCH, -t=BRANCH, -t BRANCH   heal the worktree checked out at BRANCH
--worktree-name NAME, --worktree-name=NAME, -w=NAME, -w NAME           heal the worktree directory named NAME
-a, --all                                                              heal every worktree
--dry-run                                                              report problems without fixing them
-f, --force                                                            skip all confirmation prompts (assume yes)

With no options, heals the worktree at the current directory.

Usage examples:

bash
# Heal current worktree (repairs submodules, stale locks, and prunes dead records in main)
g-wh

# Heal all worktrees across the repository
g-wh --all

# Heal or prune a specific worktree by branch or directory name
g-wh -t feature/broken-branch
g-wh -w broken_worktree

# Preview repairs and prunes without making changes
g-wh --all --dry-run

# Skip confirmation prompts
g-wh -a -f

Targeted Failure Modes:

  • Broken submodule gitdirs: When submodule setup is interrupted mid-operation, incomplete gitdirs cause fatal: not a git repository errors. g-wh removes incomplete gitdirs and re-runs submodule update.
  • Stale index.lock files: Interrupted git processes leave lock files preventing further git actions.
  • Stale / prunable worktrees: When worktree directories are deleted manually without g-wr, Git retains orphaned metadata that prevents re-checking out branches. g-wh detects these and cleanly prunes them.

The command will automatically:

  • Heal the current worktree directory when run with no options
  • When run in main or with -a/--all, detect and offer to prune all stale worktrees in the repo
  • Target individual worktrees by branch (-t) or directory name (-w)
  • Preview detected issues and proposed fixes with --dry-run
  • Skip confirmation prompts with -f/--force

Delete Branch (g-db)

Delete a branch locally and optionally push the deletion to remote.

bash
g-db - delete a branch locally and optionally on remote

g-db [options]

options:
-h, --help                                                             show brief help
--target-branch BRANCH, --target-branch=BRANCH, -t=BRANCH, -t BRANCH   specify the branch to delete

Usage examples:

bash
# Delete branch (prompts for remote deletion)
g-db -t feature/completed

The command will automatically:

  • Prompt for confirmation before deleting the branch
  • Check if the branch exists locally
  • Delete the local branch (requires branch to be fully merged)
  • Prompt to delete the branch on remote if it exists

Discard Last Commit (g-dlc)

Discard the last commit with optional force mode.

bash
g-dlc - discard the last commit

g-dlc [options]

options:
-h, --help      show brief help
-f, --force     force discard without checking uncommitted changes

Usage examples:

bash
# Discard last commit (soft reset)
g-dlc

# Force discard (hard reset)
g-dlc --force

Warning: Using --force performs a hard reset, permanently discarding all uncommitted changes in your working directory. This action cannot be undone.

The command will automatically:

  • Prompt for confirmation before discarding
  • Check for uncommitted changes (unless --force is used)
  • Perform soft reset (keeps changes) or hard reset (discards changes) based on --force flag

Stash Working Directory (g-rmf)

Clear your working directory by stashing all changes with a timestamped message.

bash
g-rmf - clear your working directory by stashing changes

g-rmf [options]

options:
-h, --help                                                  show brief help
--message MESSAGE, --message=MESSAGE, -m=MESSAGE, -m MESSAGE   specify custom message for stash

Usage examples:

bash
# Stash with auto-generated message
g-rmf

# Stash with custom message
g-rmf -m "WIP: refactoring"

The command will automatically:

  • Create a timestamped stash message if none is provided
  • Stash all uncommitted changes (staged and unstaged)
  • Clear your working directory

Reset To Remote Branch (g-rto)

Reset your working directory hard to the latest remote branch, stashing changes beforehand.

bash
g-rto - reset to remote branch

g-rto [options]

options:
-h, --help          show brief help

Usage examples:

bash
# Reset current branch to remote
g-rto

The command will automatically:

  • Stash any uncommitted changes
  • Fetch the latest changes from remote
  • Perform a hard reset to the remote branch
  • Pull the latest changes (⚠️ this is destructive, stashes changes first)

Current Branch (g-cb)

Display the current git branch name.

bash
g-cb - show current branch name

g-cb [options]

options:
-h, --help          show brief help

Usage examples:

bash
# Show current branch (copies to clipboard)
g-cb

The command will automatically:

  • Fetch the current branch name
  • Display the branch name
  • Copy the branch name to your clipboard

Git Status (g-s)

Show the output of git status.

bash
g-s - show git status

g-s [options]

options:
-h, --help          show brief help

Usage examples:

bash
# Show git status
g-s

The command will automatically:

  • Fetch the current branch name
  • Display git status with color formatting
  • Show staged, unstaged, and untracked files

Compare Branches (g-diff)

Compare and show differences between two branches.

bash
g-diff - compare changes between two git branches

g-diff [options]

options:
-h, --help                                                             show brief help
--target-branch BRANCH, --target-branch=BRANCH, -t=BRANCH, -t BRANCH   specify the target branch
--source-branch BRANCH, --source-branch=BRANCH, -s=BRANCH, -s BRANCH   specify the source branch (defaults to current branch)
-f, --full                                                             show full diff and copy to clipboard
--files-only                                                           show only file names (no stats, no clipboard)

Usage examples:

bash
# Compare current branch with target (shows stats, copies stats to clipboard)
g-diff -t main

# Compare two branches
g-diff -s feature/a -t feature/b

# Show only file names (no stats, no clipboard)
g-diff -t main --files-only

# Full diff (copies formatted diff to clipboard)
g-diff -t main --full

The command will automatically:

  • Use current branch as source if not specified
  • Fetch the latest changes for the target branch

Default mode (no flags):

  • Show a stat summary of changes (files changed, insertions, deletions)
  • Copy stats to clipboard

Example clipboard content:

text
src/components/Button.tsx    | 23 ++++++---------
src/utils/helper.ts         |  4 ++--
src/pages/index.tsx         | 15 +++++++++++
3 files changed, 28 insertions(+), 13 deletions(-)

With --files-only:

  • Show only file names without stats
  • No clipboard copying

Example output:

text
src/components/Button.tsx
src/utils/helper.ts
src/pages/index.tsx

With --full:

  • Display the complete diff output with all changes
  • Copy the formatted diff to clipboard (full diff content with color codes stripped)

Example clipboard content:

text
file: src/components/Button.tsx
stats: +15 -8
changes:

   @@ -10,7 +10,9 @@ export function Button() {
   -  const handleClick = () => {
   -    console.log('clicked');
   -  };
   +  const handleClick = useCallback(() => {
   +    console.log('Button clicked');
   +    onAction();
   +  }, [onAction]);

file: src/utils/helper.ts
stats: +3 -1
changes:

   @@ -5,7 +5,9 @@ export function formatDate() {
   -  return new Date().toISOString();
   +  return new Date().toLocaleString('en-US', {
   +    dateStyle: 'medium'
   +  });

Contributing

Contributions are welcome! Please fork the repository and submit pull requests. For bugs or feature requests, open an issue on the repository.

View source code, report issues, and contribute

License

This project is licensed under the MIT License.

About

Author: Santhosh Siva
GitHub: https://github.com/san-siva