How to Use Git Flow: Branch, Commit, Push, PR, Merge

How to Use Git Flow: Branch, Commit, Push, PR, Merge

Version: 1.0 Date:

2025-01-20

This guide explains the git workflow used in this project. Follow these steps for every change you make.

You cannot break anything permanently. Git keeps history of everything. Mistakes can be undone. The develop branch has protections - even if you accidentally try to push to it directly, GitHub will reject it. This workflow ensures develop quality increases over time as more tests are added to CI.

What is a Pull Request (PR)?

A Pull Request is a quality gate. It is how your code gets reviewed and approved before it joins the develop branch.

When you create a PR: 1. Your changes are visible for review 2. Automated checks (CI) run on your code 3. Only after checks pass can you merge

For this project: We use automatic CI checks as our quality gate. This includes linting (svlint), compilation, and tests. When CI passes, you can merge - no manual reviewer approval is required. After merge, your branch is automatically deleted.

The PR makes it less likely that broken or untested code reaches develop .

Quick Visual Overview

<!-- image -->

The Golden Rule: Small Branches

One branch = One logical change

A branch should contain: - One feature, OR - One bug fix, OR - One documentation update

Why small branches?

| Small Branch | Large Branch | |--------------------------|----------------------| | Easy to review | Hard to review | | Few merge conflicts | Many merge conflicts | | Fast to merge | Slow to merge | | Easy to revert if needed | Difficult to revert |

When in doubt, split your work

If your branch has changes to many unrelated files, consider splitting it into multiple branches. Each branch should be meaningful and complete - it should not break anything when merged.

Never work directly on develop

Always create a branch first. The develop branch is protected - direct pushes will be rejected by GitHub.

Step-by-Step Workflow

Step 1: Start Fresh from Develop

Before starting any new work, make sure you have the latest code.

git checkout develop

What this does: Switches your working directory to the develop branch.

git pull origin develop

What this does: Downloads the latest changes from GitHub and updates your local develop branch.

Step 2: Create Your Feature Branch

git checkout -b feature/add-uart-driver

What this does: Creates a new branch called feature/add-uart-driver AND switches to it. You are now working on your own branch, separate from develop .

Claude Prompt - Starting new work: I want to start working on [describe your task]. Help me create a new feature branch from develop with an appropriate name.

Branch naming examples:

| Type | Example | When to use | |-----------|----------------------------|----------------------------------| | feature/ | feature/add-spi-controller | Adding new functionality | | fix/ | fix/uart-baudrate-calc | Fixing a bug | | docs/ | docs/update-readme | Documentation changes | | refactor/ | refactor/cleanup-fsm | Code cleanup, no behavior change |

Tips for branch names: - Use lowercase letters - Use hyphens -to separate words (not spaces or underscores) - Keep it short but descriptive - Example: feature/addtiming-generator (good) vs feature/AddNewTimingGeneratorModuleForROIC (too long)

Step 3: Do Your Work and Commit Often

Make your changes to the code. When you reach a good stopping point, save your work with a commit.

git add hdl/uart_controller.sv

What this does: T ells git "I want to include this file in my next commit." This is called "staging" a file.

To stage all changed files at once:

git add .

What this does: Stages ALL modified files in the current directory and subdirectories.

git commit -m "add: UART transmit logic"

What this does: Saves your staged changes with a message describing what you did. This is saved locally on your computer only.

Claude Prompt - Ready to commit: Review my changes and help me write a good commit message.

Run git status and git diff to see what I changed.

Commit message tips: - Start with a verb: add , fix , update , remove , refactor - Keep it short (under 50 characters is ideal) - Describe WHAT you did, not HOW

Good commit messages: -add: SPI clock divider module -fix: incorrect reset polarity in FSM -update: timing constraints for UART -docs: add pin assignment table

Bad commit messages: -fixed stuff -WIP -asdfasdf -changes

Step 3.5: Check HDL Code (if you modified hdl/ files)

If you changed any files in the hdl/ folder, your code must pass svlint before CI will accept it.

