Re: On the behavior of checkout with uncommitted local changes
Dear Juno Thanks for your answer. My fair criticism in my previous emails (and below) is just to try to convince you that with a few short sentences you risk to transmit only vague ideas, while a serious user is interested to understand the behavior of git in any occurrence, with no ambiguity. Once more, in my view a short pseudo code -- or its equivalent in words -- would be a useful compromise among simplicity and accuracy. I'm attacking git checkout but I guess that what I say is a general problem of the git official documentation (i.e git stash in my experience has problems). Each undocumented feature (simulated by my dumb questions) enforces the loss of a significant percentage of the users. Lacking details, a hurried user will not use the feature, or if they are brave enough, they will use it without understanding (i.e. risking data loss one day or the other)... Lacking details, a serious user will have to waste their time in trials or in studing the sources. Do not fear that giving details in a man page would scare newbyes: as a git newbye I can say that what scares me is the lack of information, not the complexity(=power) of a program (*) Do not waste your precious time in explaining me/us general ideas, we can find them in the tens of pedagogic tutorials/books out there, please give us those details that nobody out there seems to know and that man (un)intentionally hides! I would be happy to submit a patch for the man git-checkout but I'm not sure that my understanding of git checkout (as encoded in the pseudocode I submitted) is correct. My friendly regards, ric (*) of course you're allowed to discard my suggestions pretending that I'm not a representative user ;) On Friday 20 September 2013 15:58:27 Junio C Hamano wrote: > The principle is that we allow you to check out a different branch > when you have local changes to the working tree and/or to the index, > as long as we can make the index and the working tree pretend as if > you reached that locally modified state, starting from a clean state > of the branch you are checking out. Of course I understand the idea, but if I try to grasp the details I'm in trouble: the problem in this statement is the ambiguity of "change" and "pretend as". In plain english I can start from any content and change it to any other content, so in this semantics your statement is empty, or worse. If I assume that change means "differences with N lines of unchanged context" I must still guess differences with respect to what? head-index, index-work, head-work ... and how much is N? 3, 4, 1028? Then, in order to understand I (a user) make the trials below, and concludes that also the nice principle stated above is somewhat incomplete git-test15$ echo -e 'a\n1\n2\n3\n4\n5\nb\n6\n7\n8\n9\n10\n'>f; cat f;git init; git add f; git commit -a -m 'ab'; git checkout -b dev; echo -e 'A\n1\n2\n3\n4\n5\nb\n6\n7\n8\n9\n10\n'>f;cat f;git commit -a -m 'Ab'; echo -e 'A\n1\n2\n3\n4\n5\nB\n6\n7\n8\n9\n10\n'>f;cat f;git add f; git checkout master a 1 2 3 4 5 b 6 7 8 9 10 Initialized empty Git repository in /home/git-test15/.git/
Re: On the behavior of checkout with uncommitted local changes
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 >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//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' " part and it may make >the result read easier. I 100% agree that the git checkout' 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,
On the behavior of checkout with uncommitted local changes
Dear all I'm not a power git user but I profit of git every day and I like to fully understand what I do. The man section for git checkout is too vague for my taste. In particular it is not clearly (unambiguously) stated what happens to index and worktree whenever local uncommitted changes are around. I've already rised a similar problem in this mail list [1], but I understand that a man page must be concise. On the other hand, I couldn't find any complete information on this behavior: tutorials and books seem to avoid the problem, user posts seems confused ... To grasp some more information, I've spent some hours in trials (sorry I'm unable to grasp information browsing the code repository). That resulted in the algorithm below presented. Could anybody authoritative on that subject confirm/correct/discharge my statement? That could be of help for me and may others. Nonetheless to say having this kind of pseudocodes available somewhere (e.g. for stash [2] and other tools modifing index and working tree) would make my git experience (and that of many more people) happier. Thanks to all developers for their efforts. Regards ric Notations: let us fix a file and denote C0 = its version in the initial commit I0 = its version in the initial index W0 = its version in the working tree C1 = its version in the target commit W1= its version in working tree after checkout completed I1 = its version in index after checkout completed git checkout Branch 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 Note: in particular, if W0=I0 !=C0 then (in general) abort Note: in particular, if C0=I0 and C1=W0 then abort (...actually why that? no information is lost) REFS [1]http://thread.gmane.org/gmane.linux.debian.devel.bugs.general/782914/focus=164647 [2]http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=717088 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
