[PATCH v3 3/6] doc: git-checkout: clarify `-b` and `-B`
From: Julia Evans <julia@jvns.ca>
- 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 <julia@jvns.ca>
---
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 <branch> --track <remote>/<branch>
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) <new-branch> [<start-point>]`::
-
- 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, _<new-branch>_ is created if it doesn't exist; otherwise, it
-is reset. This is the transactional equivalent of
-+
-------------
-$ git branch -f <branch> [<start-point>]
-$ git checkout <branch>
-------------
+`git checkout -b <new-branch> [<start-point>]`::
+
+ Create a new branch named _<new-branch>_, start it at _<start-point>_
+ (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
+_<new-branch>_, for example if checking out the `<start-point>`
+commit would overwrite your uncommitted changes.
+
+`git checkout -B <branch> [<start-point>]`::
+
+ The same as `-b`, except that if the branch already exists it
+ resets `_<branch>_` to the start point instead of creating it.
`git checkout --detach [<branch>]`::
`git checkout [--detach] <commit>`::
@@ -156,16 +150,14 @@ of it").
see linkgit:git-branch[1] for details.
`-B <new-branch>`::
- Creates the branch _<new-branch>_, start it at _<start-point>_;
- if it already exists, then reset it to _<start-point>_. 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 `_<branch>_` 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
Julia Evans via GitGitGadget <gitgitgadget@gmail.com>