Subject: Re: [PATCH 2/2] Documentation: git-clean: make description more readable

From: Stephen Boyd <[email-masked]>
Date: Sat, 25 Apr 2009 11:36:35 -0700

Wesley J. Landaker wrote:
>  DESCRIPTION
>  -----------
> -Removes files unknown to git.  This allows cleaning the working tree
> -of files that are not under version control.  If the '-x' option is
> -specified, ignored files are also removed, allowing the removal of all
> -build products.
> +
> +This allows cleaning the working tree by removing files that are not
> +under version control.
> +

Why is the "Removes files unknown to git" part lost? Maybe it should be
replaced with a copy of the Name section, similar to log and diff. For
example:

DESCRIPTION
-----------
Removes untracked files from the working tree. This allows cleaning the
working tree by removing files that are not under version control.

But then the second sentence becomes redundant.

> +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.

This seems overly wordy. Maybe:

Specifying the '-x' option will also remove ignored files. This is
useful to remove generated files.

Better?

On a side note, why is -x getting special treatment here but not -X or
-d? You might want to just describe the general usefulness of the
command and let the reader move onto the options to learn more.