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

From: Wesley J. Landaker <wjl@icecavern.net>
Date: Apr 26, 2009, 01:23 UTC
Message-ID: <200904251923.46448.wjl@icecavern.net>
In-Reply-To: <49F35833.5070005@gmail.com>

On Saturday 25 April 2009 12:36:35 Stephen Boyd wrote:

Show 15 quoted lines

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

Show 10 quoted lines

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