@flxbl-io/gspace NPM

GSpace

Git workspace manager using worktree for isolated development environments.

Overview

GSpace simplifies working with Git worktrees by providing a user-friendly interface to manage multiple workspaces (branches) in separate directories. This makes it easy to work on multiple features or bug fixes simultaneously without having to stash and switch branches.

Features

Workspace Management: Create, remove, and list workspaces
Directory Isolation: Each branch gets its own directory, keeping work separate
Interactive UI: Browse workspaces and commits with a terminal UI
Automatic Navigation: Change directory to newly created workspaces
Commit History: View detailed commit history with an interactive UI
Git Operations: Pull, push, rebase, merge, and sync commands with --all options
Convenient Aliases: Use either gspace or the shorter gsp command

Installation

Option 1: Install from npm (Recommended)

# Install globally from npm
npm install -g @flxbl-io/gspace

Option 2: Install from source

# Clone the repository
git clone https://github.com/flxbl-io/gspace.git

# Install dependencies
cd gspace
npm install

# Build the project
npm run build

# Create a symlink to make gspace available globally
npm link

Shell Integration for Automatic Directory Changing

To enable the automatic directory changing functionality with gspace checkout, add this to your .bashrc or .zshrc:

function gspace() {
  # Get the output from the gspace wrapper
  output=$($(npm config get prefix)/bin/gspace-wrapper "$@")
  
  # Check if there's a CD_DIR variable
  if [[ "$output" == *CD_DIR=* ]]; then
    # Extract the CD_DIR from the output for changing directory
    cd_dir=$(echo "$output" | grep "^CD_DIR=" | sed 's/^CD_DIR=//')
    
    # Change to the directory
    cd "$cd_dir"
    echo "Changed directory to: $cd_dir"
    
    # Display the rest of the output (excluding the CD_DIR line)
    echo "$output" | grep -v "^CD_DIR="
  else
    # Just echo the output
    echo "$output"
  fi
}

The above function extracts the directory path from the wrapper script output and changes to that directory when you run gspace checkout <workspace>.

If you installed from source, replace $(npm config get prefix)/bin/gspace-wrapper with the path to your local gspace-wrapper.sh file:

function gspace() {
  # Get the output from the gspace wrapper
  output=$(/path/to/gspace/gspace-wrapper.sh "$@")
  
  # Check if there's a CD_DIR variable
  if [[ "$output" == *CD_DIR=* ]]; then
    # Extract the CD_DIR from the output for changing directory
    cd_dir=$(echo "$output" | grep "^CD_DIR=" | sed 's/^CD_DIR=//')
    
    # Change to the directory
    cd "$cd_dir"
    echo "Changed directory to: $cd_dir"
    
    # Display the rest of the output (excluding the CD_DIR line)
    echo "$output" | grep -v "^CD_DIR="
  else
    # Just echo the output
    echo "$output"
  fi
}

After adding this function, remember to source your shell configuration file:

source ~/.zshrc  # or ~/.bashrc if using bash

Using the `gsp` Alias

For faster typing, you can use the shorter gsp alias for all commands instead of typing gspace:

# Examples using the shorter alias
gsp checkout feature-branch
gsp status
gsp diff

Both gspace and gsp commands are completely identical - use whichever you prefer!

If you're using the shell integration function, you'll need to create a similar function for the gsp alias:

function gsp() {
  # Simply call the gspace function with the same arguments
  gspace "$@"
}

Add this function to your .bashrc or .zshrc after the gspace() function.

Usage

Basic Commands

# Clone a repository with worktree structure
gspace clone https://github.com/user/repo.git

# Clone a repository to a specific directory
gspace clone https://github.com/user/repo.git my-repo-dir

# Create a new workspace and automatically cd into it
gspace checkout feature/my-feature

# Create a workspace without changing directory
gspace checkout feature/my-feature --no-cd

# List all workspaces
gspace list

# View status of all workspaces
gspace status

# Remove a workspace
gspace remove feature/my-feature

# Open a workspace in your editor
gspace open feature/my-feature

Working with Commits

# View interactive commit history for current workspace
gspace diff

# View commit history for a specific workspace
gspace diff feature/my-feature

# View commit history with only merge commits
gspace log --merges-only

# View all commits (not just branch-specific ones)
gspace log --all

# Create a workspace and view its commits in one command
gspace log feature/new-feature --create

Git Operations

# Pull changes for current workspace
gspace pull

# Pull changes for all workspaces
gspace pull --all

# Push current workspace to remote
gspace push

# Push all workspaces with changes
gspace push --all

# Rebase current workspace on main
gspace rebase

# Rebase all workspaces
gspace rebase --all

# Sync current workspace (pull, rebase, push)
gspace sync

# Sync all workspaces
gspace sync --all

# Merge another workspace into the current workspace
gspace merge feature/other-branch

# Merge with specific options
gspace merge feature/other-branch --squash -m "Merge feature/other-branch into main"

Session Management (requires tmux)

GSpace provides built-in tmux session management to work with multiple workspaces simultaneously. Each workspace is arranged in a split-pane layout, allowing you to view and control multiple workspaces at once.

# Create a session with all workspaces in split panes
gspace session start

# Create a session with a custom name
gspace session start my-project-session

# Create a session without automatically attaching to it
gspace session start --detach

# Create a session and run the same command in all workspaces
gspace session exec "npm install && npm test"

# List all active sessions
gspace session list

# Attach to an existing session
gspace session attach

# Kill a session
gspace session kill

Sessions are organized with workspaces arranged in multiple windows, with up to two panes per window. This provides an efficient layout for working across multiple branches simultaneously. Each pane displays the workspace name at the top for easy identification.

Session Navigation:

Ctrl+b then arrow keys - Move between panes
Ctrl+b then o - Cycle through panes
Ctrl+b then z - Zoom in/out of current pane
Ctrl+b then c - Create new window
Ctrl+b then n/p - Next/previous window
Ctrl+b then d - Detach from session (return to normal terminal)

Tips and Tricks

Use the shorter gsp alias instead of gspace for faster typing (e.g., gsp checkout feature).
Use gspace checkout <workspace> -n to avoid changing directories automatically.
For merge commits, the diff view will show all changes introduced by the merge.
Navigate commit history with 'j'/'k' keys or PgUp/PgDn.
Press 'q' or ESC to exit interactive views.
Use --create option with log or diff to automatically create a workspace if it doesn't exist.
When using gspace merge, you can use --squash to combine all commits from the source branch into a single commit.
For more complex merge scenarios, use --no-commit to merge changes without automatically creating a commit.