gitmedaddy (gmd)

Note: The package names I wanted were either taken or too similar to an existing or well-known package, which npm does not allow. That is why I used this name.

Philosophy

I wanted a better way to manage GitHub branches locally when every PR should have a single goal and AI (or other tools) need to work on different goals in parallel. (This does not replace Git or Git worktrees; it is built entirely on top of them.)

gitmedaddy (short alias: gmd) is a Git worktree-based CLI for running branch workflows in parallel. It keeps Git as the source of truth while organizing each branch as its own local workspace folder.

Why use it

Git worktrees already let you check out more than one branch at a time; the hard part is keeping branches organized, named, and discoverable as your list grows. gmd is a thin layer on top of worktrees: one folder per branch, consistent layout, and project metadata so PR-sized goals stay easy to find and switch between.

• Manage many branch workspaces without hand-maintaining worktree paths and bases
• Reduce mental overhead versus ad hoc git worktree workflows
• Keep one workspace per task/goal with local state tracked in state/branches.json
• Stay fully compatible with normal Git commands

Installation

From the registry (global)

pnpm

pnpm add -g gitmedaddy

bun

bun add -g gitmedaddy

Core Concepts

• The first workspace is a normal Git clone (or your existing repo root); extra branches are Git worktrees that share the same object database.
• Workspace metadata lives in state/branches.json at the project root. This includes the default base branch, visible workspaces, saved goals, and default CLI behavior (json / interactive). The CLI discovers a gmd project by walking up until it finds that file.

Example layout:

my-project/
├── state/
│   └── branches.json
├── main/
└── feat-create-footer/

Quick Start

Option A: Start from a remote repository

gmd clone https://github.com/OWNER/PROJECT_NAME.git

During setup, you will choose a default base branch (for example main). The initial CLI defaults are also saved in state/branches.json.

Option B: Initialize inside an existing local Git repo

cd your-existing-repo
gmd foundadaddy

This sets up state/branches.json and your first displayed workspace (or reuses the repo root when it already matches your default base branch).

Create a new branch workspace

gmd new feat/create-footer

gmd new prompts for:

• Workspace folder name (defaults to a branch-based slug)
• Goal (optional; stored in workspace metadata)

Use a custom base branch when needed:

gmd new feat/create-footer --from staging

Change the saved project defaults used by gmd new and related commands without editing state/branches.json by hand:

gmd update

You can also override behavior for a single command:

gmd --json --no-interactive show feat/create-footer
gmd --no-json pull --all

Typical Workflow

# 1) Create/show branch workspaces
gmd new feat/login
gmd show bugfix/session-timeout

# 2) Work inside each workspace folder with normal git commands
cd feat-login
git status
git add .
git commit -m "Implement login form"

# 3) Pull latest updates
gmd pull --all

# 4) Merge base updates into your current workspace
gmd merge

# 5) Create PR from current workspace branch
gmd pr --draft

Command Reference

clone

gmd clone <repo-url>

Clone a repository into a gmd-managed project: a default branch folder (full clone) plus state/branches.json.

foundadaddy

gmd foundadaddy

Initialize gmd in an existing Git repository.

update

gmd update
gmd update --base staging

Fetch from origin, then update saved project defaults in state/branches.json:

• default base branch
• default output mode (json or text)
• default command mode (interactive or non-interactive)

new (n)

gmd new <branch-name>
gmd new <branch-name> --from <base-branch>

Create and display a new workspace branch (or attach to existing remote branch if it already exists).

show (s)

gmd show <branch-name>

Display an existing branch (local or remote) as a workspace folder.

hide (h)

gmd hide <branch-name>

Hide a displayed workspace by removing its local worktree folder.

clean (c)

gmd clean
gmd clean --from <branch-name>

Hide all displayed workspaces except one branch to keep visible.

pull

gmd pull
gmd pull --all

Pull latest changes for the current displayed workspace, or all displayed workspaces.

merge

gmd merge
gmd merge --from <source-branch> --to <target-branch>

Merge source branch changes into a target displayed workspace branch.

setgoal

gmd setgoal "<goal text>"
gmd setgoal "<goal text>" <branch-name>

Set/update goal text for a displayed workspace.

showgoal

gmd showgoal
gmd showgoal <branch-name>

Show saved goal text for a displayed workspace.

pr

gmd pr
gmd pr --base <branch-name> --title "<title>"
gmd pr --draft

Create a GitHub pull request for the current workspace branch. This command pushes with upstream (git push -u origin <branch>) before opening the PR.

Notes and Requirements

• Requires Git installed and available in PATH.
• gmd pr requires GitHub CLI (gh) installed and authenticated.
• Run commands from inside a gmd project/workspace for non-clone operations.
• Use --json / --no-json to override output format for a single command.
• Use --interactive / --no-interactive to override prompting for a single command.
• Saved defaults live in state/branches.json and can be updated with gmd update.

Roadmap

1. Better integration for AI info streaming.

foundadaddy

gmd foundadaddy

Initialize gmd in an existing Git repository and create the first workspace from your selected default base branch.

cheatondaddy

gmd cheatondaddy

Reverse gmd setup for the current project:

• removes all tracked workspace folders
• restores the repository root as the main working tree on your default base branch
• removes state/ metadata so the project behaves like a normal Git repo again

Under the Hood

gmd is built on Git branches + Git worktrees. Your repositories remain standard Git repositories; gmd adds local orchestration for parallel branch workflows.