git-workshop/03_BEST-PRACTICES.md

Best Practices for Cloud-Based Git Collaboration

When multiple people work on the same project, merge conflicts are inevitable. But with good habits, you can dramatically reduce how often they happen and how painful they are to resolve.

Pull Early, Pull Often

The most common cause of merge conflicts is working on outdated code. The longer you work without syncing, the more your code drifts from what others are doing.

Do this:

# Start every work session by pulling
git pull

# Pull again before pushing
git pull
git push

Why it works: Small, frequent syncs mean small, manageable conflicts. A conflict in 3 lines is easy to fix. A conflict in 300 lines is a nightmare.

Keep Commits Small and Focused

Large commits that touch many files are conflict magnets.

Instead of this:

"Implemented user authentication, fixed navbar, updated styles, refactored database"

Do this:

"Add login form to auth page"
"Add password validation"
"Connect login form to auth API"
"Add logout button to navbar"

Why it works:

• Smaller changes = smaller chance of overlap with others
• If a conflict does happen, it's easier to understand and resolve
• Easier to review, revert, or cherry-pick specific changes

Communicate About Shared Files

Some files are conflict hotspots because everyone needs to edit them:

• Configuration files
• Route definitions
• Database schemas
• Shared constants or types

Do this:

• Tell your team when you're editing shared files
• Make those changes in dedicated commits
• Push changes to shared files quickly - don't let them sit

Use Short-Lived Branches

Long-running branches drift further from the main branch every day.

main:     A───B───C───D───E───F───G───H
                \
feature:         X───────────────────────Y
                 (2 weeks of drift = painful merge)

Better approach:

main:     A───B───C───D───E───F───G───H
              \       \       \
feature:       X───────Y───────Z
               (merge main frequently)

Do this:

• Merge main into your branch regularly (daily if active)
• Keep features small enough to complete in days, not weeks
• Break large features into smaller incremental changes

Organize Code to Minimize Overlap

How you structure your code affects how often people collide.

Conflict-prone structure:

src/
  app.py           # 2000 lines, everyone edits this
  utils.py         # 500 lines of mixed utilities

Better structure:

src/
  auth/
    login.py
    logout.py
  users/
    profile.py
    settings.py
  utils/
    dates.py
    strings.py

Why it works: When each file has a clear purpose, different team members naturally work in different files.

Avoid Reformatting Wars

Nothing creates unnecessary conflicts like two people reformatting the same file differently.

Do this:

• Agree on code formatting standards as a team
• Use automatic formatters (Prettier, Black, clang-format, etc.)
• Configure your editor to format on save
• Run formatters before committing

Important: If you need to reformat a file, do it in a dedicated commit with no other changes. This keeps the reformatting separate from your actual work.

Coordinate Large Refactors

Renaming a widely-used function or moving files around will conflict with almost everyone's work.

Do this:

• Announce refactors to the team before starting
  • This is important to coordinate merges of features that are being worked before the great refactoring. A large renaming of namespaces or moving of files becomes hard to deal with when you rely on the old file-structure before the great merge. Instead you should freeze any further features until the great refactoring has been completed and then resume feature-building
• Do them quickly and push immediately
• Consider doing them when others aren't actively working
• Keep refactoring commits separate from feature work This keeps your commits clean and doesn't dirty the actual work with actual feature work (which also makes it easy to cherry-pick while minimizing conflicts).

The Golden Rules

1. Sync frequently - Pull before you start, pull before you push
2. Commit small - Many small commits beat one large commit A way to think of it is to keep commit atomic. In other words try to make them self-contained units that are easy to cherry-pick at a later time.
3. Talk to your team - A quick message prevents hours of conflict resolution Communication is key. Even though alot is delegated to the process itself, it's still a good idea to keep communicating with the team regarding larger changes or features being built.
4. Stay focused - One branch = one purpose (and ususally one person)
5. Push promptly - Don't sit on finished work

When Conflicts Do Happen

Even with best practices, conflicts will occur. When they do:

1. Don't panic - Conflicts are normal, not failures
2. Read carefully - Understand both sides before choosing
3. Test after resolving - Make sure the merged code actually works. A usual, and rather basic test flow is build -> test -> run
4. Ask if unsure - If you don't understand the other person's code, ask them

Remember: merge conflicts are a communication problem as much as a technical one. The best tool for reducing conflicts is talking to your team.