From: Julia Evans via GitGitGadget Date: Wed, 03 Sep 2025 16:49:58 GMT Subject: [PATCH v3 2/6] doc: git-checkout: clarify `git checkout ` Message-ID: <940cd17e7e15684c0ca8c7b2994835f63e1fd02a.1756918202.git.gitgitgadget@gmail.com> In-Reply-To: From: Julia Evans - Reduce use of jargon ("index", "HEAD") - Clarify that only identical files will be left unchanged, and that `git checkout` will fail rather than overwrite an unchanged file - Explain what `git checkout` with no arguments does in a more direct way Signed-off-by: Julia Evans --- Documentation/git-checkout.adoc | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index 218d3dd13d..50923ff118 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -28,11 +28,12 @@ DESCRIPTION See ARGUMENT DISAMBIGUATION below for how Git decides which one to do. `git checkout []`:: - To prepare for working on __, 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 - __. + Switch to __. This sets the current branch to __ and + updates the files in your working directory. Files which are + identical in __ and your current commit are left unchanged + so that you can keep your uncommitted changes to those files. + This will not overwrite uncommitted changes to a file: instead it + will fail without making any changes. + If __ is not found but there does exist a tracking branch in exactly one remote (call it __) with a matching name and @@ -42,10 +43,8 @@ exactly one remote (call it __) with a matching name and $ git checkout -b --track / ------------ + -You could omit __, 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 has no effect except +to print out the tracking information for the current branch. `git checkout (-b|-B) []`:: -- gitgitgadget