[PATCH v3 2/6] doc: git-checkout: clarify `git checkout <branch>`
From: Julia Evans <julia@jvns.ca>
- 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
waySigned-off-by: Julia Evans <julia@jvns.ca>
---
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 [<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 sets the current branch to _<branch>_ and
+ updates the files in your working directory. Files which are
+ identical in _<branch>_ 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 _<branch>_ is not found but there does exist a tracking branch in
exactly one remote (call it _<remote>_) with a matching name and
@@ -42,10 +43,8 @@ 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 has no effect except
+to print out the tracking information for the current branch.
`git checkout (-b|-B) <new-branch> [<start-point>]`::
--
gitgitgadget
Julia Evans via GitGitGadget <gitgitgadget@gmail.com>