baretree

README

[!WARNING] This is an experimental project that is not yet thoroughly tested; use with caution as breaking changes are likely. Bug reports and contributions are welcome.

🪾 baretree

Git repositories, worktrees, and branches, organized.

baretree combines centralized repository management (inspired by ghq) with powerful Git worktree support. Manage all your repositories in one place, keep branches organized, and switch contexts instantly.

Why baretree?

Before

~/projects/
├── my-app/                    # main branch... or was it develop?
├── my-app-feature/            # Which feature branch is this?
├── my-app-auth-backup/        # Forgot to delete after merge
├── my-app-hotfix-20240115/    # Old hotfix, still needed?
└── ...scattered everywhere

After

~/baretree/                              # All repositories organized
├── github.com/
│   └── user/
│       ├── my-app/                      # One repository
│       │   ├── .git/                    # Bare repository
│       │   ├── .shared/                 # Shared across all worktrees (.env, etc.)
│       │   ├── main/                    # worktree ← main branch
│       │   └── feature/
│       │       ├── auth/                # worktree ← feature/auth branch
│       │       └── api/                 # worktree ← feature/api branch
│       └── another-project/
└── gitlab.com/
    └── ...

• All worktrees in one directory - No more scattered clones for each branch
• Shared files across worktrees - .env, node_modules linked automatically
• Instant context switching - Jump between worktrees (bt cd) and repositories (bt go)
• Migrate existing repos instantly - One command converts any repository
• Centralized repository management - All repos in ~/baretree/{host}/{user}/{repo}
• AI Agent ready - Parallel tasks and isolated workspaces for AI coding assistants

🚀 Quick Start

1. Install

# Homebrew (macOS/Linux)
brew install amaya382/tap/baretree

# GitHub Release (download binary)
# Download from https://github.com/amaya382/baretree/releases
# Extract and add to your PATH
# Example for Linux (amd64)
curl -L https://github.com/amaya382/baretree/releases/latest/download/baretree_Linux_x86_64.tar.gz | tar xz
sudo mv bt /usr/local/bin/

2. Shell Integration (required for bt cd)

This is required for bt cd and completion, however, you can skip the manual setup if installed via Homebrew (shell integration is automatically configured).

Note (Homebrew users): After installing via Homebrew, open a new terminal window for shell integration to take effect.

# Bash
echo 'eval "$(bt shell-init bash)"' >> ~/.bashrc && source ~/.bashrc

# Zsh
echo 'eval "$(bt shell-init zsh)"' >> ~/.zshrc && source ~/.zshrc

# Fish
echo 'bt shell-init fish | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish

---

📖 Getting Started

Choose your style: Centralized (recommended) or Standalone.

Option A: Centralized (Recommended)

Manage all repositories in a central location (~/baretree by default).

Migrate existing repositories to baretree managed directory

cd ~/projects/my-existing-repo
bt migrate . --to-managed  # or -m
# Your repo is now baretree-structured and placed under ~/baretree
# Working tree state (staged, unstaged, untracked) is preserved
# Original repository is preserved by default (use --remove-source to delete)
bt go my-existing-repo

Clone a new repository

# Clone to ~/baretree/github.com/user/repo
bt get user/repo  # Defaults to github.com
bt get github.com/user/repo # With domain
bt get git@github.com:user/repo.git # By full URL

Navigate between repositories

bt repos                  # List all repositories
bt go my-repo             # Jump to repository
bt go user/repo           # Jump with more specific path

Work with worktrees

bt add -b feature/auth            # Create feature branch
bt cd feature/auth                # Jump to worktree
bt ls                             # List all worktrees
bt rm feature/auth                # Remove when done
bt unbare main ~/standalone-repo  # Export worktree as standalone repo

Option B: Standalone (without centralized management)

Use baretree for a single project without centralized repository management.

Start fresh

bt init my-project
cd my-project
bt cd @
# Start coding!

Migrate an existing repository in-place

cd ~/projects/my-repo
bt migrate . --in-place
# Your repo is now baretree-structured
# Working tree state (staged, unstaged, untracked) is preserved

Clone to a specific location

bt clone git@github.com:user/repo.git ~/projects/my-project
cd ~/projects/my-project

Work with worktrees

bt add -b feature/auth            # Create feature branch
bt cd feature/auth                # Jump to worktree
bt ls                             # List all worktrees
bt rm feature/auth                # Remove when done
bt unbare main ~/standalone-repo  # Export worktree as standalone repo

---

🔗 Post-create Actions

Automate worktree setup with shared files and commands that run on creation.

Shared Files

Share files like .env or node_modules across all worktrees automatically.

# Add shared files (symlink by default, stored in .shared/ directory)
bt post-create add symlink .env
bt post-create add symlink node_modules

# Use copy instead of symlink for files that need independent copies
bt post-create add copy .vscode/settings.json

# Use --no-managed to source from default branch instead of .shared/
bt post-create add symlink .env --no-managed

Commands

