Version Control Best Practices | Git Workflows
Master Git workflows for teams. Branching strategies, commit conventions, PR practices, and merge strategies. GitScrum links commits to tasks.
9 min read
Version control is the foundation of collaborative development—it enables teams to work on code simultaneously, track changes, and coordinate releases. GitScrum integrates directly with GitHub and GitLab to connect commits, branches, and pull requests to tasks, creating full traceability from idea to deployment. The right branching strategy and commit practices make the difference between smooth collaboration and merge conflict chaos.
Branching Strategies
| Strategy | Complexity | Best For |
|---|---|---|
| Trunk-based | Low | Continuous deployment |
| GitHub Flow | Low | Regular releases |
| GitFlow | High | Scheduled releases |
| Forking | Medium | Open source |
Branching Workflows
BRANCHING STRATEGIES COMPARISON
TRUNK-BASED DEVELOPMENT:
┌─────────────────────────────────────────────────┐
│ main ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ ╲ ╱ ╲ ╱ ╲ ╱ │
│ ┊ ┊ ┊ │
│ (small, short-lived branches) │
│ │
│ Characteristics: │
│ ├── Small, frequent commits to main │
│ ├── Feature flags for incomplete work │
│ ├── Branches live < 1 day │
│ └── Continuous integration essential │
│ │
│ Best for: Continuous deployment teams │
└─────────────────────────────────────────────────┘
GITHUB FLOW:
┌─────────────────────────────────────────────────┐
│ main ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ ╲ ╱ ╲ ╱ │
│ ╲────────╱ ╲────────╱ │
│ feature-x feature-y │
│ │
│ Workflow: │
│ 1. Branch from main │
│ 2. Commit to branch │
│ 3. Open PR when ready │
│ 4. Review and discuss │
│ 5. Merge to main │
│ 6. Deploy from main │
│ │
│ Best for: Simple, regular release cycles │
└─────────────────────────────────────────────────┘
GITFLOW:
┌─────────────────────────────────────────────────┐
│ main ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ ╲ ╱ │
│ develop ─────────●─────────●───────── │
│ ╱ ╲ ╱ │
│ feature-a feature-b │
│ ╲ │
│ release/1.0 │
│ ╲ │
│ hotfix ─────────────────────●──── │
│ │
│ Branches: │
│ ├── main: Production code │
│ ├── develop: Integration branch │
│ ├── feature/*: New features │
│ ├── release/*: Release preparation │
│ └── hotfix/*: Production fixes │
│ │
│ Best for: Scheduled releases, versioned │
└─────────────────────────────────────────────────┘
Branch Naming
BRANCH NAMING CONVENTIONS
STRUCTURE:
┌─────────────────────────────────────────────────┐
│ type/description │
│ type/issue-description │
│ │
│ Examples: │
│ ├── feature/user-authentication │
│ ├── feature/GS-123-export-csv │
│ ├── fix/login-timeout-error │
│ ├── fix/GS-456-missing-validation │
│ ├── refactor/simplify-payment-flow │
│ ├── docs/api-documentation │
│ └── chore/update-dependencies │
└─────────────────────────────────────────────────┘
TYPES:
┌─────────────────────────────────────────────────┐
│ feature/ - New features │
│ fix/ - Bug fixes │
│ hotfix/ - Urgent production fixes │
│ refactor/ - Code refactoring │
│ docs/ - Documentation │
│ chore/ - Maintenance tasks │
│ test/ - Test additions │
│ release/ - Release preparation │
└─────────────────────────────────────────────────┘
RULES:
┌─────────────────────────────────────────────────┐
│ ✓ Lowercase only │
│ ✓ Hyphens to separate words │
│ ✓ Include ticket number if applicable │
│ ✓ Descriptive but concise │
│ │
│ ✗ feature/NewUserAuthenticationSystem │
│ ✓ feature/user-auth │
└─────────────────────────────────────────────────┘
Commit Messages
COMMIT MESSAGE CONVENTIONS
CONVENTIONAL COMMITS FORMAT:
┌─────────────────────────────────────────────────┐
│ type(scope): subject │
│ │
│ [optional body] │
│ │
│ [optional footer] │
└─────────────────────────────────────────────────┘
TYPES:
┌─────────────────────────────────────────────────┐
│ feat: New feature │
│ fix: Bug fix │
│ docs: Documentation only │
│ style: Formatting (no code change) │
│ refactor: Code change (no feature/fix) │
│ perf: Performance improvement │
│ test: Adding/fixing tests │
│ chore: Build, tools, dependencies │
│ ci: CI configuration │
│ revert: Reverting previous commit │
└─────────────────────────────────────────────────┘
GOOD COMMIT MESSAGES:
┌─────────────────────────────────────────────────┐
│ feat(auth): add password reset functionality │
│ │
│ fix(api): handle null response from payment │
│ │
│ refactor(dashboard): simplify chart rendering │
│ │
│ docs(readme): update installation instructions │
│ │
│ feat(export): add CSV export for reports │
│ │
│ Implements export functionality requested in │
│ GS-123. Supports date filtering and column │
│ selection. │
│ │
│ Closes #123 │
└─────────────────────────────────────────────────┘
BAD COMMIT MESSAGES:
┌─────────────────────────────────────────────────┐
│ ✗ "fix" │
│ ✗ "WIP" │
│ ✗ "updates" │
│ ✗ "fixed bug" │
│ ✗ "changed stuff" │
│ ✗ "asdfjkl" │
│ ✗ "please work" │
└─────────────────────────────────────────────────┘
Pull Requests
PULL REQUEST BEST PRACTICES
PR SIZE:
┌─────────────────────────────────────────────────┐
│ Ideal PR size: │
│ ├── < 400 lines of code changes │
│ ├── Single focused purpose │
│ ├── Reviewable in 30-60 minutes │
│ │
│ Large PRs cause: │
│ ├── Slower reviews │
│ ├── More bugs missed │
│ ├── Review fatigue ("LGTM") │
│ └── Merge conflicts │
│ │
│ Break large work into stacked PRs │
└─────────────────────────────────────────────────┘
PR DESCRIPTION TEMPLATE:
┌─────────────────────────────────────────────────┐
│ ## What │
│ Brief description of changes │
│ │
│ ## Why │
│ Context and motivation │
│ │
│ ## How │
│ Implementation approach │
│ │
│ ## Testing │
│ How was this tested? │
│ │
│ ## Screenshots (if UI) │
│ Before/after if applicable │
│ │
│ ## Checklist │
│ - [ ] Tests added/updated │
│ - [ ] Documentation updated │
│ - [ ] No console.logs │
│ │
│ Closes #123 │
└─────────────────────────────────────────────────┘
REVIEW WORKFLOW:
┌─────────────────────────────────────────────────┐
│ 1. Author creates PR with description │
│ 2. CI runs (tests, linting) │
│ 3. Reviewers assigned automatically or │
│ manually │
│ 4. Reviewers comment within 24 hours │
│ 5. Author addresses feedback │
│ 6. Approval(s) obtained │
│ 7. Author merges (squash/merge/rebase) │
│ 8. Branch deleted │
└─────────────────────────────────────────────────┘
Merge Strategies
MERGE STRATEGIES
MERGE COMMIT:
┌─────────────────────────────────────────────────┐
│ main ─────●─────────────●──── │
│ ╲ ╱ │
│ ●───●───●───● │
│ feature branch │
│ │
│ Pros: │
│ ├── Preserves all history │
│ ├── Easy to see branch context │
│ └── Can revert entire feature │
│ │
│ Cons: │
│ ├── History can be messy │
│ └── Many merge commits │
└─────────────────────────────────────────────────┘
SQUASH AND MERGE:
┌─────────────────────────────────────────────────┐
│ main ─────●─────────────●──── │
│ ╲ ╱ │
│ ●───●───●───● → squashed to 1 │
│ │
│ Pros: │
│ ├── Clean, linear history │
│ ├── One commit per feature │
│ └── Easy to understand main history │
│ │
│ Cons: │
│ ├── Loses individual commit context │
│ └── Can't bisect within feature │
└─────────────────────────────────────────────────┘
REBASE AND MERGE:
┌─────────────────────────────────────────────────┐
│ main ─────●─────────────●───●───●───●─── │
│ (rebased commits) │
│ │
│ Pros: │
│ ├── Linear history │
│ ├── Preserves individual commits │
│ └── Clean and detailed │
│ │
│ Cons: │
│ ├── Rewrites history │
│ ├── Can cause issues if misused │
│ └── Loses merge context │
└─────────────────────────────────────────────────┘
RECOMMENDATION:
┌─────────────────────────────────────────────────┐
│ Most teams do well with: │
│ ├── Squash for feature branches │
│ ├── Merge for release/long-lived branches │
│ └── Pick one approach and be consistent │
└─────────────────────────────────────────────────┘
Git Workflow Tips
DAILY GIT PRACTICES
STAY CURRENT:
┌─────────────────────────────────────────────────┐
│ # Start of day: update main │
│ git checkout main │
│ git pull origin main │
│ │
│ # Rebase branch on latest main │
│ git checkout feature-branch │
│ git rebase main │
│ │
│ # Or merge main into branch │
│ git checkout feature-branch │
│ git merge main │
│ │
│ Avoid diverging too far from main │
└─────────────────────────────────────────────────┘
COMMIT OFTEN:
┌─────────────────────────────────────────────────┐
│ ✓ Commit when you have a working change │
│ ✓ Commit before trying something risky │
│ ✓ Commit at end of day (WIP if needed) │
│ │
│ Small commits: │
│ ├── Easier to review │
│ ├── Easier to revert │
│ ├── Better bisect debugging │
│ └── More granular history │
└─────────────────────────────────────────────────┘
CLEAN UP BEFORE PR:
┌─────────────────────────────────────────────────┐
│ Before opening PR: │
│ ├── Rebase on latest main │
│ ├── Squash WIP commits if desired │
│ ├── Write good commit messages │
│ ├── Remove debug code │
│ └── Run tests locally │
│ │
│ # Interactive rebase to clean up │
│ git rebase -i main │
└─────────────────────────────────────────────────┘
Handling Conflicts
MERGE CONFLICT RESOLUTION
PREVENTING CONFLICTS:
┌─────────────────────────────────────────────────┐
│ ├── Small, frequent merges │
│ ├── Communicate with team │
│ ├── Update branch regularly │
│ ├── Keep PRs small │
│ └── Avoid long-lived branches │
└─────────────────────────────────────────────────┘
RESOLVING CONFLICTS:
┌─────────────────────────────────────────────────┐
│ 1. Understand both changes │
│ 2. Communicate with other author if needed │
│ 3. Choose correct resolution │
│ 4. Test thoroughly after resolving │
│ 5. Commit resolution with clear message │
│ │
│ # Conflict markers │
│ <<<<<<< HEAD │
│ your changes │
│ ======= │
│ their changes │
│ >>>>>>> feature-branch │
│ │
│ Remove markers, keep correct code │
└─────────────────────────────────────────────────┘
Best Practices
Anti-Patterns
✗ Long-lived branches
✗ Cryptic commit messages
✗ Giant PRs (1000+ lines)
✗ Merging without review
✗ Force pushing to shared branches
✗ Committing to main directly