What's the difference between magit-branch-checkout and magit-branch-and-checkout?

Question

If I'm on the commandline, and I'm in the master branch, and I want to create a new branch and immediately start working on it, I'd just do git checkout -b foo.

So I'm looking for the magit equivalent to this, i.e., I'd like to be able to call some magit function from within a branch, and then find myself working on the same buffer, but in a new branch that I've named. Once I find that function, I intend to bind it to a key so that I can avoid having to muck around with transient states and such.

In the magit docs, I see two different commands that might qualify:

1. magit-branch-and-checkout which, according to the manual, "creates a new branch like magit-branch, but then also checks it out." (Incidentally, this is kind of a bizarre bit of documentation, since according to the very same page of the manual, magit-branch does not, in fact, create a new branch, but rather is a prefix command that puts one in a branching transient stage. so... huh??)

2. magit-branch-checkout which, according to the docs, takes the name of a branch from the user (I assume magit-branch-and-checkout must do that too, right? unless, like, magit just picks a name for you for the new branch?), and then, per the docs, "If the user enters a new branch name, then it creates and checks that out, after also reading the starting-point from the user."

So, those sound like the exact same functionality. Except maybe that magit-branch-checkout asks for a "starting point" (is that a commit hash? a preexisting branch? we are not told.). But if that's the difference between the two, then this raises a sub-puzzle, viz.: how does magit determine the starting point for whatever magit-branch-and-checkout does?

So if I wanted to just do the magit equivalent of git checkout -b foo and immediately be working on the buffer in the new branch, would I use one of those? Something else entirely? Impossible within magit?

(I really wish there were a translation table somewhere from ordinary commandline git calls to magit function calls.)

Answer 1

I think all of your confusion is due to a typo in the docs. I believe "creates a new branch like magit-branch" should read "creates a new branch like magit-branch-create".

So bc magit-branch-and-checkout does this:

Create [and checkout] a new branch. The user is asked for a branch or arbitrary revision to use as the starting point of the new branch. When a branch name is provided, then that becomes the upstream branch of the new branch. The name of the new branch is also read in the minibuffer.

While bl magit-branch-checkout does this:

This command checks out an existing or new local branch. It reads a branch name from the user offering all local branches and a subset of remote branches as candidates. Remote branches for which a local branch by the same name exists are omitted from the list of candidates. The user can also enter a completely new branch name.

• If the user selects an existing local branch, then that is checked out.
• If the user selects a remote branch, then it creates and checks out a new local branch with the same name, and configures the selected remote branch as the push target.
• If the user enters a new branch name, then it creates and checks 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 starting point or something else depends on the value of magit-branch-adjust-remote-upstream-alist.

---

So to answer your questions:

magit-branch-checkout asks for a "starting point" (is that a commit hash? a preexisting branch? we are not told.)

A "starting point" means the same thing as <start-point> does in Git's own documentation (see, e.g., man git-branch): any commit reference -- which might be a commit hash, a branch name, or a tag (i.e. anything which git accepts as a point in the commit history).

how does magit determine the starting point for whatever magit-branch-and-checkout does?

Magit acts contextually -- in most cases where a reference is read from the user, the reference at point will be offered as a default value. If there is no commit at point, then a default value may be offered (in this case, the current HEAD commit).

So a great deal of the time you would just type RET at that prompt to use the default. So long as you understand where the default value is coming from, the simplest way of selecting a commit to do something with is usually to arrange that it will be the default value (typically by having point on the relevant line).

So if I wanted to just do the magit equivalent of git checkout -b foo and immediately be working on the buffer in the new branch, would I use one of those?

You could use either -- it will only really affect the order in which you enter the two arguments (being the name of the new branch, and its starting point). I always use bc for this.