"man git-clean" doesn't clarify the *default* behaviour of "git clean"

"man git-clean" doesn't clarify the *default* behaviour of "git clean"

[Robert P. J. Day]

  (against my better judgment at this point, i'm going to suggest a
slight reworking of "man git-clean" to make the OPTIONS more
comprehensible.)

  while the man page for "git clean" explains how options like -d and
-e and -x and -X, etc etc, alter the default behaviour of "git clean",
that man page doesn't clearly explain what that initial default
behaviour *is*.

  this sort of goes back to an earlier question of mine -- what is the
precise definition of files that are "[un]known to Git", because
that's what you read in that man page:

  "Normally, only files unknown to Git are removed, ..."

but i submit that unless the reader knows precisely what that means,
then all of the OPTIONS explanations are potentially confusing since
they're all worded in the sense of, "it's the default behaviour, but
with this alteration."

  based on a few simple tests, it *seems* that, in this case, the
absolutely default behaviour of just "git clean" (with no options) is
to remove files that are all of:

  1) untracked
  2) not ignored
  3) 1) and 2) above within only *tracked* directories
  4) not within subdirs named ".git"

is this accurate? because if this were explicitly listed at the
opening of that man page, it would make the subsequent OPTIONS far
more understandable, in that each option would now clearly show the
change from the default operation. does that make sense? and two more
things.

  first, the exclusion options mention overriding both of .gitignore
and $GIT_DIR/info/exclude, but what about one's personal
core.excludesFile setting? does that not play a part in this?

  finally, just an observation, but it seemed that as i was playing
with testing cleaning of tracked versus untracked directories, it
appeared that simply *staging* a directory made it "known" to git for
the purposes of cleaning. thinking about it, that seems to make sense,
but i've never seen that mentioned anywhere.

rday

p.s. with respect to trying to improve the docs, i am not trying to be
difficult, i am merely succeeding. :-)

  as hard as this may be to believe, i actually teach courses in git,
and often, i just display the man page for a command and walk through
it to explain its operation, and there are times when that man page is
simply not clear which is why i'm working so hard at trying to improve
them.

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================