Git Flow Setup Guide

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

# 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

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:

Understanding Git Flow

Main Branches

Supporting Branches

Feature Branches

# 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

# Start a release
git flow release start 1.0.0
# Finish a release
git flow release finish 1.0.0

Hotfix Branches

# 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

Advantages of Git Flow

Troubleshooting

Issue: "Local branch does not exist"

Issue: "src refspec does not match any"

Issue: Git Flow commands not found

Resources

Repository Information

Practical Workflows: Complete Command Sequences

1. Creating 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

# 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

# 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

# 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

# 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

# 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!"

# 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

# 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

# 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