Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
602 lines (455 loc) · 20.2 KB

ARCHITECTURE.md

File metadata and controls

602 lines (455 loc) · 20.2 KB

git-flow-next Technical Overview

git-flow-next is a modern, flexible implementation of Git workflow management that builds upon the original git-flow concepts while providing extensive customization capabilities for modern development practices.

See also: CODE_REFERENCE.md for a quick codebase navigation guide with file paths, struct definitions, and implementation details.

Project Structure

The project follows Go best practices with clear separation of concerns:

git-flow-next/
├── cmd/                    # Command implementations
│   ├── root.go            # Root CLI command setup with Cobra
│   ├── init.go            # Repository initialization command
│   ├── start.go           # Branch starting logic  
│   ├── finish.go          # Branch finishing logic (most complex)
│   ├── topicbranch.go     # Dynamic command registration for branch types
│   ├── list.go            # Branch listing commands
│   ├── checkout.go        # Branch checkout functionality
│   ├── delete.go          # Branch deletion
│   ├── rename.go          # Branch renaming
│   ├── update.go          # Branch updating from parent
│   └── overview.go        # Repository overview/status
├── internal/              # Internal packages (not exported)
│   ├── config/           # Git configuration management
│   │   └── config.go     # Branch type definitions, config loading
│   ├── git/              # Git command wrapper
│   │   └── repo.go       # Git operations with error handling
│   ├── mergestate/       # Merge conflict state persistence
│   │   └── mergestate.go # State management for multi-step operations
│   ├── errors/           # Custom error types and exit codes
│   │   └── errors.go     # Structured error handling
│   ├── util/             # Validation and utility functions
│   │   └── validation.go # Input validation helpers
│   └── update/           # Branch updating logic
│       └── update.go     # Shared update functionality
├── test/                  # Test files (mirrors source structure)
│   ├── cmd/              # Command-level integration tests
│   ├── internal/         # Internal package unit tests
│   └── testutil/         # Test utilities and Git repo helpers
├── scripts/              # Build and deployment scripts
│   └── build.sh          # Multi-platform build script
├── main.go               # Application entry point
└── [documentation files] # README.md, ARCHITECTURE.md, etc.

Key Organizational Principles

  • cmd/: Contains all CLI command implementations using the Cobra framework
  • internal/: Private packages that handle core functionality (config, git operations, state management)
  • test/: Mirrors the source structure with comprehensive test coverage
  • testutil/: Shared testing utilities, especially Git repository helpers

Core Architecture

Branch Dependency Model

The foundation of git-flow-next is a branch dependency model that formalizes the parent-child relationship between branches. This model enables:

  • Automatic tracking of dependencies between branches
  • Intelligent synchronization of changes across branch hierarchies
  • Consistent propagation of changes through the dependency tree
  • Visualization of branch relationships

Every branch (except root branches) has a parent, and branches can have multiple children. This simple paradigm enables powerful workflow customization.

Branch Types

git-flow-next defines two fundamental branch types:

Base Branches (Long-living)

  • Exist throughout the project lifecycle
  • Serve as integration points for features and releases
  • Examples: main, develop, staging, production
  • Configured with parent-child relationships for change propagation

Topic Branches (Short-living)

  • Created for specific purposes (features, hotfixes, releases)
  • Always have a defined parent base branch
  • Automatically cleaned up after completion
  • Examples: feature/login, hotfix/security-fix, release/v1.0

Single Topic Branch Implementation

Unified Command Structure

Instead of separate commands for feature, hotfix, and release branches, git-flow-next implements a single topic branch mechanism:

# Traditional git-flow
git flow feature start my-feature
git flow hotfix start critical-fix
git flow release start v1.0

# git-flow-next unified approach
git flow topic start feature my-feature
git flow topic start hotfix critical-fix  
git flow topic start release v1.0

All topic branches use the same start and finish commands, with behavior determined by configuration rather than branch type.

Configurable Behavior

Topic branch behavior is defined through Git configuration at two levels. Branch type configuration (Layer 1) defines the branch type's identity and process characteristics:

  • Parent branch: Which base branch to branch from (structural)
  • Start point: Where to create the branch (structural)
  • Merge strategies: How changes flow upstream and downstream (process)
  • Tag creation: Whether the branch type produces tags on finish (process)
  • Child branch updates: Automatic updating of child base branches after finish (process)

