From: Julia Evans <julia@xxxxxxx> - 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@xxxxxxx> --- 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
