Configuration Reference

This document provides a comprehensive reference for all git-flow-next configuration options. All configuration is stored in Git configuration using the gitflow.* key namespace.

Configuration Overview

git-flow-next uses a hierarchical configuration system with three levels of precedence:

Branch Type Definition (gitflow.branch.*) - The identity and process characteristics of a branch type
Command-Specific Configuration (gitflow.<branchtype>.*) - How specific commands behave for a branch type
Command-Line Flags - Highest priority - one-off overrides that always win

Understanding the Layers

Layer 1 defines what a branch type is — its role in the workflow, not tunable defaults. These properties describe the branch type's identity (where it lives in the hierarchy, its naming convention) and its process characteristics (how it participates in the workflow). For example, tag=true on a release branch means "releases are the kind of branch that produces tags on finish" — it describes the release process, not merely a default that you toggle.

Layer 2 controls how commands execute — operational settings like whether to fetch before an operation, sign tags, or keep branches after finishing. These are genuine behavioral knobs that adjust command execution without changing what the branch type fundamentally is.

Layer 3 provides one-off overrides via CLI flags for ad-hoc situations.

Many command options intentionally have no Layer 1 equivalent — they exist only in Layer 2 and Layer 3. For example, publish push-options are purely operational and don't define any branch type characteristic.

For developers adding new options: Most new options need only Layer 2 + Layer 3. Add Layer 1 support only when the option defines a branch type characteristic. See CODING_GUIDELINES.md → "Adding New Configuration Options" for the full decision guide and checklist.

Core System Configuration

System Settings

Key	Description	Default	Example
`gitflow.version`	Internal version marker for compatibility	`1.0`	`1.0`
`gitflow.initialized`	Marks repository as git-flow initialized	`false`	`true`
`gitflow.origin`	Remote name to use for operations	`origin`	`upstream`
`gitflow.remote`	Alias for `gitflow.origin`	`origin`	`upstream`

Branch Type Configuration (Layer 1)

Branch type configuration defines the identity and process characteristics of each branch type using the pattern: gitflow.branch.<branchname>.<property>

These properties describe what the branch type is — its structural role and how it participates in the workflow. They should only contain essential branch-type-relevant configuration.

Structural Properties

Define where the branch type fits in the hierarchy:

Property	Description	Values	Default
`type`	Branch type classification	`base`, `topic`	Required
`parent`	Parent branch for this branch type	Branch name	Varies by type
`startPoint`	Branch to start new branches from	Branch name	Same as parent
`prefix`	Branch name prefix (topic only)	String ending in `/`	`<type>/`

Process Characteristics

Define how the branch type participates in the workflow:

Property	Description	Values	Default
`upstreamStrategy`	How changes flow TO parent on finish	`merge`, `rebase`, `squash`	`merge`
`downstreamStrategy`	How updates flow FROM parent	`merge`, `rebase`	`merge`
`tag`	Branch type produces tags on finish (topic only)	`true`, `false`	`false`
`tagprefix`	Prefix for created tags (topic only)	String	`""`
`autoUpdate`	Auto-update from parent on finish (base only)	`true`, `false`	`false`
`deleteRemote`	Delete remote branch on finish (topic only)	`true`, `false`	`false`

For example, setting tag=true on release branches means "releases produce tags" — it characterizes the release process. This can still be overridden per-command (Layer 2: gitflow.release.finish.notag) or per-invocation (Layer 3: --notag), but the branch config establishes the branch type's intended role.

Default Branch Types

Base Branches

# Main branch (production releases)
gitflow.branch.main.type=base
gitflow.branch.main.parent=             # No parent (root)
gitflow.branch.main.upstreamStrategy=merge
gitflow.branch.main.downstreamStrategy=merge
gitflow.branch.main.autoUpdate=false

# Develop branch (integration)  
gitflow.branch.develop.type=base
gitflow.branch.develop.parent=main
gitflow.branch.develop.startPoint=main
gitflow.branch.develop.upstreamStrategy=merge
gitflow.branch.develop.downstreamStrategy=merge
gitflow.branch.develop.autoUpdate=true    # Auto-updates from main

Topic Branches