Command-specific configuration (Layer 2) then controls operational details like fetch behavior, tag signing, and branch retention. CLI flags (Layer 3) override everything for one-off situations.

Configuration System

Default Configuration Overview

git-flow-next provides sensible defaults that work for most teams while remaining fully customizable.

Branch Structure

main/master     ← Production releases
    ↓
develop         ← Integration branch (auto-updated from main)
    ↓
feature/        ← New features
release/        ← Release preparation  
hotfix/         ← Emergency fixes

Base Branches

Branch Type Parent Config Key Auto-Update from Parent
main base (root) gitflow.branch.main None
develop base main gitflow.branch.develop ✅ Yes

Topic Branches

Branch Type Prefix Parent Start Point Config Key Created by Default
Feature feature/ develop develop gitflow.branch.feature ✅ Yes
Release release/ main develop gitflow.branch.release ✅ Yes
Hotfix hotfix/ main main gitflow.branch.hotfix ✅ Yes

Merge Strategies

Upstream Strategy (Finish Operations) - How topic branches merge into their parent:

Branch Type Default Options Target Branch
Feature merge merge, rebase, squash → develop
Release merge merge, rebase, squash → main
Hotfix merge merge, rebase, squash → main

Downstream Strategy (Update Operations) - How parent updates are pulled into topic branches:

Branch Type Default Options Source Branch
Feature rebase merge, rebase ← develop
Release merge merge, rebase ← main
Hotfix rebase merge, rebase ← main

Note: The --rebase flag can be used with the update command to override the configured strategy and force rebase behavior.

Tag Configuration

Branch Type Default Tagging Tag Prefix When Tagged
Feature ❌ Disabled (configurable) Never by default
Bugfix ❌ Disabled (configurable) Never by default
Release ✅ Enabled v (during init) On finish
Hotfix ✅ Enabled v (during init) On finish
Support ❌ Disabled (configurable) Never by default

Branch Retention (After Finish)

Setting Default Description
Delete Local ✅ Yes Remove local branch after successful merge
Delete Remote ✅ Yes Remove remote branch after successful merge
Force Delete ❌ No Use safe delete (checks for unmerged commits)

Core Configuration Commands

# Base branch names
git config gitflow.branch.main main
git config gitflow.branch.develop develop

# Base branch relationships
git config gitflow.branch.develop.parent main
git config gitflow.branch.develop.upstreamStrategy merge
git config gitflow.branch.develop.downstreamStrategy merge
git config gitflow.branch.develop.autoUpdate true

# Topic branch prefixes
git config gitflow.branch.feature.prefix feature/
git config gitflow.branch.release.prefix release/
git config gitflow.branch.hotfix.prefix hotfix/

# Branch relationships
git config gitflow.branch.feature.parent develop
git config gitflow.branch.release.parent main
git config gitflow.branch.hotfix.parent main

# Merge strategies (upstream - finish operations)
git config gitflow.feature.finish.merge merge
git config gitflow.release.finish.merge merge
git config gitflow.hotfix.finish.merge merge

# Merge strategies (downstream - update operations)
git config gitflow.feature.downstreamStrategy rebase
git config gitflow.release.downstreamStrategy merge
git config gitflow.hotfix.downstreamStrategy rebase

# Tag settings
git config gitflow.feature.finish.notag true
git config gitflow.release.finish.notag false
git config gitflow.hotfix.finish.notag false

# Usage examples
git flow update feature/my-feature              # Uses configured strategy
git flow update feature/my-feature --rebase     # Forces rebase strategy
git flow rebase                                 # Shorthand for update --rebase

Note: Release and hotfix branches merge only into main, then develop is automatically updated from main to stay synchronized.

Branch Configuration Structure

Base branches are configured with dependency relationships:

[gitflow "branch.main"]
    type = base
    parent = 
    upstreamStrategy = none
    downstreamStrategy = none

[gitflow "branch.develop"] 
    type = base
    parent = main
    upstreamStrategy = merge
    downstreamStrategy = merge

Topic branch types are configured with the same key format:

[gitflow "branch.feature"]
    type = topic
    parent = develop
    startPoint = develop
    upstreamStrategy = rebase
    downstreamStrategy = squash-merge

