Skip to content

Getting Started

Installation

Install via Homebrew

brew install daileyo/gws/git-workspace

Build from Source

# Clone the repository
git clone https://github.com/daileyo/gws.git
cd gws

# Build the binary
make build

# The binary will be in ./build/git-workspace
# Optionally, install to your PATH
make install

Shell Integration

Before using the gws shorthand, set up shell integration. Add these lines to your ~/.zshrc (or ~/.bashrc):

export PATH="$HOME/.local/bin:$PATH"
eval "$(git-workspace shell-init zsh)"   # or: shell-init bash

This gives you the gws function with tab completion. See Shell Integration for full details.

Quick Start

1. Initialize a Workspace

Scan a directory for git repositories:

# Initialize in current directory
gws init

# Initialize in a specific directory
gws init ~/projects

# Initialize with absolute path
gws init /path/to/your/workspace

This command will:

  • Recursively scan the directory for git repositories
  • Extract repository metadata (name, path, remote URL)
  • Detect repository type and user configuration
  • Save the configuration to ~/.gws/config.json

2. List Your Repositories

Once initialized, run gws with no arguments to see your repositories:

gws

Output (compact multi-column names):

Found 15 repositories:

my-project       work-api         client-site      my-api
frontend-app     docs-site        infra-tools      backend-svc
mobile-app       shared-libs      auth-service     data-pipeline
ml-models        cli-tools        test-harness

3. View Repository Details

Use verbose mode to see more information:

gws list -v

Output:

Found 15 repositories:

NAME              TYPE       VISIBILITY  TAGS              PATH
----------------  ---------  ----------  ----------------  ------------------------------------
my-project        github     private     personal, web     /home/user/projects/my-project
work-api          gitlab     private     work              /home/user/projects/work-api
client-site       bitbucket  unknown     client, archived  /home/user/projects/client-site

4. Check Version

gws --version

Output:

git-workspace version dev
  commit: abc1234
  built:  2025-12-25T21:00:00Z

Next Steps