Git Guide

This guide covers essential Git workflows and advanced techniques for contributing to wiRedPanda. Whether you're new to Git or looking to refine your skills, this guide will help you contribute effectively.

Table of Contents

• Why Git Matters
• Quick Start
• Basic Git Workflow
• Git Flow Workflow
• Interactive Rebase
• Git Bisect
• Advanced Git Techniques
• Best Practices
• Troubleshooting
• Git Configuration
• Resources
• Next Steps

Why Git Matters for wiRedPanda Contributors

Git skills enable you to:

• 🤝 Collaborate effectively with other contributors worldwide
• 📝 Track changes and maintain clean development history
• 🔄 Contribute safely without breaking existing functionality
• 🎯 Focus on your contribution while others work simultaneously

Master these workflows once, and you'll be ready to contribute to any open-source project!

Quick Start

• 🆕 New to Git? → Start with Basic Git Workflow
• 🔀 Ready to contribute? → Learn about Git Flow
• 🔧 Need to clean up commits? → Check Interactive Rebase
• 🐛 Hunting bugs? → Use Git Bisect

Basic Git Workflow

Initial Setup

1. Clone the repository:

   git clone https://github.com/GIBIS-UNIFESP/wiRedPanda.git
   cd wiRedPanda

2. Configure your identity:

   git config --global user.name "Your Name"
   git config --global user.email "your.email@example.com"

3. Set up upstream (for forks):

   git remote add upstream https://github.com/GIBIS-UNIFESP/wiRedPanda.git

Daily Git Commands

# Check status
git status

# Add changes
git add .                    # Add all changes
git add specific-file.cpp    # Add specific file

# Commit changes
git commit -m "Your descriptive message"

# Push changes
git push origin your-branch-name

# Pull latest changes
git pull upstream master

Branching Workflow

wiRedPanda uses a simple branching model: master is the main branch, and all work happens on feature branches created from it.

Branch Types

• master: Main branch, always stable
• Feature branches: Created from master for new features, bug fixes, or improvements

Feature Development Workflow

1. Start from master:

   git checkout master
   git pull upstream master

2. Create feature branch:

   git checkout -b feat/your-feature-name

3. Work on your feature:

   # Make changes
   git add .
   git commit -m "feat: add new logic gate implementation"
   
   # Continue development
   git add .
   git commit -m "test: add unit tests for new gate"

4. Keep up with master (periodically):

   git fetch upstream
   git rebase upstream/master

5. Push and create Pull Request:

   git push origin feat/your-feature-name
   # Create PR on GitHub: feat/your-feature-name → master

Interactive Rebase

Interactive rebase lets you clean up commit history before merging. Use it to:

• Squash multiple commits into one
• Reorder commits logically
• Edit commit messages
• Split large commits

Basic Interactive Rebase

# Rebase last 3 commits
git rebase -i HEAD~3

# Rebase since branching from master
git rebase -i master

Rebase Commands

When the interactive editor opens, you'll see:

pick a1b2c3d Add new feature
pick b2c3d4e Fix typo
pick c3d4e5f Add documentation

# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# d, drop = remove commit

Common Rebase Scenarios

Squash Commits

pick a1b2c3d Add new feature
s b2c3d4e Fix typo          # Squash this into previous
s c3d4e5f Add documentation # Squash this into first

Reorder Commits

pick c3d4e5f Add documentation  # Move this first
pick a1b2c3d Add new feature     # Then this
pick b2c3d4e Fix typo            # Then this

Edit Commit Message

r a1b2c3d Add new feature       # Will prompt for new message
pick b2c3d4e Fix typo
pick c3d4e5f Add documentation

Resolving Rebase Conflicts

# If conflicts occur during rebase
git status                    # See conflicted files
# Edit files to resolve conflicts
git add resolved-file.cpp
git rebase --continue

# If you want to abort the rebase
git rebase --abort

Git Bisect

Git bisect helps you find the commit that introduced a bug using binary search.

Basic Bisect Workflow

1. Start bisect:

   git bisect start

2. Mark known good and bad commits:

   git bisect bad                    # Current commit is bad
   git bisect good v2.1.0           # This tag/commit was good

3. Test each commit Git suggests:

   # Git checks out a commit in the middle
   # Test your application
   # If bug is present:
   git bisect bad
   # If bug is not present:
   git bisect good

4. Git finds the problematic commit:

   a1b2c3d4e5f is the first bad commit
   commit a1b2c3d4e5f
   Author: Developer <dev@example.com>
   Date: Mon Jan 15 14:30:22 2024 +0000
   
   Add new simulation feature
   

5. End bisect session:

   git bisect reset

Automated Bisect

For reproducible tests, you can automate bisect:

git bisect start HEAD v2.1.0
git bisect run ./test-script.sh

Your test script should:

• Exit with 0 if commit is good
• Exit with 1-127 (except 125) if commit is bad
• Exit with 125 to skip a commit

Example test script (test-script.sh):

#!/bin/bash
cmake -B build -G Ninja
cmake --build build
if [ $? -ne 0 ]; then
    exit 125  # Skip if it doesn't compile
fi

