Welcome to the comprehensive guide for understanding GitHub workflows, branching strategies, merging techniques, and Git best practices!

This documentation project provides an in-depth exploration of:

• Git Fundamentals - Core concepts and terminology
• Branching Strategies - Popular approaches (Git Flow, GitHub Flow, Trunk-Based)
• Branching Workflows - Real-world implementation patterns
• Merging vs Rebasing - Detailed comparison and use cases
• Commit Best Practices - Writing meaningful commits
• Main Branch - Production stability and protection
• Develop Branch - Integration and feature readiness
• Release Branch - Planned release procedures
• Hotfix Branch - Emergency production fixes
• Version Tagging - Semantic versioning and release management
• GitHub Actions Automation - Automated versioning, branch protection, and release workflows
• Cherry Picking & Feature Flipping - Advanced techniques for selective commits and controlled rollouts
• Hands-On Examples - Complete real-world scenarios

1. Start with 01-git-fundamentals.md
2. Learn basic Git concepts and commands
3. Move to 02-branching-strategy.md

1. Jump to 02-branching-strategy.md to compare strategies
2. Check 04-merging-rebase.md for merge decisions
3. Review 03-branching-workflow.md for implementation details

1. Read 02-branching-strategy.md for strategy selection
2. Review 06-main-branch.md and 07-develop-branch.md for branch protection
3. Check 08-release-branch.md and 09-hotfix-branch.md for process documentation
4. See 10-hands-on-example.md for complete workflow

