### Complex Workflow Setup Example

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-config.1.md

This example demonstrates setting up a GitLab Flow workflow by configuring multiple base and topic branches with specific relationships and options.

```bash
# Base branches
git flow config add base production
git flow config add base staging production  
git flow config add base main staging

# Topic branches  
git flow config add topic feature main --prefix=feature/
git flow config add topic hotfix production --starting-point=production --tag=true
```

--------------------------------

### Start and Publish Feature Branch

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-start.1.md

This example demonstrates starting a new feature branch with remote synchronization and immediately pushing it to the origin. This is useful for collaborative workflows.

```bash
git flow feature start new-api --fetch
git push -u origin feature/new-api
```

--------------------------------

### Basic Test Setup for Git Flow

Source: https://github.com/gittower/git-flow-next/blob/main/TESTING_GUIDELINES.md

A minimal setup for testing Git Flow, including repository creation and initialization with defaults.

```go
func TestExample(t *testing.T) {
    // Setup temporary repository
    dir := testutil.SetupTestRepo(t)
    defer testutil.CleanupTestRepo(t, dir)
    
    // Initialize git-flow with defaults
    output, err := testutil.RunGitFlow(t, dir, "init", "--defaults")
    if err != nil {
        t.Fatalf("Failed to initialize git-flow: %v\nOutput: %s", err, output)
    }
    
    // Test implementation...
}
```

--------------------------------

### Install git-flow-next with WinGet

Source: https://github.com/gittower/git-flow-next/blob/main/README.md

Use WinGet to install git-flow-next on Windows systems.

```bash
winget install GitTower.GitFlowNext
```

--------------------------------

### Spot-Check Documentation Examples

Source: https://github.com/gittower/git-flow-next/blob/main/CODING_GUIDELINES.md

This command helps to spot-check documentation examples by searching for 'git flow' within markdown files in the docs directory.

```bash
# Ensure examples work
cd docs && grep -r "git flow" *.md | head -10  # Spot-check examples
```

--------------------------------

### Setup Test Repo with Pre-configured Remote Helper

Source: https://github.com/gittower/git-flow-next/blob/main/GIT_TEST_SCENARIOS.md

This Go snippet shows how to use the `SetupTestRepoWithRemote` helper function for a simplified setup of a test repository that already has a remote configured. It initializes Git Flow and prepares the repository for remote operations.

```go
func TestWithRemote(t *testing.T) {
    dir, remoteDir := testutil.SetupTestRepoWithRemote(t)
    defer testutil.CleanupTestRepo(t, dir)
    defer testutil.CleanupTestRepo(t, remoteDir)

    // Initialize git-flow
    output, err := testutil.RunGitFlow(t, dir, "init", "--defaults")
    if err != nil {
        t.Fatalf("Failed to initialize git-flow: %v", err)
    }

    // Remote 'origin' is already configured and tracking branches pushed
    // Test remote operations...
}
```

--------------------------------

### Install pandoc for manpage rendering

Source: https://github.com/gittower/git-flow-next/blob/main/docs/README.md

Install pandoc using Homebrew to enable proper rendering of manpages. This is recommended for viewing the documentation in a formatted manpage style.

```bash
# Install pandoc for best rendering
brew install pandoc
```

--------------------------------

### Local Development Setup and Build

Source: https://github.com/gittower/git-flow-next/blob/main/CONTRIBUTING.md

Steps to clone the repository, set up remotes, create a branch, build the project, and run tests.

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/git-flow-next.git
cd git-flow-next

# Add upstream remote
git remote add upstream https://github.com/gittower/git-flow-next.git

# Create branch
git checkout -b your-feature

# Build
go build -o git-flow

# Run tests
go test ./...
```

--------------------------------

### Configuration Precedence Examples

Source: https://github.com/gittower/git-flow-next/blob/main/CONFIGURATION.md

Illustrates the three-layer precedence for git-flow-next configuration settings.

```properties
# Layer 1: Branch Type Definition (Lowest Priority)
gitflow.branch.release.tag=true    # "Releases produce tags" — a process characteristic

# Layer 2: Command-Specific Configuration (Medium Priority)
gitflow.release.finish.notag=true  # Override: skip tagging for this command