# Run your specific test
./build/wiredpanda --test-feature
if [ $? -eq 0 ]; then
    exit 0    # Good commit
else
    exit 1    # Bad commit
fi

Advanced Git Techniques

Cherry-Pick Commits

Apply specific commits from other branches:

# Apply single commit
git cherry-pick a1b2c3d

# Apply multiple commits
git cherry-pick a1b2c3d..b2c3d4e

# Cherry-pick with conflicts
git cherry-pick a1b2c3d
# Resolve conflicts
git add resolved-files
git cherry-pick --continue

Stash Changes

Temporarily save changes without committing:

# Stash current changes
git stash

# Stash with description
git stash push -m "Work in progress on new feature"

# List stashes
git stash list

# Apply most recent stash
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Drop a specific stash
git stash drop stash@{1}

Reset and Revert

Git Reset (rewrites history - use carefully)

# Soft reset - keep changes staged
git reset --soft HEAD~1

# Mixed reset - keep changes unstaged (default)
git reset HEAD~1

# Hard reset - discard all changes
git reset --hard HEAD~1

Git Revert (safe for shared branches)

# Revert single commit
git revert a1b2c3d

# Revert merge commit
git revert -m 1 merge-commit-hash

Best Practices

Commit Messages

Follow the Conventional Commits format:

type: description

[optional body]

Examples:

feat: add iterative convergence for feedback loops
fix: resolve memory leak in graphics rendering
docs: update installation guide for Qt6
test: add unit tests for AND gate behavior

Types:

Prefix	Use
feat:	New feature
fix:	Bug fix
refactor:	Refactoring without behavior change
docs:	Documentation changes
test:	Adding or fixing tests
perf:	Performance improvement
chore:	Maintenance tasks (CI, dependencies, etc.)

Branch Naming

feat/description-of-feature
fix/critical-bug-description
docs/update-installation-guide
test/add-missing-gate-tests

Before Pushing

1. Review your changes:

   git diff --cached

2. Run tests (if available):

   # Build and test using CMake presets
   cmake --preset debug
   cmake --build --preset debug
   ctest --preset debug
   
   # Or run a specific test class
   ./build/test_wiredpanda TestClassName

3. Check commit history:

   git log --oneline -5

Troubleshooting

Common Issues

"Detached HEAD" State

# Create branch from current state
git checkout -b rescue-branch

# Or return to previous branch
git checkout master

Accidentally Committed to Wrong Branch

# Reset current branch (loses commit)
git reset --hard HEAD~1

# Switch to correct branch and cherry-pick
git checkout correct-branch
git cherry-pick a1b2c3d  # Use the commit hash

Merge Conflicts

# See conflicted files
git status

# Edit files to resolve conflicts
# Look for <<<<<<< ======= >>>>>>> markers

# Mark as resolved
git add resolved-file.cpp

# Complete merge
git commit

Recovery Commands

# Find lost commits
git reflog

# Recover lost commit
git checkout a1b2c3d

# Show what would be deleted (dry run)
git clean -n

# Actually clean untracked files
git clean -f

Git Configuration

Useful Global Settings

# Better diff algorithm
git config --global diff.algorithm histogram

# Auto-correct typos
git config --global help.autocorrect 1

# Colorful output
git config --global color.ui auto

# Default branch name
git config --global init.defaultBranch main

# Rebase by default on pull
git config --global pull.rebase true

# Auto-prune deleted remote branches
git config --global remote.origin.prune true

Aliases for Common Commands

git config --global alias.st status
git config --global alias.co checkout  
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual '!gitk'
git config --global alias.lg 'log --oneline --graph --decorate --all'

Resources

• 📖 Official Git Documentation: git-scm.com
• 🎓 Interactive Git Tutorial: learngitbranching.js.org
• 🔧 Git Flow Tutorial: atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
• 🆘 Oh Shit, Git!: ohshitgit.com - Recovery from common mistakes
• 📋 Git Cheat Sheet: education.github.com/git-cheat-sheet

Next Steps

You're now equipped with powerful Git skills for contributing to wiRedPanda! 🎉

🚀 Start Contributing

• 👨‍💻 Set up development environment → Development Setup
• 🌍 Quick start: Help with translations → Translation Guide
• 🔧 Advanced: Create custom elements → Element Creation Guide

📚 Deepen Your Understanding

• 📖 Developer onboarding → Developer Guide (learning path, starter tasks, tips)
• 🔬 Learn how wiRedPanda works internally → Simulation Guide
• 🏛️ Codebase architecture → Architecture Overview
• 🏠 Explore all contribution opportunities → Home

🤝 Join the Community

• 💬 Ask questions: GitHub Discussions
• 🐛 Report issues: GitHub Issues
• ⭐ Star the project: GitHub Repository

🆘 Need Git Help?

• 🔗 Official Git Documentation: git-scm.com
• 🆘 Recovery from mistakes: ohshitgit.com
• 💭 Ask the community: GitHub Discussions

---

Remember: Git is a powerful tool—with great power comes great responsibility. Always create backups of important work and don't hesitate to ask for help when dealing with complex Git situations! 🛡️

You're ready to collaborate and contribute effectively! Welcome to the wiRedPanda development community! 🙏