Configurable Properties (Layer 1 — Branch Type Definition)

These properties define the branch type's identity and process characteristics. They describe what the branch type is, not how individual commands behave.

For Base Branches:

  • parent: The parent base branch for dependency tracking (structural)
  • upstreamStrategy: How changes flow to parent (process)
  • downstreamStrategy: How updates flow from parent (process)
  • autoUpdate: Whether the branch receives updates automatically on finish (process)

For Topic Branch Types (using gitflow.branch.* keys):

  • parent: Default parent base branch (structural)
  • startPoint: Branch to create from — can differ from parent (structural)
  • prefix: Branch name prefix (structural)
  • upstreamStrategy: How to merge back to parent on finish (process)
  • downstreamStrategy: How to receive updates from parent (process)
  • tag: Whether the branch type produces tags on finish (process)
  • tagPrefix: Prefix for created tags (process)

Merge Strategies

git-flow-next supports multiple merge strategies:

  • merge: Standard Git merge with merge commit
  • rebase: Rebase changes onto target branch
  • squash: Squash all commits into single commit
  • none: No automatic merging

Example Workflow Configurations

1. Simple GitHub Flow

Perfect for continuous deployment with hotfix capability:

[gitflow "branch.main"]
    type = base
    parent = 
    upstreamStrategy = none
    downstreamStrategy = none

[gitflow "branch.feature"]
    type = topic
    parent = main
    startPoint = main
    upstreamStrategy = rebase
    downstreamStrategy = rebase

[gitflow "branch.hotfix"]
    type = topic
    parent = main
    startPoint = main
    upstreamStrategy = merge
    downstreamStrategy = none

Branch Structure:

main
├── feature/user-interface
├── feature/api-integration
└── hotfix/security-patch

2. Traditional Git-Flow

Classic git-flow with develop branch and release management:

[gitflow "branch.main"]
    type = base
    parent = 
    upstreamStrategy = none
    downstreamStrategy = none

[gitflow "branch.develop"]
    type = base
    parent = main
    upstreamStrategy = merge
    downstreamStrategy = merge

[gitflow "branch.feature"]
    type = topic
    parent = develop
    startPoint = develop
    upstreamStrategy = rebase
    downstreamStrategy = merge

[gitflow "branch.release"]
    type = topic
    parent = main
    startPoint = develop
    upstreamStrategy = merge
    downstreamStrategy = none
    tag = true

[gitflow "branch.hotfix"]
    type = topic
    parent = main
    startPoint = main
    upstreamStrategy = merge
    downstreamStrategy = none
    tag = true

Branch Structure:

main
├── hotfix/critical-fix
├── release/v1.0
└── develop
     ├── feature/payment-gateway
     │    └── feature/card-processing
     ├── feature/user-authentication
     │    └── feature/two-factor-auth

3. Web Application Flow

Multi-environment deployment with staging and production:

[gitflow "branch.production"]
    type = base
    parent = 
    upstreamStrategy = none
    downstreamStrategy = none

[gitflow "branch.staging"]
    type = base
    parent = production
    upstreamStrategy = merge
    downstreamStrategy = merge

[gitflow "branch.main"]
    type = base
    parent = staging
    upstreamStrategy = merge
    downstreamStrategy = merge

[gitflow "branch.feature"]
    type = topic
    parent = main
    startPoint = main
    upstreamStrategy = rebase
    downstreamStrategy = rebase

[gitflow "branch.hotfix"]
    type = topic
    parent = production
    startPoint = production
    upstreamStrategy = merge
    downstreamStrategy = none

Branch Structure:

production
├── hotfix/urgent-fix
└── staging
    └── main
        ├── feature/new-feature
        └── feature/ui-improvement

Advanced Features

Automatic Branch Updates

Configure branches to automatically receive updates from their parent:

[gitflow "branch.develop"]
    parent = main
    autoUpdate = true
    downstreamStrategy = merge

When autoUpdate is enabled, finishing a topic branch into main automatically propagates changes to develop.

Cascade Updates

Changes can cascade through multiple levels of the dependency tree:

  1. Finish hotfix/security-patch into production
  2. Changes automatically flow to staging (if configured)
  3. Changes then flow to main (if configured)
  4. Finally cascade to develop (if configured)