# Layer 3: Command-Line Flags (Highest Priority)
git flow release finish v1.0 --tag  # Force tagging for this invocation
```

--------------------------------

### Classic GitFlow Release Workflow

Source: https://context7.com/gittower/git-flow-next/llms.txt

Illustrates the process of starting and finishing a release, including versioning and merging to main.

```bash
git flow release start 2.0.0             # branches from develop, merges to main
# ... bump version, update changelog ...
git flow release finish 2.0.0            # merges to main + tag v2.0.0 + updates develop
```

--------------------------------

### Install git-flow-next with Homebrew

Source: https://github.com/gittower/git-flow-next/blob/main/README.md

Use Homebrew to install git-flow-next on macOS and Linux systems.

```bash
brew install gittower/tap/git-flow-next
```

--------------------------------

### Standard Test Setup with Git Flow Defaults

Source: https://github.com/gittower/git-flow-next/blob/main/TESTING_GUIDELINES.md

Use this for most tests. It sets up a temporary repository, initializes Git Flow with defaults, and includes cleanup.

```go
func TestExample(t *testing.T) {
    dir := testutil.SetupTestRepo(t)
    defer testutil.CleanupTestRepo(t, dir)
    
    // Initialize with defaults - creates main, develop, and configures feature/release/hotfix
    output, err := testutil.RunGitFlow(t, dir, "init", "--defaults")
    if err != nil {
        t.Fatalf("Failed to initialize git-flow: %v\nOutput: %s", err, output)
    }
    
    // Use feature branches for topic branch testing
    output, err = testutil.RunGitFlow(t, dir, "feature", "start", "test-branch")
    // ... test implementation
}
```

--------------------------------

### Example: Add --dry-run option to commands

Source: https://github.com/gittower/git-flow-next/blob/main/ISSUE_GUIDELINES.md

Demonstrates how to propose a new feature with example usage and expected output. This includes a table for priority and code blocks for command-line interactions.

```markdown
> **Title:** Add `--dry-run` option to commands that perform more complex actions
>
> **Body:**
>
> Add a `--dry-run` / `-n` flag to commands that perform complex or destructive actions. When enabled, the command displays all operations that would be performed without actually executing them.
>
> ### Commands to Support
>
> | Priority | Command | Reason |
> |----------|---------|--------|
> | Critical | `finish` | Multi-stage: merge, tag, update children, delete |
> | High | `delete` | Permanently removes local/remote branches |
> | Medium | `publish` | Network operation, pushes to remote |
> | Medium | `update` | Merge/rebase operations, modifies history |
> | Low | `start` | Safe operation, but useful for preview |
>
> ### Example Usage
>
> ```bash
> # Preview what finish will do
> git flow feature finish my-feature --dry-run
>
> # Short flag (follows Git conventions)
> git flow release finish v1.0 -n
> ```
>
> ### Example Output
>
> ```
> Dry-run: git flow feature finish my-feature
> Target: feature/my-feature
> --------------------------------------------------
>
> Actions that would be performed:
>
>   1. Checkout parent branch 'develop'
>       $ git checkout develop
>   2. Merge 'feature/my-feature' into 'develop' using merge strategy
>       $ git merge feature/my-feature
>   3. [!] Delete local branch 'feature/my-feature'
>       $ git branch -d feature/my-feature
>
> No changes were made (dry-run mode).
> ```
```

--------------------------------

### Document Go Packages

Source: https://github.com/gittower/git-flow-next/blob/main/CODING_GUIDELINES.md

Provide package-level documentation at the top of main package files. This example shows documentation for the `config` package.

```go
// Package config provides git-flow configuration management.
// It handles loading branch type definitions and workflow settings
// from Git configuration files.
package config
```

--------------------------------

### View All Git Flow Configuration

Source: https://github.com/gittower/git-flow-next/blob/main/CONFIGURATION.md

Retrieves all configuration settings that start with 'gitflow.'. Useful for auditing or backing up your current setup.

```bash
git config --get-regexp '^gitflow\.'
```

--------------------------------

### Configure Traditional Git-Flow

Source: https://github.com/gittower/git-flow-next/blob/main/CONFIGURATION.md

Full Git-Flow setup with main, develop, and all topic types. Configures branch types, parents, start points, and tag settings for features, releases, and hotfixes.

```bash
git config gitflow.branch.main.type base
git config gitflow.branch.develop.type base
git config gitflow.branch.develop.parent main
git config gitflow.branch.develop.autoUpdate true
git config gitflow.branch.feature.type topic
git config gitflow.branch.feature.parent develop
git config gitflow.branch.feature.prefix feature/
git config gitflow.branch.release.type topic
git config gitflow.branch.release.parent main
git config gitflow.branch.release.startPoint develop
git config gitflow.branch.release.tag true
git config gitflow.branch.hotfix.type topic
git config gitflow.branch.hotfix.parent main
git config gitflow.branch.hotfix.tag true
```

--------------------------------

### Version Filter Hook for Release Start

Source: https://context7.com/gittower/git-flow-next/llms.txt

Automatically prepend 'v' to release version names during the 'start' action.

```bash
#!/bin/bash
# $1 = proposed version name; echo the transformed name to stdout
echo "v$1"   # Automatically prepend "v" to all release names
```

--------------------------------

### Configure Automatic Fetch for Release Starts

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-start.1.md

Globally enable fetching from the remote before starting any release branch. This ensures the latest changes are pulled.

```bash
git config gitflow.release.start.fetch true
```

--------------------------------

### Git Flow Feature Start Command Flow

Source: https://github.com/gittower/git-flow-next/blob/main/CODE_REFERENCE.md

Illustrates the sequence of operations when starting a new feature branch using the 'git flow feature start' command. It details steps like configuration loading, determining the starting point, fetching, and branch creation.

```shell
git flow feature start my-feature
    ↓
1. Load config → get feature.parent (develop)
2. Determine startPoint → feature.startPoint or parent
3. Fetch if configured → gitflow.feature.start.fetch
4. Create branch → git checkout -b feature/my-feature develop
```

--------------------------------

### Tag Creation Configuration Hierarchy Example

Source: https://github.com/gittower/git-flow-next/blob/main/CODING_GUIDELINES.md

Demonstrates the three-layer precedence for tag creation configuration, showing how command-line flags override Git configurations.

```bash
# Layer 1: Branch config default
git config gitflow.branch.release.tag true

# Layer 2: Command-specific override
git config gitflow.release.finish.notag true  # Disables tags

# Layer 3: Command-line override (WINS)
git flow release finish v1.0 --tag  # Forces tag creation despite config
```

--------------------------------

### Check Existing Features Before Starting New One

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-list.1.md

Before starting a new feature, list existing features to avoid conflicts or redundancy.

```bash
git flow feature list
git flow feature start new-feature
```

--------------------------------

### Configure Release Branch Starting Point

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-start.1.md

Define the default branch for starting new release branches. Typically 'develop'.

```bash
git config gitflow.branch.release.startPoint develop
```

--------------------------------

### Start a Topic Branch

Source: https://context7.com/gittower/git-flow-next/llms.txt

Creates a new topic branch from its configured start point, with options to fetch from remote and override the base. Supports pre/post hooks.

```bash
# Start a feature branch from develop (the configured start point)
git flow feature start my-feature
# Created branch 'feature/my-feature' from 'develop'

# Start a release branch — note: starts from develop by default in classic flow
git flow release start 1.2.0
# Created branch 'release/1.2.0' from 'develop'

# Start a hotfix from main
git flow hotfix start critical-security-fix
# Created branch 'hotfix/critical-security-fix' from 'main'

