dannystocker/navidocs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
navidocs/docs/testing/WORKTREE_SETUP.md
ggq-admin 4b91896838 feat: Add image extraction design, database schema, and migration 
- 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>
2025-10-19 19:47:30 +02:00

7.6 KiB
Raw Export PDF Permalink Blame History

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

/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

# 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

# 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

cd /home/setup/navidocs-ui-test

Step 4: Verify Branch

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:

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:

# 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:

# 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:

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

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

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

# 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

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

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)

cd /home/setup/navidocs

# Remove worktree (keeps branch)
git worktree remove /home/setup/navidocs-ui-test

Delete Test Branch (After Merging)

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

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:

# 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:

# 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:

# 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:

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:

# 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:

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:

# 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:

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

# 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

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

# 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