Skip to content

USAGE.md

Latest commit

 

History

History
838 lines (602 loc) · 16.4 KB

USAGE.md

File metadata and controls

838 lines (602 loc) · 16.4 KB

Rhiza Usage Guide

This guide provides practical examples and tutorials for using Rhiza CLI.

Table of Contents

Getting Started

Installation

Install Rhiza using pip:

pip install rhiza

Or use uvx to run without installation:

uvx rhiza --help

With uvx, you don't need to install rhiza - it automatically uses the latest version each time you run it.

Verify installation:

rhiza --help

Your First Project

Let's set up a new Python project with Rhiza templates:

# Create a new project directory
mkdir my-awesome-project
cd my-awesome-project

# Initialize git repository
git init

# Initialize Rhiza
rhiza init

You should see output like:

[INFO] Initializing Rhiza configuration in: /path/to/my-awesome-project
[INFO] Creating default .rhiza/template.yml
✓ Created .rhiza/template.yml

Understanding the Configuration

View the created configuration:

cat .rhiza/template.yml

You'll see:

template-repository: jebel-quant/rhiza
template-branch: main
include:
  - .github
  - .editorconfig
  - .gitignore
  - .pre-commit-config.yaml
  - Makefile
  - pytest.ini

This tells Rhiza to fetch these files from the jebel-quant/rhiza repository.

Materializing Templates

Apply the templates to your project:

rhiza sync

Review what was added:

git status
ls -la

Commit the changes:

git add .
git commit -m "chore: initialize project with rhiza templates"

Understanding the History File

After materialization, Rhiza creates a .rhiza.history file that tracks all files under template control:

cat .rhiza.history

You'll see:

# Rhiza Template History
# This file lists all files managed by the Rhiza template.
# Template repository: jebel-quant/rhiza
# Template branch: main
#
# Files under template control:
.editorconfig
.gitignore
Makefile
.github/workflows/ci.yml
...

This file helps you:

  • Track which files are managed by the template
  • Understand what will be updated when you re-run rhiza sync
  • Identify which files to be careful with when making local modifications
  • Detect orphaned files - when you re-run rhiza sync, any files listed in .rhiza.history but no longer in the current template configuration will be automatically deleted

Important: The .rhiza.history file is regenerated each time you run rhiza sync, so you should commit it along with your other template files. When re-running sync, Rhiza will compare the old history with the new configuration and remove any files that are no longer being managed.

Basic Workflows

Workflow 1: Starting a New Project

Complete workflow for a new Python project:

# 1. Create project structure
mkdir new-python-lib
cd new-python-lib
git init

# 2. Initialize Rhiza
rhiza init

# 3. Materialize templates
rhiza sync

# 4. Review and commit
git status
git diff
git add .
git commit -m "feat: initial project setup with rhiza"

# 5. Validate everything is correct
rhiza validate

Workflow 2: Updating Existing Project

Add Rhiza to an existing project:

# 1. Navigate to existing project
cd existing-project

# 2. Ensure it's a git repository
git status

# 3. Create feature branch
git checkout -b add-rhiza-templates

# 4. Initialize Rhiza
rhiza init

# 5. Review generated template.yml and customize if needed
vim .rhiza/template.yml

# 6. Materialize templates (use --force carefully!)
rhiza sync

# 7. Review changes carefully
git diff

# 8. Commit
git add .
git commit -m "chore: add rhiza template management"

# 9. Create PR
git push -u origin add-rhiza-templates

Workflow 3: Updating Templates

Periodically update your project's templates:

# 1. Create update branch
git checkout -b update-templates

# 2. Validate current configuration
rhiza validate

# 3. Update templates
rhiza sync

# 4. Review changes
git diff

# 5. If changes look good, commit
git add .
git commit -m "chore: update rhiza templates to latest"

# 6. If not, revert
git checkout .

Advanced Usage

Specifying Template Repository at Init

By default, rhiza init creates a configuration that uses the jebel-quant/rhiza repository. You can specify your own template repository during initialization using the --template-repository option:

# Initialize with a custom template repository
rhiza init --template-repository myorg/python-standards

# Use a custom repository and branch
rhiza init --template-repository myorg/python-standards --template-branch v2.0

# Combine with other options
rhiza init --git-host gitlab --template-repository myorg/gitlab-templates --template-branch production

This automatically creates a .rhiza/template.yml file configured to use your custom template, eliminating the need to manually edit the file afterwards.

Example workflow:

mkdir my-project
cd my-project
git init

# Initialize with your organization's template
rhiza init --template-repository mycompany/python-templates --template-branch stable

# Materialize templates
rhiza sync

Custom Template Repository

Use your organization's template repository:

Edit .rhiza/template.yml:

template-repository: myorg/python-templates
template-branch: production
include:
  - .github/workflows
  - .github/dependabot.yml
  - pyproject.toml
  - Makefile
  - docker-compose.yml
  - src/config