# Override the start point for this invocation
git flow feature start experimental-ui develop-v2

# Fetch from remote before creating the branch
git flow feature start new-api --fetch

# Enable fetching by default in config
git config gitflow.feature.start.fetch true
git flow feature start auth-service  # now fetches automatically

# Custom branch type (after configuring it)
git config gitflow.branch.bugfix.type topic
git config gitflow.branch.bugfix.parent develop
git config gitflow.branch.bugfix.prefix bugfix/
git flow bugfix start login-error
# Created branch 'bugfix/login-error' from 'develop'
```

--------------------------------

### Install git-flow-next via Package Manager

Source: https://context7.com/gittower/git-flow-next/llms.txt

Installs git-flow-next using common package managers for macOS, Linux, and Windows. Includes a verification step.

```bash
# macOS / Linux (Homebrew)
brew install gittower/tap/git-flow-next

# Windows (WinGet)
winget install GitTower.GitFlowNext

# Verify installation
git flow version
# git-flow-next version 1.1.0
```

--------------------------------

### Start a New Support Branch

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-avh/support.md

Initiates a new support branch with a specified version name. Optionally, it can be based on a different branch than master and can fetch from origin before starting.

```bash
git flow support start [-h] [-F] <version> [<base>]
```

--------------------------------

### Setup Test Repository with Git Flow Init

Source: https://github.com/gittower/git-flow-next/blob/main/GIT_TEST_SCENARIOS.md

Initializes a temporary Git repository and sets up git-flow with default configurations. Ensures proper cleanup of the test repository after execution.

```go
func TestExample(t *testing.T) {
    // Setup temporary repository
    dir := testutil.SetupTestRepo(t)
    defer testutil.CleanupTestRepo(t, dir)

    // Initialize git-flow with defaults
    output, err := testutil.RunGitFlow(t, dir, "init", "--defaults")
    if err != nil {
        t.Fatalf("Failed to initialize git-flow: %v\nOutput: %s", err, output)
    }

    // Test implementation...
}
```

--------------------------------

### Git Flow Configuration Example

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-init.1.md

Example of Git Flow configuration stored in the .git/config file. Shows settings for version, initialization status, and branch configurations.

```gitconfig
[gitflow]
    version = 1.0
    initialized = true
[gitflow "branch.main"]
    type = base
[gitflow "branch.develop"]
    type = base
    parent = main
    autoupdate = true
[gitflow "branch.feature"]
    type = topic
    parent = develop
    prefix = feature/
```

--------------------------------

### Configure Automatic Fetch for Feature Starts

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-start.1.md

Globally enable fetching from the remote before starting any feature branch. This ensures the latest changes are pulled.

```bash
git config gitflow.feature.start.fetch true
```

--------------------------------

### Start a new feature branch

Source: https://github.com/gittower/git-flow-next/blob/main/README.md

Begin a new feature by starting a dedicated branch. This command sets up the branch according to git-flow conventions.

```bash
git flow feature start my-feature
```

--------------------------------

### Classic GitFlow Feature Workflow

Source: https://context7.com/gittower/git-flow-next/llms.txt

Demonstrates the start and finish commands for a feature branch within the classic GitFlow model.

```bash
# Full workflow:
git flow feature start user-auth         # branches from develop
# ... commit work ...
git flow feature finish user-auth        # merges into develop
```

--------------------------------

### Initialize Git Flow with Preset and Defaults

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-init.1.md

Combines a specific preset with default settings to initialize Git Flow. Ensures a consistent setup with minimal interaction.

```bash
git flow init --preset=classic --defaults
```

--------------------------------

### Partial Matching Examples

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-checkout.1.md

Illustrates how partial names are matched against existing feature branches. Ambiguous matches will prompt for clarification.

```bash
git flow feature checkout user    # Ambiguous - shows options
```

```bash
git flow feature checkout user-a  # Matches user-authentication
```

```bash
git flow feature checkout api     # Matches api-endpoints
```

--------------------------------

### Install a Git-flow Hook

Source: https://github.com/gittower/git-flow-next/blob/main/contrib/hooks/README.md

Copy a hook script to your repository's .git/hooks/ directory and make it executable.

```bash
cp contrib/hooks/pre-flow-release-start /path/to/repo/.git/hooks/

chmod +x /path/to/repo/.git/hooks/pre-flow-release-start
```

--------------------------------

### Start a New Release Branch

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-avh/release.md

Initiates a new release branch for a specified version. Optionally fetches from origin and shows git commands.

```bash
git flow release start [-h] [-F] <version>
```

--------------------------------

### Start a New Release Branch

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-start.1.md

Initiate a new release branch with a specified version number. The 'release/' prefix is automatically prepended.

```bash
git flow release start 1.2.0
```

--------------------------------

### Pattern Matching Examples

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-list.1.md

Illustrates various shell-style globbing patterns for filtering branch names.

```bash
git flow feature list "api-*"
```

```bash
git flow feature list "*-test"
```

```bash
git flow feature list "user-?"
```

```bash
git flow feature list "[a-m]*"
```

--------------------------------

### Merge Strategy Configuration Hierarchy Example

Source: https://github.com/gittower/git-flow-next/blob/main/CODING_GUIDELINES.md

Illustrates the configuration precedence for merge strategies, highlighting how command-line options like --squash can override Git configurations.

```bash
# Layer 1: Branch config default
git config gitflow.branch.feature.upstreamStrategy merge

# Layer 2: Command-specific override
git config gitflow.feature.finish.merge rebase

