Re: [PATCH] Documentation: Clarify which paths git-clean will affect

From: Thomas Rast <trast@student.ethz.ch>
Date: May 5, 2009, 12:26 UTC
Message-ID: <200905051426.18814.trast@student.ethz.ch>
In-Reply-To: <20090505100506.GF27900@frsk.net>

Fredrik Skolmli wrote:

Show 5 quoted lines

> On Tue, May 05, 2009 at 11:55:17AM +0200, Thomas Rast wrote:
> > That makes it sound as if the <path> case was not recursive, but it
> > is!
> 
> Auch, good point. Any suggestions on how to formulate it?

I'm not entirely happy with it, but if we're going to change it, I'd put the "recursive" near the top to make it more visible. Maybe like so:

-- 8< --

diff --git i/Documentation/git-clean.txt w/Documentation/git-clean.txt
index 43b2de7..3550fc0 100644
--- i/Documentation/git-clean.txt
+++ w/Documentation/git-clean.txt
@@ -13,15 +13,15 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-This allows cleaning the working tree by removing files that are not
+Cleans the working tree by recursively removing files that are not
 under version control.
 
 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.
 
-If any optional `<path>...` arguments are given, only those paths
-are affected.
+If any optional `<path>...` arguments are given, those paths are
+affected.  Otherwise, the cleaning starts at the current directory.
 
 OPTIONS
 -------
-- >8 --

As a side note, a random survey among a few other manpages did not
give any conclusive advice on the formulation of the first sentence.
I originally wanted to make it imperative ("clean the working
tree..."), but my perception may be skewed by the commit message
guidelines.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch