Git Flow Setup Guide

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

Installing Git Flow on Ubuntu
Initial Repository Setup
Git Flow Branch Naming Conventions
Understanding Git Flow
Common Git Flow Commands

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

master (or main): Production-ready code
- Contains official release history
- Every commit represents a new production release
- Tagged with version numbers
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

Never commit directly to master/main: Always use proper Git Flow branches
Keep features small: Easier to review and merge
Update develop regularly: Pull latest changes before starting new features
Use descriptive names: feature/add-user-authentication not feature/fix
Clean up branches: Delete finished feature branches
Tag releases: Use semantic versioning (e.g., 1.0.0, 1.1.0, 2.0.0)
Test before finishing: Ensure features work before merging to develop
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:

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
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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Git Flow Setup Guide

Table of Contents

Installing Git Flow on Ubuntu

Ubuntu 22.04 and newer:

Ubuntu 20.04 and older:

Verify Installation:

Initial Repository Setup

Git Flow Branch Naming Conventions

Default Prefixes Explained:

Understanding Git Flow

Main Branches

Supporting Branches

Feature Branches

Release Branches

Hotfix Branches

Git Flow Workflow Diagram

Common Git Flow Commands

Initialization

Feature Workflow

Release Workflow

Hotfix Workflow

Useful Options

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

2. Creating a Release Branch

3. Git Hooks and Automation

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Git Flow Setup Guide

Table of Contents

Installing Git Flow on Ubuntu

Ubuntu 22.04 and newer:

Ubuntu 20.04 and older:

Verify Installation:

Initial Repository Setup

Git Flow Branch Naming Conventions

Default Prefixes Explained:

Understanding Git Flow

Main Branches

Supporting Branches

Feature Branches

Release Branches

Hotfix Branches

Git Flow Workflow Diagram

Common Git Flow Commands

Initialization

Feature Workflow

Release Workflow

Hotfix Workflow

Useful Options

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

2. Creating a Release Branch

3. Git Hooks and Automation