Manage Git worktrees declaratively with YAML (plan/apply + guardrails) — gion

TL;DR: I built gion, a CLI to manage Git worktrees declaratively.

Write your desired state in gion.yaml, then plan/apply to create/update/cleanup in bulk with guardrails.

It also supports task-scoped workspaces (grouping multiple repos for a monorepo-like workflow) and fast navigation via giongo.

Repo / docs:
https://github.com/tasuku43/gion

---

Why I built this

After I started using AI coding agents more often, I ended up doing more parallel work. That naturally led me to git worktree.

But the more parallel tasks I had, the more I kept asking myself:

• Where should I create the next worktree?
• Navigating across many worktrees is annoying.
• Can I delete this safely? (Or will I accidentally lose local changes?)

There are already tools around worktrees, but I wanted two things in particular:

1) Guardrails during cleanup

I wanted to prevent “I didn’t mean to delete it, but it was deletable anyway.”

2) Task-scoped workspaces

I wanted a “box per task” that can contain one or more worktrees, possibly across multiple repositories, so I can run my coding agent from the workspace root — and then delete the whole box when done.

That’s what gion is.

---

Overview

The core workflow is Create / Move / Cleanup:

• Create: edit gion.yaml manually, or use gion manifest add (interactive) → gion apply (Plan → confirm → Apply)
• Move: use giongo to search and jump (no state changes)
• Cleanup: edit gion.yaml manually, or use gion manifest gc (automatic) / gion manifest rm (interactive) → gion apply (Plan → confirm → Apply)

Tip: gion manifest can be shortened to gion m or gion man.

---

How it works: gion.yaml and the manifest subcommands

The center of gion is gion.yaml.

• gion.yaml is the source of truth (“desired state” / inventory).
• gion manifest ... is an entry point to update that YAML (you can also edit it directly).
• After any update (via command or direct editing), you run gion apply to reconcile the filesystem with the desired state.
• gion apply computes a plan, shows the diff, and then applies it when you confirm.
• By default, gion manifest ... will run gion apply after rewriting gion.yaml. Use --no-apply if you want to update gion.yaml only and apply later.

Terminology: worktree vs workspace

• A Git worktree is a working directory that checks out a branch (or a specific commit).
• A workspace (in gion’s terms) is a task-scoped directory that can contain one or more worktrees — potentially from multiple repos.

A typical layout looks like this:

GION_ROOT/
├─ gion.yaml           # desired state (inventory)
├─ bare/               # shared bare repo store
└─ workspaces/         # task-scoped workspaces
   ├─ PROJ-123/        # workspace_id (task)
   │  ├─ backend/      # worktree (repo: backend)
   │  ├─ frontend/
   │  └─ docs/
   └─ PROJ-456/
      └─ backend/

---

Create: review a plan, then create in bulk

There are two ways to declare “create this workspace”:

• Use gion manifest add, or
• Edit gion.yaml directly

In both cases, you’re declaring a desired state first, and then reconciling with gion apply:
1) compute the plan
2) show the diff
3) apply when you confirm

Four creation modes

gion manifest add supports four entry paths:

• repo
• issue
• review
• preset

The entry point differs, but the destination is the same: everything ends up in gion.yaml as desired state.

issue / review: queue up many, then apply once

If you use issue / review, you’ll need the gh CLI (GitHub-only).
These correspond to --issue / --review.

The intended flow is:

• select multiple Issues / PRs
• add them to gion.yaml
• run gion apply once
• review the plan, then apply

This is great when you want to spin up many review/issue worktrees quickly.

repo: create a single workspace quickly

If you just want the fastest “create one workspace”, repo is the simplest:

• choose a repo
• set a workspace id
• confirm the plan
• apply

preset: group multiple repos under one task workspace (monorepo-like workflow)

A workspace is a “task box”, so it’s common to want something like:

• backend + frontend + docs
• backend + infra
• or any other multi-repo set

With presets, you define the set once, and then reuse it to create workspaces repeatedly.

Direct YAML editing

Direct editing is useful when you want to:

• adjust branch names in bulk
• create/remove multiple workspaces at once
• refactor/reorganize existing definitions

After editing, run:

gion apply

You’ll get a plan showing creates / deletes / updates together, so you can calmly review what will happen before applying.

---

Move: search and jump to a workspace/worktree

Once worktrees start to accumulate, you waste time thinking:

“Where was I working on that?”

For navigation, use giongo (installed alongside gion via Homebrew/mise).

• giongo does not change any state.
• It lists both workspaces and worktrees, and lets you filter and select.
• Select a workspace → jump to the workspace directory
• Select a worktree → jump to that repo’s working directory

Shell integration: make giongo change directories

If you want selection → cd, you need a small shell integration. The README includes options, but the simplest is:

eval "$(giongo init)"

(That prints a function you can paste into ~/.zshrc or ~/.bashrc for permanent setup.)

---

Cleanup: conservative gc, and guarded rm

As worktrees pile up, you eventually pause and ask:

“Is it safe to delete this?”

gion splits cleanup into two commands:

• gion manifest gc: automatic, conservative cleanup
• gion manifest rm: manual selection with guardrails

gion manifest gc: conservative auto-cleanup

gion manifest gc proposes candidates that are highly likely safe to delete.

For example:

• workspaces whose checked-out branches are already merged into the default branch can be reclaimed
• anything ambiguous (uncommitted / unpushed / unreadable state, etc.) is excluded by default
• even “created but no commits” workspaces are excluded so you don’t delete something by accident

In short: gc aims to keep false-positives very low.

gion manifest rm: manual removal, with guardrails

gion manifest rm is for cases where a human decides what to delete.

It supports interactive selection and then a final confirmation. During selection, each workspace gets lightweight tags like:

• [dirty]
• [unpushed]
• [diverged]
• [unknown]

What those mean:

• dirty: working tree has uncommitted changes (including untracked files or conflicts)
• unpushed: your local branch is ahead of upstream (has commits not pushed)
• diverged: local and upstream have both advanced (ahead and behind)
• unknown: cannot be determined (no upstream, detached HEAD, git error, etc.)

When you delete something risky (e.g., dirty), the plan will show a risk summary (e.g., risk: dirty (unstaged=2)) and (for dirty cases) the changed files, so you can sanity-check quickly before you confirm.

Cleanup via direct YAML editing

You can also remove workspaces by editing gion.yaml directly.

Even then, gion apply will:

• clearly show what will be removed in the plan
• ask for a confirmation before destructive changes

So if you get nervous, you can just answer n and stop.

---

Closing

Installation (Homebrew / mise) and full usage examples are in the GitHub README. If you’ve ever felt the pain of worktree sprawl — especially in multi-repo tasks — I’d love for you to try gion and share feedback.

https://github.com/tasuku43/gion