Git Branching Workflow

Compare common branching models and choose one that matches team size, release cadence, and review needs.

A model is a contract, not a Git command

Git Branch already taught the pointer: a name that moves with new commits. A branching model is the team agreement about which names exist, how long they live, and how they return to the default branch. Git will create any name you type. It will not tell you whether that name belongs in this repository.

# These are Git. None of them selects GitHub Flow, trunk-based, or Git Flow.
git switch -c feature/search
git merge feature/search
git rebase origin/main

GitHub Code Review assumed a feature branch and a reviewed merge. This lesson names that path as a model, compares two others, and makes you write the choice down so the next person does not invent a second default branch.

GitHub Flow

GitHub Flow is the shape this course has already been using: update main, branch for one intention, open a pull request, review, merge, delete the branch. main is always releasable in principle. There is no long-lived develop.

Two Clone Sync pushed to main because the job was two working copies sharing history. That was Git sync, not GitHub Flow. Once review exists, main moves through a pull request.

Trunk-based development

Trunk-based development also treats one branch as the source of truth—usually main, called the trunk. The difference is cadence. Changes are tiny. Branches last hours, or you commit to the trunk behind a flag. Integration is constant, so merge conflicts stay small.

Git Flow names, not Git objects

Git Flow is a popular naming scheme: main for supported releases, develop for integration, feature/* off develop, release/* when you cut a version, hotfix/* off main. Every one of those is an ordinary Git branch. Git does not create them at git init. GitHub does not add them when you click Create repository.

Choose by size, cadence, and review

Pick a model you can defend in one paragraph. Write it in the repository. Do not mix a silent develop into GitHub Flow “just in case.”

Run one short-lived branch

Start from an up-to-date main. One branch, one document: the model itself. Push the branch. Open a pull request the way GitHub Pull Requests already taught. Do not commit the workflow note on main first and then try to invent a model around it.

# Branching model

This repository uses GitHub Flow.

- Default branch: main
- A change lives on a short-lived feature branch
- The branch returns through a GitHub pull request, then is deleted
- Do not commit review work on main
- Do not keep a long-lived develop branch

# From a clone of a GitHub repository YOU own
git switch main
git pull origin main
git switch -c feature/workflow-note

# Add WORKFLOW.md with the model this repo actually uses, then:
git add WORKFLOW.md
git diff --cached
git commit -m "Document the branching model this repository uses"
git push -u origin feature/workflow-note

git push -u origin feature/workflow-note publishes the branch. GitHub still has the same main until the pull request merges. That is GitHub Flow in one move: the default branch did not absorb the work yet.

Retire the branch after merge

After GitHub merges, fetch and update local main. Then delete the feature name locally and on origin. A short-lived branch that survives merge is a long-lived branch you did not admit.

# After the pull request is merged on GitHub
git fetch origin
git switch main
git pull origin main
git branch --merged main
git branch -d feature/workflow-note
git push origin --delete feature/workflow-note
git log --oneline --decorate --graph -n 8

git branch -d feature/workflow-note refuses if the branch is not an ancestor of the current branch—usually because you have not updated main yet. Update first, then delete. git push origin --delete feature/workflow-note removes the GitHub branch name. It does not delete the commits that already landed on main.

git branch --merged main lists names whose tips are already in main. Use it to catch leftover feature branches. Do not delete main.

What not to invent

Guided practice: name the model

1. 01
   Pick a repository you own

   Confirm git remote -v is your GitHub URL. git switch main and git pull origin main.

2. 02
   Write the contract

   On feature/workflow-note, add WORKFLOW.md that names GitHub Flow, the default branch, the pull-request return path, and why Git Flow is not in use here.

3. 03
   Open the pull request

   git push -u origin feature/workflow-note, then gh pr create as you already can. Keep the diff to that file.

4. 04
   Merge, then retire the branch

   Merge on GitHub. Update local main. git branch -d feature/workflow-note. git push origin --delete feature/workflow-note.

5. 05
   Prove the names

   git branch -a should not still list the feature branch. WORKFLOW.md should be on main.

Independent lab: branching workflow

1. On a GitHub repository you own, choose GitHub Flow unless you can name a real supported release that needs Git Flow. Write that choice in WORKFLOW.md on a short-lived feature branch—not on main.
2. Push the branch, open a pull request, and merge it. Do not add a develop branch “for later.”
3. Update local main. Delete the feature branch locally with git branch -d and on origin with git push origin --delete.
4. Show git branch -a without that feature name, and git log --oneline --decorate -n 5 with WORKFLOW.md on main.
5. Write six lines: repository URL, model name, default branch, how a change returns, why Git Flow was or was not chosen, and one sentence that distinguishes GitHub Flow from git switch. Do not push workflow branches to a project you do not maintain.

Common workflow mistakes

Lesson review

You can choose a branching model as a written contract, keep GitHub Flow distinct from Git commands and from Git Flow, and retire a short-lived branch after a reviewed merge. Branch protection that enforces the default branch is GitHub Branch Protection.

• I know a branching model is a team agreement, not a Git subcommand and not a GitHub Issue.
• I can tell GitHub Flow from trunk-based cadence and from Git Flow’s extra long-lived names.
• I can git switch -c a short-lived branch, return it through a pull request, then git branch -d and git push origin --delete.
• I practice on a repository I own, and I do not invent develop without a job for it.