Skip to content

Version Control Setup

Version control is the memory of your project. It records every change, protects you from mistakes, and lets teams work in parallel without chaos.
Git is the tool we use to manage this memory — like a shared timeline where everyone’s work meets, merges, and sometimes collides.

Glossary

Repository (Repo) – The central folder that stores all your code history.
Commit – A snapshot of your code at a moment in time.
Branch – A separate line of development, like a parallel universe where you can experiment safely.
Merge – Combining one branch’s changes into another.
Rebase – Rewriting history to make a branch look like it started later (advanced).
Tag – A label for a specific commit, often marking a release.
Remote – The online copy of your repo (GitLab).
Push / Pull / Fetch – Send your work to the remote / bring new work down / update local metadata.
Main / Dev – The long-lived, stable branches everyone relies on.
Feature Branch – A short-lived branch for adding or fixing something specific.
Merge Request (MR) – A proposal to merge changes back into a main branch.

Branching Model — The Shape of Your History

Your branching model defines how the team’s work flows. Without one, everyone pushes wherever they want — and Git history becomes spaghetti.

Tip

Think of branches like workstations in a factory.
main is the showroom, dev is the workshop, feature/* are personal benches.
Keep them organized so products move smoothly from idea to delivery.

Good habits:

  • Have two or three main branches only (e.g. main, dev, maybe release/*).
  • Use consistent names for temporary branches (feature/…, bugfix/…, docs/…).
  • Include issue IDs if possible (123-fix-login) — GitLab auto-links them.
  • Clean up merged branches regularly.

Danger

Never work directly on main.
Treat it as the “safe version” your team can always fall back to.

Visualize your model in a diagram or screenshot. A picture helps new members understand in 10 seconds what takes paragraphs to explain.

Commit Message Style — Clear Communication

Commits are your team’s diary entries. They should explain what happened and why — not just “fix stuff”.

A good commit tells:

  • What changed — short summary, imperative form (“Add”, “Fix”, “Refactor”).
  • Why it changed — the reason or context.
  • Optionally how it changed — key approach or technique.

Example

1
2
3
4
5
feat(login): add session timeout warning

Added auto-logout after 15 minutes of inactivity.
Helps avoid forgotten logins on shared computers.
Fixes #42

Use Conventional Commits (type(scope): summary) if possible — they make automation and changelogs easier.
Common types: feat, fix, docs, refactor, test, chore.

Tip

Keep each commit small and focused: one logical change per commit.
Large “mixed” commits make debugging painful later.

Danger

Avoid vague messages like “update code” or “fix bugs.”
They tell future you nothing about what actually happened.

Push and Commit Policies — Team Safety Rules

Good Git habits protect the project from losing work or breaking the main line.
These rules are like driving etiquette: they prevent collisions.

Key ideas:

  • Commit early, push smart. Work locally often, but push when it’s tested or when you need review.
  • Never push broken code to shared branches.
  • Protect main and dev from direct pushes. Only merge through reviewed MRs.
  • Link commits to issues (Fixes #123) to keep traceability.

Tip

Use “Draft” or “WIP” merge requests when your feature is still in progress.
This invites early feedback without breaking builds.

Example

Policy example, you should understand them, but you may not adopt all of them:

  • Squash commits when merging to main (clean history, but considered advenced, and loose some of the low level details of commits).
  • Rebase feature branches before merging.
  • Delete old branches weekly.

Danger

Never commit secrets (API keys, passwords, tokens).
Add .gitignore and .gitattributes to keep binaries and sensitive files out.

When pipelines fail (red status), the last committer fixes it immediately.
Everyone depends on a green pipeline — treat it as a team responsibility.

Tooling — How You Interact with Git

Different teammates prefer different interfaces: CLI, IDE plugin, or GUI tools like GitKraken or SourceTree.
That’s fine — but you must speak the same language.

Info

Agree on shared vocabulary: “pull”, “fetch + rebase”, “merge”, “checkout” —
everyone should understand what those mean, even if they click or type them differently.

Understand Git Concepts First

Before picking tools, ensure everyone understands core Git concepts (branches, commits, merges).
Tools are just interfaces — the underlying ideas remain the same.

Yous should not race in F1 cars without knowing how to drive first. We suggest starting with Git CLI to learn the basics.

Best practices:

  • Record your main tool choice in the README.
  • Configure your Git identity correctly (user.name, user.email).
  • Commit a sample .gitconfig.example with useful aliases and color settings.
  • Test cloning, authentication (HTTPS), and diff tools on all OSes.

Tip

Visual diff and merge tools (like meld or VS Code diff) help beginners understand conflicts faster.
Configure one early.

For shared learning, create a short “Cross-Tool Cheat Sheet” listing how GUI actions map to Git commands. Assuming you already have a basic understanding of Git commands.

Putting It All Together

A strong version control setup helps your team:

  • Work in parallel without stepping on each other’s toes.
  • Review and merge changes safely.
  • Recover from mistakes easily.
  • Understand why and how the code evolved.

Quote

“Good Git hygiene is invisible — until bad Git hygiene costs you hours.”

Your team’s goal is not to memorize commands but to understand workflows.
Every choice — branch model, commit style, push policy, or tool — should make collaboration faster, not harder.