Skip to content

Quick Start Guide

Jump to bottom
Alexander Klee edited this page Dec 18, 2025 · 1 revision

Quick Start Guide

Get started with git-forest in under 5 minutes! This guide will walk you through initializing your first forest, installing a plan, and creating your first plants.

What You'll Learn

By the end of this guide, you'll know how to:

  • Initialize a forest in your repository
  • Install and reconcile a plan
  • View and manage plants
  • Understand the basic workflow

Step 1: Initialize Your Forest

Navigate to a git repository and initialize a forest:

cd /path/to/your/git/repo
git-forest init

Expected output:

initialized (.git-forest)

This creates a .git-forest/ directory in your repository with the initial structure.

Verify initialization:

git-forest status

Example output:

Forest: initialized  Repo: origin/main
Plans: 0 installed
Plants: 0 total
Planters: 0 available
Lock: free

Step 2: Install Your First Plan

Let's install the developer-experience plan, which helps optimize build times, improve error messages, and streamline workflows:

git-forest plans install config/plans/team-process/developer-experience.yaml

Verify the plan is installed:

git-forest plans list

Example output:

Plan ID              Version  Name                 Category
developer-experience 1.0.0    Developer Experience team-process

Step 3: Reconcile the Plan

Reconciliation analyzes your repository and generates plants (work items) based on the plan's rules:

git-forest plan developer-experience reconcile

Expected output:

Reconciling plan 'developer-experience@1.0.0'...
Planners: +2 ~0 -0
Planters: +3 ~1 -0
Plants:   +4 ~0 -0 (archived 0)
done

This creates several plants representing improvements to your developer experience.

Step 4: View Your Plants

List all plants generated by the plan:

git-forest plants list --plan developer-experience

Example output:

Key                                    Status   Title                              Plan                 Planter
developer-experience:optimize-build    planned  Optimize build performance         developer-experience -
developer-experience:improve-errors    planned  Improve error messages             developer-experience -
developer-experience:reduce-warnings   planned  Reduce compiler warnings           developer-experience -
developer-experience:cache-deps        planned  Add dependency caching             developer-experience -

Step 5: Work with a Plant

Let's examine a specific plant and assign a planter to work on it.

Show plant details:

git-forest plant P01 show

Or use the full key:

git-forest plant developer-experience:optimize-build show

List available planters:

git-forest planters list

Assign a planter to the plant:

git-forest plant P01 assign build-optimizer

Or plant it directly with automatic branch creation:

git-forest planter build-optimizer plant P01 --branch auto --yes

Step 6: Check Status

View your forest status at any time:

git-forest status

Example output:

Forest: initialized  Repo: origin/main
Plans: 1 installed (developer-experience@v1.0.0)
Plants: planned 3 | planted 1 | growing 0 | harvestable 0 | harvested 0
Planters: 3 available | 1 active
Lock: free
Hints: gf plants list --status planned

Understanding the Workflow

git-forest follows a natural lifecycle:

Plan ? Reconcile ? Plants ? Assign Planter ? Grow ? Harvest
  1. Plan: Install a plan that defines what improvements to make
  2. Reconcile: Generate plants (work items) by analyzing your codebase
  3. Plants: Review the generated work items
  4. Assign: Assign planters (agents) to execute the work
  5. Grow: Planters propose or apply changes
  6. Harvest: Mark completed work as harvested

Common Commands

Here are the most common commands you'll use:

# Status and information
git-forest status
git-forest status --json

# Plans
git-forest plans list
git-forest plans install <source>
git-forest plan <id> reconcile

# Plants
git-forest plants list
git-forest plants list --status planned
git-forest plant <selector> show

# Planters
git-forest planters list
git-forest planter <id> assign <plant-selector>

# Configuration
git-forest config show

Using JSON Output

Every command supports --json for automation:

git-forest status --json
git-forest plants list --json
git-forest plan developer-experience reconcile --json

This makes git-forest perfect for CI/CD integration.

Next Steps

Now that you have a basic understanding, explore more:

Learn Core Concepts

  • Core Concepts - Deep dive into Plans, Plants, Planters, and Planners

Explore Plans

Manage Plants

Automate

Try More Plans

Here are some popular plans to try next:

# Improve code quality
git-forest plans install config/plans/engineering-excellence/dependency-hygiene.yaml
git-forest plan dependency-hygiene reconcile

# Boost test coverage
git-forest plans install config/plans/quality-reliability/unit-testing-discipline.yaml
git-forest plan unit-testing-discipline reconcile

# Security hygiene
git-forest plans install config/plans/security-compliance/secret-hygiene.yaml
git-forest plan secret-hygiene reconcile

# Get repository overview (team leads)
git-forest plans install config/plans/meta-governance/repository-overview.yaml
git-forest plan repository-overview reconcile

Complete Walkthrough Example

Here's a complete end-to-end workflow:

# 1. Initialize
git-forest init

# 2. Install plan
git-forest plans install config/plans/team-process/developer-experience.yaml

# 3. Reconcile
git-forest plan developer-experience reconcile

# 4. View plants
git-forest plants list --plan developer-experience

# 5. Pick a plant (use P01 or full key)
git-forest plant P01 show

# 6. Plant it (assign + create branch)
git-forest planter build-optimizer plant P01 --branch auto --yes

# 7. Grow it (propose changes)
git-forest planter build-optimizer grow P01 --mode propose

# 8. Check status
git-forest status

# 9. When done, harvest
git-forest plant P01 harvest

Troubleshooting

Forest not initialized

Error: Forest not initialized in this repository

Solution: Run git-forest init

Plan not found

Error: Plan 'xyz' not found

Solution: Run git-forest plans list to see installed plans

Command not found

bash: git-forest: command not found

Solution: Check Installation guide for PATH setup

Getting Help

# General help
git-forest --help

# Command-specific help
git-forest plans --help
git-forest plant --help

For more help:

Alias Setup

Make your life easier with the gf alias:

PowerShell:

Set-Alias gf git-forest

Bash/Zsh:

alias gf='git-forest'

Now you can use:

gf status
gf plants list
gf plan developer-experience reconcile

Congratulations! ?? You've completed the Quick Start Guide. You now know the basics of git-forest and are ready to start cultivating your codebase.

Continue learning:

Clone this wiki locally