┌─────────────────────────────────────────────────┐
│              Git Flow Branches                  │
├─────────────────────────────────────────────────┤
│                                                 │
│ main              ─ Production code (tagged)    │
│ develop           ─ Integration branch          │
│ feature/*         ─ New features (temporary)    │
│ release/*         ─ Release preparation         │
│ hotfix/*          ─ Emergency fixes (from main) │
│                                                 │
└─────────────────────────────────────────────────┘

Feature Development:
feature/* ──→ Code Review ──→ Merge to develop

Release Preparation:
develop ──→ release/* ──→ Final testing ──→ Merge to main

Production Issue:
main ──→ hotfix/* ──→ Quick fix ──→ Merge to main & develop

• Local Repository: On your computer
• Remote Repository: On GitHub (usually "origin")
• Branches: Independent lines of development

• Snapshots of your project at a specific point
• Include message, author, date, and changes
• Should be atomic (single logical change)

• Combines branches by creating a merge commit
• Non-destructive (preserves all history)
• Best for shared branches

• Replays commits on a new base
• Creates linear history
• Only use on branches you own

✓ Require pull request reviews (minimum 2)
✓ Require status checks to pass
✓ Require branches to be up to date
✓ Require signed commits
✓ Restrict push permissions
✗ No force pushes

✓ Require pull request reviews (minimum 1)
✓ Require status checks to pass
✓ Require branches to be up to date
✓ Restrict admin bypass
✗ No force pushes

# 1. Create feature from develop
git checkout develop
git pull origin develop
git checkout -b feature/awesome-feature

# 2. Make commits
git commit -m "feat(core): implement awesome feature"

# 3. Push and create PR
git push -u origin feature/awesome-feature

# 4. After approval, merge to develop
git checkout develop
git merge --no-ff feature/awesome-feature

# 5. Delete feature branch
git branch -d feature/awesome-feature
git push origin --delete feature/awesome-feature

# 1. Create release branch from develop
git checkout -b release/1.2.0

# 2. Update version and changelog
# vim package.json
# vim CHANGELOG.md

# 3. Test thoroughly, fix bugs if needed
# git commit -m "fix(release): ..."

# 4. Merge to main with tag
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin main --tags

# 5. Merge back to develop
git checkout develop
git merge --no-ff release/1.2.0
git push origin develop

# 1. Create hotfix from main
git checkout main
git checkout -b hotfix/critical-bug

# 2. Fix the issue
# git commit -m "fix: ..."

# 3. Merge to main and develop
git checkout main
git merge --no-ff hotfix/critical-bug
git tag -a v1.2.1 -m "Hotfix 1.2.1"
git push origin main --tags

git checkout develop
git merge --no-ff hotfix/critical-bug
git push origin develop

• ✓ Write clear, descriptive messages
• ✓ Keep commits atomic (one logical change)
• ✓ Reference issue numbers in messages
• ✗ Avoid vague messages ("update", "fix")
• ✗ Don't mix unrelated changes

• ✓ Use consistent naming conventions
• ✓ Delete branches after merging
• ✓ Keep branches up to date with develop
• ✓ Keep features small and focused
• ✗ Don't rebase shared branches
• ✗ Don't force push to main or develop

• ✓ Use --no-ff for feature branches
• ✓ Require code review before merge
• ✓ Run tests before merging
• ✓ Keep commit history clean
• ✗ Avoid merge commits on main
• ✗ Don't skip testing

• ✓ Plan releases in advance
• ✓ Test thoroughly in staging
• ✓ Use semantic versioning
• ✓ Tag all releases
• ✓ Keep changelog updated
• ✗ Don't release without testing
• ✗ Don't skip version updates

# Set your identity
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Use better diff viewer
git config --global diff.tool vimdiff

# Enable helpful color output
git config --global color.ui auto

# See your configuration
git config --global --list

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 'log --oneline --graph --all'

• GitHub Desktop - Visual Git client for beginners
• GitKraken - Feature-rich Git GUI
• VS Code - Built-in Git integration
• SourceTree - Free visual Git client
• git-flow - Git extensions for Git Flow workflow

• ✓ You have planned release schedules
• ✓ You support multiple versions simultaneously
• ✓ Your team is large (5+ developers)
• ✓ You need clear separation of concerns
• ✓ Your project has complex workflows

• ✓ You deploy continuously
• ✓ You maintain only one production version
• ✓ Your team is small (1-5 developers)
• ✓ You want simplicity and speed
• ✓ You're building a web application

• ✓ You deploy very frequently (multiple times daily)
• ✓ You have strong automated testing
• ✓ Your team is highly coordinated
• ✓ You want minimal branching overhead
• ✓ You use feature flags extensively

Issue: "merge conflict"

# View conflicts
git status

# Manually resolve conflicts in files
# Then stage and commit
git add .
git commit -m "resolve merge conflicts"

Issue: "detached HEAD"

# You're on a commit, not a branch
# Go back to develop
git checkout develop

# Or create a new branch from current commit
git checkout -b feature/new-branch

Issue: "need to undo last commit"

# Keep changes
git reset --soft HEAD~1

# Discard changes
git reset --hard HEAD~1

# Create opposite commit
git revert HEAD

For more troubleshooting, see individual guide files.

1. Read 01-git-fundamentals.md
2. Setup Git locally
3. Create a test repository
4. Practice basic commands

1. Read 02-branching-strategy.md
2. Read 03-branching-workflow.md
3. Practice creating feature branches
4. Practice merging branches

1. Read 04-merging-rebase.md
2. Read 05-commits.md
3. Practice rebasing locally
4. Practice interactive rebase

1. Read 06-main-branch.md
2. Read 07-develop-branch.md
3. Read 08-release-branch.md
4. Read 09-hotfix-branch.md
5. Read 10-hands-on-example.md

1. Review all documents
2. Customize for your team
3. Setup branch protection
4. Document team conventions
5. Train team on workflow

• Clone a repository
• Create and switch branches
• Make commits with meaningful messages
• Push branches to remote
• Create a pull request

• Merge a feature branch
• Resolve merge conflicts
• Update a branch with git rebase
• Use interactive rebase
• Create and push a git tag

• Setup branch protection rules
• Create a release branch
• Simulate a hotfix scenario
• Revert a problematic commit
• Squash commits before merging

1. Branching enables parallel development
2. Git Flow is great for complex projects
3. GitHub Flow is great for simple, fast-moving projects
4. Merging preserves history; rebasing linearizes it
5. Good commits are atomic and well-documented
6. Main branch must always be production-ready
7. Develop branch is where features integrate
8. Release branches prepare code for production
9. Hotfix branches fix critical production issues
10. Communication and discipline make workflow smooth

• Git Official Documentation
• GitHub Flow Guide
• Atlassian Git Tutorials
• Oh My Git! - Interactive Learning
• Git Visualization Tool

If you have questions:

1. Check the relevant guide file
2. Review the diagrams in diagrams/ folder
3. See the command examples in examples/ folder
4. Consult the 10-hands-on-example.md
5. Ask a team lead or more experienced developer

• Created: January 2026
• Version: 1.0
• Status: Complete and ready for team use
• Format: Markdown with ASCII diagrams
• Next Steps: Deploy to GitHub, train team, customize for your workflow

Found an issue or want to improve the documentation?

1. Create a feature branch: git checkout -b docs/improvement
2. Make your changes
3. Create a pull request
4. Get review and merge

Ready to master Git and GitHub workflows? Start with 01-git-fundamentals.md! 🚀