Git best practices establish version control workflows that enable safe collaboration, clean history, and reliable code management — using branching strategies, commit conventions, and review processes that keep ML projects organized and enable teams to work together effectively on complex AI codebases.

Why Git Best Practices Matter

• Collaboration: Multiple contributors work without conflicts.
• History: Track what changed, when, and why.
• Rollback: Revert problematic changes quickly.
• Review: Code review catches issues before merge.
• Reproducibility: Tag releases for exact reproduction.

Essential Commands

Daily Workflow:

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

# Make changes and commit
git add -p                    # Interactive staging
git commit -m "feat: add new embedding model"

# Keep up with main
git fetch origin
git rebase origin/main

# Push and create PR
git push -u origin feature/my-feature

Useful Commands:

# View history
git log --oneline -20
git log --graph --oneline --all

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Discard local changes
git checkout -- file.py
git restore file.py           # Modern alternative

# Stash work temporarily
git stash
git stash pop

# Interactive rebase (clean history)
git rebase -i HEAD~3

Branching Strategy

GitHub Flow (Recommended for most teams):

<svg viewBox="0 0 393 226" xmlns="http://www.w3.org/2000/svg" style="max-width:100%;height:auto" role="img"><rect x="0" y="0" width="393" height="226" rx="12" fill="#0d1117"/><g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,&quot;Liberation Mono&quot;,monospace" font-size="14"><text xml:space="preserve" x="20" y="31.7"><tspan fill="#c9d1d9">main (always deployable)</tspan></text><text xml:space="preserve" x="20" y="50.7"><tspan fill="#c9d1d9">  </tspan><tspan fill="#6e7681">│</tspan></text><text xml:space="preserve" x="20" y="69.7"><tspan fill="#c9d1d9">  </tspan><tspan fill="#6e7681">├──</tspan><tspan fill="#c9d1d9"> feature/add-rag-pipeline</tspan></text><text xml:space="preserve" x="20" y="88.7"><tspan fill="#c9d1d9">  </tspan><tspan fill="#6e7681">│</tspan><tspan fill="#c9d1d9">     </tspan><tspan fill="#6e7681">└──</tspan><tspan fill="#c9d1d9"> [PR] </tspan><tspan fill="#6e7681">→</tspan><tspan fill="#c9d1d9"> review </tspan><tspan fill="#6e7681">→</tspan><tspan fill="#c9d1d9"> merge </tspan><tspan fill="#6e7681">→</tspan><tspan fill="#c9d1d9"> delete</tspan></text><text xml:space="preserve" x="20" y="107.7"><tspan fill="#c9d1d9">  </tspan><tspan fill="#6e7681">│</tspan></text><text xml:space="preserve" x="20" y="126.7"><tspan fill="#c9d1d9">  </tspan><tspan fill="#6e7681">├──</tspan><tspan fill="#c9d1d9"> feature/fix-embedding-bug</tspan></text><text xml:space="preserve" x="20" y="145.7"><tspan fill="#c9d1d9">  </tspan><tspan fill="#6e7681">│</tspan><tspan fill="#c9d1d9">     </tspan><tspan fill="#6e7681">└──</tspan><tspan fill="#c9d1d9"> [PR] </tspan><tspan fill="#6e7681">→</tspan><tspan fill="#c9d1d9"> review </tspan><tspan fill="#6e7681">→</tspan><tspan fill="#c9d1d9"> merge </tspan><tspan fill="#6e7681">→</tspan><tspan fill="#c9d1d9"> delete</tspan></text><text xml:space="preserve" x="20" y="164.7"><tspan fill="#c9d1d9">  </tspan><tspan fill="#6e7681">│</tspan></text><text xml:space="preserve" x="20" y="183.7"><tspan fill="#c9d1d9">  </tspan><tspan fill="#6e7681">└──</tspan><tspan fill="#c9d1d9"> feature/upgrade-model</tspan></text><text xml:space="preserve" x="20" y="202.7"><tspan fill="#c9d1d9">        </tspan><tspan fill="#6e7681">└──</tspan><tspan fill="#c9d1d9"> [PR] </tspan><tspan fill="#6e7681">→</tspan><tspan fill="#c9d1d9"> review </tspan><tspan fill="#6e7681">→</tspan><tspan fill="#c9d1d9"> merge </tspan><tspan fill="#6e7681">→</tspan><tspan fill="#c9d1d9"> delete</tspan></text></g></svg>

Branch Naming:

feature/add-vector-store    # New functionality
fix/memory-leak-inference   # Bug fixes
docs/update-readme          # Documentation
refactor/clean-prompts      # Code improvement
experiment/new-model-arch   # Exploratory work

Commit Message Convention

Conventional Commits:

<type>(<scope>): <description>

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation only
- refactor: Code change (no feature/fix)
- test: Adding tests
- chore: Maintenance

Examples:
feat(rag): add hybrid search with BM25
fix(inference): resolve OOM on long contexts
docs: add API usage examples
refactor(prompts): consolidate system prompts

Good Commit Messages:

# ✅ Good
git commit -m "feat: add streaming response support"
git commit -m "fix: handle empty context in RAG pipeline"

# ❌ Bad
git commit -m "fixed stuff"
git commit -m "WIP"
git commit -m "changes"

Code Review Process

PR Best Practices:

## Description
Brief explanation of what this PR does.

## Changes
- Added new embedding model
- Updated vector store config
- Fixed chunking logic

## Testing
- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] Eval set shows no regression

## Screenshots
(if applicable)

Review Checklist:

□ Code is readable and follows style guide
□ Tests cover new functionality
□ No hardcoded secrets or credentials
□ ML-specific: eval results attached
□ Documentation updated if needed

Git for ML Projects

What to Track:

✅ Track in Git:
- Source code
- Config files
- Small test fixtures
- Documentation

❌ Don't track (use DVC/LFS):
- Model weights (too large)
- Datasets (use DVC)
- Generated outputs
- API keys/secrets

.gitignore for ML:

# Python
__pycache__/
*.pyc
.venv/
venv/

# ML artifacts
*.pt
*.onnx
*.safetensors
models/
checkpoints/

# Data
data/raw/
data/processed/
*.parquet
*.csv

# Secrets
.env
*_key.json

# IDE
.vscode/
.idea/

Advanced Techniques

# Bisect to find breaking commit
git bisect start
git bisect bad HEAD
git bisect good v1.0.0
# Git will guide you to the breaking commit

# Cherry-pick specific commits
git cherry-pick abc1234

# Find who changed a line
git blame file.py

Git best practices are essential infrastructure for team productivity — clean workflows, meaningful commits, and effective review processes enable rapid development while maintaining code quality and collaboration on complex ML projects.