Tag Creation

Automatic tag creation with configurable naming:

[gitflow "branch.release"]
    tag = true
    tagPrefix = "v"

Child Branch Updates

When finishing a topic branch, git-flow-next automatically updates child base branches that depend on the target parent branch. This ensures consistency across the branch hierarchy:

# Finishing a hotfix into main automatically updates develop
git flow topic finish hotfix security-patch

# The system will:
# 1. Merge hotfix/security-patch into main  
# 2. Automatically update develop from main (if configured)
# 3. Update any other child branches of main

Configure automatic updates in base branch settings:

[gitflow "branch.develop"]
    parent = main
    autoUpdate = true
    downstreamStrategy = merge

Command Structure

Core Commands

# Initialize git-flow configuration
git flow init

# Topic branch operations
git flow topic start <type> <name>
git flow topic finish <type> <name>
git flow topic list <type>

# Base branch operations  
git flow merge-upstream <branch>  # or: git flow up <branch>
git flow update <branch>
git flow update <branch> --rebase  # Force rebase strategy

# Shorthand commands (auto-detect branch type)
git flow rebase                    # Shorthand for: git flow <type> update --rebase
git flow update                    # Shorthand for: git flow <type> update
git flow finish                    # Shorthand for: git flow <type> finish

# Status and overview
git flow status
git flow overview

Command Aliases

For compatibility, traditional commands are aliased:

git flow feature start <name>    # → git flow topic start feature <name>
git flow hotfix finish <name>    # → git flow topic finish hotfix <name>
git flow release list            # → git flow topic list release

Shorthand Commands

git-flow-next provides convenient shorthand commands that automatically detect your current topic branch:

git flow rebase                   # → git flow <type> update --rebase
git flow update                   # → git flow <type> update
git flow finish                   # → git flow <type> finish
git flow delete                   # → git flow <type> delete
git flow rename <name>            # → git flow <type> rename <name>

Command Implementation

Command Structure Overview

Commands in git-flow-next are implemented using the Cobra CLI framework with a clear architectural pattern:

  1. Root Command (cmd/root.go): Sets up the main CLI structure and global flags
  2. Dynamic Registration (cmd/topicbranch.go): Automatically registers branch type commands based on configuration
  3. Individual Commands (cmd/*.go): Each major operation has its own file with specific logic

All commands follow a consistent pattern: validate inputs, load configuration, execute Git operations, and handle errors gracefully.

The Finish Command: A Deep Dive

The finish command (cmd/finish.go) is the most complex command in the system, demonstrating the sophisticated architecture used throughout git-flow-next.

Step-Based State Machine

The finish command uses a step-based state machine approach to handle complex multi-step operations that can be interrupted by merge conflicts:

Steps: merge → create_tag → update_children → delete_branch

This architecture allows the command to:

  • Resume operations after conflict resolution
  • Provide clear progress feedback
  • Handle complex branching scenarios
  • Maintain consistency across interruptions

State is persisted to disk (mergestate.MergeState) so the operation can resume after conflict resolution via --continue or be cancelled with --abort. Each step has a dedicated handler, and child branch updates respect individual downstream strategies (see Advanced Features > Child Branch Updates above).

For implementation details—struct definitions, handler functions, and code examples—see CODE_REFERENCE.md.

Integration Points

Tower Integration

git-flow-next integrates seamlessly with Tower, providing graphical workflow management while using the same configuration system.

CI/CD Integration

The flexible configuration system enables easy integration with modern CI/CD pipelines by supporting:

  • Webhook-triggered deployments based on branch patterns
  • Environment-specific deployment strategies
  • Automatic tag-based releases

Migration from git-flow-avh

git-flow-next maintains compatibility with existing git-flow-avh configurations while providing migration tools for enhanced features:

# Import existing configuration
git flow init --import-avh

# Migrate to new configuration format
git flow config migrate

Extensibility

The unified topic branch implementation and configuration-driven approach make git-flow-next highly extensible:

  • Add custom branch types through configuration
  • Define organization-specific workflow templates
  • Create custom merge strategies through hooks
  • Extend functionality through plugin architecture

This technical foundation enables teams to implement any branching strategy while maintaining the automation and convenience that made git-flow popular.