list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
* "man git-clean" doesn't clarify the *default* behaviour of "git clean"
@ 2017-11-13 10:21 Robert P. J. Day
  0 siblings, 0 replies; only message in thread
From: Robert P. J. Day @ 2017-11-13 10:21 UTC (permalink / raw)
  To: Git Mailing list

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

  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

  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.


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


Robert P. J. Day                                 Ottawa, Ontario, CANADA


^ permalink raw reply	[flat|nested] only message in thread

only message in thread, other threads:[~2017-11-13 10:22 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-11-13 10:21 "man git-clean" doesn't clarify the *default* behaviour of "git clean" Robert P. J. Day list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ \
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
 note: .onion URLs require Tor:

code repositories for project(s) associated with this inbox:

AGPL code for this site: git clone