> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.
# Git Workflow Guide
> Integrate version control into your AI-assisted development with T3 Code's Git features
## 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:
```typescript theme={null}
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
### From the Toolbar
Let the AI make changes to your codebase
Click the Git icon in the toolbar
See uncommitted changes count
Enter a descriptive commit message
Click "Commit" to stage and commit all changes
### Commit Message Tips
```text Feature theme={null}
feat: add user authentication
Implement OAuth2 flow with Google provider
```
```text Fix theme={null}
fix: resolve race condition in file upload
Ensure mutex lock before writing to shared buffer
```
```text Refactor theme={null}
refactor: extract validation logic to separate module
Move validation from controller to middleware for reuse
```
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):
1. AI makes changes in your current branch
2. You commit when ready
3. Create new branch manually if needed
4. Continue conversation in new branch context
### Worktree Threads
Worktree threads create isolated environments:
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/`
Specify a branch when creating the thread:
* Choose existing branch to check out
* Or create new branch name
* Thread works in that branch
### 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
Use the keyboard shortcut for new worktree thread (varies by platform)
Choose base branch or let T3 create one
T3 creates `.t3-worktrees/thread-id/` directory
All changes happen in the worktree, not main workspace
Worktree location:
```bash theme={null}
project-root/
.t3-worktrees/
thread_abc123/ # Worktree for thread abc123
src/
package.json
...
```
### Worktree Lifecycle
```mermaid theme={null}
graph LR
A[Create Thread] --> B[Create Worktree]
B --> C[Make Changes]
C --> D[Commit]
D --> E{Keep Branch?}
E -->|Yes| F[Delete Worktree Only]
E -->|No| G[Delete Worktree + Branch]
```
When deleting a thread with a worktree:
1. T3 detects the worktree is orphaned (no other threads use it)
2. Prompts to delete the worktree directory
3. 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:
```bash theme={null}
git worktree list
```
Remove worktree:
```bash theme={null}
git worktree remove .t3-worktrees/thread_abc123
```
Prune deleted worktrees:
```bash theme={null}
git worktree prune
```
## Creating Pull Requests
### From the Toolbar
Ensure your changes are committed
Click the Git icon in toolbar
Select "Create Pull Request"
T3 auto-generates title and description from commits
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
```markdown theme={null}
## 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:
```bash theme={null}
# macOS
brew install gh
# Windows
winget install GitHub.cli
# Linux
sudo apt install gh
```
```bash theme={null}
gh auth login
```
Follow prompts to authenticate with GitHub.
```bash theme={null}
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:
```typescript theme={null}
type GitStackedAction =
| 'commit' // Commit current changes
| 'commit-and-pr' // Commit and create PR
| 'push' // Push to remote
| 'pull' // Pull from remote
```
### Commit and Push
```bash theme={null}
# Via toolbar: Git → Commit and Push
```
This:
1. Stages all changes
2. Commits with your message
3. Pushes to remote branch
### Commit and Create PR
```bash theme={null}
# Via toolbar: Git → Create Pull Request
```
This:
1. Stages all changes
2. Commits with your message
3. Pushes to remote
4. Creates PR using `gh` CLI
## Advanced Git Operations
### Reverting Changes
T3 Code provides checkpoint-based revert:
Find the conversation turn before unwanted changes
Click the undo icon on that message
T3 runs `git reset --hard` to the checkpoint commit
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:
```bash theme={null}
# 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:
```bash theme={null}
# 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:
```bash theme={null}
# Initialize if needed
git init
# Set user info
git config user.name "Your Name"
git config user.email "you@example.com"
# Add remote
git remote add origin https://github.com/user/repo.git
```
### Gitignore
Add T3 Code directories to `.gitignore`:
```gitignore theme={null}
# 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
```bash theme={null}
# 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)
```bash theme={null}
# Feature branches
# PRs for review
# Worktrees for isolation
```
**Recommended**:
* Always use worktree threads
* Create PRs for all features
* Review before merging
### Large Team (6+)
```bash theme={null}
# 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:
1. Run `git init` in project root
2. Refresh the page
3. 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:
1. `gh` CLI is installed and authenticated
2. Remote repository is set
3. Branch is pushed to remote
4. GitHub access token has permissions
### Merge Conflicts
If AI changes conflict with other commits:
1. Pull latest changes: `git pull`
2. Resolve conflicts manually
3. Commit resolution
4. Continue conversation
T3 Code does not auto-resolve merge conflicts.
## Best Practices
* **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
```bash theme={null}
# Good
feature/user-authentication
fix/memory-leak-in-parser
refactor/extract-validation
# Avoid
changes
test
temp
working
```
## Next Steps
* Explore [Web Interface](/guides/web-interface) for daily use
* Configure [CLI Usage](/guides/cli-usage) for automation
* Organize work with [Project Management](/guides/project-management)