Seth-Workflow-April-2026/rules/03-git-workflow.md

Git Workflow

Daily Workflow

Start Fresh

git checkout main
git pull origin main
git checkout -b feature/descriptive-name

Commit Frequently

Create a commit after ANY of these:

• Completing a single feature or function
• Fixing a bug (even small ones)
• Adding or modifying tests
• Updating documentation
• Before switching to a different task
• Every 15-30 minutes of active coding (at natural breakpoints)

When NOT to commit:

• Code doesn't run/compile
• Broken functionality
• Incomplete features with no clean boundary

Push for Backup

git push -u origin feature/branch-name    # First time
git push origin feature/branch-name       # Subsequent pushes

Branch Naming

feature/add-user-auth       # New features
bugfix/fix-login-error      # Bug fixes
hotfix/critical-security    # Urgent fixes
docs/update-readme          # Documentation
refactor/cleanup-database   # Code improvements

Conventional Commits

All commits MUST follow conventional commits:

<type>(<optional-scope>): <description>

[optional body]

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation
style	Formatting (no code change)
refactor	Code restructure (no behavior change)
test	Adding or updating tests
chore	Maintenance, dependencies
perf	Performance improvement
ci	CI/CD changes

Scope (optional)

Indicates the area affected:

feat(auth): Add password reset flow
fix(api): Handle timeout errors
test(auth): Add integration tests for login flow

Good Messages

git commit -m "feat: Add user authentication with JWT tokens"
git commit -m "fix: Resolve memory leak in image processing"
git commit -m "refactor: Extract validation into shared module"

Bad Messages

git commit -m "fix"           # Too vague
git commit -m "updates"       # Meaningless
git commit -m "WIP"           # Not descriptive
git commit -m "Fixed bug"     # Missing type prefix

Why Conventional Commits?

1. Automated changelogs — tools can categorize changes by type
2. Clear history — easy to understand what changed and why
3. Semantic versioning — feat = minor, fix = patch
4. Searchable — git log --grep="feat:" finds all features

Proactive Git Behavior

After completing a logical unit of work:

1. Run tests and linter (if configured)
2. Stage and commit with a conventional commit message
3. Inform the user: "I've committed this change: feat: ..."

If uncommitted changes accumulate, proactively suggest committing.

Team Collaboration

1. Never commit to main directly — always use feature branches
2. Always pull before push — git pull origin main first
3. Use meaningful branch names — not test, mywork, temp
4. Merge via Pull Requests — for code review and history

Recovery Commands

Uncommitted Changes

git status                    # See what changed
git checkout -- filename      # Restore single file
git stash                     # Temporarily save work
git stash pop                 # Restore saved work

Committed But Not Pushed

git reset --soft HEAD~1       # Undo commit, keep changes staged
git reset HEAD~1              # Undo commit, unstage changes

Already Pushed (Safe)

git revert HEAD               # Create undo commit
git push origin branch-name

Emergency Recovery

git reflog                    # See all actions (your safety net)
git checkout abc1234          # Go back to specific state

Danger Commands (Confirm Before Using)

git reset --hard HEAD         # Deletes all uncommitted work
git push --force              # Overwrites remote history
git branch -D branch-name     # Force delete branch