Git Workflow Guide

Overview

T3 Code provides deep Git integration, allowing you to commit changes, create branches, manage worktrees, and create pull requests directly from the interface. The AI works within your Git workflow, respecting your branching strategy and providing tools for safe experimentation.

Git Status

Real-Time Updates

The interface shows live Git status for each thread:

Current Branch: Displayed in thread metadata and toolbar
PR Status: Badge shows if thread has an open/merged/closed PR
Uncommitted Changes: Indicated in the Git actions menu

Status Information

Git status includes:

interface GitStatus {
  branch: string | null;          // Current branch name
  isRepo: boolean;                // Is this a Git repository?
  hasUncommittedChanges: boolean; // Uncommitted changes present?
  pr: {                           // Associated pull request
    number: number;
    title: string;
    state: 'open' | 'closed' | 'merged';
    url: string;
  } | null;
}

Status refreshes automatically every 15 seconds and on window focus.

Committing Changes

Make Changes

Let the AI make changes to your codebase

Open Git Menu

Click the Git icon in the toolbar

Review Changes

See uncommitted changes count

Write Message

Enter a descriptive commit message

Commit

Click “Commit” to stage and commit all changes

Commit Message Tips

feat: add user authentication

Implement OAuth2 flow with Google provider

Follow conventional commit format for clarity:

feat: - New feature
fix: - Bug fix
refactor: - Code restructuring
docs: - Documentation
test: - Tests
chore: - Maintenance

Branching Strategy

Local Development

When working locally (non-worktree threads):

AI makes changes in your current branch
You commit when ready
Create new branch manually if needed
Continue conversation in new branch context

Worktree Threads

Worktree threads create isolated environments:

Automatic Branching
Manual Branch

When creating a worktree thread:

T3 creates a new branch (t3code/abc123)
Branch is based on current HEAD
Changes are isolated from main workspace
Worktree path: .t3-worktrees/thread-id/

Branch Naming

T3 Code uses these conventions:

Temporary: t3code/8hex - Auto-generated for ephemeral work
Feature: feature/your-name - User-specified feature branches
Main branches: main, master, develop - Never auto-created

Temporary branches starting with t3code/ are detected and can be cleaned up automatically.

Git Worktrees

What Are Worktrees?

Git worktrees let you work on multiple branches simultaneously. Each worktree is a separate directory with its own checked-out branch. Benefits:

✅ Isolated changes per thread
✅ No branch switching in main workspace
✅ Safe experimentation
✅ Parallel development

Trade-offs:

⚠️ Additional disk space per worktree
⚠️ Need to manage cleanup
⚠️ Can be confusing for Git beginners

Creating Worktree Threads

Start New Thread

Use the keyboard shortcut for new worktree thread (varies by platform)

Branch Selection

Choose base branch or let T3 create one

Worktree Created

T3 creates .t3-worktrees/thread-id/ directory

Work Isolated

All changes happen in the worktree, not main workspace

Worktree location:

project-root/
  .t3-worktrees/
    thread_abc123/    # Worktree for thread abc123
      src/
      package.json
      ...

Worktree Lifecycle

When deleting a thread with a worktree:

T3 detects the worktree is orphaned (no other threads use it)
Prompts to delete the worktree directory
Optionally removes the Git worktree registration

Deleting a worktree does NOT delete the branch by default. The branch remains in your repository.

Manual Worktree Management

List worktrees:

git worktree list

Remove worktree:

git worktree remove .t3-worktrees/thread_abc123

Prune deleted worktrees:

git worktree prune

Creating Pull Requests

Commit Changes

Ensure your changes are committed

Open Git Menu

Click the Git icon in toolbar

Click Create PR

Select “Create Pull Request”

Review Details

T3 auto-generates title and description from commits

Submit

PR is created on GitHub (requires gh CLI)

PR Title and Description

T3 Code automatically generates PR metadata: Title: Based on most recent commit or conversation context

Add user authentication with OAuth2

Description: Markdown summary of changes

## Summary
- Implement OAuth2 authentication flow
- Add Google provider configuration  
- Create user session management
- Update API to require authentication

## Testing
Manually tested login flow with Google OAuth.

GitHub CLI Setup

T3 Code uses gh CLI for PR creation:

Install
Authenticate
Verify

# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
sudo apt install gh

gh auth login

Follow prompts to authenticate with GitHub.

gh auth status

Should show authenticated status.

PR Status Tracking

Once created, the PR is tracked in the thread:

Badge: Shows PR number and state (open/closed/merged)
Link: Click badge to open PR in browser
Updates: Status refreshes automatically

Stacked Actions

T3 Code supports Git stacked workflows for incremental changes:

type GitStackedAction = 
  | 'commit'          // Commit current changes
  | 'commit-and-pr'   // Commit and create PR
  | 'push'            // Push to remote
  | 'pull'            // Pull from remote

Commit and Push

# Via toolbar: Git → Commit and Push

This:

Stages all changes
Commits with your message
Pushes to remote branch

Commit and Create PR

# Via toolbar: Git → Create Pull Request

This:

Stages all changes
Commits with your message
Pushes to remote
Creates PR using gh CLI

Advanced Git Operations

Reverting Changes

T3 Code provides checkpoint-based revert:

Identify Checkpoint

Find the conversation turn before unwanted changes

Revert

Click the undo icon on that message

Git Reset

T3 runs git reset --hard to the checkpoint commit

