Function: magit-branch-checkout

magit-branch-checkout is an autoloaded, interactive and byte-compiled function defined in magit-branch.el.

Signature

(magit-branch-checkout BRANCH &optional START-POINT)

Documentation

Checkout an existing or new local branch.

Read a branch name from the user offering all local branches and a subset of remote branches as candidates. Omit remote branches for which a local branch by the same name exists from the list of candidates. The user can also enter a completely new branch name.

- If the user selects an existing local branch, then check that
  out.

- If the user selects a remote branch, then create and checkout
  a new local branch with the same name. Configure the selected
  remote branch as push target.

- If the user enters a new branch name, then create and check
  that out, after also reading the starting-point from the user.

In the latter two cases the upstream is also set. Whether it is set to the chosen START-POINT or something else depends on the value of magit-branch-adjust-remote-upstream-alist, just like when using magit-branch-and-checkout.

Key Bindings

Source Code

;; Defined in ~/.emacs.d/elpa/magit-20260411.1452/magit-branch.el
;;;###autoload
(defun magit-branch-checkout (branch &optional start-point)
  "Checkout an existing or new local branch.

Read a branch name from the user offering all local branches and
a subset of remote branches as candidates.  Omit remote branches
for which a local branch by the same name exists from the list
of candidates.  The user can also enter a completely new branch
name.

- If the user selects an existing local branch, then check that
  out.

- If the user selects a remote branch, then create and checkout
  a new local branch with the same name.  Configure the selected
  remote branch as push target.

- If the user enters a new branch name, then create and check
  that out, after also reading the starting-point from the user.

In the latter two cases the upstream is also set.  Whether it is
set to the chosen START-POINT or something else depends on the
value of `magit-branch-adjust-remote-upstream-alist', just like
when using `magit-branch-and-checkout'."
  (declare (interactive-only magit-call-git))
  (interactive
    (let* ((current (magit-get-current-branch))
           (local   (magit-list-local-branch-names))
           (remote  (seq-filter (##and (string-match "[^/]+/" %)
                                       (not (member (substring % (match-end 0))
                                                    (cons "HEAD" local))))
                                (magit-list-remote-branch-names)))
           (choices (nconc (delete current local) remote))
           (atpoint (magit-branch-at-point))
           (choice  (magit-completing-read
                     "Checkout branch" choices
                     nil nil nil 'magit-revision-history
                     (or (car (member atpoint choices))
                         (and atpoint
                              (car (member (and (string-match "[^/]+/" atpoint)
                                                (substring atpoint (match-end 0)))
                                           choices)))))))
      (cond ((member choice remote)
             (list (and (string-match "[^/]+/" choice)
                        (substring choice (match-end 0)))
                   choice))
            ((member choice local)
             (list choice))
            ((list choice (magit-read-starting-point "Create" choice))))))
  (cond
    ((not start-point)
     (magit--checkout branch (magit-branch-arguments))
     (magit-refresh))
    (t
     (when (magit-anything-modified-p t)
       (user-error "Cannot checkout when there are uncommitted changes"))
     (magit-run-git-async "checkout" (magit-branch-arguments)
                          "-b" branch start-point)
     (set-process-sentinel
      magit-this-process
      (lambda (process event)
        (when (memq (process-status process) '(exit signal))
          (magit-branch-maybe-adjust-upstream branch start-point)
          (when (magit-remote-branch-p start-point)
            (pcase-let ((`(,remote . ,remote-branch)
                         (magit-split-branch-name start-point)))
              (when (and (equal branch remote-branch)
                         (not (equal remote (magit-get "remote.pushDefault"))))
                (magit-set remote "branch" branch "pushRemote"))))
          (magit-process-sentinel process event)))))))