# Layer 3: Command-line override (WINS)
git flow feature finish my-feature --squash  # Forces squash merge
```

--------------------------------

### Good Test Comment Examples

Source: https://github.com/gittower/git-flow-next/blob/main/TESTING_GUIDELINES.md

Examples illustrating effective test comments that are specific, numbered, include verification steps, and use active voice, aligning with the test's implementation.

```go
// TestConfigAddBase tests adding base branch configurations.
// Steps:
// 1. Sets up a test repository and initializes git-flow
// 2. Adds various base branches with different configurations  
// 3. Verifies branches are created and configuration is saved correctly
// 4. Tests error conditions like duplicate branches and invalid parents
func TestConfigAddBase(t *testing.T) { ... }
```

```go
// TestStartFeatureBranch tests the start command for feature branches.
// Steps:
// 1. Sets up a test repository and initializes git-flow with defaults
// 2. Runs 'git flow feature start my-feature'
// 3. Verifies feature/my-feature branch is created
// 4. Verifies branch is based on develop branch
func TestStartFeatureBranch(t *testing.T) { ... }
```

--------------------------------

### Typical workflow - finish then clean up

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-delete.1.md

This example shows the common practice of finishing a feature branch and then cleaning it up using git-flow-delete.

```bash
# Typical workflow - finish then clean up
git flow feature finish my-feature
git flow feature delete my-feature  # Clean up local branch
```

--------------------------------

### Interactive git-flow initialization - Preset selection

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-init.1.md

Example of the interactive menu presented when initializing git-flow without options, showing preset selection.

```bash
? Choose initialization method:
  ❯ Use preset workflow
    Custom configuration

? Choose a preset:
  ❯ Classic GitFlow
    GitHub Flow  
    GitLab Flow
```

--------------------------------

### Standard Test Structure

Source: https://github.com/gittower/git-flow-next/blob/main/CODING_GUIDELINES.md

Demonstrates a typical test structure including setup, execution of a Git Flow command, and assertions to verify the outcome and state.

```go
func TestExample(t *testing.T) {
    // Setup
    dir := testutil.SetupTestRepo(t)
    defer testutil.CleanupTestRepo(t, dir)
    
    // Execute
    output, err := testutil.RunGitFlow(t, dir, "feature", "start", "test")
    
    // Assert
    if err != nil {
        t.Fatalf("Expected success, got error: %v\nOutput: %s", err, output)
    }
    
    // Verify state
    if !testutil.BranchExists(t, dir, "feature/test") {
        t.Error("Expected feature branch to be created")
    }
}
```

--------------------------------

### Go Option Struct Example

Source: https://github.com/gittower/git-flow-next/blob/main/CODING_GUIDELINES.md

Demonstrates the use of an option struct to group related configuration parameters for a function. This is beneficial when concepts are logically connected.

```go
// GOOD: Option struct groups related concepts
type TagOptions struct {
    ShouldTag   *bool
    ShouldSign  *bool
    SigningKey  string
    Message     string
}
```

--------------------------------

### Classic GitFlow Configuration

Source: https://github.com/gittower/git-flow-next/blob/main/docs/gitflow-config.5.md

Example configuration for a classic Gitflow workflow, defining base and topic branches with their respective properties and strategies.

```ini
[gitflow]
    version = 1.0
    initialized = true

# Base branches
[gitflow "branch.main"]
    type = base
    upstreamstrategy = none
    downstreamstrategy = none
    
[gitflow "branch.develop"]
    type = base
    parent = main
    autoupdate = true
    upstreamstrategy = merge
    downstreamstrategy = merge

# Topic branches
[gitflow "branch.feature"]
    type = topic
    parent = develop
    prefix = feature/
    upstreamstrategy = merge
    downstreamstrategy = rebase
    
[gitflow "branch.release"]
    type = topic
    parent = main
    startpoint = develop
    prefix = release/
    upstreamstrategy = merge
    downstreamstrategy = merge
    tag = true

[gitflow "branch.hotfix"]
    type = topic
    parent = main
    prefix = hotfix/
    upstreamstrategy = merge
    downstreamstrategy = merge
    tag = true
```

--------------------------------

### Document Exported Functions in Go

Source: https://github.com/gittower/git-flow-next/blob/main/CODING_GUIDELINES.md

Document all exported functions with clear descriptions, including their purpose and behavior. This example shows documentation for a `LoadConfig` function.

```go
// LoadConfig loads the git-flow configuration from git config.
// It reads all gitflow.branch.* configuration keys and constructs
// a Config struct with branch definitions and settings.
func LoadConfig() (*Config, error) {
    // Implementation
}
```

--------------------------------

### Git Flow Start Fetch and Base Parameter

Source: https://github.com/gittower/git-flow-next/blob/main/docs/avh-compatibility-analysis.md

Shows the usage of the --fetch flag and the base parameter for the git flow start command, indicating full parity between AVH and git-flow-next.

```bash
git flow start -F <branch> <base>
git flow start --fetch <branch> <base>
```

--------------------------------

### Configure Feature Branch Starting Point

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-start.1.md

Set the default branch from which new feature branches will be created. 'develop' is a common choice.

```bash
git config gitflow.branch.feature.startPoint develop
```

--------------------------------

### Custom Branch Type Configuration Example

Source: https://github.com/gittower/git-flow-next/blob/main/CONFIGURATION.md

Define a new custom branch type, such as 'support' branches, by setting its properties.

```properties
# Example: Support branches
gitflow.branch.support.type=topic
gitflow.branch.support.parent=main
gitflow.branch.support.startPoint=main
gitflow.branch.support.prefix=support/
gitflow.branch.support.tag=true
gitflow.branch.support.tagprefix=support-
```

--------------------------------

### Publishing Before Finishing a Feature

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-publish.1.md

Illustrates the workflow of starting a feature locally, working on it, publishing it to share with the team, and then finishing it.

```bash
# Start feature locally
git flow feature start collaborative-feature

# Work on the feature
# ... make commits ...

# Publish to share with team
git flow feature publish collaborative-feature

