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

["Wesley J. Landaker" <wjl@icecavern.net>]

On Saturday 25 April 2009 12:36:35 Stephen Boyd wrote:
> 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:

The main reason I took that out in my patch was because I think the second 
sentence more says the same thing, except more clearly, and the exact 
semantics of "files unknown to git" versus "ignored files", etc seem to not have 
good definitions anyway, so I left that for the second paragraph that talks 
about how '-x' changes things.

Also, the NAME section already says "Remove untracked files from the working 
tree", and most other git command documentation pages do not repeat the 
summary in the description, but start right in to the behavioral details.

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

I agree more concise is usually better. But I do think keeping the "for 
example" is important so that the user doesn't think that "generated files" is 
something special (ignore rules are used for lots of different things).

So I might edit yours to say:

Specifying the '-x' option will also remove ignored files. This is useful to 
remove, for example, generated files that are normally ignored.

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

I left the part about '-x' there mostly because it was already in there, so I 
figured someone at some point thought it was special enough. I didn't want to 
undo any good decisions that had already been made. =) That said, both -x and 
-X are somewhat special because they change the behavior a LOT compared to, 
say, -d.