Git¶

Simple, robust workflows for solo work and team collaboration.

Git is essential for any software project. This section covers practical Git workflows that actually work in real development scenarios, from simple solo projects to team collaboration.

🎯 Goals¶

Clean workflows that prevent common Git problems
Collaboration patterns for teams and open source
Conflict resolution strategies that actually work
Best practices for commit messages, branching, and releases

🔍 Quick Verification¶

Test your Git setup:

# Check Git installation and version
git --version

# Verify your identity setup
git config --global user.name
git config --global user.email

# Check SSH setup for GitHub
ssh -T git@github.com

# Test basic Git functionality
git status
git log --oneline -n 5

📚 Essential Guides¶

Setup & Fundamentals¶

Setup & Identity - User configuration, SSH keys, and GitHub setup
Basic Workflow - clone, status, add, commit, push, pull patterns
Branching Model - main + feature branch strategy that scales

Team Collaboration¶

Pull Requests - Creating, reviewing, and merging PRs effectively
Merge vs Rebase - When to use each approach
Resolve Conflicts - Step-by-step conflict resolution

Advanced Tools & Practices¶

GitHub CLI - Command-line interface for GitHub operations
.gitignore & Secrets - What to ignore and how to handle secrets
Commit Messages - Conventional commits and clear history
Multiple GitHub Accounts - SSH and gh CLI for different accounts
Tags & Releases - Versioning and release management

🚀 Common Workflows¶

Daily Development¶

# Start work on new feature
git checkout main
git pull origin main
git checkout -b feature/new-feature

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push and create PR
git push -u origin feature/new-feature
gh pr create --title "Add new feature" --body "Description here"  # Requires GitHub CLI

Project Initialization¶

# New repository
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin git@github.com:username/repo.git
git push -u origin main

# Clone existing project
git clone git@github.com:username/repo.git
cd repo
git status

Python - Git workflows for Python projects
Node.js - Version control for Node applications
AI Tools - Using Claude Code with Git workflows
Toolkit - VS Code, MkDocs, and development tools

⚡ Quick References¶

Essential Commands:

# Status and info
git status                    # Working directory status
git log --oneline -n 10      # Recent commits
git diff                     # Unstaged changes
git diff --staged            # Staged changes

# Basic workflow
git add file.txt             # Stage specific file
git add .                    # Stage all changes
git commit -m "message"      # Commit with message
git push                     # Push to remote
git pull                     # Pull from remote

Branching:

# Branch management
git branch                   # List branches
git branch feature-name      # Create branch
git checkout feature-name    # Switch to branch
git checkout -b feature-name # Create and switch

# Modern git switch/restore
git switch main              # Switch to main
git switch -c feature-name   # Create and switch
git restore file.txt         # Restore file

Undo Operations:

# Undo staged changes
git restore --staged file.txt

# Undo committed changes (safe)
git revert HEAD              # Revert last commit
git revert commit-hash       # Revert specific commit

# Reset (be careful!)
git reset --soft HEAD~1      # Undo last commit, keep changes
git reset --hard HEAD~1      # Undo last commit, lose changes

Conflict Resolution:

# During merge conflict
git status                   # See conflicted files
# Edit files to resolve conflicts
git add resolved-file.txt    # Mark as resolved
git commit                   # Complete merge

# Abort merge if needed
git merge --abort

Remote Management:

# Remote repositories
git remote -v                # List remotes
git remote add upstream url  # Add upstream remote
git fetch upstream           # Fetch from upstream
git merge upstream/main      # Merge upstream changes

Useful Aliases:

# Add to ~/.gitconfig or set with git config --global
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.cm commit
git config --global alias.lg "log --oneline --graph --all"

Commit Message Format:

feat: add user authentication

- Implement login/logout functionality
- Add JWT token handling  
- Include password validation

Closes #123

Start here: If you're new to Git, begin with Setup & Identity to configure Git properly, then follow Basic Workflow to learn the essential commands.