# Later, finish the feature
git flow feature finish collaborative-feature
```

--------------------------------

### Classic GitFlow Hotfix Workflow

Source: https://context7.com/gittower/git-flow-next/llms.txt

Shows how to start and finish a hotfix, branching from main and merging back.

```bash
git flow hotfix start fix-null-pointer   # branches from main
# ... fix the bug ...
git flow hotfix finish fix-null-pointer  # merges to main + tag + updates develop
```

--------------------------------

### Remove All Git Flow Configuration

Source: https://github.com/gittower/git-flow-next/blob/main/CONFIGURATION.md

Resets all git-flow specific configurations for the current repository. This is equivalent to starting with a clean git-flow setup.

```bash
git config --remove-section gitflow
```

--------------------------------

### Pre-hook: Verify CI Passing Before Release

Source: https://github.com/gittower/git-flow-next/blob/main/docs/gitflow-hooks.7.md

This pre-hook checks if the CI build is successful on the base branch before starting a release. It requires the 'gh' CLI to be installed and configured.

```bash
#!/bin/sh
# .git/hooks/pre-flow-release-start

if command -v gh &> /dev/null; then
    STATUS=$(gh run list --branch "${BASE_BRANCH:-develop}" --limit 1 --json conclusion -q '.[0].conclusion')
    if [ "$STATUS" != "success" ]; then
        echo "Error: CI is not passing on ${BASE_BRANCH:-develop}"
        exit 1
    fi
fi

exit 0
```

--------------------------------

### Formatted Output Messages

Source: https://github.com/gittower/git-flow-next/blob/main/CODING_GUIDELINES.md

Provides examples for standard output patterns, including regular progress, error output to stderr, and success messages with context.

```go
// Regular progress output
fmt.Printf("Merging using strategy: %s\n", strategy)

// Error output to stderr
fmt.Fprintf(os.Stderr, "Error: %s\n", err)

// Success messages with context
fmt.Printf("Successfully finished branch '%s' and updated %d child branches\n", 
    branchName, len(updatedBranches))
```

--------------------------------

### Start Feature from Specific Commit

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-start.1.md

Create a feature branch starting from a particular commit hash. This overrides the default starting point for features.

```bash
git flow feature start emergency-fix abc123def
```

--------------------------------

### Start a New Feature Branch

Source: https://github.com/gittower/git-flow-next/blob/main/CLAUDE.md

Use this command to create a new branch for developing a specific feature. Replace `<feature-name>` with a descriptive name for your feature.

```bash
git flow feature start <feature-name>
```

--------------------------------

### Git Flow Configuration Storage Example

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-config.1.md

Illustrates how git-flow-next configuration is stored in the .git/config file, showing settings for version, initialization, and branch defaults.

```ini
[gitflow]
    version = 1.0
    initialized = true
[gitflow "branch.main"]
    type = base
    upstreamstrategy = none  
    downstreamstrategy = none
[gitflow "branch.develop"]
    type = base
    parent = main
    autoupdate = true
[gitflow "branch.feature"]
    type = topic
    parent = develop
    prefix = feature/
    upstreamstrategy = merge
    downstreamstrategy = rebase
```

--------------------------------

### Custom git-flow initialization - Trunk branch prompt

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-init.1.md

Example of the prompt for the trunk branch name when using git-flow init with the --custom option.

```bash
? What's your trunk branch (holds production code)? [main] production
✓ Trunk branch: production

Configuration commands:
  git-flow config add base <name> [<parent>] [options...]
  git-flow config add topic <name> <parent> [options...]
  [... full command reference displayed ...]
```

--------------------------------

### Initialize Classic GitFlow Workflow

Source: https://context7.com/gittower/git-flow-next/llms.txt

Sets up the project with the classic GitFlow branching model, including main and develop branches.

```bash
# ── Classic GitFlow ──────────────────────────────────────────────────────────
# main ← hotfix/*, release/*
# develop ← feature/*, bugfix/*, release/* (start point)
git flow init --preset=classic
```

--------------------------------

### Basic Remote Repository Setup for Git Flow Testing

Source: https://github.com/gittower/git-flow-next/blob/main/GIT_TEST_SCENARIOS.md

This Go snippet demonstrates how to set up a basic local bare repository to act as a remote for testing Git Flow's remote operations. It includes adding the remote, creating a feature branch, making changes, and then finishing the feature with a fetch operation.

```go
// Add a remote repository
remoteDir, err := testutil.AddRemote(t, dir, "origin", true)
if err != nil {
    t.Fatalf("Failed to add remote: %v", err)
}
default := testutil.CleanupTestRepo(t, remoteDir)

// Create feature branch and make changes
output, err = testutil.RunGitFlow(t, dir, "feature", "start", "fetch-test")
testutil.WriteFile(t, dir, "feature.txt", "feature content")
_, err = testutil.RunGit(t, dir, "add", "feature.txt")
_, err = testutil.RunGit(t, dir, "commit", "-m", "Add feature file")

// Test operations with remote (fetch, push, etc.)
output, err = testutil.RunGitFlow(t, dir, "feature", "finish", "fetch-test", "--fetch")
```

--------------------------------

### Use git-flow shorthand commands

Source: https://github.com/gittower/git-flow-next/blob/main/README.md

Examples demonstrating the use of shorthand commands for common git-flow operations. These commands automatically detect the branch type.

```bash
# On a feature branch
git checkout feature/my-awesome-feature
git flow finish  # Executes: git flow feature finish my-awesome-feature
git flow rebase  # Executes: git flow feature update --rebase

# On a release branch
git checkout release/v1.2.0
git flow publish  # Executes: git flow release publish v1.2.0

# On a hotfix branch
git checkout hotfix/critical-bug
git flow finish  # Executes: git flow hotfix finish critical-bug
git flow rebase  # Executes: git flow hotfix update --rebase
```

--------------------------------

### Manual Gitflow Initialization and Configuration

Source: https://github.com/gittower/git-flow-next/blob/main/docs/gitflow-config.5.md

Steps to manually migrate from git-flow-avh by exporting configuration, initializing git-flow-next, and re-adding configurations.

```bash
# Export AVH config
git config --get-regexp '^gitflow\.' > avh-config.txt