exclude:
  - .github/workflows/experimental.yml

Materialize:

rhiza sync

Using Different Branches

Test templates from a development branch:

# Temporarily override template branch
rhiza sync --branch develop

# Or update template.yml
vim .rhiza/template.yml  # Change template-branch to 'develop'
rhiza sync

Using GitLab Repositories

Configure Rhiza to use a GitLab template repository:

Edit .rhiza/template.yml:

template-repository: mygroup/python-templates
template-host: gitlab
template-branch: main
include:
  - .gitlab-ci.yml
  - .editorconfig
  - .gitignore
  - Makefile
  - pytest.ini
exclude:
  - .gitlab-ci.yml  # Example exclusion

Materialize:

rhiza sync

Notes:

  • The template-host field supports github (default) and gitlab
  • Repository format is the same: owner/repo for GitHub or group/project for GitLab
  • All other Rhiza features work identically with GitLab repositories

Multi-Language Support

Rhiza supports templates for multiple programming languages, not just Python. By default, Rhiza assumes Python projects (requiring pyproject.toml), but you can specify a different language in your template configuration.

Supported Languages

  • Python (default): Validates pyproject.toml, src/, and tests/ directories
  • Go: Validates go.mod, cmd/, pkg/, and internal/ directories

Configuring a Go Project

For a Go project, specify the language in .rhiza/template.yml:

template-repository: jebel-quant/rhiza-go
language: go
include:
  - .github
  - .editorconfig
  - .gitignore
  - Makefile

Validate your Go project:

rhiza validate

You'll see language-specific validation:

[INFO] Project language: go
[SUCCESS] go.mod exists: /path/to/project/go.mod
[WARNING] Standard 'cmd' folder not found
[WARNING] Consider creating a 'cmd' directory for main applications

Configuring a Python Project (Explicit)

While Python is the default, you can explicitly specify it:

template-repository: jebel-quant/rhiza
language: python
include:
  - .github
  - pyproject.toml
  - Makefile

Backward Compatibility

If you omit the language field, Rhiza defaults to Python for backward compatibility:

# This is treated as a Python project
template-repository: jebel-quant/rhiza
include:
  - .github

Language-Specific Validation

Each language has its own validation rules:

Python projects must have:

  • pyproject.toml (required)
  • src/ directory (recommended, warning if missing)
  • tests/ directory (recommended, warning if missing)

Go projects must have:

  • go.mod (required)
  • cmd/ directory (recommended, warning if missing)
  • pkg/ or internal/ directory (recommended, warning if missing)

Example: Converting a Project to Go

If you have an existing Python project and want to convert it to Go:

# 1. Update template.yml
vim .rhiza/template.yml

# Add or change language field:
# language: go
# template-repository: jebel-quant/rhiza-go

# 2. Create Go project structure
go mod init example.com/myproject
mkdir -p cmd/myapp
mkdir -p pkg/mypackage

# 3. Validate
rhiza validate

# 4. Materialize Go templates
rhiza sync

Selective Inclusion

Include only specific files:

template-repository: jebel-quant/rhiza
include:
  - .github/workflows/ci.yml         # Single file
  - .github/workflows/release.yml    # Another file
  - .editorconfig                    # Configuration file
  - Makefile                         # Build file

Exclusion Patterns

Include a directory but exclude specific files:

template-repository: jebel-quant/rhiza
include:
  - .github                    # Include entire directory
exclude:
  - .github/CODEOWNERS         # But exclude this file
  - .github/workflows/deploy.yml  # And this workflow

Multiple Template Sources

While Rhiza doesn't directly support multiple repositories, you can manage them:

Create multiple configuration files:

# .rhiza/template-base.yml
# .rhiza/template-testing.yml
# .rhiza/template-docs.yml

Use a script to apply them:

#!/bin/bash
# apply-all-templates.sh

for template in .rhiza/template-*.yml; do
  cp "$template" .rhiza/template.yml
  rhiza sync
done

Integration Examples

GitHub Actions Validation

Validate Rhiza configuration in CI:

.github/workflows/validate-rhiza.yml:

name: Validate Rhiza Configuration

on:
  push:
    paths:
      - '.rhiza/template.yml'
  pull_request:
    paths:
      - '.rhiza/template.yml'

jobs:
  validate:
    name: Validate Template Configuration
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install Rhiza
        run: pip install rhiza
      
      - name: Validate configuration
        run: rhiza validate

Pre-commit Hook

Validate before every commit:

.git/hooks/pre-commit:

#!/bin/sh
# Validate Rhiza configuration before commit

if [ -f .rhiza/template.yml ]; then
    echo "Validating Rhiza configuration..."
    rhiza validate || {
        echo "ERROR: Rhiza validation failed"
        exit 1
    }
fi

Make it executable:

chmod +x .git/hooks/pre-commit

Makefile Integration

