bug: stale merge.json blocks all future `feature finish` when `--abort` is called without MERGE_HEAD

[weigosw]

Summary

When git flow feature finish encounters a merge conflict and the user manually resolves+commits the conflict (bypassing --continue), MERGE_HEAD is cleared by git but the merge.json state file remains. Any subsequent call to --abort then fails because git merge --abort returns exit code 128 (no MERGE_HEAD), causing handleAbort() to return early — ClearMergeState() is never called. The repository is permanently stuck until the state file is deleted manually.

Steps to Reproduce

# 1. Init repo with github preset (feature parent = main)
mkdir /tmp/repro && cd /tmp/repro
git init && git config user.email "x@x.com" && git config user.name "X"
echo "base" > file.txt && git add . && git commit -m "initial"
git flow init --preset github

# 2. Create feature branch and make changes
git flow feature start conflict-feature
echo "feature content" > file.txt && git add . && git commit -m "feat: change"

# 3. Create a diverging commit on main
git checkout main
echo "main content" > file.txt && git add . && git commit -m "chore: diverge"
git checkout feature/conflict-feature

# 4. Trigger feature finish → merge conflict → state file is written
git flow feature finish conflict-feature
# Error: there are still unresolved conflicts. Resolve them and try again
# .git/gitflow/state/merge.json is now written (currentStep: "merge")

# 5. User manually resolves and commits (bypassing --continue)
echo "resolved" > file.txt && git add file.txt
git commit -m "manually resolved"
# MERGE_HEAD is now GONE; merge.json still present

# 6. Try --abort → FAILS (git merge --abort returns exit 128)
git flow feature finish --abort conflict-feature
# Error: failed to abort merge: failed to abort merge: exit status 128
# merge.json is STILL present — ClearMergeState() was never called

# 7. All future feature finish calls are now BLOCKED
git flow feature start another-feature
echo "new" > another.txt && git add . && git commit -m "feat"
git flow feature finish another-feature
# Error: a merge is already in progress for branch 'feature/conflict-feature'. Use --continue or --abort

Workaround: Manually delete the state file:

rm .git/gitflow/state/merge.json

Root Cause

In cmd/finish.go, handleAbort() calls git.MergeAbort() first. If that fails (e.g., no active merge, exit code 128), the function returns an error immediately — mergestate.ClearMergeState() on line ~458 is never reached:

func handleAbort(state *mergestate.MergeState) error {
    var err error
    switch state.MergeStrategy {
    case strategyMerge:
        err = git.MergeAbort()   // returns exit 128 when no MERGE_HEAD
    ...
    }
    if err != nil {
        return &errors.GitError{...}  // ← early return; state file NOT cleared
    }
    // ...
    mergestate.ClearMergeState()  // ← never reached
    return nil
}

Additionally, the state file uses a hardcoded relative path .git/gitflow/state/merge.json (in internal/mergestate/mergestate.go:11), which is resolved relative to the current working directory. This works correctly in regular repos and submodules (where .git is a gitfile pointing to the real git dir), but the hardcoded path makes it sensitive to where the binary is invoked from.

Expected Behavior

--abort should clear the state file even when git merge --abort fails (or when there is no active git-level merge to abort). The semantic intent of --abort is "abandon this git-flow operation and clean up state", which should succeed regardless of the underlying git merge status.

Suggested Fix

handleAbort() should call ClearMergeState() unconditionally (or at minimum when git merge --abort fails with "no merge in progress"):

func handleAbort(state *mergestate.MergeState) error {
    var err error
    switch state.MergeStrategy {
    case strategyMerge:
        err = git.MergeAbort()
    case strategyRebase:
        err = git.RebaseAbort()
    default:
        err = git.MergeAbort()
    }

    // Only treat it as a real error if git reported something other than
    // "no merge/rebase in progress" (exit 128 with that message is expected
    // when the user already committed the resolution manually).
    if err != nil && !isNoMergeInProgressError(err) {
        return &errors.GitError{Operation: "abort merge", Err: err}
    }

    if err := git.Checkout(state.FullBranchName); err != nil {
        return &errors.GitError{...}
    }

    // Always clear state, even if git-level abort was a no-op
    return mergestate.ClearMergeState()
}

