Re: Suggestion: make git checkout safer
Torsten Bögershausen <tboegi <at> web.de> writes:
>Do you think you can write a patch to improve the documentation ?
Here is my attempt, but it is only a starting point.
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index d263a56..ee25354 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -3,7 +3,7 @@ git-checkout(1)
NAME
----
-git-checkout - Checkout a branch or paths to the working tree
+git-checkout - Overwrite working tree files with a given branch
SYNOPSIS
--------
@@ -17,10 +17,11 @@ SYNOPSIS
DESCRIPTION
-----------
-Updates files in the working tree to match the version in the index
-or the specified tree. If no paths are given, 'git checkout' will
-also update `HEAD` to set the specified branch as the current
-branch.
+Updates, creates, or overwrites files in the working tree to match the
+version in the index or the specified tree. If no paths are given,
+'git checkout' will also update `HEAD` to set the specified branch as
+the current branch, and will keep local changes. If paths are given,
+'git checkout' will unconditionally overwrite local changes.
'git checkout' <branch>::
To prepare for working on <branch>, switch to it by updating
@@ -81,21 +82,24 @@ Omitting <branch> detaches HEAD at the tip of the
current branch.
'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
When <paths> or `--patch` are given, 'git checkout' does *not*
- switch branches. It updates the named paths in the working tree
- from the index file or from a named <tree-ish> (most often a
- commit). In this case, the `-b` and `--track` options are
- meaningless and giving either of them results in an error. The
- <tree-ish> argument can be used to specify a specific tree-ish
- (i.e. commit, tag or tree) to update the index for the given
- paths before updating the working tree.
-+
-The index may contain unmerged entries because of a previous failed merge.
-By default, if you try to check out such an entry from the index, the
-checkout operation will fail and nothing will be checked out.
-Using `-f` will ignore these unmerged entries. The contents from a
-specific side of the merge can be checked out of the index by
-using `--ours` or `--theirs`. With `-m`, changes made to the working tree
-file can be discarded to re-create the original conflicted merge result.
+ switch branches. It overwrites the named paths in the working
+ tree from the index file or from a named <tree-ish> (most
+ often a commit). Unlike other modes, local modifications to
+ the files in the working tree are *not* kept.
+
+ In this case, the `-b` and `--track` options are meaningless
+ and giving either of them results in an error. The <tree-ish>
+ argument can be used to specify a specific tree-ish (i.e.
+ commit, tag or tree) to update the index for the given paths
+ before updating the working tree. + The index may contain
+ unmerged entries because of a previous failed merge. By
+ default, if you try to check out such an entry from the index,
+ the checkout operation will fail and nothing will be checked
+ out. Using `-f` will ignore these unmerged entries. The
+ contents from a specific side of the merge can be checked out
+ of the index by using `--ours` or `--theirs`. With `-m`,
+ changes made to the working tree file can be discarded to
+ re-create the original conflicted merge result.
OPTIONS
-------
@@ -110,7 +114,9 @@ OPTIONS
local changes.
+
When checking out paths from the index, do not fail upon unmerged
-entries; instead, unmerged entries are ignored.
+entries; instead, unmerged entries are ignored. (Note that when
+checking out paths, local changes are thrown away whether or not
+this flag is given.)
--ours::
--theirs::
@@ -481,10 +487,10 @@ $ git checkout hello.c <3>
------------
+
<1> switch branch
-<2> take a file out of another commit
-<3> restore hello.c from the index
+<2> take a file out of another commit, overwriting any local changes
+<3> restore hello.c from the index (would overwrite it if it existed)
+
-If you want to check out _all_ C source files out of the index,
+If you want to revert _all_ C source files out of the index,
you can say
+
------------
@@ -492,7 +498,7 @@ $ git checkout -- '*.c'
------------
+
Note the quotes around `*.c`. The file `hello.c` will also be
-checked out, even though it is no longer in the working tree,
+created, even though it is no longer in the working tree,
because the file globbing is used to match entries in the index
(not in the working tree by the shell).