Add Rhiza commands to your Makefile:

.PHONY: template-init template-update template-validate

template-init: ## Initialize Rhiza templates
	rhiza init

template-update: ## Update templates from repository
	rhiza sync
	@echo "Review changes with: git diff"

template-validate: ## Validate template configuration
	rhiza validate

sync-templates: template-validate template-update ## Validate and update templates

Usage:

make template-init
make template-update
make template-validate
make sync-templates

Docker Integration

Include Rhiza in your Docker workflow:

Dockerfile.dev:

FROM python:3.11

WORKDIR /app

# Install Rhiza
RUN pip install rhiza

# Copy project
COPY . .

# Initialize templates if needed
RUN if [ ! -f .rhiza/template.yml ]; then rhiza init; fi

# Validate configuration
RUN rhiza validate

CMD ["/bin/bash"]

Pre-commit Framework

Use with the pre-commit framework:

.pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: rhiza-validate
        name: Validate Rhiza Configuration
        entry: rhiza validate
        language: system
        pass_filenames: false
        files: ^\.rhiza/template\.yml$

Install and run:

pip install pre-commit
pre-commit install
pre-commit run --all-files

Best Practices

1. Version Control Template Configuration

Always commit .rhiza/template.yml:

git add .rhiza/template.yml
git commit -m "feat: add rhiza template configuration"

2. Document Custom Configurations

Add comments to your template.yml:

# Custom template configuration for our microservices
template-repository: myorg/microservice-templates
template-branch: v2.0  # Use stable v2.0 branch

# Core files needed for all microservices
include:
  - .github/workflows       # CI/CD pipelines
  - docker-compose.yml      # Local development
  - Dockerfile              # Container definition
  - pyproject.toml          # Python project config
  - src/config              # Shared configuration

# Exclude service-specific files
exclude:
  - .github/workflows/deploy-specific.yml

3. Regular Template Updates

Set up a schedule for template updates:

# Monthly template update
0 0 1 * * cd /path/to/project && rhiza sync

4. Review Before Committing

Always review changes before committing:

rhiza sync
git diff                    # Review all changes
git add -p                  # Stage changes selectively
git commit -m "chore: update templates"

5. Test in Branches

Test template changes in feature branches:

git checkout -b test-template-update
rhiza sync
# Test your project
# If OK: merge; If not: delete branch

6. Document Exclusions

If you exclude files, document why:

exclude:
  # We maintain our own deployment workflow
  - .github/workflows/deploy.yml
  
  # Team-specific CODEOWNERS
  - .github/CODEOWNERS

7. Validate in CI

Always validate in your CI pipeline:

# In your CI workflow
- name: Validate Rhiza
  run: rhiza validate

8. Keep Templates Minimal

Only include what you actually need:

# Good: Specific files
include:
  - .github/workflows/ci.yml
  - .editorconfig
  - pyproject.toml

# Less good: Too broad
include:
  - .github
  - src
  - tests

9. Use Semantic Versioning for Template Branches

In your template repository:

# Create versioned branches
git checkout -b v1.0
git checkout -b v2.0

In projects:

# Pin to specific version
template-branch: v1.0

10. Communicate Changes

When updating templates, explain why:

# Use proper multi-line commit message
git commit -m "chore: update rhiza templates" \
  -m "" \
  -m "Updated from template repo v1.0 to v2.0:" \
  -m "- New GitHub Actions workflows" \
  -m "- Updated linting rules in ruff.toml" \
  -m "- Added security scanning workflow" \
  -m "" \
  -m "Refs: https://github.com/org/templates/releases/v2.0"

Troubleshooting Scenarios

Scenario 1: Merge Conflicts After Update

Problem: Template update causes merge conflicts

Solution:

# Update templates
rhiza sync

# If conflicts, review each file
git diff path/to/conflicted/file

# Manually resolve or keep local version
git checkout --ours path/to/file  # Keep local
git checkout --theirs path/to/file  # Keep template

# Commit resolution
git add .
git commit -m "chore: update templates, resolve conflicts"

Scenario 2: Template Override Local Changes

Problem: Need to keep local modifications to template files

Solution:

# Exclude files you've customized
exclude:
  - .github/workflows/custom-ci.yml
  - Makefile  # We have custom targets

Scenario 3: Testing New Templates

Problem: Want to test templates before applying

Solution:

# Create a test directory
mkdir /tmp/template-test
cd /tmp/template-test
git init

# Copy your template.yml
cp /path/to/project/.rhiza/template.yml .rhiza/

# Test sync
rhiza sync

# Review what would be added
ls -la
cat important-file.yml

# If satisfied, apply to real project
cd /path/to/project
rhiza sync

Additional Resources

Getting Help

If you need help:

  1. Check this usage guide
  2. Review the CLI Quick Reference
  3. Run rhiza <command> --help
  4. Check existing GitHub issues
  5. Open a new issue with details about your problem