Re: [PATCH 0/2] Documentation: git-clean: description updates

From: Wesley J. Landaker <wjl@icecavern.net>
Date: Apr 26, 2009, 01:33 UTC
Message-ID: <200904251933.56710.wjl@icecavern.net>
In-Reply-To: <7vhc0cxok0.fsf@gitster.siamese.dyndns.org>

On Saturday 25 April 2009 18:10:23 Junio C Hamano wrote:

> Thanks, will queue for 1.6.3, as I think both are clearly improvements.
>
> One could argue that the second one could be further improved, but I do
> not see anything controversial in it.

Okay, great! I'm all for incremental improvements, so please do hack my patch up if it helps!

Show 21 quoted lines

>     This allows cleaning the working tree by removing files that are not
>     under version control.
>
>     Normally, only files unknown to git are removed, but if the '-x'
>     option is specified, ignored files are also removed. This can, for
>     example, be useful to remove all build products.
>
> The only iffy point I can see is that "unknown" is a bit fuzzy phrase in
> this context.  I know what you mean, but you are not writing for people
> who know what "git clean" does ;-)
>
> In the above, "unknown" refers to a set of files that is a strict subset
> of "untracked" files, excluding the "ignored" set.  But that is not
> defined anywhere in the glossary.
>
> Sometimes we colloquially say "files _known_ to git" to refer to "tracked"
> files (paths that appear in the index).  But your "files _unknown_ to git"
> is different from the complement of it.
>
> The saddest part is that "untracked files" is not defined in the glossary
> either.

Well, I wasn't sure how to canonically refer to "git that git does not track but also does not have ignore rules for" and "files that git ignores", so I tried to mostly just use the same terminology I saw kicking around in other documentation. I think "unknown files" and "ignored files" are fairly clear and seem like the terms I usually hear people using. If we add them to the glossary then we could use them in a standard way in the documentation.

>     Normally, the command removes files that are not in the index, but
>     ignored (see linkgit:gitignore[5]) files are kept.  With the '-x'
>     option, the command removes the ignored files as well.

Are you already queuing this or any of these other things? If not, I would be happy to work on another patchset that attacks both this and the glossary issue.