How-To Guide

Git Branching Strategy

Simple, effective branching for solo and small team development.

When to use branches

For installations, branching strategy depends on team size:

Solo developer (default)

Commit directly to main. No branching overhead for small, reversible changes.

 git add .
git commit -m "Update homepage copy"
git push origin main 

Small team (2-4 people)

Use feature branches for non-trivial work. Merge via pull request for review.

 git checkout -b feature/new-testimonials
# Make changes
git commit -m "Add testimonial component"
git push origin feature/new-testimonials
# Create PR → Review → Merge 

Larger team (5+)

Always use branches. Require reviews before merging. Consider GitFlow or trunk-based development.

Rule of thumb: If you'd feel comfortable reverting the commit, skip the branch. If you need review first, use a branch.

Creating and managing branches

Standard branch workflow:

1. Create feature branch

 # From main branch
git checkout main
git pull origin main

# Create and switch to new branch
git checkout -b feature/add-contact-form

# Or separate commands:
git branch feature/add-contact-form
git checkout feature/add-contact-form 

2. Work on feature

 # Make changes
vim src/components/ContactForm.astro

# Commit often (granular commits)
git add src/components/ContactForm.astro
git commit -m "Create contact form component"

# More changes
git add src/pages/contact.astro
git commit -m "Add contact page with form" 

3. Push to remote

 # First push (set upstream)
git push -u origin feature/add-contact-form

# Subsequent pushes
git push 

4. Merge back to main

 # Update main
git checkout main
git pull origin main

# Merge feature branch
git merge feature/add-contact-form

# Push merged main
git push origin main

# Delete feature branch (optional)
git branch -d feature/add-contact-form
git push origin --delete feature/add-contact-form 

Branch naming conventions

Clear names make branches easier to manage:

Prefix	Purpose	Example
`feature/`	New functionality	feature/testimonials
`fix/`	Bug fixes	fix/mobile-menu
`docs/`	Documentation	docs/api-reference
`refactor/`	Code restructuring	refactor/components
`chore/`	Maintenance tasks	chore/dependencies

 # Good branch names
feature/dark-mode-toggle
fix/navigation-mobile-overflow
docs/deployment-guide
refactor/reduce-component-size

# Avoid
my-branch
test
updates
wip 

Merge strategies

Three ways to merge branches:

Regular merge (default)

Creates a merge commit. Preserves branch history.

 git checkout main
git merge feature/add-contact-form

# Creates merge commit with two parents 

When to use: Feature branches with multiple commits, want to preserve full history

Squash merge

Combines all commits into one. Clean linear history.

 git checkout main
git merge --squash feature/add-contact-form
git commit -m "Add contact form feature"

# All feature commits become one commit on main 

When to use: Many small commits during development, want clean main history

Rebase (advanced)

Replays commits on top of main. Linear history, no merge commit.

 git checkout feature/add-contact-form
git rebase main
git checkout main
git merge feature/add-contact-form  # Fast-forward 

When to use: Want linear history, comfortable with rebase workflows

Recommendation: Use regular merge for small teams. Squash merge for cleaner history. Avoid rebase unless you understand the tradeoffs.

Handling merge conflicts

Conflicts occur when same lines changed in both branches:

1. Identify conflict

 git merge feature/my-feature

# Output:
# Auto-merging src/pages/index.astro
# CONFLICT (content): Merge conflict in src/pages/index.astro
# Automatic merge failed; fix conflicts and then commit the result. 

2. Open conflicted file

 <<<<<<< HEAD
<h1>Welcome to our site</h1>
=======
<h1>Welcome to my installation</h1>
>>>>>>> feature/my-feature 

3. Resolve conflict

Edit file to keep desired changes, remove conflict markers:

<h1>Welcome to my installation</h1>

4. Complete merge

 git add src/pages/index.astro
git commit  # Use default merge message
git push origin main 

Preventing conflicts:

• Pull main frequently while working on branch
• Keep feature branches short-lived (days, not weeks)
• Coordinate changes to same files with team
• Merge main into feature branch before merging feature to main

Forking workflow (optional)

For client installations you maintain, consider forking the base repository:

1. Fork base installation → client-specific repository
2. Client customizations stay in their fork
3. Pull upstream changes from base when needed
4. Push improvements back to base (optional)

 # One-time setup
git remote add upstream https://github.com/base/installation.git

# Pull upstream changes
git fetch upstream
git merge upstream/main

# Push improvements upstream (via PR)
git push origin feature/new-component
# Create PR to base repository 

Quick reference

Task	Command
Create branch	`git checkout -b feature/name`
List branches	`git branch -a`
Switch branches	`git checkout branch-name`
Merge branch	`git merge feature/name`
Delete local branch	`git branch -d feature/name`
Delete remote branch	`git push origin --delete feature/name`
View branch graph	`git log --graph --oneline`