From 042d6f3402126d01a0484e83da0a4f0d3ac037ab Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 10 Sep 2025 19:14:26 +0000 Subject: [PATCH] doc: git-checkout: clarify `-b` and `-B` From user feedback: several users reported having trouble understanding the difference between `-b` and `-B` ("I think it's because my brain expects it to contrast with `-b`, but instead it starts off explaining how they're the same"). Also, in `-B`, 2 users can't tell what the branch is reset *to*. Simplify the sentence structure in the explanations of `-b` and `-B` and add a little extra information (what `` is, what the branch is reset to). Splitting up `-b` and `-B` into separate items helps simplify the sentence structure since there's less "In this case...". Replace the long "the branch is not reset/created unless "git checkout" is successful..." with just "will fail", since we should generally assume that Git will fail operations in a clean way and not leave operations half-finished, and that cases where it does not fail cleanly are the exceptions that the documentation should flag. Signed-off-by: Julia Evans Signed-off-by: Junio C Hamano --- Documentation/git-checkout.adoc | 44 ++++++++++++++------------------- 1 file changed, 18 insertions(+), 26 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index 7d7505ad40..aaff488929 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -47,27 +47,21 @@ $ git checkout -b --track / Running `git checkout` without specifying a branch has no effect except to print out the tracking information for the current branch. -`git checkout (-b|-B) []`:: - - Specifying `-b` causes a new branch to be created as if - linkgit:git-branch[1] were called and then checked out. In - this case you can use the `--track` or `--no-track` options, - which will be passed to `git branch`. As a convenience, - `--track` without `-b` implies branch creation; see the - description of `--track` below. -+ -If `-B` is given, __ is created if it doesn't exist; otherwise, it -is reset. This is the transactional equivalent of -+ ------------- -$ git branch -f [] -$ git checkout ------------- +`git checkout -b []`:: + + Create a new branch named __, start it at __ + (defaults to the current commit), and check out the new branch. + You can use the `--track` or `--no-track` options to set the branch's + upstream tracking information. + -that is to say, the branch is not reset/created unless "git checkout" is -successful (e.g., when the branch is in use in another worktree, not -just the current branch stays the same, but the branch is not reset to -the start-point, either). +This will fail if there's an error checking out __, for +example if checking out the `` commit would overwrite your +uncommitted changes. + +`git checkout -B []`:: + + The same as `-b`, except that if the branch already exists it + resets `__` to the start point instead of failing. `git checkout --detach []`:: `git checkout [--detach] `:: @@ -157,16 +151,14 @@ of it"). see linkgit:git-branch[1] for details. `-B `:: - Creates the branch __, start it at __; - if it already exists, then reset it to __. And then - check the resulting branch out. This is equivalent to running - `git branch` with `-f` followed by `git checkout` of that branch; - see linkgit:git-branch[1] for details. + The same as `-b`, except that if the branch already exists it + resets `__` to the start point instead of failing. `-t`:: `--track[=(direct|inherit)]`:: When creating a new branch, set up "upstream" configuration. See - `--track` in linkgit:git-branch[1] for details. + `--track` in linkgit:git-branch[1] for details. As a convenience, + --track without -b implies branch creation. + If no `-b` option is given, the name of the new branch will be derived from the remote-tracking branch, by looking at the local part of -- 2.47.3