# Remove AVH config (optional)
git config --remove-section gitflow

# Initialize git-flow-next
git flow init --custom

# Recreate configuration using config commands
git flow config add base main
git flow config add base develop main --auto-update=true
git flow config add topic feature develop --prefix=feature/
```

--------------------------------

### Git Flow Start Show Commands Flag

Source: https://github.com/gittower/git-flow-next/blob/main/docs/avh-compatibility-analysis.md

The --showcommands flag for the git flow start command is available in AVH but not implemented in git-flow-next.

```bash
git flow start --showcommands <branch>
```

--------------------------------

### Testing Continue Behavior Without Fetch (Good)

Source: https://github.com/gittower/git-flow-next/blob/main/GIT_TEST_SCENARIOS.md

Demonstrates a correct test setup that isolates the 'continue' behavior without relying on a successful fetch. It first creates a conflict, resolves it, and then tests the continue step, verifying that no fetch occurs.

```go
// Finish without fetch to create conflict (simple setup)
output, _ := RunGitFlow(t, dir, "feature", "finish", "test")

// Verify conflict occurred
if !strings.Contains(output, "conflict") {
    t.Error("Expected conflict")
}

// Resolve conflict
WriteFile(t, dir, "conflict.txt", "resolved")
RunGit(t, dir, "add", "conflict.txt")

// Continue and verify NO fetch happens
continueOutput, _ := RunGitFlow(t, dir, "feature", "finish", "--continue")
if strings.Contains(continueOutput, "Fetching") {
    t.Error("Continue should not fetch") // Tests exactly one behavior
}
```

--------------------------------

### Setup Git Hooks Directory

Source: https://github.com/gittower/git-flow-next/blob/main/docs/gitflow-hooks.7.md

This command demonstrates how to set up a directory for storing Git hooks, which is recommended for sharing hooks across a team as the default .git/hooks directory is not tracked by Git.

```bash
# Store hooks in a tracked directory
mkdir .githooks
```

--------------------------------

### Initialize git-flow with Defaults

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-avh/README.md

Use this command to initialize the repository for git-flow with default settings.

```bash
git flow init -d
```

--------------------------------

### Build and Verify Version

Source: https://github.com/gittower/git-flow-next/blob/main/RELEASING.md

After updating version files, build the project and verify the new version is correctly reported.

```bash
go build -o /tmp/git-flow main.go && /tmp/git-flow version
```

--------------------------------

### Configure Hotfix Branch Start Behavior

Source: https://github.com/gittower/git-flow-next/blob/main/docs/gitflow-avh-reference.md

Control whether Git Flow fetches from the remote repository before starting a new hotfix branch. Set to 'true' to enable fetching.

```bash
git config gitflow.hotfix.start.fetch true
```

--------------------------------

### Configure Bugfix Branch Start Behavior

Source: https://github.com/gittower/git-flow-next/blob/main/docs/gitflow-avh-reference.md

Control whether Git Flow fetches from the remote repository before starting a new bugfix branch. Set to 'true' to enable fetching.

```bash
git config gitflow.bugfix.start.fetch true
```

--------------------------------

### Ensure Latest State Before Starting Team Feature

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-start.1.md

In a team environment, it's crucial to fetch the latest changes before starting a new feature branch to avoid conflicts and ensure consistency.

```bash
git flow feature start team-feature --fetch
```

--------------------------------

### Using testutil for Git and Git Flow Commands

Source: https://github.com/gittower/git-flow-next/blob/main/TESTING_GUIDELINES.md

Illustrates the recommended approach for executing Git and Git Flow commands in tests. It shows proper setup and cleanup of the test repository and uses `testutil.RunGit` and `testutil.RunGitFlow`, which handle working directory management.

```go
func TestExample(t *testing.T) {
    dir := testutil.SetupTestRepo(t)
    defer testutil.CleanupTestRepo(t, dir)

    // CORRECT: testutil.RunGit sets cmd.Dir internally
    output, err := testutil.RunGit(t, dir, "checkout", "-b", "feature/test")
    if err != nil {
        t.Fatalf("Failed to create branch: %v", err)
    }

    // CORRECT: testutil.RunGitFlow also sets cmd.Dir
    output, err = testutil.RunGitFlow(t, dir, "feature", "finish", "test")
    // ...
}
```

--------------------------------

### Configuration Loading Pattern

Source: https://github.com/gittower/git-flow-next/blob/main/CODING_GUIDELINES.md

Load configuration once at the beginning of command execution and pass it through all subsequent function calls. This avoids redundant loading and ensures consistent configuration usage.

```go
func executeCommand(params...) error {
    // Load config ONCE at the start
    cfg, err := config.LoadConfig()
    if err != nil {
        return &errors.GitError{Operation: "load configuration", Err: err}
    }
    
    // Pass cfg to all subsequent function calls
    return doWork(cfg, params...)
}
```

--------------------------------

### Add Topic Branch Configuration

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-config.1.md

Configure a new topic branch type. This command saves the configuration for use with the 'start' command and allows specifying a prefix, starting point, and merge strategies.

```bash
git flow config add topic feature develop --prefix=feat/
```

```bash
git flow config add topic release main --starting-point=develop --tag=true
```

```bash
git flow config add topic bugfix develop --upstream-strategy=squash --prefix=bug/
```

--------------------------------

### Topic Branch Operations

Source: https://github.com/gittower/git-flow-next/blob/main/ARCHITECTURE.md

Commands for managing topic branches, including starting, finishing, and listing them.

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

--------------------------------

### Create and Validate Implementation Plan

Source: https://github.com/gittower/git-flow-next/blob/main/DEV_WORKFLOW.md

Generates an implementation plan and then validates the test approach against guidelines. These commands should be run sequentially after creating the feature branch.

```bash
# 4. Create and validate implementation plan
/create-plan
/validate-tests
```

--------------------------------

### Build with Script

Source: https://github.com/gittower/git-flow-next/blob/main/CLAUDE.md

Executes the multi-platform build script. Optionally specify a version to embed in the binary.

```bash
./scripts/build.sh
```

```bash
./scripts/build.sh v1.0.0
```

--------------------------------

### Initialize Git-Flow Configuration

Source: https://github.com/gittower/git-flow-next/blob/main/ARCHITECTURE.md

Use this command to set up the initial git-flow configuration in your repository.

```bash
# Initialize git-flow configuration
git flow init
```

--------------------------------

### Build Local Binary with Go

Source: https://github.com/gittower/git-flow-next/blob/main/CLAUDE.md

Builds the git-flow-next binary locally using the Go toolchain. Ensure you are in the project's root directory.

```bash
go build -o git-flow main.go
```

--------------------------------

### Git Flow Init Defaults and Force Flags

Source: https://github.com/gittower/git-flow-next/blob/main/docs/avh-compatibility-analysis.md

Demonstrates the use of the --defaults and --force flags with the git flow init command, showing full parity between AVH and git-flow-next.

```bash
git flow init -d
git flow init --defaults
git flow init -f
git flow init --force
```

--------------------------------

### Quick Switch Between Features

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-checkout.1.md

Demonstrates rapid context switching between different feature branches during daily development.

```bash
# Quick switch between features
git flow feature checkout api
git flow feature checkout user-a
```

--------------------------------

### Commit Message Example

Source: https://github.com/gittower/git-flow-next/blob/main/CONTRIBUTING.md

Follow this format for commit messages, including type, subject, body, and issue resolution.

```git
feat: Add support for custom merge strategies

