From: Stephen Boyd Date: Sat, 25 Apr 2009 18:36:35 GMT Subject: Re: [PATCH 2/2] Documentation: git-clean: make description more readable Message-ID: <49F35833.5070005@gmail.com> In-Reply-To: <1240672421-10309-3-git-send-email-wjl@icecavern.net> 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.