Environment

• git-flow-next version: 1.1.0 (Homebrew)
• macOS arm64
• Reproduced with --preset github (feature parent = main, no develop branch)
• Also reproduced in a git submodule context (identical behaviour)

Reproduction Script

A self-contained shell script to reproduce this locally:

#!/usr/bin/env bash
set -e
REPRO_DIR="/tmp/gf-repro-$(date +%s)"
mkdir -p "$REPRO_DIR" && cd "$REPRO_DIR"
git init -q
git config user.email "repro@test.local" && git config user.name "Repro Test"
echo "initial" > file.txt && git add . && git commit -q -m "initial commit"
git flow init --preset github 2>&1 | tail -2
git flow feature start conflict-feature 2>&1 | head -1
echo "feature content" > file.txt && git add . && git commit -q -m "feat"
git checkout -q main
echo "main content" > file.txt && git add . && git commit -q -m "chore: diverge"
git checkout -q feature/conflict-feature
echo "--- Step 1: trigger conflict ---"
git flow feature finish conflict-feature 2>&1 | grep -E "conflict|Error" || true
echo "State file: $(ls .git/gitflow/state/merge.json 2>/dev/null && echo YES || echo NO)"
echo "--- Step 2: manual resolve + commit (bypass --continue) ---"
echo "resolved" > file.txt && git add file.txt && git commit -q -m "manual resolve"
echo "MERGE_HEAD: $(cat .git/MERGE_HEAD 2>/dev/null || echo GONE)"
echo "--- Step 3: --abort should clean up state (BUG: it doesn't) ---"
git flow feature finish --abort conflict-feature 2>&1 || true
echo "State file after --abort: $(ls .git/gitflow/state/merge.json 2>/dev/null && echo STILL THERE (BUG) || echo gone)"
echo "--- Step 4: new feature finish is blocked ---"
git flow feature start another-feature 2>&1 | head -1
echo "x" > x.txt && git add . && git commit -q -m "feat"
git flow feature finish another-feature 2>&1 | grep -E "Error|blocked|progress" || true

[weigosw]

Additional Context: Workflow-Level Prevention & A Deeper Fix

How this is triggered (workflow perspective)

This bug requires a specific user action to trigger: after a merge conflict, manually running git commit instead of git flow feature finish --continue <name>.

git commit completes the in-flight merge at the git level (MERGE_HEAD is cleared by git), but bypasses the git-flow-next state machine entirely — so merge.json is never advanced to the next step or cleaned up.

The correct workflow is:

# After conflict: resolve files, then...
git add <resolved-files>
git flow feature finish --continue <name>   # ← correct: goes through state machine
# NOT: git commit                            # ← triggers this bug

While better documentation/user guidance can prevent this, the tool should still be resilient to it.

---

A Deeper Fix: Self-Healing State Validation at Load Time

The fix suggested in the issue description (handleAbort() treating exit 128 as non-error) is correct but only addresses the --abort path. It still requires the user to know to run --abort first.

A cleaner approach is to make the state self-healing at load time in IsMergeInProgress():

// internal/mergestate/mergestate.go

// IsMergeInProgress checks if there's a merge in progress.
// If merge.json exists but the git-level merge is no longer active,
// the state is stale and is automatically cleared.
func IsMergeInProgress() bool {
    state, err := LoadMergeState()
    if err != nil || state == nil {
        return false
    }

    // Validate git-level state matches our recorded step.
    // If the user manually committed the resolution, MERGE_HEAD is gone
    // but merge.json still exists — detect and auto-clean this.
    if state.CurrentStep == "merge" {
        switch state.MergeStrategy {
        case "merge":
            if !fileExists(filepath.Join(resolveGitDir(), "MERGE_HEAD")) {
                _ = ClearMergeState() // stale state — auto-clean
                return false
            }
        case "rebase":
            gitDir := resolveGitDir()
            if !dirExists(filepath.Join(gitDir, "rebase-merge")) &&
                !dirExists(filepath.Join(gitDir, "rebase-apply")) {
                _ = ClearMergeState()
                return false
            }
        }
    }

    return true
}

Where resolveGitDir() uses git rev-parse --git-dir to correctly resolve the actual .git directory (which also fixes the submodule path issue noted in the original report).

Why this is better than only fixing handleAbort():

	Fix A: handleAbort() only	Fix B: load-time validation
Unblocks --abort path	✅	✅ (auto-cleared before --abort is even needed)
Unblocks next feature finish directly	❌ user must run --abort first	✅ next command just works
Handles all stale-state paths	❌	✅
User action required	--abort (which currently errors)	None

Ideal fix: apply both — Fix B as the primary defense (self-healing), Fix A as a secondary fix so --abort is semantically consistent even when state is already stale.

---

Related: Submodule Path Issue

The hardcoded stateDir = ".git/gitflow/state" path works in submodules because git resolves .git as a file pointing to the real git directory (e.g., ../.git/modules/wiki). The OS follows the file path transparently on macOS/Linux. However, using git rev-parse --git-dir would make this explicitly correct and portable, and is required for the resolveGitDir() helper in Fix B above.

[weigosw]

Deeper / Cleaner Fix: Self-Healing at IsMergeInProgress() Layer

While making handleAbort() tolerant of exit 128 would unblock the --abort path, I'd like to propose an even cleaner fix that requires no user action at all.

Root insight

The only reason merge.json can become stale is that the git-level merge operation already completed (or was aborted) without going through git-flow-next's ClearMergeState(). This can happen via:

1. git commit after resolving a conflict (the case in this issue)
2. git merge --abort called manually outside git-flow-next
3. Any other direct git operation that clears MERGE_HEAD

In all these cases, the invariant that "a merge.json exists ↔ git has an active merge/rebase in progress" is violated.

Proposed fix: cross-check MERGE_HEAD inside IsMergeInProgress()

// mergestate/mergestate.go

func IsMergeInProgress() bool {
    state, err := LoadMergeState()
    if err != nil || state == nil {
        return false
    }

    // Auto-heal: state file exists but git has no active merge or rebase.
    // This happens when the user manually ran `git commit` to resolve a
    // conflict instead of using `--continue`, or manually ran `git merge --abort`.
    // In either case, the merge is truly done — clear the stale state file
    // transparently so future operations are not permanently blocked.
    if !gitHasMergeOrRebaseInProgress() {
        _ = ClearMergeState() // best-effort, ignore error
        return false
    }

    return true
}

// gitHasMergeOrRebaseInProgress checks git's own state files,
// independent of git-flow-next's merge.json.
func gitHasMergeOrRebaseInProgress() bool {
    gitDir, err := git.GetGitDir() // `git rev-parse --git-dir`
    if err != nil {
        return false
    }
    for _, marker := range []string{
        filepath.Join(gitDir, "MERGE_HEAD"),
        filepath.Join(gitDir, "rebase-merge"),
        filepath.Join(gitDir, "rebase-apply"),
    } {
        if _, err := os.Stat(marker); err == nil {
            return true
        }
    }
    return false
}

Why this is cleaner than patching handleAbort()

Approach	Requires user action	Handles all stale-state sources	Scope of change
Patch handleAbort() to tolerate exit 128	No	Only the --abort code path	Local to one function
Self-heal in IsMergeInProgress()	No	All sources (manual commit, manual abort, anything)	One central check point

The self-healing approach fixes the symptom at the detection layer. Every code path that calls IsMergeInProgress() — including future ones — benefits automatically. No user ever needs to know about the stale state file.

Tradeoff acknowledgment

The only risk is silently discarding a state file that was legitimately still needed. However, since merge.json existing while MERGE_HEAD is absent means the merge is already complete at the git level, there is no meaningful state left to resume. The --continue path would fail anyway (there is nothing to continue), so clearing it is the correct behavior.

---

For reference: we encountered this bug across multiple repos in our project. The immediate workaround (manually deleting the stale merge.json) works, but we'd love to see a permanent fix upstream. Happy to contribute a PR if this direction looks good to you.