gitbranch

---
name: gitbranch
description: "Work on a git branch — create, switch, push, and manage branches. Use when the user says 'make a branch', 'work on a branch', 'create a branch', 'switch branch', 'new branch', or wants to isolate work from master/main. Also use when starting a new feature or phase of work that should be kept separate until ready to merge."
---

# Git Branch — Work on a Branch

Create and work on git branches to isolate changes from master/main.

## Commands

### Create and switch to a new branch
```bash
git checkout -b <branch-name>
```
This creates the branch locally AND switches to it.

### Push to remote (first time)
```bash
git push -u origin <branch-name>
```
The `-u` flag sets the upstream tracking, so future `git push` commands know where to go.

### Push subsequent changes
```bash
git push
```
Works after the upstream is set with `-u`.

### Switch between branches
```bash
git checkout <branch-name>
```

### List branches
```bash
git branch          # local branches
git branch -r       # remote branches
git branch -a       # all branches
```

### Delete a branch
```bash
git branch -d <branch-name>         # local (safe — won't delete unmerged)
git push origin --delete <branch-name>  # remote
```

### Merge a branch into master
```bash
git checkout master
git merge <branch-name>
git push
```

## Naming Conventions

- `feat/<name>` — new feature (e.g., `feat/visual-mockup-architecture`)
- `fix/<name>` — bug fix
- `refactor/<name>` — code refactoring
- `docs/<name>` — documentation changes

## When to Branch

- Starting a new phase of work
- Experimenting with something that might be thrown away
- Working on a feature that isn't ready for master yet

## When NOT to Branch

- Solo dev on a simple project with linear progress — just push to master
- Quick fixes that are immediately ready — commit straight to master

## Rules

- Never force push to master/main
- Always commit or stash changes before switching branches
- Delete branches after merging to keep things clean