Skip to content

A comprehensive Git Flow workflow implementation guide with practical examples, automated hooks, and best practices for managing feature branches, releases, and collaborative development

Notifications You must be signed in to change notification settings

LinusBwana/ALXprodev-advanced_git

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 

Repository files navigation

Git Flow Setup Guide

This guide walks you through installing and configuring Git Flow for your development workflow.

Table of Contents

Installing Git Flow on Ubuntu

Ubuntu 22.04 and newer:

sudo apt update sudo apt install git-flow

Ubuntu 20.04 and older:

sudo apt update sudo apt install git-flow-avh

Verify Installation:

git flow version

Initial Repository Setup

Follow these steps to set up a new repository with Git Flow:

# Clone your repository git clone https://github.com/YOUR_USERNAME/ALXprodev-advanced_git.git cd ALXprodev-advanced_git # Create and setup master branch git checkout -b master git commit --allow-empty -m "Initial commit" git push -u origin master # Create and setup develop branch git checkout -b develop git commit --allow-empty -m "Initial commit on develop" git push -u origin develop # Initialize git-flow with defaults git flow init -d # Create README.md touch README.md git add README.md git commit -m "Add README.md" git push origin develop

Git Flow Branch Naming Conventions

When you run git flow init (without the -d flag), you'll be prompted to configure branch prefixes:

How to name your supporting branch prefixes? Feature branches? [feature/] Bugfix branches? [bugfix/] Release branches? [release/] Hotfix branches? [hotfix/] Support branches? [support/] Version tag prefix? [] 

Default Prefixes Explained:

Branch Type Prefix Purpose Example
Feature feature/ New features or enhancements feature/user-authentication
Bugfix bugfix/ Bug fixes during development bugfix/login-error
Release release/ Preparing for production release release/1.0.0
Hotfix hotfix/ Critical fixes for production hotfix/security-patch
Support support/ Long-term support branches support/v1.x
Version Tag (empty) Version tags for releases 1.0.0, v2.1.3

Recommendation: Use the default prefixes unless you have specific team requirements.

Understanding Git Flow

Git Flow is a branching model that defines a strict branching structure designed around project releases.

Main Branches

  1. master (or main): Production-ready code

    • Contains official release history
    • Every commit represents a new production release
    • Tagged with version numbers
  2. develop: Integration branch for features

    • Contains the latest development changes
    • Serves as the base for feature branches
    • Merged into master for releases

Supporting Branches

