From: Julia Evans via GitGitGadget Date: Wed, 03 Sep 2025 16:49:59 GMT Subject: [PATCH v3 3/6] doc: git-checkout: clarify `-b` and `-B` Message-ID: <043fec7e66dc57427f441b020f9eb7862ba93fc1.1756918202.git.gitgitgadget@gmail.com> In-Reply-To: From: Julia Evans - Remove some unnecessary detail about `--track` (users can refer to the OPTIONS section instead) - Explain what the start point defaults to - Describe `-B` much more tersely as "the same as `-b`, except ..", since potential users of `-B` are almost certainly already very familiar with `-b`. Move all of the other contents of `-B` to `-b`, updating the example so that it's appropriate for `-b` Signed-off-by: Julia Evans --- 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 50923ff118..a2777fb5b0 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -46,27 +46,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 fails without making any changes 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 creating it. `git checkout --detach []`:: `git checkout [--detach] `:: @@ -156,16 +150,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 creating it. `-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 -- gitgitgadget