svlint -c .svlint.toml -I ./hdl/include ./hdl/*.sv

What this does: Runs the SystemVerilog linter on all HDL files and reports any coding style violations.

Claude Prompt - Fix svlint errors: I modified HDL files and need to pass svlint. Run svlint on my changes and help me fix any violations. Follow the OXOS HDL Coding Standards in docs/oxos_coding_style_standard.md.

Why check locally? - Faster feedback - you see errors immediately - No waiting for CI to fail - Fix problems while the code is fresh in your mind

Common svlint issues:

| Issue | Fix | |------------------------------|----------------------------| | Missing default_nettype none | Add at the top of the file | | Wrong indentation | Use 2 spaces, not tabs |

| Issue | Fix | |-----------------------|------------------------------------------------| | Line too long | Break into multiple lines (max 160 characters) | | Missing signal prefix | Use i_ for inputs, o_ for outputs |

See docs/oxos_coding_style_standard.md for the complete coding standard.

Step 4: Push Your Branch to GitHub

git push -u origin feature/add-uart-driver

What this does: Uploads your branch and all its commits to GitHub. The -u flag links your local branch to the remote branch (you only need -u the first time).

After the first push, you can simply use:

git push

Push often! This creates a backup of your work on GitHub. If your computer breaks, your work is safe.

Claude Prompt - Ready to push and create PR:

Help me push my branch and create a pull request. The target branch is develop.

Step 5: Create a Pull Request (PR)

• Go to the repository on GitHub 1.
• You will see a yellow banner: "feature/add-uart-driver had recent pushes" 2.
• Click the green "Compare & pull request" button 3.

Compare and pull request banner

• Fill in the PR title and description 1.
• Make sure the base branch is develop 2.
• Click "Create pull request" 3.

Create pull request form

What happens next: - CI (Continuous Integration) runs automatically - CI checks: linting, compilation, tests - You can see the CI status on the PR page

If CI fails: - Read the error message - Fix the problem in your local code - Commit and push again - CI will run again automatically

Step 5.5: Merge the Pull Request

<!-- image -->

Important: Your code will NOT merge automatically. You must take action on the PR page.

Option A: Merge immediately (when CI passes)

• Wait for all CI checks to pass (green checkmarks) 1.
• Click the green "Merge pull request" button 2.
• Click "Confirm merge" 3.

<!-- image -->

Option B: Enable auto-merge (merge automatically when CI passes)

If CI is still running, you can enable auto-merge so it merges as soon as checks pass:

• Click "Enable auto-merge" button 1.
• Select "Squash and merge" or "Create a merge commit" 2.
• Click "Confirm auto-merge" 3.

<!-- image -->

The PR will merge automatically once all checks pass. You do not need to come back to click merge.

Note: If you do not click "Merge" or "Enable auto-merge", your PR will stay open forever and your code will not reach develop .

Step 6: After Merge - Start Fresh

After your PR is merged:

• Your branch is automatically deleted on GitHub 1.
• Go back to develop and get your merged changes: 2.

git checkout develop

What this does: Switches back to the develop branch.

git pull origin develop

What this does: Downloads the latest changes, including your merged work.

• Delete your local branch (optional but recommended): 1.

git branch -d feature/add-uart-driver

What this does: Removes the branch from your local computer. This keeps your local repository clean.

• Start your next task with a NEW branch (go back to Step 1) 1.

Claude Prompt - After merge, next cycle: My PR was merged. Help me clean up and prepare for my next task.

Common Questions (Q&A)

Q: What if I forgot to create a branch and committed to develop?

A: Do not worry. Your commits are safe. Do this:

# Create a new branch with your commits

git checkout -b feature/my-work # The new branch now has your commits # Push it to GitHub git push -u origin feature/my-work # Now fix your local develop branch git checkout develop git reset --hard origin/develop

What this does: Moves your commits to a new branch, then resets your local develop to match GitHub.

Q: What if CI fails on my PR?

A: This is normal. CI failures are not a problem - they are helpful feedback.

• Click on the failed check to see the error message 1.
• Read the error carefully 2.
• Fix the problem in your local code 3.
• Commit and push: bash git add . git commit -m "fix: resolve CI failure" git push 4.
• CI will run again automatically on your PR 5.

Q: What if develop changed while I was working?

A: This happens when teammates merge their work before you. Update your branch:

git checkout develop git pull origin develop

git checkout feature/my-work

git merge develop

What this does: Gets the latest develop changes and merges them into your branch.

If there are merge conflicts , git will tell you which files have conflicts. Open those files, look for the conflict markers ( <<<<<<< , ======= , >>>>>>> ), and manually choose the correct code. Then:

git add . git commit -m "merge: resolve conflicts with develop" git push

Ask for help if merge conflicts are confusing. It is better to ask than to make mistakes.

Claude Prompt - Merge conflicts: I have merge conflicts and need help resolving them. Show me the conflicts and help me choose the correct code.

Q: How should I name my branch?

A: Use this format: <type>/<short-description>

| Type | Use for | Example | |-----------|-------------------|----------------------------| | feature/ | New functionality | feature/add-dma-controller | | fix/ | Bug fixes | fix/spi-clock-polarity | | docs/ | Documentation | docs/update-pin-table | | refactor/ | Code cleanup | refactor/simplify-fsm | | test/ | Adding tests | test/add-uart-coverage |

Q: Can I have multiple branches at once?

A: Yes, but it is easier to finish one branch before starting another.

If you must work on multiple things:

# Save your current work git add . git commit -m "wip: save progress"

git push # Switch to another branch git checkout develop git checkout -b feature/other-task

To return to your first branch:

git checkout feature/first-task

Q: What if I need to make more changes after creating a PR?

A: Just push more commits. They will be added to the same PR automatically.

# Make your changes git add . git commit -m "update: address review feedback" git push

The PR will update and CI will run again.

Q: What if I accidentally pushed something wrong?

A: Do not panic. Ask for help before trying to fix it yourself.

Claude Prompt - Something went wrong: I made a mistake with git. Here is what happened: [describe the problem]. Help me fix it safely without losing my other work.

Quick Reference Card

For experienced users who need a fast reminder:

# Start new work git checkout develop && git pull origin develop git checkout -b feature/my-work # Save work git add . && git commit -m "message" # Push (first time) git push -u origin feature/my-work # Push (after first time) git push

# After PR merged git checkout develop && git pull origin develop git branch -d feature/my-work # Check HDL lint svlint -c .svlint.toml -I ./hdl/include ./hdl/*.sv

Remember

• Small branches are better - easier to review, fewer conflicts ·
• Commit and push often - creates backups of your work ·
• CI failures are helpful - they catch problems before merge ·
• Asking questions is good - asking is faster than fixing mistakes ·
• Mistakes can be undone - git keeps history of everything ·

If you are unsure about anything, ask for help. It is always better to ask than to guess.

Sources and Further Reading

• Atlassian: Git Feature Branch Workflow ·
• Atlassian: Gitflow Workflow ·
• GitKraken: Git Branch Strategy Best Practices ·
• GitLab Flow Best Practices ·