When checking out a remote branch by name, ask the user how (#3388)

- **PR Description**

When checking out a remote branch by name, ask the user how they want to
check it out; the choices are to create a new local branch that tracks
the remote, or a detached head.

This is an alternative to #3371, and fixes #2312.

15 files changed, 133 insertions, 13 deletions

diff --git a/docs/keybindings/Keybindings_en.md b/docs/keybindings/Keybindings_en.md
index 328d544bf..d3fa58cca 100644
--- a/docs/keybindings/Keybindings_en.md
+++ b/docs/keybindings/Keybindings_en.md
@@ -263,7 +263,7 @@ If you would instead like to start an interactive rebase from the selected commi
 | Key | Action | Info |
 |-----|--------|-------------|
 | `` <c-o> `` | Copy branch name to clipboard |  |
-| `` <space> `` | Checkout | Checkout a new local branch based on the selected remote branch. The new branch will track the remote branch. |
+| `` <space> `` | Checkout | Checkout a new local branch based on the selected remote branch, or the remote branch as a detached head. |
 | `` n `` | New branch |  |
 | `` M `` | Merge | Merge selected branch into currently checked out branch. |
 | `` r `` | Rebase | Rebase the checked-out branch onto the selected branch. |
diff --git a/docs/keybindings/Keybindings_ja.md b/docs/keybindings/Keybindings_ja.md
index 4be81952c..bcf56e761 100644
--- a/docs/keybindings/Keybindings_ja.md
+++ b/docs/keybindings/Keybindings_ja.md
@@ -327,7 +327,7 @@ If you would instead like to start an interactive rebase from the selected commi
 | Key | Action | Info |
 |-----|--------|-------------|
 | `` <c-o> `` | ブランチ名をクリップボードにコピー |  |
-| `` <space> `` | チェックアウト | Checkout a new local branch based on the selected remote branch. The new branch will track the remote branch. |
+| `` <space> `` | チェックアウト | Checkout a new local branch based on the selected remote branch, or the remote branch as a detached head. |
 | `` n `` | 新しいブランチを作成 |  |
 | `` M `` | 現在のブランチにマージ | Merge selected branch into currently checked out branch. |
 | `` r `` | Rebase | Rebase the checked-out branch onto the selected branch. |
diff --git a/docs/keybindings/Keybindings_ko.md b/docs/keybindings/Keybindings_ko.md
index 1302c2778..531ed4e46 100644
--- a/docs/keybindings/Keybindings_ko.md
+++ b/docs/keybindings/Keybindings_ko.md
@@ -240,7 +240,7 @@ _Legend: `<c-b>` means ctrl+b, `<a-b>` means alt+b, `B` means shift+b_
 | Key | Action | Info |
 |-----|--------|-------------|
 | `` <c-o> `` | 브랜치명을 클립보드에 복사 |  |
-| `` <space> `` | 체크아웃 | Checkout a new local branch based on the selected remote branch. The new branch will track the remote branch. |
+| `` <space> `` | 체크아웃 | Checkout a new local branch based on the selected remote branch, or the remote branch as a detached head. |
 | `` n `` | 새 브랜치 생성 |  |
 | `` M `` | 현재 브랜치에 병합 | Merge selected branch into currently checked out branch. |
 | `` r `` | 체크아웃된 브랜치를 이 브랜치에 리베이스 | Rebase the checked-out branch onto the selected branch. |
diff --git a/docs/keybindings/Keybindings_nl.md b/docs/keybindings/Keybindings_nl.md
index af9c7095d..a55c1a445 100644
--- a/docs/keybindings/Keybindings_nl.md
+++ b/docs/keybindings/Keybindings_nl.md
@@ -241,7 +241,7 @@ If you would instead like to start an interactive rebase from the selected commi
 | Key | Action | Info |
 |-----|--------|-------------|
 | `` <c-o> `` | Kopieer branch name naar klembord |  |
-| `` <space> `` | Uitchecken | Checkout a new local branch based on the selected remote branch. The new branch will track the remote branch. |
+| `` <space> `` | Uitchecken | Checkout a new local branch based on the selected remote branch, or the remote branch as a detached head. |
 | `` n `` | Nieuwe branch |  |
 | `` M `` | Merge in met huidige checked out branch | Merge selected branch into currently checked out branch. |
 | `` r `` | Rebase branch | Rebase the checked-out branch onto the selected branch. |
diff --git a/docs/keybindings/Keybindings_pl.md b/docs/keybindings/Keybindings_pl.md
index 0d906eee4..e422d2963 100644
--- a/docs/keybindings/Keybindings_pl.md
+++ b/docs/keybindings/Keybindings_pl.md
@@ -240,7 +240,7 @@ If you would instead like to start an interactive rebase from the selected commi
 | Key | Action | Info |
 |-----|--------|-------------|
 | `` <c-o> `` | Copy branch name to clipboard |  |
-| `` <space> `` | Przełącz | Checkout a new local branch based on the selected remote branch. The new branch will track the remote branch. |
+| `` <space> `` | Przełącz | Checkout a new local branch based on the selected remote branch, or the remote branch as a detached head. |
 | `` n `` | Nowa gałąź |  |
 | `` M `` | Scal do obecnej gałęzi | Merge selected branch into currently checked out branch. |
 | `` r `` | Zmiana bazy gałęzi | Rebase the checked-out branch onto the selected branch. |
diff --git a/docs/keybindings/Keybindings_ru.md b/docs/keybindings/Keybindings_ru.md
index 2e78ac759..40ed1e2f4 100644
--- a/docs/keybindings/Keybindings_ru.md
+++ b/docs/keybindings/Keybindings_ru.md
@@ -297,7 +297,7 @@ If you would instead like to start an interactive rebase from the selected commi
 | Key | Action | Info |
 |-----|--------|-------------|
 | `` <c-o> `` | Скопировать название ветки в буфер обмена |  |
-| `` <space> `` | Переключить | Checkout a new local branch based on the selected remote branch. The new branch will track the remote branch. |
+| `` <space> `` | Переключить | Checkout a new local branch based on the selected remote branch, or the remote branch as a detached head. |
 | `` n `` | Новая ветка |  |
 | `` M `` | Слияние с текущей переключённой веткой | Merge selected branch into currently checked out branch. |
 | `` r `` | Перебазировать переключённую ветку на эту ветку | Rebase the checked-out branch onto the selected branch. |
diff --git a/docs/keybindings/Keybindings_zh-CN.md b/docs/keybindings/Keybindings_zh-CN.md
index a8693c4c8..c622e4bbc 100644
--- a/docs/keybindings/Keybindings_zh-CN.md
+++ b/docs/keybindings/Keybindings_zh-CN.md
@@ -340,7 +340,7 @@ If you would instead like to start an interactive rebase from the selected commi
 | Key | Action | Info |
 |-----|--------|-------------|
 | `` <c-o> `` | 将分支名称复制到剪贴板 |  |
-| `` <space> `` | 检出 | Checkout a new local branch based on the selected remote branch. The new branch will track the remote branch. |
+| `` <space> `` | 检出 | Checkout a new local branch based on the selected remote branch, or the remote branch as a detached head. |
 | `` n `` | 新分支 |  |
 | `` M `` | 合并到当前检出的分支 | Merge selected branch into currently checked out branch. |
 | `` r `` | 将已检出的分支变基到该分支 | Rebase the checked-out branch onto the selected branch. |
diff --git a/docs/keybindings/Keybindings_zh-TW.md b/docs/keybindings/Keybindings_zh-TW.md
index 0ebb9789c..42da8c2e2 100644
--- a/docs/keybindings/Keybindings_zh-TW.md
+++ b/docs/keybindings/Keybindings_zh-TW.md
@@ -351,7 +351,7 @@ If you would instead like to start an interactive rebase from the selected commi
 | Key | Action | Info |
 |-----|--------|-------------|
 | `` <c-o> `` | 複製分支名稱到剪貼簿 |  |
-| `` <space> `` | 檢出 | Checkout a new local branch based on the selected remote branch. The new branch will track the remote branch. |
+| `` <space> `` | 檢出 | Checkout a new local branch based on the selected remote branch, or the remote branch as a detached head. |
 | `` n `` | 新分支 |  |
 | `` M `` | 合併到當前檢出的分支 | Merge selected branch into currently checked out branch. |
 | `` r `` | 將已檢出的分支變基至此分支 | Rebase the checked-out branch onto the selected branch. |
diff --git a/pkg/commands/git_commands/branch.go b/pkg/commands/git_commands/branch.go
index d05738ef3..6a347b8ac 100644
--- a/pkg/commands/git_commands/branch.go
+++ b/pkg/commands/git_commands/branch.go
@@ -28,6 +28,17 @@ func (self *BranchCommands) New(name string, base string) error {
 	return self.cmd.New(cmdArgs).Run()
 }
 
+// CreateWithUpstream creates a new branch with a given upstream, but without
+// checking it out
+func (self *BranchCommands) CreateWithUpstream(name string, upstream string) error {
+	cmdArgs := NewGitCmd("branch").
+		Arg("--track").
+		Arg(name, upstream).
+		ToArgv()
+
+	return self.cmd.New(cmdArgs).Run()
+}
+
 // CurrentBranchInfo get the current branch information.
 func (self *BranchCommands) CurrentBranchInfo() (BranchInfo, error) {
 	branchName, err := self.cmd.New(
diff --git a/pkg/gui/controllers/branches_controller.go b/pkg/gui/controllers/branches_controller.go
index 068238ec7..ff9473ab6 100644
--- a/pkg/gui/controllers/branches_controller.go
+++ b/pkg/gui/controllers/branches_controller.go
@@ -436,6 +436,10 @@ func (self *BranchesController) checkoutByName() error {
 		FindSuggestionsFunc: self.c.Helpers().Suggestions.GetRefsSuggestionsFunc(),
 		HandleConfirm: func(response string) error {
 			self.c.LogAction("Checkout branch")
+			_, branchName, found := self.c.Helpers().Refs.ParseRemoteBranchName(response)
+			if found {
+				return self.c.Helpers().Refs.CheckoutRemoteBranch(response, branchName)
+			}
 			return self.c.Helpers().Refs.CheckoutRef(response, types.CheckoutRefOptions{
 				OnRefNotFound: func(ref string) error {
 					return self.c.Confirm(types.ConfirmOpts{
diff --git a/pkg/gui/controllers/helpers/refs_helper.go b/pkg/gui/controllers/helpers/refs_helper.go
index 8b066f447..6ddff118c 100644
--- a/pkg/gui/controllers/helpers/refs_helper.go
+++ b/pkg/gui/controllers/helpers/refs_helper.go
@@ -7,6 +7,7 @@ import (
 	"github.com/jesseduffield/gocui"
 	"github.com/jesseduffield/lazygit/pkg/commands/git_commands"
 	"github.com/jesseduffield/lazygit/pkg/commands/models"
+	"github.com/jesseduffield/lazygit/pkg/gui/context"
 	"github.com/jesseduffield/lazygit/pkg/gui/style"
 	"github.com/jesseduffield/lazygit/pkg/gui/types"
 	"github.com/jesseduffield/lazygit/pkg/utils"
@@ -53,7 +54,7 @@ func (self *RefsHelper) CheckoutRef(ref string, options types.CheckoutRefOptions
 
 	refreshOptions := types.RefreshOptions{Mode: types.BLOCK_UI, KeepBranchSelectionIndex: true}
 
-	return self.c.WithWaitingStatus(waitingStatus, func(gocui.Task) error {
+	f := func(gocui.Task) error {
 		if err := self.c.Git().Branch.Checkout(ref, cmdOptions); err != nil {
 			// note, this will only work for english-language git commands. If we force git to use english, and the error isn't this one, then the user will receive an english command they may not understand. I'm not sure what the best solution to this is. Running the command once in english and a second time in the native language is one option
 
@@ -93,6 +94,75 @@ func (self *RefsHelper) CheckoutRef(ref string, options types.CheckoutRefOptions
 		onSuccess()
 
 		return self.c.Refresh(refreshOptions)
+	}
+
+	localBranch, found := lo.Find(self.c.Model().Branches, func(branch *models.Branch) bool {
+		return branch.Name == ref
+	})
+	if found {
+		return self.c.WithInlineStatus(localBranch, types.ItemOperationCheckingOut, context.LOCAL_BRANCHES_CONTEXT_KEY, f)
+	} else {
+		return self.c.WithWaitingStatus(waitingStatus, f)
+	}
+}
+
+// Shows a prompt to choose between creating a new branch or checking out a detached head
+func (self *RefsHelper) CheckoutRemoteBranch(fullBranchName string, localBranchName string) error {
+	checkout := func(branchName string) error {
+		// Switch to the branches context _before_ starting to check out the
+		// branch, so that we see the inline status
+		if self.c.CurrentContext() != self.c.Contexts().Branches {
+			if err := self.c.PushContext(self.c.Contexts().Branches); err != nil {
+				return err
+			}
+		}
+		return self.CheckoutRef(branchName, types.CheckoutRefOptions{})
+	}
+
+	// If a branch with this name already exists locally, just check it out. We
+	// don't bother checking whether it actually tracks this remote branch, since
+	// it's very unlikely that it doesn't.
+	if lo.ContainsBy(self.c.Model().Branches, func(branch *models.Branch) bool {
+		return branch.Name == localBranchName
+	}) {
+		return checkout(localBranchName)
+	}
+
+	return self.c.Menu(types.CreateMenuOptions{
+		Title: utils.ResolvePlaceholderString(self.c.Tr.RemoteBranchCheckoutTitle, map[string]string{
+			"branchName": fullBranchName,
+		}),
+		Items: []*types.MenuItem{
+			{
+				Label:   self.c.Tr.CheckoutTypeNewBranch,
+				Tooltip: self.c.Tr.CheckoutTypeNewBranchTooltip,
+				OnPress: func() error {
+					// First create the local branch with the upstream set, and
+					// then check it out. We could do that in one step using
+					// "git checkout -b", but we want to benefit from all the
+					// nice features of the CheckoutRef function.
+					if err := self.c.Git().Branch.CreateWithUpstream(localBranchName, fullBranchName); err != nil {
+						return self.c.Error(err)
+					}
+					// Do a sync refresh to make sure the new branch is visible,
+					// so that we see an inline status when checking it out
+					if err := self.c.Refresh(types.RefreshOptions{
+						Mode:  types.SYNC,
+						Scope: []types.RefreshableView{types.BRANCHES},
+					}); err != nil {
+						return err
+					}
+					return checkout(localBranchName)
+				},
+			},
+			{
+				Label:   self.c.Tr.CheckoutTypeDetachedHead,
+				Tooltip: self.c.Tr.CheckoutTypeDetachedHeadTooltip,
+				OnPress: func() error {
+					return checkout(fullBranchName)
+				},
+			},
+		},
 	})
 }
 
@@ -232,3 +302,21 @@ func (self *RefsHelper) NewBranch(from string, fromFormattedName string, suggest
 func SanitizedBranchName(input string) string {
 	return strings.Replace(input, " ", "-", -1)
 }
+
+// Checks if the given branch name is a remote branch, and returns the name of
+// the remote and the bare branch name if it is.
+func (self *RefsHelper) ParseRemoteBranchName(fullBranchName string) (string, string, bool) {
+	remoteName, branchName, found := strings.Cut(fullBranchName, "/")
+	if !found {
+		return "", "", false
+	}
+
+	// See if the part before the first slash is actually one of our remotes
+	if !lo.ContainsBy(self.c.Model().Remotes, func(remote *models.Remote) bool {
+		return remote.Name == remoteName
+	}) {
+		return "", "", false
+	}
+
+	return remoteName, branchName, true
+}
diff --git a/pkg/gui/controllers/remote_branches_controller.go b/pkg/gui/controllers/remote_branches_controller.go
index 0cfdfbcd5..b46b5dbb1 100644
--- a/pkg/gui/controllers/remote_branches_controller.go
+++ b/pkg/gui/controllers/remote_branches_controller.go
@@ -35,9 +35,8 @@ func NewRemoteBranchesController(
 func (self *RemoteBranchesController) GetKeybindings(opts types.KeybindingsOpts) []*types.Binding {
 	return []*types.Binding{
 		{
-			Key: opts.GetKey(opts.Config.Universal.Select),
-			// gonna use the exact same handler as the 'n' keybinding because everybody wants this to happen when they checkout a remote branch
-			Handler:           self.withItem(self.newLocalBranch),
+			Key:               opts.GetKey(opts.Config.Universal.Select),
+			Handler:           self.withItem(self.checkoutBranch),
 			GetDisabledReason: self.require(self.singleItemSelected()),
 			Description:       self.c.Tr.Checkout,
 			Tooltip:           self.c.Tr.RemoteBranchCheckoutTooltip,
@@ -184,3 +183,7 @@ func (self *RemoteBranchesController) newLocalBranch(selectedBranch *models.Remo
 
 	return self.c.Helpers().Refs.NewBranch(selectedBranch.RefName(), selectedBranch.RefName(), nameSuggestion)
 }
+
+func (self *RemoteBranchesController) checkoutBranch(selectedBranch *models.RemoteBranch) error {
+	return self.c.Helpers().Refs.CheckoutRemoteBranch(selectedBranch.FullName(), selectedBranch.Name)
+}
diff --git a/pkg/gui/presentation/item_operations.go b/pkg/gui/presentation/item_operations.go
index 13415483b..b3ebaf8df 100644
--- a/pkg/gui/presentation/item_operations.go
+++ b/pkg/gui/presentation/item_operations.go
@@ -19,6 +19,8 @@ func ItemOperationToString(itemOperation types.ItemOperation, tr *i18n.Translati
 		return tr.DeletingStatus
 	case types.ItemOperationFetching:
 		return tr.FetchingStatus
+	case types.ItemOperationCheckingOut:
+		return tr.CheckingOutStatus
 	}
 
 	return ""
diff --git a/pkg/gui/types/common.go b/pkg/gui/types/common.go
index 91aec4913..e53260b34 100644
--- a/pkg/gui/types/common.go
+++ b/pkg/gui/types/common.go
@@ -309,6 +309,7 @@ const (
 	ItemOperationFastForwarding
 	ItemOperationDeleting
 	ItemOperationFetching
+	ItemOperationCheckingOut
 )
 
 type HasUrn interface {
diff --git a/pkg/i18n/english.go b/pkg/i18n/english.go
index 2f3f35ab5..f475ec756 100644
--- a/pkg/i18n/english.go
+++ b/pkg/i18n/english.go
@@ -113,6 +113,11 @@ type TranslationSet struct {
 	ForceCheckoutTooltip                  string
 	CheckoutByName                        string
 	CheckoutByNameTooltip                 string
+	RemoteBranchCheckoutTitle             string
+	CheckoutTypeNewBranch                 string
+	CheckoutTypeNewBranchTooltip          string
+	CheckoutTypeDetachedHead              string
+	CheckoutTypeDetachedHeadTooltip       string
 	NewBranch                             string
 	NewBranchFromStashTooltip             string
 	NoBranchesThisRepo                    string
@@ -1026,7 +1031,7 @@ func EnglishTranslationSet() TranslationSet {
 		CheckoutTooltip:                     "Checkout selected item.",
 		CantCheckoutBranchWhilePulling:      "You cannot checkout another branch while pulling the current branch",
 		TagCheckoutTooltip:                  "Checkout the selected tag tag as a detached HEAD.",
-		RemoteBranchCheckoutTooltip:         "Checkout a new local branch based on the selected remote branch. The new branch will track the remote branch.",
+		RemoteBranchCheckoutTooltip:         "Checkout a new local branch based on the selected remote branch, or the remote branch as a detached head.",
 		CantPullOrPushSameBranchTwice:       "You cannot push or pull a branch while it is already being pushed or pulled",
 		FileFilter:                          "Filter files by status",
 		CopyToClipboardMenu:                 "Copy to clipboard",
@@ -1065,6 +1070,11 @@ func EnglishTranslationSet() TranslationSet {
 		ForceCheckoutTooltip:                "Force checkout selected branch. This will discard all local changes in your working directory before checking out the selected branch.",
 		CheckoutByName:                      "Checkout by name",
 		CheckoutByNameTooltip:               "Checkout by name. In the input box you can enter '-' to switch to the last branch.",
+		RemoteBranchCheckoutTitle:           "Checkout {{.branchName}}",
+		CheckoutTypeNewBranch:               "New local branch",
+		CheckoutTypeNewBranchTooltip:        "Checkout the remote branch as a local branch, tracking the remote branch.",
+		CheckoutTypeDetachedHead:            "Detached head",
+		CheckoutTypeDetachedHeadTooltip:     "Checkout the remote branch as a detached head, which can be useful if you just want to test the branch but not work on it yourself. You can still create a local branch from it later.",
 		NewBranch:                           "New branch",
 		NewBranchFromStashTooltip:           "Create a new branch from the selected stash entry. This works by git checking out the commit that the stash entry was created from, creating a new branch from that commit, then applying the stash entry to the new branch as an additional commit.",
 		NoBranchesThisRepo:                  "No branches for this repo",
@@ -1895,6 +1905,7 @@ keybinding:
 - Squashing fixups using 'shift-S' now brings up a menu, with the default option being to squash all fixup commits in the branch. The original behaviour of only squashing fixup commits above the selected commit is still available as the second option in that menu.
 - Push/pull/fetch loading statuses are now shown against the branch rather than in a popup. This allows you to e.g. fetch multiple branches in parallel and see the status for each branch.
 - The git log graph in the commits view is now always shown by default (previously it was only shown when the view was maximised). If you find this too noisy, you can change it back via ctrl+L -> 'Show git graph' -> 'when maximised'
+- Pressing space on a remote branch used to show a prompt for entering a name for a new local branch to check out from the remote branch. Now it just checks out the remote branch directly, letting you choose between a new local branch with the same name, or a detached head. The old behavior is still available via the 'n' keybinding.
 	  `,
 		},
 	}