Git Branching Guide

Quick Summary

Use this first if you want the short version.

1. The Basic Idea

A branch is a named line of work. It lets you change code without immediately changing another branch.

In most projects, the stable branch is main or master. A feature branch is where you do one specific task, for example feature/navbar or bugfix/login-error.

2. Check Where You Are

Before you create, merge, or push branches, check your current state.

git status
git branch --show-current
git branch -vv
git remote -v

3. Branch Types

These names are conventions. Git itself does not enforce them, but teams use them for clarity.

4. Create a Branch

Start from the base branch you want to branch from, usually main.

git switch main
git pull origin main
git switch -c feature/my-change

This means: move to main, update it from the remote, then create a new local feature branch from that point.

5. Work and Commit Locally

Git work starts locally. When you edit files in your project folder, those changes are local until you commit and push them.

git status
git diff
git add .
git commit -m "Add fixed left sidebar navigation"

A commit is still local. It exists only in your clone until you push it to a remote.

6. Local vs Remote

This is one of the most important Git distinctions:

You do not work directly inside origin/main. You work on a local branch such as main or feature/my-change.

How to know if you are local or synced with remote

git status
git branch -vv
git fetch origin
git status

After git fetch origin, Git updates its knowledge of the server. Then git status and git branch -vv become more reliable for ahead/behind information.

7. Push a Branch

After committing locally, push the branch to the remote server.

git push -u origin feature/my-change

The first push uses -u to connect your local branch to its remote branch. After that, while you stay on the same branch, you can usually use:

git push

How to check what branch will be pushed

git branch -vv

If you see [origin/feature/my-change], your local branch is linked to that remote branch.

8. Merge a Feature Branch

Merging means bringing the full content of one branch into another branch.

Feature branching flow

1. Start from main.
2. Create feature/....
3. Commit all work on that feature branch.
4. Return to main.
5. Merge the feature branch into main.

git switch main
git pull origin main
git merge feature/my-change
git push origin main

Read the merge command literally: "I am on main, and I want to bring feature/my-change into this branch."

9. Merge Conflicts

A conflict happens when Git cannot decide which version of a changed section to keep.

git status

You may see markers like this:

<<<<<<< HEAD
code from current branch
=======
code from merged branch
>>>>>>> feature/my-change

Resolve the file, then continue:

git add path/to/file
git commit

To cancel the merge:

git merge --abort

10. Fetch vs Pull

git fetch origin
git log --oneline origin/main
git merge origin/main

That is the manual version. The shortcut is:

git pull origin main

11. Remote-Tracking Branches

A name like origin/main is not the server itself. It is your local snapshot of what Git last fetched from the server.

git branch -r
git branch -a
git log --oneline origin/main

If someone else pushes to GitHub, your machine does not know immediately. You must run git fetch or git pull to update your local knowledge.

12. If Codex Works on a Remote

In normal Git usage, work should still land in a branch somewhere. The question is where the commit is created and where you later pull it from.

Case A: Codex edits your local repository

This is the simple case. Codex changes files in your local clone. You review, commit, and push from your machine.

Case B: Codex commits to a remote branch

In that case the remote branch moves first, and your local clone becomes behind that remote branch until you fetch or pull.

git fetch origin
git switch your-branch
git pull origin your-branch

If the branch does not exist locally yet:

git fetch origin
git switch -c your-branch --track origin/your-branch

What happens in practice

1. Remote branch receives new commits.
2. Your local clone still has old state.
3. git fetch updates origin/....
4. git pull or git merge origin/... brings those commits into your local branch.

13. Full Example You Can Run

This example assumes the project already has a remote named origin and a stable branch named main.

# Check current state
git status
git branch -vv

# Update local main from the server
git switch main
git pull origin main

# Create a feature branch
git switch -c feature/left-panel

# Work on files, then review
git status
git diff

# Commit locally
git add .
git commit -m "Add fixed left panel navigation to Git lesson"

# Push the feature branch to the remote
git push -u origin feature/left-panel

# Later, merge it back into main
git switch main
git pull origin main
git merge feature/left-panel
git push origin main

If the remote was changed first by someone else

# Update your knowledge of the remote
git fetch origin

# See whether your local branch is behind
git branch -vv

# Bring remote changes into local main
git switch main
git pull origin main

14. Delete a Branch

Deleting a branch locally and deleting a branch remotely are two different operations.

Delete only the local branch

git branch -d feature/my-change

Use -d when the branch was already merged. Git will stop you if the branch still contains unmerged work.

Force delete only the local branch

git branch -D feature/my-change

Use -D only when you are sure you do not need the unmerged work anymore.

Delete only the remote branch

git push origin --delete feature/my-change

This deletes the branch on GitHub or another remote, but it does not automatically remove your local branch.

If you deleted the branch remotely

Your local repository may still show old remote-tracking information until you fetch and prune.

git fetch --prune origin
git branch -r

If you still have the local branch and want to remove it too:

git branch -d feature/my-change

If you deleted the branch locally

The remote branch still exists until you delete it from the server.

git push origin --delete feature/my-change

15. Cheat Sheet