From: Julia Evans <julia@xxxxxxx> - "To prepare for working on _<branch>_..." is confusing to some users: it makes it sound like these are steps that the user has to do, not steps that Git itself will do. Reword it. - Use "changes" instead of "modifications" (which Git normally does) - Mention that `git checkout` will fail if there's a merge conflict - The current explanation of `You could omit <branch>`... is confusing to users (what are the "expensive side effects"? what's a better way of getting the same info?). Be more direct and mention that `git status` is likely a better option. Signed-off-by: Julia Evans <julia@xxxxxxx> --- Documentation/git-checkout.adoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index ddda891c0ff7..a3edb95973a2 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -30,11 +30,12 @@ See ARGUMENT DISAMBIGUATION below for how Git decides which one to do. Here's a description of all of the modes: `git checkout [<branch>]`:: - To prepare for working on _<branch>_, switch to it by updating - the index and the files in the working tree, and by pointing - `HEAD` at the branch. Local modifications to the files in the - working tree are kept, so that they can be committed to the - _<branch>_. + Switch to _<branch>_. This will update the files in the working tree, + point `HEAD` at the branch, and update the index. Local changes to + the files in the working tree are kept, so that they can be committed + to the _<branch>_. If the local changes conflict with the changes on + _<branch>_, no changes will be made and the checkout operation will + fail. + If _<branch>_ is not found but there does exist a tracking branch in exactly one remote (call it _<remote>_) with a matching name and @@ -44,10 +45,9 @@ exactly one remote (call it _<remote>_) with a matching name and $ git checkout -b <branch> --track <remote>/<branch> ------------ + -You could omit _<branch>_, in which case the command degenerates to -"check out the current branch", which is a glorified no-op with -rather expensive side-effects to show only the tracking information, -if it exists, for the current branch. +Running `git checkout` without specifying a branch will output the +tracking information, if it exists, for the current branch, but it's +slower than getting the same information from `git status`. `git checkout (-b|-B) <new-branch> [<start-point>]`:: -- gitgitgadget