Feature Branches

  • Branch from: develop
  • Merge back into: develop
  • Purpose: Develop new features
  • Naming: feature/*
# Start a new feature git flow feature start user-login # Finish a feature (merges back to develop) git flow feature finish user-login

Release Branches

  • Branch from: develop
  • Merge back into: master and develop
  • Purpose: Prepare for production release
  • Naming: release/*
# Start a release git flow release start 1.0.0 # Finish a release git flow release finish 1.0.0

Hotfix Branches

  • Branch from: master
  • Merge back into: master and develop
  • Purpose: Quick fixes for production issues
  • Naming: hotfix/*
# Start a hotfix git flow hotfix start critical-bug # Finish a hotfix git flow hotfix finish critical-bug

Git Flow Workflow Diagram

master ──●────────────●──────────●──────→ │ │ │ │ release/1.0 │ │ │ │ develop ───●──●──●──●──●──●──●────●──●──→ │ │ │ feature/ │ feature/ login │ payment bugfix/ error 

Common Git Flow Commands

Initialization

# Initialize with defaults git flow init -d # Initialize with custom settings git flow init

Feature Workflow

# List features git flow feature list # Start new feature git flow feature start <feature-name> # Publish feature to remote git flow feature publish <feature-name> # Finish feature git flow feature finish <feature-name> # Delete feature git flow feature delete <feature-name>

Release Workflow

# Start release git flow release start <version> # Publish release git flow release publish <version> # Finish release (creates tag) git flow release finish <version>

Hotfix Workflow

# Start hotfix git flow hotfix start <version> # Finish hotfix git flow hotfix finish <version>

Useful Options

# Keep branch after finishing git flow feature finish -k <feature-name> # Don't tag on release finish git flow release finish -n <version> # Force deletion git flow feature delete -f <feature-name>

Best Practices

  1. Never commit directly to master/main: Always use proper Git Flow branches
  2. Keep features small: Easier to review and merge
  3. Update develop regularly: Pull latest changes before starting new features
  4. Use descriptive names: feature/add-user-authentication not feature/fix
  5. Clean up branches: Delete finished feature branches
  6. Tag releases: Use semantic versioning (e.g., 1.0.0, 1.1.0, 2.0.0)
  7. Test before finishing: Ensure features work before merging to develop
  8. Document in README: Keep this file updated with project-specific conventions

Advantages of Git Flow

  • Parallel Development: Multiple features can be developed simultaneously
  • Organized Releases: Clear release preparation process
  • Emergency Fixes: Hotfix support without disrupting development
  • Clear History: Easy to track what was released and when
  • Team Collaboration: Standardized workflow for all team members

Troubleshooting

Issue: "Local branch does not exist"

Solution: Ensure master and develop branches exist before running git flow init

Issue: "src refspec does not match any"

Solution: Make at least one commit before pushing a branch

Issue: Git Flow commands not found

Solution: Reinstall git-flow or check installation with git flow version

Resources

Repository Information

  • Repository: ALXprodev-advanced_git
  • Default Branch: develop
  • Production Branch: master
  • Git Flow Version: Check with git flow version

Practical Workflows: Complete Command Sequences

1. Creating a Feature Branch

Complete workflow for creating and pushing a feature branch:

# Ensure you're on develop branch git checkout develop # Create feature branch git flow feature start implement-login # Create directory and file mkdir login-page echo "Login Feature Coming soon" > login-page/README.md # Stage, commit, and push git add login-page/README.md git commit -m "feat: scaffolding login page" git push origin feature/implement-login

Verification:

# Check current branch git branch # Check file exists cat login-page/README.md # Check commit history git log --oneline -1

2. Creating a Release Branch

Complete workflow for creating a release, updating files, and tagging:

# Step 1: Create and push signup feature git checkout develop git flow feature start implement-signup mkdir signup-page echo "feature coming soon" > signup-page/README.md git add signup-page/README.md git commit -m "feat: scaffolding signup page" git push origin feature/implement-signup # Step 2: Merge features to develop git flow feature finish implement-signup git checkout develop git fetch origin git merge origin/feature/implement-login # If login feature exists on remote git push origin develop # Step 3: Create release branch git flow release start 1.0.0 # Step 4: Update signup README with requirements echo "feature coming soon data requirements: email, firstName, lastName, profilePic]" > signup-page/README.md git add signup-page/README.md git commit -m "docs: add data requirements to signup page" git push origin release/1.0.0 # Step 5: Finish release and push everything git flow release finish 1.0.0 # Enter tag message when prompted: "Release version 1.0.0" git push origin main git push origin develop git push origin v1.0.0 # Or push all tags: git push --tags

Alternative Manual Merge (if git flow finish has issues):

# Merge release to main git checkout main git merge release/1.0.0 git push origin main # Create and push tag git tag -a v1.0.0 -m "Release version 1.0.0" git push origin v1.0.0 # Merge release back to develop git checkout develop git merge release/1.0.0 git push origin develop # Delete release branch git branch -d release/1.0.0 git push origin --delete release/1.0.0

Verification:

# Check all branches git branch -a # Check tags git tag -l # Verify main branch has both features git checkout main ls -la cat signup-page/README.md

3. Git Hooks and Automation

Complete setup for pre-commit and post-merge hooks:

# Navigate to repository root cd /home/ALXprodev-advanced_git # Create pre-commit hook (checks for README files in all directories) cat > .git/hooks/pre-commit << 'EOF' #!/bin/bash  # Pre-commit hook: Check if each directory has a README file  echo "Running pre-commit hook: Checking for README files..."  # Get all directories in the repository (excluding .git) directories=$(find . -type d -not -path '*/\.*' -not -path '.')  missing_readme=0  for dir in $directories; do  # Skip root directory  if [ "$dir" = "." ]; then  continue  fi    # Check if README.md or README exists in the directory  if [ ! -f "$dir/README.md" ] && [ ! -f "$dir/README" ]; then  echo "ERROR: Missing README file in directory: $dir"  missing_readme=1  fi done  if [ $missing_readme -eq 1 ]; then  echo ""  echo "❌ Pre-commit hook failed!"  echo "Please add README.md files to all directories before committing."  exit 1 fi  echo "✅ All directories have README files." exit 0 EOF # Create post-merge hook (logs merges to main branch) cat > .git/hooks/post-merge << 'EOF' #!/bin/bash  # Post-merge hook: Log merge information  # Get current branch current_branch=$(git rev-parse --abbrev-ref HEAD)  # Only log if we're on main/master branch if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then    # Create logs directory if it doesn't exist  log_dir=".git/logs/merge-logs"  mkdir -p "$log_dir"    # Log file path  log_file="$log_dir/merge-history.log"    # Get merge information  timestamp=$(date '+%Y-%m-%d %H:%M:%S')  commit_hash=$(git rev-parse HEAD)  commit_message=$(git log -1 --pretty=%B)  author=$(git log -1 --pretty=%an)    # Log the merge  echo "================================" >> "$log_file"  echo "Merge completed on: $current_branch" >> "$log_file"  echo "Timestamp: $timestamp" >> "$log_file"  echo "Commit Hash: $commit_hash" >> "$log_file"  echo "Author: $author" >> "$log_file"  echo "Commit Message: $commit_message" >> "$log_file"  echo "================================" >> "$log_file"  echo "" >> "$log_file"    echo "✅ Merge logged successfully to $log_file" fi  exit 0 EOF # Make both hooks executable chmod +x .git/hooks/pre-commit chmod +x .git/hooks/post-merge echo "✅ Git hooks installed successfully!"

Test Pre-Commit Hook:

# Try to commit without README in a new directory mkdir test-dir touch test-dir/test.txt git add test-dir/ git commit -m "test commit" # Should fail with error message # Fix it by adding README echo "Test directory" > test-dir/README.md git add test-dir/ git commit -m "test commit" # Should succeed

Test Post-Merge Hook:

# Create a test feature and merge to main git checkout develop git flow feature start test-hook echo "test" > test-file.txt git add test-file.txt git commit -m "test: hook testing" git flow feature finish test-hook # Merge to main to trigger post-merge hook git checkout main git merge develop # Check the log file cat .git/logs/merge-logs/merge-history.log

Verify Hook Installation:

# Check if hooks exist and are executable ls -la .git/hooks/pre-commit ls -la .git/hooks/post-merge # View hook contents cat .git/hooks/pre-commit cat .git/hooks/post-merge

What These Hooks Do:

  1. Pre-Commit Hook:

    • Runs before every commit
    • Scans all directories in the repository
    • Checks if each directory has a README.md or README file
    • Blocks the commit if any directory is missing a README
    • Provides clear error messages
  2. Post-Merge Hook:

    • Runs after every successful merge
    • Only activates when merging into main/master branch
    • Logs merge details to .git/logs/merge-logs/merge-history.log
    • Records: timestamp, commit hash, author, and commit message

About

A comprehensive Git Flow workflow implementation guide with practical examples, automated hooks, and best practices for managing feature branches, releases, and collaborative development

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published