4b91896838
- Comprehensive image extraction architecture design - Database schema for document_images table - Migration 004: Add document_images table with indexes - Migration runner script - Design and status documentation Prepares foundation for image extraction feature with OCR on images. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
400 lines
7.6 KiB
Markdown
400 lines
7.6 KiB
Markdown
# Git Worktree Setup for NaviDocs Testing
|
|
|
|
## Overview
|
|
|
|
Git worktrees allow you to have multiple working directories from the same repository, enabling parallel development and testing without affecting the main branch.
|
|
|
|
## Current Worktree Configuration
|
|
|
|
### Active Worktrees
|
|
|
|
```bash
|
|
/home/setup/navidocs ff3c306 [master]
|
|
/home/setup/navidocs-ui-test ff3c306 [ui-smoketest-20251019]
|
|
```
|
|
|
|
### Worktree Details
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| **Main Repository** | `/home/setup/navidocs` |
|
|
| **Test Worktree** | `/home/setup/navidocs-ui-test` |
|
|
| **Test Branch** | `ui-smoketest-20251019` |
|
|
| **Base Commit** | `ff3c306` (master) |
|
|
| **Created** | 2025-10-19 |
|
|
|
|
---
|
|
|
|
## Setup Process
|
|
|
|
### Step 1: Create Testing Worktree
|
|
|
|
```bash
|
|
# Navigate to main repository
|
|
cd /home/setup/navidocs
|
|
|
|
# Create worktree with new branch
|
|
git worktree add -b ui-smoketest-20251019 /home/setup/navidocs-ui-test master
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
Preparing worktree (new branch 'ui-smoketest-20251019')
|
|
HEAD is now at ff3c306 chore(env): add MEILISEARCH_SEARCH_KEY for dev
|
|
```
|
|
|
|
### Step 2: Verify Worktree
|
|
|
|
```bash
|
|
# List all worktrees
|
|
git worktree list
|
|
```
|
|
|
|
**Expected Output:**
|
|
```
|
|
/home/setup/navidocs ff3c306 [master]
|
|
/home/setup/navidocs-ui-test ff3c306 [ui-smoketest-20251019]
|
|
```
|
|
|
|
### Step 3: Navigate to Test Worktree
|
|
|
|
```bash
|
|
cd /home/setup/navidocs-ui-test
|
|
```
|
|
|
|
### Step 4: Verify Branch
|
|
|
|
```bash
|
|
git status
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
On branch ui-smoketest-20251019
|
|
nothing to commit, working tree clean
|
|
```
|
|
|
|
---
|
|
|
|
## Use Cases
|
|
|
|
### 1. Isolated UI Testing
|
|
|
|
Test UI changes without affecting the master branch:
|
|
|
|
```bash
|
|
cd /home/setup/navidocs-ui-test/client
|
|
npm run dev # Runs on separate port if 5174 is occupied
|
|
```
|
|
|
|
### 2. Parallel Development
|
|
|
|
Work on features in the test worktree while keeping master stable:
|
|
|
|
```bash
|
|
# In test worktree
|
|
cd /home/setup/navidocs-ui-test
|
|
# Make changes, commit, test
|
|
|
|
# In main repository (master remains unchanged)
|
|
cd /home/setup/navidocs
|
|
git status # Still on master, clean working tree
|
|
```
|
|
|
|
### 3. A/B Testing
|
|
|
|
Compare implementations side-by-side:
|
|
|
|
```bash
|
|
# Terminal 1: Master branch
|
|
cd /home/setup/navidocs/client
|
|
npm run dev # Port 5174
|
|
|
|
# Terminal 2: Test branch
|
|
cd /home/setup/navidocs-ui-test/client
|
|
npm run dev -- --port 5175 # Different port
|
|
```
|
|
|
|
### 4. Smoke Testing
|
|
|
|
Run comprehensive tests in isolation:
|
|
|
|
```bash
|
|
cd /home/setup/navidocs-ui-test
|
|
./start-all.sh # Start all services in test environment
|
|
# Run tests, verify functionality
|
|
./stop-all.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Working with the Test Worktree
|
|
|
|
### Making Changes
|
|
|
|
```bash
|
|
cd /home/setup/navidocs-ui-test
|
|
|
|
# Make changes to files
|
|
vim client/src/components/SearchBar.jsx
|
|
|
|
# Stage and commit
|
|
git add client/src/components/SearchBar.jsx
|
|
git commit -m "feat(ui): improve search bar accessibility"
|
|
```
|
|
|
|
### Syncing with Master
|
|
|
|
```bash
|
|
cd /home/setup/navidocs-ui-test
|
|
|
|
# Fetch latest changes
|
|
git fetch origin
|
|
|
|
# Merge master into test branch
|
|
git merge origin/master
|
|
|
|
# Or rebase onto master
|
|
git rebase origin/master
|
|
```
|
|
|
|
### Viewing Differences
|
|
|
|
```bash
|
|
# Compare test branch with master
|
|
git diff master..ui-smoketest-20251019
|
|
|
|
# See commit differences
|
|
git log master..ui-smoketest-20251019
|
|
```
|
|
|
|
---
|
|
|
|
## Merging Test Changes Back to Master
|
|
|
|
### Option 1: Merge from Test Worktree
|
|
|
|
```bash
|
|
cd /home/setup/navidocs-ui-test
|
|
|
|
# Ensure all changes are committed
|
|
git status
|
|
|
|
# Switch to main repository
|
|
cd /home/setup/navidocs
|
|
|
|
# Merge test branch
|
|
git merge ui-smoketest-20251019
|
|
```
|
|
|
|
### Option 2: Create Pull Request
|
|
|
|
```bash
|
|
cd /home/setup/navidocs-ui-test
|
|
|
|
# Push test branch to remote
|
|
git push origin ui-smoketest-20251019
|
|
|
|
# Create PR via GitHub/GitLab/Bitbucket UI
|
|
# Or use gh CLI
|
|
gh pr create --base master --head ui-smoketest-20251019 \
|
|
--title "UI Smoketest: Accessibility improvements" \
|
|
--body "Testing results and UI enhancements from ui-smoketest-20251019"
|
|
```
|
|
|
|
---
|
|
|
|
## Cleanup
|
|
|
|
### Remove Test Worktree (Temporary)
|
|
|
|
```bash
|
|
cd /home/setup/navidocs
|
|
|
|
# Remove worktree (keeps branch)
|
|
git worktree remove /home/setup/navidocs-ui-test
|
|
```
|
|
|
|
### Delete Test Branch (After Merging)
|
|
|
|
```bash
|
|
cd /home/setup/navidocs
|
|
|
|
# Delete local branch
|
|
git branch -d ui-smoketest-20251019
|
|
|
|
# Delete remote branch (if pushed)
|
|
git push origin --delete ui-smoketest-20251019
|
|
```
|
|
|
|
### Complete Cleanup
|
|
|
|
```bash
|
|
cd /home/setup/navidocs
|
|
|
|
# Remove worktree and delete branch
|
|
git worktree remove /home/setup/navidocs-ui-test
|
|
git branch -D ui-smoketest-20251019 # Force delete
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Worktree Already Exists
|
|
|
|
**Error:**
|
|
```
|
|
fatal: '/home/setup/navidocs-ui-test' already exists
|
|
```
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Remove existing worktree first
|
|
git worktree remove /home/setup/navidocs-ui-test
|
|
# Or manually delete directory
|
|
rm -rf /home/setup/navidocs-ui-test
|
|
# Then recreate
|
|
git worktree add -b ui-smoketest-20251019 /home/setup/navidocs-ui-test master
|
|
```
|
|
|
|
### Branch Already Exists
|
|
|
|
**Error:**
|
|
```
|
|
fatal: invalid reference: ui-smoketest-20251019
|
|
```
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Use existing branch
|
|
git worktree add /home/setup/navidocs-ui-test ui-smoketest-20251019
|
|
|
|
# Or delete existing branch first
|
|
git branch -D ui-smoketest-20251019
|
|
git worktree add -b ui-smoketest-20251019 /home/setup/navidocs-ui-test master
|
|
```
|
|
|
|
### Locked Worktree
|
|
|
|
**Error:**
|
|
```
|
|
fatal: 'remove' cannot be used with reason 'locked'
|
|
```
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Unlock worktree
|
|
git worktree unlock /home/setup/navidocs-ui-test
|
|
# Then remove
|
|
git worktree remove /home/setup/navidocs-ui-test
|
|
```
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
### 1. Descriptive Branch Names
|
|
|
|
Use date-stamped or feature-based names:
|
|
```bash
|
|
git worktree add -b ui-smoketest-20251019 /path/to/worktree master
|
|
git worktree add -b feature-search-v2 /path/to/worktree master
|
|
git worktree add -b bugfix-pdf-streaming /path/to/worktree master
|
|
```
|
|
|
|
### 2. Keep Worktrees Short-Lived
|
|
|
|
Remove worktrees after testing/development is complete:
|
|
```bash
|
|
# Merge changes
|
|
git merge ui-smoketest-20251019
|
|
|
|
# Clean up
|
|
git worktree remove /home/setup/navidocs-ui-test
|
|
git branch -d ui-smoketest-20251019
|
|
```
|
|
|
|
### 3. Sync Regularly
|
|
|
|
Keep test worktree in sync with master:
|
|
```bash
|
|
cd /home/setup/navidocs-ui-test
|
|
git fetch origin
|
|
git merge origin/master
|
|
```
|
|
|
|
### 4. Isolate Services
|
|
|
|
When running services in test worktree, use different ports:
|
|
```bash
|
|
# In test worktree's .env
|
|
PORT=8002 # Instead of 8001
|
|
CLIENT_PORT=5175 # Instead of 5174
|
|
```
|
|
|
|
### 5. Document Test Results
|
|
|
|
Always document findings in the worktree:
|
|
```bash
|
|
cd /home/setup/navidocs-ui-test
|
|
vim docs/testing/SMOKETEST_REPORT_20251019.md
|
|
git add docs/testing/SMOKETEST_REPORT_20251019.md
|
|
git commit -m "docs: add smoketest report for 2025-10-19"
|
|
```
|
|
|
|
---
|
|
|
|
## Advanced Usage
|
|
|
|
### Create Multiple Test Worktrees
|
|
|
|
```bash
|
|
# UI testing
|
|
git worktree add -b ui-test /home/setup/navidocs-ui-test master
|
|
|
|
# API testing
|
|
git worktree add -b api-test /home/setup/navidocs-api-test master
|
|
|
|
# Performance testing
|
|
git worktree add -b perf-test /home/setup/navidocs-perf-test master
|
|
```
|
|
|
|
### List All Worktrees with Details
|
|
|
|
```bash
|
|
git worktree list --porcelain
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
worktree /home/setup/navidocs
|
|
HEAD ff3c30687f0a6e8d9c2b1e4f5a6c7d8e9f0a1b2c
|
|
branch refs/heads/master
|
|
|
|
worktree /home/setup/navidocs-ui-test
|
|
HEAD ff3c30687f0a6e8d9c2b1e4f5a6c7d8e9f0a1b2c
|
|
branch refs/heads/ui-smoketest-20251019
|
|
```
|
|
|
|
### Prune Stale Worktrees
|
|
|
|
```bash
|
|
# Remove worktrees that no longer exist on disk
|
|
git worktree prune
|
|
```
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- **Git Worktree Documentation:** https://git-scm.com/docs/git-worktree
|
|
- **NaviDocs Testing Guide:** `/home/setup/navidocs/docs/testing/`
|
|
- **Smoketest Report:** `/home/setup/navidocs/docs/testing/SMOKETEST_REPORT_20251019.md`
|
|
|
|
---
|
|
|
|
**Document Version:** 1.0
|
|
**Created:** 2025-10-19
|
|
**Last Updated:** 2025-10-19
|
|
**Maintainer:** NaviDocs Development Team
|