thothctl

Project Upgrade

The thothctl project upgrade command allows you to upgrade your project with the latest changes from a remote template repository. It provides intelligent comparison, conflict detection, and interactive file selection to ensure safe and controlled upgrades.

Command Syntax

thothctl project upgrade [OPTIONS]

Options

Option	Description
`-dr, --dry-run`	Show what changes would be made without applying them
`-i, --interactive`	Enable interactive mode for selective file updates
`-f, --force`	Force upgrade even when conflicts are detected
`--help`	Show help message and exit

Features

Commit Hash Comparison

The upgrade command intelligently compares commit hashes between your local project and the remote template repository:

Up-to-date: If commits match, no upgrade is needed
Behind: Shows available updates when remote has newer commits
Ahead: Warns when local project has commits not in remote

File Change Detection

The command categorizes file changes into three types:

📄 NEW: Files that don’t exist locally but are present in the remote template
🔄 UPDATE: Files that exist locally but have different content in the remote template
⚠️ CONFLICT: Files that have been modified locally and also changed in the remote template

Project-Specific File Exclusion

The upgrade process automatically excludes project-specific configuration files to prevent overwriting customizations:

.thothcf.toml - Project configuration file
common/common.hcl - Common Terragrunt configuration
common/common.tfvars - Common Terraform variables
docs/catalog/catalog-info.yaml - Backstage catalog information

Usage Examples

Dry Run Mode

Check what changes would be made without applying them:

# See what files would be updated
thothctl project upgrade --dry-run

Example output:

📊 Commit Comparison:
   Local:  abc123def (2024-01-15)
   Remote: xyz789ghi (2024-01-20)
   Status: Behind by 3 commits

📄 NEW files (2):
   - templates/new-component.tf
   - scripts/deploy.sh

🔄 UPDATE files (1):
   - README.md

⚠️ CONFLICT files (1):
   - main.tf (modified locally and in remote)

Interactive Mode

Selectively choose which files to update:

# Enable interactive file selection
thothctl project upgrade --interactive

Interactive mode allows you to:

Review each file change individually
Choose which files to update
Skip files you want to keep unchanged
Handle conflicts manually

Force Mode

Apply all changes, including conflicted files:

# Force upgrade all files
thothctl project upgrade --force

⚠️ Warning: Force mode will overwrite local changes in conflicted files. Use with caution.

Combined Options

# Preview interactive selections
thothctl project upgrade --dry-run --interactive

# Force upgrade with interactive selection
thothctl project upgrade --interactive --force

Upgrade Process

1. Repository Analysis

The command first analyzes both local and remote repositories:

# Clone remote template repository
git clone <template-repo-url> /tmp/template-repo

# Compare commit hashes
local_commit = git.Repo('.').head.commit
remote_commit = git.Repo('/tmp/template-repo').head.commit

2. File Comparison

For each file in the remote template:

Check if file exists locally
Compare content if file exists
Categorize as NEW, UPDATE, or CONFLICT
Apply exclusion rules for project-specific files

3. Change Application

Based on the selected mode:

Dry Run: Display changes without applying
Interactive: Prompt for each file selection
Standard: Apply non-conflicted changes
Force: Apply all changes including conflicts

Best Practices

Before Upgrading

Commit Local Changes: Ensure all local changes are committed

git add .
git commit -m "Save local changes before upgrade"

Create Backup Branch: Create a backup branch for safety

git checkout -b backup-before-upgrade
git checkout main

Run Dry Run: Always check what changes will be made
```
thothctl project upgrade --dry-run
```

During Upgrade

Use Interactive Mode: For better control over changes
```
thothctl project upgrade --interactive
```
Review Conflicts: Carefully review conflicted files before applying
Test Incrementally: Apply changes in small batches when possible

After Upgrade

Test Functionality: Ensure the project still works correctly

# Run your project's test suite
terraform plan  # for Terraform projects

Commit Upgrade: Commit the upgrade changes

git add .
git commit -m "chore: Upgrade project from template"

Document Changes: Update project documentation if needed

Troubleshooting

Common Issues

Path Corruption

If you encounter path corruption issues, ensure emoji prefixes are handled correctly:

📄 NEW: = 7 characters
🔄 UPDATE: = 10 characters

Git Authentication

Ensure proper git authentication for private repositories:

# Configure git credentials
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Merge Conflicts

For complex conflicts, consider manual resolution:

# After upgrade, resolve conflicts manually
git status
git diff
# Edit conflicted files
git add .
git commit -m "resolve: Manual conflict resolution"

Integration with CI/CD

Automated Upgrade Checks

# GitHub Actions example
name: Check Template Updates

on:
  schedule:
    - cron: '0 9 * * MON'  # Weekly on Monday
  workflow_dispatch:

jobs:
  check-updates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
          
      - name: Install ThothCTL
        run: pip install thothctl
        
      - name: Check for updates
        run: |
          thothctl project upgrade --dry-run > upgrade-report.txt
          
      - name: Create Issue if Updates Available
        if: contains(steps.check.outputs.result, 'UPDATE') || contains(steps.check.outputs.result, 'NEW')
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: 'Template Updates Available',
              body: 'New template updates are available. Run `thothctl project upgrade --dry-run` to see changes.'
            })

Pull Request Workflow

name: Template Upgrade PR

on:
  workflow_dispatch:
    inputs:
      upgrade_mode:
        description: 'Upgrade mode'
        required: true
        default: 'interactive'
        type: choice
        options:
          - dry-run
          - interactive
          - force

jobs:
  upgrade:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          token: $
          
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
          
      - name: Install ThothCTL
        run: pip install thothctl
        
      - name: Run Upgrade
        run: |
          git checkout -b template-upgrade-$(date +%Y%m%d)
          thothctl project upgrade --$
          
      - name: Create Pull Request
        if: github.event.inputs.upgrade_mode != 'dry-run'
        uses: peter-evans/create-pull-request@v5
        with:
          title: 'chore: Upgrade project from template'
          body: |
            Automated template upgrade using ThothCTL.
            
            Please review the changes carefully before merging.
          branch: template-upgrade-$(date +%Y%m%d)

Advanced Usage

Custom Exclusion Patterns

While the command has built-in exclusions, you can extend them by modifying the upgrade service configuration in your project.

Batch Processing

For multiple projects, create a script to upgrade them systematically:

#!/bin/bash
# upgrade-all-projects.sh

projects=("project1" "project2" "project3")

for project in "${projects[@]}"; do
    echo "Upgrading $project..."
    cd "$project"
    thothctl project upgrade --dry-run
    read -p "Proceed with upgrade? (y/n): " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        thothctl project upgrade --interactive
    fi
    cd ..
done

This upgrade functionality ensures your projects stay current with template improvements while maintaining control over which changes to apply.

This site is open source. Improve this page.