https://github.com/lugassawan/rimba
Git worktree manager CLI — automate branch naming, dependency sharing, hooks, and parallel development workflows
https://github.com/lugassawan/rimba
branch-management cli developer-productivity developer-tools git git-worktree git-worktrees go golang parallel-development workflow-automation worktree
Last synced: 9 days ago
JSON representation
Git worktree manager CLI — automate branch naming, dependency sharing, hooks, and parallel development workflows
- Host: GitHub
- URL: https://github.com/lugassawan/rimba
- Owner: lugassawan
- License: mit
- Created: 2026-02-07T18:44:09.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-06-10T10:42:17.000Z (12 days ago)
- Last Synced: 2026-06-10T11:05:00.864Z (12 days ago)
- Topics: branch-management, cli, developer-productivity, developer-tools, git, git-worktree, git-worktrees, go, golang, parallel-development, workflow-automation, worktree
- Language: Go
- Size: 1010 KB
- Stars: 2
- Watchers: 0
- Forks: 5
- Open Issues: 29
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
rimba
A CLI tool to create, sync, merge, and organize git worktrees — so you can work on multiple branches in parallel without the hassle.
**rimba** automates the full git worktree lifecycle — branch naming, file copying, dependency sharing, post-create hooks, and cleanup — so you can develop across multiple branches simultaneously with zero friction.
---
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Verifying releases](#verifying-releases)
- [Quick Start](#quick-start)
- [Commands](#commands)
- [Configuration](#configuration)
- [Trust model](#trust-model)
- [Troubleshooting](#troubleshooting)
- [Contributing](CONTRIBUTING.md)
- [License](#license)
## Features
🌿 **Core Workflow**
- **Automatic branch naming** — fixed prefix types (`feature/`, `bugfix/`, `hotfix/`, `docs/`, `test/`, `chore/`) selected per task via flags
- **File & directory copying** — auto-copies `.env`, `.env.local`, `.envrc`, `.tool-versions` and other files or directories (e.g. `.vscode/`) into new worktrees
- **Duplicate worktrees** — copy an existing worktree with auto-suffixed or custom name
- **Local merge** — merge worktree branches into main or other worktrees with auto-cleanup
- **Sync worktrees** — rebase or merge onto the latest main branch, with bulk sync support
- **Monorepo support** — service-scoped worktrees with auto-detected 3-segment branch naming (`service/prefix/task`)
🔧 **Automation**
- **Shared dependencies** — auto-detect lockfiles and clone dependency directories using copy-on-write
- **Post-create hooks** — run shell commands after worktree creation (e.g. `./gradlew build`)
- **Auto-cleanup hook** — post-merge Git hook that cleans merged worktrees after `git pull`
- **Stale cleanup** — prune stale references or auto-detect and remove merged worktrees
🖥️ **Developer Experience**
- **Status dashboard** — colored tabular view with dirty state, ahead/behind counts, and filtering
- **Pre-execution hints** — shows available flags before long-running commands, auto-filtered and suppressible
- **Worktree navigation** — open worktrees or run commands inside them via `open`
- **Shell completions** — bash, zsh, fish, and PowerShell
- **Cross-platform** — Linux, macOS, and Windows (amd64/arm64)
## Installation
### Quick install (Linux/macOS)
```sh
curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/install.sh | bash
```
### Go install
```sh
go install github.com/lugassawan/rimba@latest
```
### Build from source
```sh
git clone https://github.com/lugassawan/rimba.git
cd rimba
make build
# Binary is at ./bin/rimba
```
### Verifying releases
Each release publishes a `checksums.txt` signed with [cosign](https://github.com/sigstore/cosign) keyless signing (Sigstore OIDC via GitHub Actions). To verify a downloaded checksum file:
```sh
cosign verify-blob \
--certificate checksums.txt.pem \
--signature checksums.txt.sig \
--certificate-identity-regexp 'https://github.com/lugassawan/rimba/.github/workflows/release.yml@refs/tags/v.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
checksums.txt
```
Each release archive also ships a companion `*.sbom.json` (SPDX format) on the GitHub Release page.
## Quick Start
```sh
# Initialize rimba in your repo
rimba init
# Create a worktree for a task
rimba add my-feature
# List all worktrees with status (colored output)
rimba list
# Remove a worktree and its branch when done
rimba remove my-feature
```
## Commands
| Command | Description |
|---------|-------------|
| `rimba init` | Initialize rimba in the current repo; with `--agents` also installs team agent files, `--agents --local` for personal agent files, `-g`/`--global` for user-level installation, all registering the MCP server |
| `rimba add ` | Create a new worktree with auto-prefixed branch (`service/task` for monorepos), or `pr:` to create one from a GitHub PR |
| `rimba remove ` | Remove a worktree and delete its branch |
| `rimba rename ` | Rename a worktree's task, branch, and directory |
| `rimba duplicate ` | Create a copy of an existing worktree |
| `rimba archive ` | Archive a worktree (remove directory, keep branch) |
| `rimba restore ` | Restore an archived worktree from its preserved branch |
| `rimba list` | List worktrees (compact by default; `--full` for all columns) |
| `rimba status` | Show worktree dashboard; `--detail` adds disk size, 7-day commit velocity, and disk-footprint summary |
| `rimba log` | Show last commit from each worktree, sorted by recency |
| `rimba open ` | Open a worktree or run a command inside it |
| `rimba merge ` | Merge a worktree branch into main or another worktree |
| `rimba sync ` | Rebase or merge a worktree onto the latest main |
| `rimba merge-plan` | Recommend optimal merge order to minimize conflicts |
| `rimba conflict-check` | Detect file overlaps between worktree branches |
| `rimba exec ` | Run a shell command across worktrees |
| `rimba hook install` | Install post-merge and pre-commit hooks |
| `rimba hook uninstall` | Remove the rimba hooks |
| `rimba hook status` | Show whether the rimba hooks are installed |
| `rimba deps status` | Show detected dependency modules for all worktrees |
| `rimba deps install ` | Detect and install dependencies for a worktree |
| `rimba clean` | Prune stale references or remove merged/stale worktrees |
| `rimba update` | Check for updates and replace the binary in place; reminds you to refresh agent files after a successful update |
| `rimba version` | Print version, commit, build date, and platform info (os/arch/go) |
| `rimba mcp` | Start MCP server for AI tool integration |
| `rimba completion` | Generate shell completion scripts (bash, zsh, fish, powershell) |
> See [docs/commands.md](docs/commands.md) for the full reference with all flags, examples, and notes.
## Configuration
`rimba init` creates a `.rimba/` directory with team-shared and personal config files:
```toml
copy_files = ['.env', '.env.local', '.envrc', '.tool-versions', '.vscode']
post_create = ['./gradlew build']
[open]
ide = 'code .'
agent = 'claude'
```
> See [docs/configuration.md](docs/configuration.md) for the full field reference, dependency management, and environment variables.
Running `rimba init --agents` or `rimba init -g` additionally creates or patches MCP server config files in client tools (`.mcp.json`, `.cursor/mcp.json`, `~/.claude.json`, and others). See [docs/configuration.md#mcp-server-registration](docs/configuration.md#mcp-server-registration) for the full list of patched files and entry format.
## Trust model
**`.rimba/settings.toml` is committed and team-shared.** The following fields execute shell commands verbatim via `sh -c`:
- `post_create` — runs after a worktree is created (e.g. `rimba add`, `rimba duplicate`, `rimba restore`)
- `post_rename` — runs after a worktree is renamed (`rimba rename`)
- `deps.modules[].install` — runs when installing dependencies into a worktree
### Consent gate
rimba will **not** execute committed shell commands until you have explicitly approved them. On the first run in a new clone (or whenever the command set changes), rimba prints the commands and prompts for consent:
```
This repo's .rimba/settings.toml will run shell commands that have not been approved:
pnpm install
./scripts/setup.sh
Run these commands? [y/N]
```
Approval is stored locally in `.rimba/trust.local.toml` (covered by the `.rimba/*.local.toml` gitignore glob — each user consents independently). The approval is keyed by a hash of the command set; changing any command re-arms the gate.
**Pre-approve without prompting** (e.g. for `rimba trust` after reviewing settings, or in CI):
```sh
rimba trust # review and approve interactively
rimba trust --yes # approve without prompt (non-interactive)
rimba trust --show # inspect commands and current approval status
```
**CI / non-interactive environments:** pass `--yes` or set `RIMBA_TRUST_YES=1`:
```sh
RIMBA_TRUST_YES=1 rimba add my-task
rimba add my-task --yes
```
As a defense-in-depth measure, the `copy_files` entries and `deps.modules[].lockfile` paths are validated to stay within the worktree directory — paths that escape via `..` are rejected with an error. Note that `worktree_dir` is intentionally not subject to this constraint, because its default value (`../-worktrees`) is itself a `../`-relative path.
## Global flags
| Flag | Description |
|------|-------------|
| `--json` | Output in JSON (where supported: `list`, `status`, `deps status`, `conflict-check`, `exec`) |
| `--no-color` | Disable colored output (also respects `NO_COLOR`) |
| `--debug` | Log git commands and timings to stderr (also respects `RIMBA_DEBUG=1`) |
## Troubleshooting
Hit an error? rimba prints an actionable `To fix:` hint with most failures. Common errors — trust-gate
prompts, `exec` scope, dirty-worktree sync blocks, init/config issues — are documented with cause and
fix in the troubleshooting guide.
> See [docs/troubleshooting.md](docs/troubleshooting.md) for the full troubleshooting reference.
Pass `--debug` to any command (or set `RIMBA_DEBUG=1`) to log git commands and their timings to stderr:
```sh
rimba list --debug
```
## License
[MIT](LICENSE)