Git Workflow

Strict worktree-based workflow ensuring main branch integrity and isolated development environments.

Critical Rules

• NEVER commit to main — protected branch, pre-commit hook enforces
• NEVER git checkout in main repo — use git worktree for ALL feature work
• Main repo MUST always stay on main branch

Branch Naming

Format: <prefix>-issue-<number>-<description> or <prefix>-<description>

Prefix	Purpose
feat-	New features
fix-	Bug fixes
chore-	Maintenance tasks
hotfix-	Urgent production fixes
docs-	Documentation
refactor-	Code restructuring
test-	Test additions

Dashes not slashes — allows using the same name for worktree folder and branch.

Worktree Workflow

# 1. Create worktree
git worktree add ./worktrees/<name> -b <branch>
 
# 2. Sync with main
git fetch origin && git merge origin/main
 
# 3. Setup and start
cd renewa-one && make dev-init    # See [[Makefile Commands]]
 
# 4. Implement + quality checks
make typecheck && make lint && make test
 
# 5. Push + create PR
git push origin <branch> && gh pr create --draft

Quick start: ./scripts/issue-to-worktree.sh <issue-number> "<description>" (see Scripts)

Pre-Push Conflict Check

MANDATORY before every git push:

git fetch origin main && git merge origin/main

Never push a branch that would show merge conflicts on GitHub.

Git Hooks (Two-Tier)

Hook	Speed	Checks
Pre-commit	~5s	Format + lint staged files, i18n parity, LocalizedText validation, migration consistency, block main
Pre-push	Thorough	Conflict check, changelog fragment check, full typecheck, affected tests

Hooks installed via scripts/setup-git-hooks.sh. See Scripts for details.

Branch Protection (GitHub Ruleset)

Rule	Purpose
required_status_checks (ci-gate)	CI must pass
pull_request	PRs required, stale reviews dismissed
required_linear_history	Squash merges only
non_fast_forward	No force pushes to main
deletion	Cannot delete main

PR Rules

• Title format: Add payment integration (#123) (with issue) or Add user authentication system (without)
• Corrections: Never create new branches — reuse existing branch/worktree
• Squash merges only

Changelog Fragments

Required for PRs changing frontend/src/, backend/, or shared/:

• Location: renewa-one/frontend/changelog/{de,en}/<branch-name>.md
• Exempt prefixes: chore-, docs-, test-, refactor-
• Enforced by pre-push hook + [[CI-CD Workflows|CI changelog-check job]]

Cleanup

After PR merge: ./scripts/cleanup-merged-worktrees.sh (--dry-run to preview, --auto for no-prompt)

See Also

• CI-CD Workflows — automated checks on push/PR
• Makefile Commands — quality check commands
• Scripts — hook installation and worktree management
• Coding Guidelines — code standards enforced by hooks