patchgit-checkout(1) mention fate of extraneous files

Signed-off-by: jidanni <jidanni@jidanni.org>
---
 Documentation/git-checkout.txt |   13 +++++++------
 1 files changed, 7 insertions(+), 6 deletions(-)

jidanni@jidanni.org, 17.01.2009:

Why do you reformat the whole paragraph? Just inserting your sentence would give a much nicer diff for easier review, it's no difference for asciidoc. Indeed to find the change, I just copied the old and new text into two Vim windows, reformatted and diffed them.

Then you would get this

  Documentation/git-checkout.txt |   2 ++
  1 files changed, 2 insertions(+), 0 deletions(-)

Markus

MH> Why do you reformat the whole paragraph?

OK, glad to know that I don't need to!!

Signed-off-by: jidanni <jidanni@jidanni.org>
---
 Documentation/git-checkout.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

The parenthetical remark is not true, here: $ git status # On branch anagrams nothing to commit (working directory clean) $ ls anagram fsdupfind $ git checkout master Switched to branch "master" $ ls fsdupfind

I think you mean "No untracked content is removed,...".

Signed-off-by: jidanni <jidanni@jidanni.org>
---
Thanks Boyd.
 Documentation/git-checkout.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

Hi,

On Mon, 19 Jan 2009, Boyd Stephen Smith Jr. wrote:

As "checkout" is about switching branches, and as Git is very keen on avoiding loss of uncommitted changes, I think this comment is utterly unnecessary. Indeed, it is rather annoying: when I read a document the other day, that I _had_ to read, and which was full of obvious statements, sure enough, I missed the single important half-sentence.

IOW do not clutter the man page with distracting stuff, please, please, please.

Ciao, Dscho

Signed-off-by: jidanni <jidanni@jidanni.org>
---
OK thanks Johannes.
I'm still worried that there is no exact statement on the fate of the
various different classes of files, but OK, moving this to only a SEE ALSO.

 Documentation/git-checkout.txt |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

Hi,

On Tue, 20 Jan 2009, jidanni@jidanni.org wrote:

You completely misread me. So I will say it out directly: I think no patch is needed.

Hth, Dscho

On Monday 19 January 2009, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote about 'Re: [PATCH,v4] git-checkout(1): mention fate of extraneous files':

I think some users will expect to get a clean checkout when simply doing "git checkout <branch>". It would be nice for the documentation mention that is not the case, and reference the tool that helps get the tree into that state. Just my opinion, though.

It seems natural to me for this to be mentioned in the 'git checkout' documentation. Perhaps there's a better place?

"Boyd Stephen Smith Jr." <bss@iguanasuicide.net> writes:

I think this is probably on the other side of the borderline.

First I was about to agree with you, but the more I think about it, I do not think it is natural at all to expect "checkout" to behave as if you did "rm -fr" everything and then "tar xf" over the void. What other SCM implements branch switching that way, and what workflow would such a behaviour help?

We need to draw a line somewhere to avoid cluttering the documentation too much, and I do not think this is something even a person with CVS braindamage would get confused about, which is where I think is a reasonable place to draw that line.

Having said all that, I share a desire to help people who do not have any prior experience nor knowledge to form a reasonable expectation out of the system.

For example, a person who does not have a clue on what version control system is about may think that the contents recorded in a branch is like a tarball, a version control system is not about helping you make changes but its _sole_ purpose is to extract one such tarball after another on demand to let you travel in time. Running an equivalent of "git clean" automatically upon checkout may feel as if it is a valid a convenience feature to deal with files that was in one tarball but not in the new one. It is not completely implausible that such a person may be confused upon learning that "checkout" leaves untracked paths intact. If you start from a flawed understanding of what problem the system helps you to solve, you end up with flawed expectations.

It would not help him if you only taught that checkout leaves untracked paths intact. You have instead to teach him why you may have, and you would want to keep, untracked paths in the work tree (i.e. they are build products and notes you take while developing, iow, files that are essential during your work, but does not belong to the end product, and you would want to keep them around even while switching branches because you may be growing both branches at the same time), and that it is one of the prime design concern to _any_ command in git not to lose them without being told. When a user lacks such a basic understanding of the system, what it was designed for and what it was designed to do, the user's expectation will never match what many parts of the system do. The user will stay confused.

I've always thought such basic concepts should be covered by the tutorial and the users are expected to read them before reading about individual commands, but that approach may not work in practice. Perhaps a separate section "Basic Understanding" at the end of each manual page of the command to cover minimum necessary basics to understand the command might help. The section may quote from the tutorial, or written afresh.

But I think that such a basic description should be in a separate section so that it does not clutter the main text for people who understand the basics. Also I fear there will be quite a lot of repetition (e.g. you may have to repeat that untracked files are unintersting and that is why the command does not say anything about them in manual pages for "diff", "grep", "checkout", etc.). Once it is understood, the user does not need it to be repeated, but if we want to let the user freely start reading from anywhere, the repetition cannot be avoided.

Hi,

On Mon, 19 Jan 2009, Junio C Hamano wrote:

IIRC both CVS and Subversion allow you to say "$SCM co" with an existing working directory, which is then updated (and untracked files are left alone, as "$SCM up" always did and should do).

So no, not even people with CVS/SVN braindamage would get confused thusly.

Ciao, Dscho

Thank you all for your responses. I hope one day the git-checkout man page will document what git-checkout does.

I believe that when classified in terms of their differing fates, there are two or three different types of files that might be sitting around in one's working tree at the time a "git checkout comes down on their heads".

Perhaps a brief table of their different fates might nice to have on the bottom of the man page.

OK, never mind.