Dear Junio, thanks for your answer and you availability to revise the man text. Below my (irreverent) comments On Thursday 19 September 2013 10:43:16 Junio C Hamano wrote: > Let's see how we can improve the text. Points to notice are: > > * "by updating the index and the files" does not say "how" they are > updated and can be clarified: > > - The index is made to match the state the commit at the tip of > <branch> records. > > - The working tree files without local modifications are updated > the same way. > > - The working tree files with local modifications are not > touched. mmm maybe I'm wrong, but it seems to me that the first statement on the index (above) is oversimplifing and not correct in presence of local changes. In the example below, when in the branch 'dev' the index content was '2 in index' and the workspace content was '3 in work' and the commited contents dev:a=master:a='1'. In this case checkout completed and the index (and workspace) contents after checkout where preserved, hence the index was different from the head commit in both branches master and dev. $ echo '1'>a; git init; git add a; git commit -a -m '1';git checkout -b dev;echo '2 in index'>a;git add a; echo '3 in work'>a; git checkout master; cat a; git diff; git diff HEAD Initialized empty Git repository in /home/xxxx/git-test12/.git/ [master (root-commit) d0064f1] 1 1 file changed, 1 insertion(+) create mode 100644 a Switched to a new branch 'dev' M a Switched to branch 'master' 3 in work diff --git a/a b/a index d35137c..ee9231a 100644 --- a/a +++ b/a @@ -1 +1 @@ -2 in index +3 in work diff --git a/a b/a index d00491f..ee9231a 100644 --- a/a +++ b/a @@ -1 +1 @@ -1 +3 in work $ This is what I ment by the line "if C1=C0, then: W1=W0 and I1=I0;" ... am I missing something? > * Because "the command refuses to checkout another branch under > this and that condition" does not have its own section, the > description of "-m" needs to say it as a background information > to explain in what situation the option may be useful. It can be > moved to the main "'git checkout' <branch>" part and it may make > the result read easier. I 100% agree that the git checkout' <branch> should mention that the command might not complete in some cases, and hopefully describe when. A normal user (me) learning the command tries to first understand the simpler usage before going below and learning the action of the options. > "in order to preserve your modifications in context" is correct > and sufficient description :((( this is one of the points I considered "vague"... what is "context"? "parent commit" or "parent commit AND index" or "index"? the reader starts to asks theirself too much questions, whose aswers requires an educated guess that should ideally not be necessary when reading a man page.... Maybe I'm to much mathematically minded, but few clean lines of pseudocode explain everything without any doubt. > If we allowed such a checkout and then you did "git commit -a", > you will end up reverting the state between X0 (contents in your > original branch) and X2 (contents in the new branch), even though > the change you wanted to make was only the difference between X0 > and X1. > ... OK I understand your motivations, in your example the contents would have been preserved by checkout, but a shallow user could be then "overchange" by mistake. > > Also, if you did "git add X" and then "checkout <branch>", unless > the version in the index at path X match either your original branch > or the branch you are checking out, the command will stop you, ... disagree (or misunderstand), if X0=X2 and index = X1 (work) then checkout does not fail, an example would be the example above with echo '2 in index'>a; replaced by echo '3 in work'>a. $ echo '1'>a; git init; git add a; git commit -a -m '1';git checkout -b dev;echo '3 in work'>a;git add a; echo '3 in work'>a; git checkout master; cat a; git diff; git diff HEAD Initialized empty Git repository in /home/xxx/git-test13/.git/ [master (root-commit) f8d39d9] 1 1 file changed, 1 insertion(+) create mode 100644 a Switched to a new branch 'dev' M a Switched to branch 'master' 3 in work diff --git a/a b/a index d00491f..ee9231a 100644 --- a/a +++ b/a @@ -1 +1 @@ -1 +3 in work $ ... again, sorry if I'm stupidly missing a point or I'm too much irreverent. Any suggestion of references on that would be very welcome. ric PS, BTW, updated in your glossary my statement would be For each path, denote by C0 = its content in the head commit before checkout I0 = its content in the index before checkout W0 = its content in the working tree before checkout C1 = its content in the head commit of the target branch <branch> W1= its content in working tree after checkout <branch> successfully completed I1 = its content in index after checkout <branch> successfully completed then: if C0=W0=I0, then: W1=I1=C1; if C1=I0, then: W1=W0 and I1=C1=I0; if C1=C0, then: W1=W0 and I1=I0; otherwise: abort -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html