# Feature branches
gitflow.branch.feature.type=topic
gitflow.branch.feature.parent=develop
gitflow.branch.feature.startPoint=develop
gitflow.branch.feature.prefix=feature/
gitflow.branch.feature.upstreamStrategy=merge
gitflow.branch.feature.downstreamStrategy=rebase
gitflow.branch.feature.tag=false
gitflow.branch.feature.autoUpdate=false

# Release branches
gitflow.branch.release.type=topic
gitflow.branch.release.parent=main
gitflow.branch.release.startPoint=develop
gitflow.branch.release.prefix=release/
gitflow.branch.release.upstreamStrategy=merge
gitflow.branch.release.downstreamStrategy=merge
gitflow.branch.release.tag=true
gitflow.branch.release.autoUpdate=false

# Hotfix branches  
gitflow.branch.hotfix.type=topic
gitflow.branch.hotfix.parent=main
gitflow.branch.hotfix.startPoint=main
gitflow.branch.hotfix.prefix=hotfix/
gitflow.branch.hotfix.upstreamStrategy=merge
gitflow.branch.hotfix.downstreamStrategy=merge
gitflow.branch.hotfix.tag=true
gitflow.branch.hotfix.autoUpdate=false

Custom Branch Types

You can define custom branch types by setting the appropriate configuration:

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

Command-Specific Configuration (Layer 2)

Command-specific configuration controls how commands execute for a branch type, using the pattern: gitflow.<branchtype>.<command>.<option>

These are operational settings — they adjust command behavior without changing the branch type's identity. Some of these can override Layer 1 process characteristics (e.g., notag overrides the branch type's tag setting), while others exist only at this layer (e.g., sign, keep, fetch).

Finish Command Options

The finish command supports per-branch-type configuration:

Option	Description	Values	Default
`merge`	Override merge strategy	`merge`, `rebase`, `squash`	From branch config
`notag`	Disable tag creation	`true`, `false`	Opposite of branch `tag`
`sign`	Sign created tags	`true`, `false`	`false`
`signingkey`	GPG key for signing	Key ID	Git default
`messagefile`	File containing tag message	File path	None
`keep`	Keep branch after finish	`true`, `false`	`false`
`keepremote`	Keep remote branch	`true`, `false`	`false`
`keeplocal`	Keep local branch	`true`, `false`	`false`
`force-delete`	Force delete branch	`true`, `false`	`false`
`fetch`	Fetch before operation	`true`, `false`	`false`

Examples

# Override feature finish to use rebase
gitflow.feature.finish.merge=rebase

# Disable tags for feature branches
gitflow.feature.finish.notag=true

# Sign all release tags
gitflow.release.finish.sign=true
gitflow.release.finish.signingkey=ABC123DEF

# Keep hotfix branches locally after finish
gitflow.hotfix.finish.keeplocal=true

Update Command Options

Option	Description	Values	Default
`downstreamStrategy`	Override update strategy	`merge`, `rebase`	From branch config

Examples

# Force rebase for feature updates
gitflow.feature.downstreamStrategy=rebase

# Use merge for release updates
gitflow.release.downstreamStrategy=merge

Configuration Precedence

git-flow-next follows a strict three-layer precedence hierarchy:

Layer 1: Branch Type Definition (Lowest Priority)

Defines the branch type's identity and process characteristics via gitflow.branch.<branchtype>.*

gitflow.branch.release.tag=true    # "Releases produce tags" — a process characteristic

Layer 2: Command-Specific Configuration (Medium Priority)

Operational settings that control how commands execute via gitflow.<branchtype>.<command>.*

gitflow.release.finish.notag=true  # Override: skip tagging for this command

Layer 3: Command-Line Flags (Highest Priority)

One-off overrides that always win

git flow release finish v1.0 --tag  # Force tagging for this invocation

Not every option spans all three layers. Layer 1 is reserved for essential branch-type properties — many command options exist only at Layer 2 and Layer 3. For example, sign, keep, and publish push-options are purely operational and have no Layer 1 equivalent.

Legacy Compatibility

Git-Flow-AVH Compatibility

git-flow-next automatically imports configuration from git-flow-avh installations:

