Skip to main content

Git Workflow

Complete Git workflow, configuration, and best practices for the Coditect AI IDE project.

Git Strategy​

User wants everything backed up with git. Always:

  1. Create meaningful commits - Describe what and why
  2. Use conventional commit format - feat:, fix:, docs:, refactor:, etc.
  3. Reference issues/ADRs in commits - Link to context
  4. Keep commits atomic - One logical change per commit

Git Configuration​

Repository Information​

Repository URL: https://github.com/coditect-ai/LM-Studio-multiple-llm-IDE.git

SSH Keys Location:

  • Path: /home/hal/v4/.ssh/
  • Private Key: /home/hal/v4/.ssh/id_ed25519
  • Public Key: /home/hal/v4/.ssh/id_ed25519.pub
  • SSH Agent: /home/hal/v4/.ssh/ssh-agent.sock

Remote Configuration​

Set Remote to SSH:

# SSH (configured)
git remote set-url origin git@github.com:coditect-ai/LM-Studio-multiple-llm-IDE.git

# Verify
git remote -v
# origin  git@github.com:coditect-ai/LM-Studio-multiple-llm-IDE.git (fetch)
# origin  git@github.com:coditect-ai/LM-Studio-multiple-llm-IDE.git (push)

Branch Configuration​

  • Main branch: main
  • Tracking: origin/main

Conventional Commit Format​

Commit Types​

TypeDescriptionExample
feat:New featurefeat: Add multi-session workspace support
fix:Bug fixfix: Resolve JWT token rotation issue
docs:Documentationdocs: Update architecture decision records
refactor:Code refactoringrefactor: Extract FDB repository patterns
test:Add/update teststest: Add integration tests for auth flow
chore:Maintenancechore: Update dependencies
style:Formattingstyle: Format code with prettier
perf:Performanceperf: Optimize FDB query patterns
ci:CI/CD changesci: Add Cloud Build validation
build:Build systembuild: Update Vite configuration

Commit Message Structure​

<type>(<scope>): <subject>

<body>

<footer>

Example:

feat(auth): Implement JWT token rotation

- Add token family tracking for multi-device support
- Implement refresh token rotation (30-day lifetime)
- Add session invalidation on logout

References: ADR-013, #123

Common Git Workflows​

Starting New Work​

# Pull latest changes
git pull origin main

# Create feature branch (if needed)
git checkout -b feature/my-feature

# Work on changes...

Committing Changes​

# Check status
git status

# Stage specific files
git add src/components/MyComponent.tsx
git add src/services/my-service.ts

# Or stage all changes
git add .

# Commit with message
git commit -m "feat(components): Add MyComponent with session support

- Implements session-aware component
- Integrates with sessionStore
- Adds TypeScript types

References: ADR-007"

Pushing Changes​

# Push to origin
git push origin main

# Or push feature branch
git push origin feature/my-feature

Creating Pull Requests​

# Push feature branch
git push origin feature/my-feature

# Create PR via GitHub CLI (if installed)
gh pr create --title "Add multi-session support" --body "Description..."

# Or create PR manually on GitHub

Working with Submodules​

The project includes 4 git submodules:

  1. .claude/agents-reference/ - 84 specialized agents
  2. .claude/commands-reference/ - 42 development tools
  3. archive/coditect-v4/ - V4 reference materials
  4. archive/agents-research-plan-code/ - Multi-llm research

Initialize Submodules​

# After cloning the repository
git submodule update --init --recursive

Update Submodules​

# Update all submodules to latest
git submodule update --remote

# Update specific submodule
git submodule update --remote .claude/agents-reference

Commit Submodule Changes​

# Submodule updates appear as changes
git add .claude/agents-reference
git commit -m "chore: Update agents-reference submodule"
git push origin main

Ignoring Files​

.gitignore Patterns​

Never commit:

  • .env files with secrets
  • node_modules/ directories
  • .coditect/logs/ log files
  • SSH keys (.ssh/id_ed25519)
  • API keys in any configuration

