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, --stash-changes
g-wr
Remove git worktree
--target-branch, --worktree-name
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-wr
Remove Worktree
Remove a git worktree by branch name or worktree directory name.
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
--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 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
    • 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
    • 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.

Remove Git Worktree (g-wr)

Remove a git worktree by branch name or worktree directory name.

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

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

The command will automatically:

  • Search for the worktree in the worktrees directory
  • Check for uncommitted changes in the worktree
  • Prompt for confirmation if uncommitted changes exist
  • Remove the worktree directory and prune git records

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