AVH Key	git-flow-next Equivalent	Description
`gitflow.branch.master`	`gitflow.branch.main`	Main branch name
`gitflow.branch.develop`	`gitflow.branch.develop`	Develop branch name
`gitflow.prefix.feature`	`gitflow.branch.feature.prefix`	Feature prefix
`gitflow.prefix.release`	`gitflow.branch.release.prefix`	Release prefix
`gitflow.prefix.hotfix`	`gitflow.branch.hotfix.prefix`	Hotfix prefix
`gitflow.prefix.support`	`gitflow.branch.support.prefix`	Support prefix
`gitflow.prefix.versiontag`	`gitflow.branch.*.tagprefix`	Tag prefix

Migration from git-flow-avh

Automatic Import: Run git flow init to automatically import existing configuration
Manual Migration: Use the mapping table above to convert AVH config to git-flow-next format
Verification: Run git flow overview to verify imported configuration

Configuration Examples

Simple GitHub Flow

# Minimal configuration - feature branches only
git config gitflow.branch.main.type base
git config gitflow.branch.feature.type topic
git config gitflow.branch.feature.parent main
git config gitflow.branch.feature.prefix feature/

Traditional Git-Flow

# Full git-flow with main, develop, and all topic types
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

Custom Workflow

# Custom branch types with specific merge strategies
git config gitflow.branch.bugfix.type topic
git config gitflow.branch.bugfix.parent develop
git config gitflow.branch.bugfix.prefix bugfix/
git config gitflow.branch.bugfix.upstreamStrategy squash

# Custom finish behavior
git config gitflow.bugfix.finish.notag true
git config gitflow.bugfix.finish.keep true

Configuration Management

Viewing Configuration

# View all git-flow configuration
git config --get-regexp '^gitflow\.'

# View branch-specific configuration
git config --get-regexp '^gitflow\.branch\.feature\.'

# View command-specific configuration  
git config --get-regexp '^gitflow\.feature\.finish\.'

Setting Configuration

# Set branch type configuration
git config gitflow.branch.feature.upstreamStrategy rebase

# Set command-specific configuration
git config gitflow.feature.finish.merge squash

# Set global configuration (all repositories)
git config --global gitflow.feature.finish.notag true

Removing Configuration

# Remove specific setting
git config --unset gitflow.feature.finish.merge

# Remove all git-flow configuration (reset)
git config --remove-section gitflow

Best Practices

Start with defaults - Use git flow init --defaults for standard configuration
Customize gradually - Override only what you need to change
Document team conventions - Use consistent configuration across team repositories
Use command precedence - Rely on command-line flags for one-off operations
Test configuration - Use git flow overview to verify your setup
Backup configuration - Export configuration before major changes:
```
git config --get-regexp '^gitflow\.' > gitflow-backup.txt
```

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Configuration Reference

Configuration Overview

Understanding the Layers

Core System Configuration

System Settings

Branch Type Configuration (Layer 1)

Structural Properties

Process Characteristics

Default Branch Types

Base Branches

Topic Branches

Custom Branch Types

Command-Specific Configuration (Layer 2)

Finish Command Options

Examples

Update Command Options

Examples

Configuration Precedence

Layer 1: Branch Type Definition (Lowest Priority)

Layer 2: Command-Specific Configuration (Medium Priority)

Layer 3: Command-Line Flags (Highest Priority)

Legacy Compatibility

Git-Flow-AVH Compatibility

Migration from git-flow-avh

Configuration Examples

Simple GitHub Flow

Traditional Git-Flow

Custom Workflow

Configuration Management

Viewing Configuration

Setting Configuration

Removing Configuration

Best Practices

FilesExpand file tree

CONFIGURATION.md

Latest commit

History

CONFIGURATION.md

File metadata and controls

Configuration Reference

Configuration Overview

Understanding the Layers

Core System Configuration

System Settings

Branch Type Configuration (Layer 1)

Structural Properties

Process Characteristics

Default Branch Types

Base Branches

Topic Branches

Custom Branch Types

Command-Specific Configuration (Layer 2)

Finish Command Options

Examples

Update Command Options

Examples

Configuration Precedence

Layer 1: Branch Type Definition (Lowest Priority)

Layer 2: Command-Specific Configuration (Medium Priority)

Layer 3: Command-Line Flags (Highest Priority)

Legacy Compatibility

Git-Flow-AVH Compatibility

Migration from git-flow-avh

Configuration Examples

Simple GitHub Flow

Traditional Git-Flow

Custom Workflow

Configuration Management

Viewing Configuration

Setting Configuration

Removing Configuration

Best Practices