Safe to commit:

  • .env.example (template without secrets)
  • .gitignore itself
  • Configuration files (.claude/, docs/)

Example .gitignore​

# Dependencies
node_modules/
.pnp/

# Environment variables
.env
.env.local
.env.*.local

# Logs
.coditect/logs/
*.log

# IDE
.vscode/
.idea/

# Build
dist/
build/
.cache/

# OS
.DS_Store
Thumbs.db

# SSH Keys
.ssh/id_*
ssh-agent.sock

Advanced Git Operations​

Squashing Commits​

# Interactive rebase for last 3 commits
git rebase -i HEAD~3

# In editor, change 'pick' to 'squash' for commits to combine
# Save and exit

# Force push (use with caution)
git push --force-with-lease origin feature/my-feature

Cherry-Picking Commits​

# Pick specific commit from another branch
git cherry-pick <commit-hash>

# Pick multiple commits
git cherry-pick <commit1-hash> <commit2-hash>

Viewing History​

# Show commit history
git log --oneline --graph --all

# Show changes in commit
git show <commit-hash>

# Show file history
git log --follow -- path/to/file.ts

Undoing Changes​

# Discard uncommitted changes
git checkout -- path/to/file.ts

# Unstage file
git reset HEAD path/to/file.ts

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

Collaboration Best Practices​

Before Committing​

  1. Review changes: git diff
  2. Run tests: npm run type-check
  3. Lint code: Ensure code follows style guide
  4. Update docs: If API changes, update CLAUDE.md or ADRs

Code Review​

When reviewing pull requests:

  1. Check commit messages - Follow conventional commits
  2. Verify tests pass - All CI checks green
  3. Review code quality - TypeScript types, error handling
  4. Check for breaking changes - Document in PR description
  5. Verify ADRs - Major architectural changes need ADRs

Merging Strategy​

Main branch protection:

  • Require pull request reviews
  • Require status checks to pass
  • Require linear history (squash merges)
  • Restrict force pushes

Merge methods:

  • Squash and merge (preferred) - Clean linear history
  • Rebase and merge - For feature branches
  • Merge commit - For release branches only

Troubleshooting​

SSH Authentication Issues​

# Test SSH connection
ssh -T git@github.com

# Start SSH agent
eval "$(ssh-agent -s)"

# Add SSH key
ssh-add /home/hal/v4/.ssh/id_ed25519

# Verify key is loaded
ssh-add -l

Remote URL Issues​

# Check current remote
git remote -v

# Change to SSH
git remote set-url origin git@github.com:coditect-ai/LM-Studio-multiple-llm-IDE.git

# Verify
git remote -v

Submodule Issues​

# If submodules not initialized
git submodule update --init --recursive

# If submodule out of sync
git submodule sync
git submodule update --remote

# Reset submodule
git submodule deinit -f path/to/submodule
git submodule update --init path/to/submodule

Git Hooks​

Pre-commit Hook​

Create .git/hooks/pre-commit:

#!/bin/bash
# Run TypeScript type checking before commit

npm run type-check
if [ $? -ne 0 ]; then
  echo "Type check failed. Please fix errors before committing."
  exit 1
fi

echo "Pre-commit checks passed!"

Make it executable:

chmod +x .git/hooks/pre-commit

Commit Message Hook​

Create .git/hooks/commit-msg:

#!/bin/bash
# Validate commit message format

commit_msg=$(cat "$1")

# Check if commit message follows conventional commits
if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|refactor|test|chore|style|perf|ci|build)(\(.+\))?: .+"; then
  echo "Invalid commit message format!"
  echo "Use: <type>(<scope>): <subject>"
  echo "Example: feat(auth): Add JWT token rotation"
  exit 1
fi

Make it executable:

chmod +x .git/hooks/commit-msg

Back to: CLAUDE.md | DOCUMENTATION-index.md