]> git.ipfire.org Git - thirdparty/git.git/commit
doc: git-checkout: clarify `-b` and `-B`
authorJulia Evans <julia@jvns.ca>
Wed, 10 Sep 2025 19:14:26 +0000 (19:14 +0000)
committerJunio C Hamano <gitster@pobox.com>
Wed, 10 Sep 2025 21:32:04 +0000 (14:32 -0700)
commit042d6f3402126d01a0484e83da0a4f0d3ac037ab
tree57b2ff85ca34d5d88e35b075565ec9b7d4f087aa
parentab215e4a8d14624c274319883c4b74956b24b0f0
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 `<start-point>` 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 <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/git-checkout.adoc