GitLab Branching Basics

A branch is an independent line of development inside your repository. You create a branch when you want to build a feature or fix a bug without disturbing the working code that everyone else relies on.

Why Branches Exist — The Book Analogy

  Imagine a shared book that everyone on your team edits.

  WITHOUT branches:
  Author A and Author B both edit Chapter 3 at the same time.
  One person's work gets erased. ❌

  WITH branches:
  Author A works on branch "chapter3-rewrite"
  Author B works on branch "chapter3-illustrations"
  Both finish their work independently, then combine it. ✅

The Main Branch

Every repository starts with one branch called main (older projects may call it master). This branch holds the official, stable version of the code. All other branches branch off from here and eventually merge back in.

  main ─────●─────────────────●──────▶ (always stable)
             \               /
    feature   ●───●───●───●          (work in progress)

Creating a Branch

From the GitLab Interface

Open your project, click the branch dropdown (it shows "main" by default), type a new branch name, and press Enter. GitLab creates the branch from the current state of main.

From the Terminal

  git checkout -b feature/add-search-bar

This command creates the branch and switches to it immediately. The -b flag means "create and switch".

Branch Naming Conventions

Good branch names describe what the branch does. Most teams follow a pattern:

Working on a Branch

After switching to your branch, every commit you make stays on that branch. The main branch is completely unaffected.

  Step 1: Switch to your branch
  git checkout feature/add-search-bar

  Step 2: Make changes to files

  Step 3: Stage and commit
  git add .
  git commit -m "Add search bar to header"

  Step 4: Push the branch to GitLab
  git push origin feature/add-search-bar

Viewing All Branches

In GitLab, go to Repository → Branches. Each branch shows:

• The branch name
• How many commits it is ahead of or behind main
• The last commit message and date
• A button to create a merge request

  Branch Name              Status              Last Activity
  ───────────────────────────────────────────────────────────
  main                     default             1 hour ago
  feature/add-search-bar   2 ahead of main     30 min ago
  fix/login-error          5 ahead, 1 behind   2 hours ago

Switching Between Branches

Use the terminal to switch to a branch that already exists:

  git checkout main                     ← switch to main
  git checkout feature/add-search-bar   ← switch to feature branch

Or use the modern syntax:

  git switch main
  git switch feature/add-search-bar

Merging a Branch

When your work is complete and tested, you merge the branch back into main. In GitLab, you do this through a Merge Request (covered in the next topic). From the terminal:

  git checkout main
  git merge feature/add-search-bar

Merge Conflicts — When Two Changes Clash

A merge conflict happens when two branches change the same line of the same file differently. Git cannot decide which version to keep, so it asks you to choose.

  Branch A changes line 10:  background-color: blue;
  Branch B changes line 10:  background-color: red;

  Git marks the conflict:
  ───────────────────────────────
  <<<<<<< HEAD (main)
  background-color: blue;
  =======
  background-color: red;
  >>>>>>> feature/new-theme
  ───────────────────────────────
  You delete the markers and keep the correct line, then commit.

Deleting a Branch After Merge

Once a branch is merged, it has served its purpose. Delete it to keep the branch list clean. GitLab shows a Delete branch button right after a merge request closes. From the terminal:

  git branch -d feature/add-search-bar         ← delete locally
  git push origin --delete feature/add-search-bar  ← delete on GitLab

Protected Branches

Admins can protect the main branch so that no one can push directly to it. All changes must come through a reviewed and approved merge request. This prevents accidental or untested code from reaching production.

  Protected branch rules example:
  ─────────────────────────────────────────────────────
  Branch: main
  Allowed to push:   No one
  Allowed to merge:  Maintainers only
  Require approval:  At least 1 reviewer must approve
  ─────────────────────────────────────────────────────

Go to Settings → Repository → Protected Branches to configure these rules.

The GitFlow Branching Model

GitFlow is a popular branching strategy used by many teams. It defines specific branches for specific purposes:

  main       → production-ready code only
  develop    → integration branch for completed features
  feature/*  → individual features (branch from develop)
  release/*  → preparing for a new version
  hotfix/*   → emergency fixes on production

Small teams often use a simpler model — just main plus short-lived feature branches — which works well for most projects.