Run commands automatically when creating new worktrees.

# Add commands to run after worktree creation
bt post-create add command "npm install"
bt post-create add command "direnv allow"

Commands are executed in the new worktree directory. Failures are warnings (won't block worktree creation).

More commands

bt post-create list              # Show configured actions
bt post-create apply             # Apply to all worktrees
bt post-create remove .env       # Remove configuration
bt post-create remove "npm install"  # Remove command

---

🤖 AI Agent Integration

baretree's worktree-based structure is ideal for AI coding assistants like Claude Code, Cursor, and GitHub Copilot Workspace. Each worktree provides an isolated workspace.

Agent Rules Template

An example rules file for AI agents is available at examples/rules/git_worktree_with_baretree.md. This template helps AI agents understand the baretree structure and work effectively with worktrees.

Copy to your project's rules directory:

# For Claude Code
cp examples/rules/git_worktree_with_baretree.md .claude/rules/

# For Cursor
cp examples/rules/git_worktree_with_baretree.md .cursor/rules/

---

📚 Command Reference

Worktree Management

Command	Description
bt add <branch>	Add worktree (-b for new branch)
bt list / bt ls	List worktrees
bt remove / bt rm	Remove worktree (--with-branch to delete branch)
bt cd <name>	Switch to worktree (@ for default, - for previous)
bt status	Show repository status
bt repair	Repair worktree/branch name mismatches
bt rename [old] <new>	Rename worktree and branch
bt unbare <wt> <dest>	Convert worktree to standalone repository
bt root	Show repository root directory path

Repository Management (Centralized)

Command	Alias	Description
bt repo get <url>	bt get	Clone to baretree root (centralized-style)
bt repo list	bt repos	List all managed repositories
bt repo cd <name>	bt go	Jump to a repository
bt repo migrate <path> --to-managed	bt migrate	Migrate and move to baretree managed directory
bt repo remove <name>	bt repo rm	Remove a baretree repository
bt repo root		Show baretree root directory
bt repo config		Manage global configuration

Repository Management (Standalone)

Command	Alias	Description
bt repo init [dir]	bt init	Initialize new baretree repository
bt repo clone <url> [dest]	bt clone	Clone to specific location
bt repo migrate <path> -i	bt migrate	Convert existing repo in-place
bt repo migrate <path> -d <dest>	bt migrate	Convert and copy to destination

Post-create Actions

Command	Description
bt post-create add symlink <file>	Add shared file as symlink
bt post-create add copy <file>	Add shared file as copy
bt post-create add command <cmd>	Add command to run on creation
bt post-create remove <source>	Remove action
bt post-create list	List configured actions
bt post-create apply	Apply to existing worktrees

Configuration

Command	Description
bt config export	Export repository config to TOML
bt config import	Import repository config from TOML
bt repo config export	Export global config to TOML
bt repo config import	Import global config from TOML

---

⚙️ Configuration

All configuration is stored in git-config (no extra config files needed).

Baretree Root

Set where repositories are stored (default: ~/baretree):

# Environment variable
export BARETREE_ROOT=~/code

# Or git config
git config --global baretree.root ~/code

[!TIP] Set baretree root to ~/ghq to use baretree alongside ghq. Run bt repo migrate -i . to add worktree support in each repository.

---

📦 Install

Homebrew (macOS/Linux)

brew install amaya382/tap/baretree

GitHub Release (Binary)

Download the latest binary from GitHub Releases:

# Example for Linux (amd64)
curl -L https://github.com/amaya382/baretree/releases/latest/download/baretree_Linux_x86_64.tar.gz | tar xz
sudo mv bt /usr/local/bin/

# Example for macOS (Apple Silicon)
curl -L https://github.com/amaya382/baretree/releases/latest/download/baretree_Darwin_arm64.tar.gz | tar xz
sudo mv bt /usr/local/bin/

[In preparation] Snap (Linux)

sudo snap install baretree --classic

[In preparation] Scoop (Windows)

scoop bucket add amaya382 https://github.com/amaya382/scoop-bucket
scoop install baretree

From Source

go install github.com/amaya382/baretree/cmd/bt@latest

---

🔧 Troubleshooting

bt cd doesn't work

Make sure shell integration is enabled:

# Check if the shell function and the command exist
type bt
type -p bt

# Re-add shell integration
eval "$(bt shell-init bash)"  # or zsh/fish

Symlinks don't work on Windows

1. Enable Developer Mode (Windows 10+)
2. Or use --type copy instead

Can't remove worktree (uncommitted changes)

bt rm feature/branch --force

Worktree and branch names don't match

bt repair --dry-run --all     # Preview changes
bt repair --all               # Fix (use branch name as source)
bt repair --source=dir --all  # Fix (use directory name as source)

---

📋 Requirements

• Git 2.15+
• Go 1.23+ (building from source)

Related Projects

• ghq - Repository management tool (inspiration for bt repo get/list/remove)
• wtp - Worktree management tool (inspiration for bt post-create)