Verify

Check that changes were reverted

Checkpoint revert is a hard reset. Uncommitted changes will be lost.

Viewing Diffs

Inline Diffs

Each conversation turn shows change summaries:

src/auth.ts        +45  -12
src/types.ts       +8   -0
tests/auth.test.ts +32  -0

Click file paths to open in your editor.

Diff Panel

Open the side-by-side diff panel:

# Keyboard shortcut (varies by platform)
# Or: Click diff icon in toolbar

The panel shows:

Unified diff format
Syntax highlighting
Per-turn filtering
Full file content

Comparing Branches

Use Git commands in the terminal:

# Compare branches
git diff main..feature/auth

# View branch history  
git log main..feature/auth

# Check branch divergence
git log --oneline --graph --all

Git Configuration

Repository Setup

Ensure your repository is configured:

# Initialize if needed
git init

# Set user info
git config user.name "Your Name"
git config user.email "[email protected]"

# Add remote
git remote add origin https://github.com/user/repo.git

Gitignore

Add T3 Code directories to .gitignore:

# T3 Code
.t3-worktrees/

This prevents worktree directories from being committed.

Hooks

Git hooks work normally with T3 Code:

pre-commit: Runs before commits from toolbar
commit-msg: Can validate commit messages
pre-push: Runs before push operations

Install hooks in .git/hooks/ or use a tool like Husky.

Workflows by Team Size

Solo Developer

# Work directly in main
# Commit frequently
# Use worktrees for experiments

Recommended:

Local threads for small changes
Worktree threads for features
Commit after each working state

Small Team (2-5)

# Feature branches
# PRs for review
# Worktrees for isolation

Recommended:

Always use worktree threads
Create PRs for all features
Review before merging

Large Team (6+)

# Strict branching strategy
# Required PR reviews
# CI/CD integration

Recommended:

Worktree threads mandatory
Branch naming convention
Protected main branch
Automated testing

Troubleshooting

”Not a Git repository”

If Git features are disabled:

Run git init in project root
Refresh the page
Verify .git directory exists

Worktree Creation Failed

Common causes:

Branch exists: Choose different branch name
Disk space: Free up space for worktree
Permissions: Ensure write access to project directory

PR Creation Failed

Check:

gh CLI is installed and authenticated
Remote repository is set
Branch is pushed to remote
GitHub access token has permissions

Merge Conflicts

If AI changes conflict with other commits:

Pull latest changes: git pull
Resolve conflicts manually
Commit resolution
Continue conversation

T3 Code does not auto-resolve merge conflicts.

Best Practices

Git Workflow Tips

Commit often: Save progress incrementally
Descriptive messages: Future you will thank present you
Use worktrees: Isolate experimental work
Review diffs: Always check changes before committing
Clean up branches: Delete merged feature branches

Commit Frequency

✅ After each logical change
✅ Before switching context
✅ When conversation reaches milestone
❌ Don’t commit broken code
❌ Don’t commit half-finished features (unless WIP marked)

Branch Naming

# Good
feature/user-authentication
fix/memory-leak-in-parser  
refactor/extract-validation

# Avoid
changes
test
temp
working

Next Steps

Explore Web Interface for daily use
Configure CLI Usage for automation
Organize work with Project Management

Get Started

Core Concepts

Usage Guides

Configuration

Development

​Overview

​Git Status

​Real-Time Updates

​Status Information

​Committing Changes

​From the Toolbar

​Commit Message Tips

​Branching Strategy

​Local Development

​Worktree Threads

​Branch Naming

​Git Worktrees

​What Are Worktrees?

​Creating Worktree Threads

​Worktree Lifecycle

​Manual Worktree Management

​Creating Pull Requests

​From the Toolbar

​PR Title and Description

​GitHub CLI Setup

​PR Status Tracking

​Stacked Actions

​Commit and Push

​Commit and Create PR

​Advanced Git Operations

​Reverting Changes

​Viewing Diffs

​Inline Diffs

​Diff Panel

​Comparing Branches

​Git Configuration

​Repository Setup

​Gitignore

​Hooks

​Workflows by Team Size

​Solo Developer

​Small Team (2-5)

​Large Team (6+)

​Troubleshooting

​”Not a Git repository”

​Worktree Creation Failed

​PR Creation Failed

​Merge Conflicts

​Best Practices

Git Workflow Tips

​Commit Frequency

​Branch Naming

​Next Steps

Build docs developers (and LLMs) love

Overview

Git Status

Real-Time Updates

Status Information

Committing Changes

From the Toolbar

Commit Message Tips

Branching Strategy

Local Development

Worktree Threads

Branch Naming

Git Worktrees

What Are Worktrees?

Creating Worktree Threads

Worktree Lifecycle

Manual Worktree Management

Creating Pull Requests

From the Toolbar

PR Title and Description

GitHub CLI Setup

PR Status Tracking

Stacked Actions

Commit and Push

Commit and Create PR

Advanced Git Operations

Reverting Changes

Viewing Diffs

Inline Diffs

Diff Panel

Comparing Branches

Git Configuration

Repository Setup

Gitignore

Hooks

Workflows by Team Size

Solo Developer

Small Team (2-5)

Large Team (6+)

Troubleshooting

”Not a Git repository”

Worktree Creation Failed

PR Creation Failed

Merge Conflicts

Best Practices

Commit Frequency

Branch Naming

Next Steps