Docs/Version Control/Branching

Version Control

Branching

Create branches to experiment with different aesthetic directions without affecting your main taste profile.

Understanding Branches

Branches in commandAGI work similarly to git branches. Each branch maintains its own independent history of changes, allowing you to:

Experiment Safely

Try new aesthetic directions without affecting your production profile.

A/B Test Tastes

Create branches for different user segments or use cases.

Collaborate

Different team members can work on separate branches simultaneously.

Version History

Each branch maintains its own commit history for easy rollback.

Branch Structure

Every taste profile starts with a main branch. You can create additional branches from any existing branch.

main ─────●─────●─────●─────●─────●──────────> (production)
           │
           └─── experiment/warm-tones ─────●─────●──> (testing)
                     │
                     └─── experiment/warm-saturated ─────●──> (iteration)

Creating a Branch

Branches can be created through the dashboard or programmatically by updating the profile's branch structure.

Via Dashboard

1Navigate to your profile's History page
2Click Create Branch
3Enter a name and optional description
4Select the parent branch to branch from

Via API

Update the profile's profileData to add a new branch:

PATCH /v1/profiles/:id

curl -X PATCH https://api.commandAGI.com/v1/profiles/prof_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileData": {
      "branches": [
        {
          "id": "main",
          "name": "main",
          "description": "Main branch",
          "headVersionId": "v_123",
          "createdAt": "2024-01-15T10:30:00Z"
        },
        {
          "id": "experiment-warm",
          "name": "experiment/warm-tones",
          "description": "Testing warmer color palette",
          "headVersionId": "v_123",
          "parentBranchId": "main",
          "createdAt": "2024-01-21T09:00:00Z"
        }
      ],
      "currentBranchId": "experiment-warm"
    }
  }'

Switching Branches

Switch between branches to work on different aesthetic directions. The profile's effective snapshot will update to reflect the current branch's state.

Update currentBranchId

curl -X PATCH https://api.commandAGI.com/v1/profiles/prof_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileData": {
      "currentBranchId": "main"
    }
  }'

Branch Data Structure

Field	Type	Description
id	string	Unique identifier for the branch
name	string	Human-readable branch name
description	string	Optional description of the branch purpose
headVersionId	string \| null	ID of the latest committed version on this branch
parentBranchId	string	Optional. The branch this was created from
createdAt	string	ISO timestamp of branch creation

Best Practices

Use Descriptive Names

Name branches after their purpose: experiment/warm-tones, user-segment/millennials, feature/high-contrast.

Keep Main Stable

Treat main as your production branch. Make experimental changes on feature branches and merge when validated.

Document Branch Purpose

Use the description field to explain what the branch is testing or achieving. This helps team members understand the context.

Clean Up Old Branches

Delete branches that have been merged or abandoned. This keeps your profile structure clean and easier to navigate.

Uncommitted Changes

Working changes (uncommitted labels, comparisons, constraints) are stored per-profile, not per-branch. Switching branches while having uncommitted changes may lead to confusion. Commit your changes before switching branches.