git-workforest

🌲 git-workforest

Manage git worktrees with a simple, predictable folder structure.
Like git worktree, but handles paths for you.

Quickstart | Commands | Configuration

Quickstart

Install:

npm install -g @dwmkerr/git-workforest

# Run init from anywhere — it detects your context and suggests what to do.
git forest init

# Migrate an existing repo to forest layout.
cd ~/repos/effective-shell
git forest migrate
# ~/repos/effective-shell/ is now:
#   .workforest.yaml
#   main/                   <- you are here

# Or clone a repo into a new forest.
git forest clone dwmkerr/effective-shell
# ~/repos/github/dwmkerr/effective-shell/
#   .workforest.yaml
#   main/

# List all trees.
git forest list

# Add a tree for a branch.
git forest add fix-typo
# ~/repos/github/dwmkerr/effective-shell/
#   .workforest.yaml
#   main/
#   fix-typo/               <- new tree

# Remove a tree.
git forest remove fix-typo

Commands mirror git worktree semantics — list, add, remove — but workforest handles paths automatically. You can also use the aliases git-workforest or workforest.

Worktree folder structure

Each branch gets its own folder inside the forest:

# Main location for your repos (see Configuration to customise)
~/repos/github/dwmkerr/effective-shell/
  .workforest.yaml        # config file
  main/                   # default branch (worktree)
  fix/typo/               # feature branch (worktree)
  big-refactor/           # another branch

Branches are created as git worktrees by default, so they share the same .git data. See fatTrees if you need full clones¹.

Global flags

Flag	Description
-v, --verbose	Print each git command and its output (dimmed) — useful for diagnosing unexpected behaviour

git forest -v add fix-typo
# $ git worktree add ../fix-typo fix-typo
# added fix-typo.

You can also enable verbose mode permanently via the config file (verbose: true).

Commands

git forest list

List all trees in the forest. Highlights the active branch when run from inside a tree.

# like: git worktree list
git forest list
# on branch main in dwmkerr/effective-shell
#
# trees:
# * main            ./main
# + feat/dark-mode  ./feat/dark-mode
# + fix-typo        ./fix-typo

git forest add <branch>

Add a tree for a branch — finds an existing tree or creates a new worktree.

# like: git worktree add ../big-refactor big-refactor
git forest add big-refactor
# added big-refactor.
#
# effective-shell/
#   main/
#   fix-typo/
#   big-refactor/       <- new tree

git forest remove <branch>

Remove a tree from the forest. Refuses if the tree has uncommitted changes (use -f to force).

# like: git worktree remove ../fix-typo
git forest remove fix-typo
# removed fix-typo.
#
# effective-shell/
#   main/
#   big-refactor/

# force remove even if dirty
git forest remove -f big-refactor

git forest clone <org/repo>

Clone a GitHub repo into a new forest. Shows the proposed location and asks for confirmation. Use -y to skip the prompt.

git forest clone dwmkerr/effective-shell
# clone dwmkerr/effective-shell to ~/repos/github/dwmkerr/effective-shell? (Y/n)
#
# effective-shell/
#   .workforest.yaml
#   main/

git forest migrate

Migrate an existing repo to forest layout. Shows a before/after preview with your real local branches, asks for confirmation, then moves your repo contents into a branch subfolder.

git forest init

Detect your context and do the right thing — show trees if already a forest, offer to migrate if inside a repo, or suggest cloning if empty.

Configuration

Customise behaviour in ~/.workforest.yaml: