jesseduffield/lazygit · warning

Cannot merge branch in detached head state. You might have c

Error message

Cannot merge branch in detached head state. You might have checked out a commit directly or a remote branch, in which case you should checkout the local branch you want to be on

What it means

Hardcoded (non-i18n) error returned by MergeRefIntoCheckedOutBranch when IsHeadDetached() is true: merging requires a named checked-out branch to merge INTO, and a detached HEAD (a raw commit or a remote-tracking ref checked out directly) gives git no branch to update, so lazygit blocks the operation before invoking git and hints at checking out a local branch.

Source

Thrown at pkg/gui/controllers/helpers/merge_and_rebase_helper.go:520

	title := utils.ResolvePlaceholderString(
		lo.Ternary(self.c.Modes().MarkedBaseCommit.GetHash() != "",
			self.c.Tr.RebasingFromBaseCommitTitle,
			self.c.Tr.RebasingTitle),
		map[string]string{
			"checkedOutBranch": checkedOutBranchName,
		},
	)

	return self.c.Menu(types.CreateMenuOptions{
		Title: title,
		Items: menuItems,
	})
}

func (self *MergeAndRebaseHelper) MergeRefIntoCheckedOutBranch(refName string) error {
	if self.c.Git().Branch.IsHeadDetached() {
		return errors.New("Cannot merge branch in detached head state. You might have checked out a commit directly or a remote branch, in which case you should checkout the local branch you want to be on")
	}
	checkedOutBranchName := self.c.Model().Branches[0].Name
	if checkedOutBranchName == refName {
		return errors.New(self.c.Tr.CantMergeBranchIntoItself)
	}

	wantFastForward, wantNonFastForward := self.fastForwardMergeUserPreference()
	canFastForward := self.c.Git().Branch.CanDoFastForwardMerge(refName)

	var firstRegularMergeItem *types.MenuItem
	var secondRegularMergeItem *types.MenuItem
	var fastForwardMergeItem *types.MenuItem

	if !wantNonFastForward && (wantFastForward || canFastForward) {
		firstRegularMergeItem = &types.MenuItem{
			Label:   self.c.Tr.RegularMergeFastForward,
			OnPress: self.RegularMerge(refName, git_commands.MERGE_VARIANT_REGULAR),
			Keys:    menuKey('m'),

View on GitHub (pinned to c477a2959b)

Solutions

1. Check out a local branch first: 'git checkout -b <name>' or select the local branch in lazygit's Branches panel and press space.
2. If you meant to update a remote-tracking ref, fetch instead of merge.
3. Retry the merge afterwards.

// before merging:
if self.c.Git().Branch.IsHeadDetached() {
    // prompt to check out a local branch first
}

When it happens

Trigger: Selecting a branch (or ref) and pressing the merge key (default 'M') while HEAD is detached — after checking out a commit hash, a tag, or a remote branch such as origin/main without a local copy.

Common situations: Inspecting an old commit then trying to merge into it; CI/scratch worktrees created in detached state; repos cloned with --no-checkout where HEAD was never attached.

Related errors

• You cannot merge a branch into itself
• Some of the selected branches are checked out by other workt
• Entire file
• You are currently neither rebasing nor merging
• You cannot remove the main worktree!

AI-assisted analysis of jesseduffield/lazygit@c477a2959b (2026-08-15). Data as JSON: /api/errors/260c1058c257ebed. Report an issue: GitHub.