Implements configurable merge strategies per branch type.

Resolves #123
```

--------------------------------

### GitLab Flow Feature Workflow

Source: https://context7.com/gittower/git-flow-next/llms.txt

Shows the process of starting and finishing a feature branch in GitLab Flow, merging into main.

```bash
git flow feature start dashboard-redesign
git flow feature finish dashboard-redesign  # merges into main
# Changes flow: main → staging → production via separate merge/deploy steps
```

--------------------------------

### Safe os.Chdir() Implementation with Defer

Source: https://github.com/gittower/git-flow-next/blob/main/TESTING_GUIDELINES.md

Provides a safe way to use `os.Chdir()` when unavoidable, by immediately saving and restoring the original working directory using `defer`. This pattern is necessary when internal functions lack a directory parameter.

```go
// If os.Chdir() is unavoidable, do it safely:
originalDir, err := os.Getwd()
if err != nil {
    t.Fatalf("Failed to get working directory: %v", err)
}
if err := os.Chdir(dir); err != nil {
    t.Fatalf("Failed to change to test directory: %v", err)
}
defer func() {
    if err := os.Chdir(originalDir); err != nil {
        t.Errorf("Failed to restore working directory: %v", err)
    }
}()
```

--------------------------------

### Start a New Hotfix Branch

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-start.1.md

Create a new hotfix branch for urgent fixes. The 'hotfix/' prefix is automatically applied.

```bash
git flow hotfix start critical-security-fix
```

--------------------------------

### Initialize git-flow with Classic preset

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-init.1.md

Initializes git-flow using the 'classic' preset. This sets up the traditional git-flow branching structure.

```bash
git flow init --preset=classic
```

--------------------------------

### Track a Remote Release Branch

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-avh/release.md

Starts tracking a release branch that has been published on the remote origin. Requires the branch name.

```bash
git flow release track [-h] <name>
```

--------------------------------

### Start a Hotfix Branch

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-avh/README.md

Begins a hotfix branch, typically for urgent bug fixes. Provide the version number for the hotfix.

```bash
git flow hotfix start 1.0.1
```

--------------------------------

### GitHub Flow Configuration

Source: https://github.com/gittower/git-flow-next/blob/main/docs/gitflow-config.5.md

Example configuration for a GitHub Flow workflow, defining base and topic branches with simplified properties.

```ini
[gitflow]
    version = 1.0
    
[gitflow "branch.main"]
    type = base
    upstreamstrategy = none
    downstreamstrategy = none
    
[gitflow "branch.feature"]
    type = topic
    parent = main
    prefix = feature/
    upstreamstrategy = merge
    downstreamstrategy = rebase
```

--------------------------------

### Initialize GitLab Flow Workflow

Source: https://context7.com/gittower/git-flow-next/llms.txt

Sets up the project for GitLab Flow, which includes main, staging, and production branches for progressive deployments.

```bash
# ── GitLab Flow ──────────────────────────────────────────────────────────────
# production ← staging ← main ← feature/*, hotfix/*
git flow init --preset=gitlab
```

--------------------------------

### Revert Commit Example

Source: https://github.com/gittower/git-flow-next/blob/main/COMMIT_GUIDELINES.md

Use this format to revert a previous commit. Include a reference to the original commit and the reason for reverting.

```git
revert: "feat: Add experimental batch processing"

This reverts commit abc1234 due to performance regression in large repositories. The feature will be reimplemented with better memory management.

Refs #567
```

--------------------------------

### Breaking Change Commit Example

Source: https://github.com/gittower/git-flow-next/blob/main/COMMIT_GUIDELINES.md

Use this format for commits that introduce breaking changes. Include a footer explaining the impact.

```git
feat: Change configuration file format to YAML

Migrates configuration from JSON to YAML format for better readability and comments support. Existing JSON configurations are automatically migrated on first run.

