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

From: Stephen Boyd <bebarino@gmail.com>
Date: Apr 25, 2009, 18:36 UTC
Message-ID: <49F35833.5070005@gmail.com>
In-Reply-To: <1240672421-10309-3-git-send-email-wjl@icecavern.net>

Wesley J. Landaker wrote:

Show 10 quoted lines

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