Git Workflow Guide

Overview

This guide outlines our Git workflow standards and best practices for all Tresor projects. Following these guidelines ensures code quality, collaboration efficiency, and maintainable project history.

Branch Strategy

We follow a modified Git Flow strategy:

Main Branches

main - Production-ready code
develop - Integration branch for features

Supporting Branches

feature/* - New features
hotfix/* - Emergency fixes for production
release/* - Release preparation
bugfix/* - Bug fixes for develop branch

Branch Naming Conventions

feature/JIRA-123-user-authentication
bugfix/JIRA-456-fix-login-error
hotfix/JIRA-789-critical-security-patch
release/v1.2.0

Workflow Steps

1. Starting a New Feature

# Update develop branch
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/JIRA-123-feature-name

# Work on your feature
git add .
git commit -m "feat: add user authentication"

2. Commit Message Format

We follow the Conventional Commits specification:

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

<body>

<footer>

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks
perf: Performance improvements

Examples

# Feature
git commit -m "feat(auth): add OAuth2 integration"

# Bug fix
git commit -m "fix(api): resolve null pointer exception in user service"

# Documentation
git commit -m "docs(readme): update installation instructions"

# With body and footer
git commit -m "feat(payment): add Stripe payment integration

- Add Stripe SDK integration
- Implement payment processing service
- Add webhook handlers for payment events

BREAKING CHANGE: Payment API endpoints have been restructured
Closes #123"

3. Pull Request Process

Creating a Pull Request

Push your feature branch

git push origin feature/JIRA-123-feature-name

Create PR on GitHub/GitLab with:
- Descriptive title
- Link to JIRA ticket
- Description of changes
- Screenshots (if UI changes)
- Testing instructions

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
- JIRA-123

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Screenshots
(if applicable)

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No console.logs or debug code

4. Code Review

For Reviewers

Check code quality and standards
Verify business logic
Test the changes locally
Look for security issues
Ensure proper error handling
Check for performance impacts

For Authors

Respond to all comments
Make requested changes promptly
Re-request review after changes
Keep PR updated with develop

5. Merging

Merge Strategy

Feature to Develop: Squash and merge
Develop to Main: Merge commit
Hotfix to Main: Merge commit

Pre-merge Checklist

[ ] All CI/CD checks pass
[ ] Code review approved
[ ] No merge conflicts
[ ] Documentation updated
[ ] JIRA ticket updated

Advanced Git Commands

Interactive Rebase

# Clean up commit history before PR
git rebase -i HEAD~3

# Options:
# pick - keep commit
# reword - change commit message
# squash - combine with previous
# drop - remove commit

Cherry Picking

# Apply specific commit to current branch
git cherry-pick <commit-hash>

Stashing

# Save work temporarily
git stash save "work in progress"

# List stashes
git stash list

# Apply stash
git stash pop

Resetting

# Soft reset (keep changes)
git reset --soft HEAD~1

# Hard reset (discard changes)
git reset --hard HEAD~1

Handling Conflicts

Merge Conflicts

# Update your branch
git checkout feature/your-branch
git pull origin develop

# Resolve conflicts in files
# Then:
git add .
git commit -m "resolve merge conflicts"

Rebase Conflicts

# Start rebase
git rebase develop

# Resolve conflicts, then:
git add .
git rebase --continue

# Or abort:
git rebase --abort

Git Hooks

We use pre-commit hooks for:

Code formatting
Linting
Running tests
Commit message validation

Setup

# Install hooks
npm install husky --save-dev
npx husky install

# Add pre-commit hook
npx husky add .husky/pre-commit "npm run lint"

Best Practices

Do's

✅ Commit early and often
✅ Write meaningful commit messages
✅ Keep commits atomic
✅ Pull latest changes before starting work
✅ Test before committing
✅ Use .gitignore properly

Don'ts

❌ Don't commit sensitive information
❌ Don't commit large binary files
❌ Don't force push to shared branches
❌ Don't commit directly to main/develop
❌ Don't commit commented-out code
❌ Don't commit console.logs

Troubleshooting

Common Issues

Accidental Commit to Wrong Branch

# Move commit to correct branch
git checkout correct-branch
git cherry-pick <commit-hash>
git checkout wrong-branch
git reset --hard HEAD~1

Undo Last Commit

# Keep changes
git reset --soft HEAD~1

# Discard changes
git reset --hard HEAD~1

Clean Up Local Branches

# Delete merged branches
git branch --merged | grep -v "\*" | xargs -n 1 git branch -d

# Delete remote tracking branches
git remote prune origin

Git Aliases

Add to ~/.gitconfig:

[alias]
    co = checkout
    br = branch
    ci = commit
    st = status
    unstage = reset HEAD --
    last = log -1 HEAD
    visual = !gitk
    lg = log --oneline --graph --decorate