BREAKING CHANGE: Configuration files must be migrated from config.json to config.yaml format. Migration is automatic but requires manual review of settings.
```

--------------------------------

### GitHub Flow Feature Workflow

Source: https://context7.com/gittower/git-flow-next/llms.txt

Demonstrates starting and finishing a feature branch in the GitHub Flow model, merging directly into main.

```bash
git flow feature start new-button
git flow feature finish new-button       # merges directly into main
```

--------------------------------

### View documentation as Markdown in browser

Source: https://github.com/gittower/git-flow-next/blob/main/docs/README.md

Open the Markdown documentation file in a web browser using the 'open' command. This requires a browser with Markdown viewing capabilities.

```bash
# View in browser (with Markdown viewer)
open docs/git-flow.1.md
```

--------------------------------

### Initialize git-flow with GitHub preset

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-init.1.md

Initializes git-flow using the 'github' preset. This sets up a simplified workflow suitable for continuous deployment.

```bash
git flow init --preset=github
```

--------------------------------

### Go Import Organization

Source: https://github.com/gittower/git-flow-next/blob/main/CODING_GUIDELINES.md

Illustrates the correct organization of Go imports, separated into standard library, third-party, and local packages with blank lines in between. Imports should be alphabetical within each group.

```go
import (
    // 1. Standard library packages (alphabetical)
    "fmt"
    "os"
    "strings"

    // 2. Third-party packages (alphabetical)
    "github.com/spf13/cobra"

    // 3. Local packages (alphabetical)
    "github.com/gittower/git-flow-next/internal/config"
    "github.com/gittower/git-flow-next/internal/errors"
    "github.com/gittower/git-flow-next/internal/git"
)
```

--------------------------------

### Initialize git-flow with file configuration scope

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-init.1.md

Initializes git-flow and stores the configuration in a specified file. The parent directory must exist and be writable.

```bash
git flow init --file=~/git-flow-config
```

--------------------------------

### Rename Branch Before Publishing

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-rename.1.md

This example shows renaming a branch to a more finalized name before publishing it to the remote. It includes pushing the updated branch.

```bash
# Clean up name before sharing
git flow feature rename wip-feature finalized-user-auth
git push -u origin feature/finalized-user-auth
```

--------------------------------

### Initialize git-flow with global configuration scope

Source: https://github.com/gittower/git-flow-next/blob/main/docs/git-flow-init.1.md

Initializes git-flow and stores the configuration in the user's global gitconfig file.

```bash
git flow init --global
```

--------------------------------

### Git Flow Init No Create Branches Flag

Source: https://github.com/gittower/git-flow-next/blob/main/docs/avh-compatibility-analysis.md

This example shows the --no-create-branches flag, which is exclusive to git-flow-next and not present in AVH.

```bash
git flow init --no-create-branches
```

--------------------------------

### Work in Progress (WIP) Commit Example

Source: https://github.com/gittower/git-flow-next/blob/main/COMMIT_GUIDELINES.md

Use this format for temporary commits during development. WIP commits should be squashed before merging to main.

```git
wip: Implement basic tag creation logic

Partial implementation of tag creation functionality. Still needs error handling and testing.
```

--------------------------------

### Simulate Remote Changes for Fetch Testing

Source: https://github.com/gittower/git-flow-next/blob/main/GIT_TEST_SCENARIOS.md

This Go snippet illustrates how to simulate remote changes to test fetch scenarios. It involves setting up a repo with a remote, cloning it to a second copy, making and pushing changes from the second copy, and then fetching those changes in the original repository.

```go
// 1. Setup repo with remote
dir, remoteDir := testutil.SetupTestRepoWithRemote(t)

// 2. Clone the remote to a second working copy
secondDir := t.TempDir()
testutil.RunGit(t, secondDir, "clone", remoteDir, ".")

// 3. Make changes in second copy and push
testutil.WriteFile(t, secondDir, "remote-change.txt", "from remote")
testutil.RunGit(t, secondDir, "add", ".")
testutil.RunGit(t, secondDir, "commit", "-m", "Remote change")
testutil.RunGit(t, secondDir, "push", "origin", "main")

// 4. Original repo now has outdated refs - fetch will get new changes
output, err := testutil.RunGitFlow(t, dir, "feature", "finish", "test", "--fetch")
```

--------------------------------

### Commit Message Format Example

Source: https://github.com/gittower/git-flow-next/blob/main/COMMIT_GUIDELINES.md

Illustrates the standard structure for commit messages, including type, scope, subject, body, and footer.

```git
feat: Add support for custom merge strategies in finish command

Implements configurable merge strategies per branch type allowing users to specify merge, rebase, or squash operations. The configuration follows the existing pattern of branch-specific settings and supports both command-line overrides and git config defaults.

- Add merge strategy validation in config loader
- Update finish command to respect strategy settings  
- Add comprehensive tests for all strategy combinations

Closes #234
```

```git
fix: Resolve state file corruption during interrupted operations

Fixes issue where merge state file could become corrupted if the process was interrupted during JSON serialization. The fix adds atomic write operations using temporary files and proper error handling for filesystem issues.

Resolves #456
```

```git
refactor: Extract tag creation logic to git module

Moves createTagWithOptions and createTag functions from cmd/finish.go to internal/git/repo.go for better separation of concerns. Combines both functions into a single git.CreateTag function with optional parameters, reducing finish command complexity by 36 lines and improving reusability across commands.

- Consolidate tag creation into single function with options struct
- Remove duplicate code and os/exec dependency from finish command
- Add better error messages and validation for tag operations
```

```git
test: Add comprehensive test for consecutive conflicts in multi-step operations

Implements TestFinishWithConsecutiveConflicts which validates the system's ability to handle multiple conflicts during a single finish operation: first conflict between release branch and main during merge, second conflict between develop branch and main during auto-update. Tests state persistence across conflict resolutions, validates proper error messages and recovery workflow, and ensures complete cleanup after successful resolution.
```

```git
docs: Update testing guidelines with default configuration details

Adds comprehensive documentation about git-flow default branches and settings to help developers write consistent tests. Includes branch relationships, merge strategies, and examples of proper test setup using git-flow defaults rather than custom configurations.
```

--------------------------------

### Status and Overview Commands

Source: https://github.com/gittower/git-flow-next/blob/main/ARCHITECTURE.md

Commands to check the current status of git-flow operations and get an overview of the repository's branch structure.

```bash
# Status and overview
git flow status
git flow overview
```