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

[Junio C Hamano <gitster@pobox.com>]

"Wesley J. Landaker" <wjl@icecavern.net> writes:

> I stumbled over the git-clean documentation when I was first learning
> git, and ran into this again when a colleage was asking for help. So
> here are two fixes.
>
> The first patch fixes some minor grammatical errors in very
> non-intrusive manner. This should be completely uncontroversial.
>
> The second patch rewrites the first paragraph in the description
> section to make it more readable and friendly. I think this change
> is a very good one, but I split it into a separate patch since it is
> a more intrusive change.

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.

    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.

    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.