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

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

[Fredrik Skolmli]

Signed-off-by: Fredrik Skolmli <fredrik@frsk.net>
---
 Documentation/git-clean.txt |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 43b2de7..ec6f743 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -23,6 +23,9 @@ example, be useful to remove all build products.
 If any optional `<path>...` arguments are given, only those paths
 are affected.
 
+If no arguments are given, the cleaning is recursive, starting at the current
+path.
+
 OPTIONS
 -------
 -d::
-- 
1.6.3.rc4.106.g0303f

-- 
Fredrik Skolmli

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

[Thomas Rast]

[-- Attachment #1: Type: text/plain, Size: 478 bytes --]

Fredrik Skolmli wrote:
> --- a/Documentation/git-clean.txt
> +++ b/Documentation/git-clean.txt
> @@ -23,6 +23,9 @@ example, be useful to remove all build products.
>  If any optional `<path>...` arguments are given, only those paths
>  are affected.
>  
> +If no arguments are given, the cleaning is recursive, starting at the current
> +path.

That makes it sound as if the <path> case was not recursive, but it
is!

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

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

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

[Fredrik Skolmli]

On Tue, May 05, 2009 at 11:55:17AM +0200, Thomas Rast wrote:
> Fredrik Skolmli wrote:
> > --- a/Documentation/git-clean.txt
> > +++ b/Documentation/git-clean.txt
> > @@ -23,6 +23,9 @@ example, be useful to remove all build products.
> >  If any optional `<path>...` arguments are given, only those paths
> >  are affected.
> >  
> > +If no arguments are given, the cleaning is recursive, starting at the current
> > +path.
> 
> 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?

-- 
Fredrik Skolmli

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

[Nicolas Sebrecht]

The 05/05/09, Fredrik Skolmli wrote:
> On Tue, May 05, 2009 at 11:55:17AM +0200, Thomas Rast wrote:
> > Fredrik Skolmli wrote:
> > > --- a/Documentation/git-clean.txt
> > > +++ b/Documentation/git-clean.txt
> > > @@ -23,6 +23,9 @@ example, be useful to remove all build products.
> > >  If any optional `<path>...` arguments are given, only those paths
> > >  are affected.
> > >  
> > > +If no arguments are given, the cleaning is recursive, starting at the current
> > > +path.
> > 
> > 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?

Maybe:

If any optional `<path>...` arguments are given, only those paths are
affected. If no arguments are given, the cleaning starts at the current
path.

The cleaning are recursive.

-- 
Nicolas Sebrecht

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

[Thomas Rast]

[-- Attachment #1: Type: text/plain, Size: 1572 bytes --]

Fredrik Skolmli wrote:
> 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

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

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

[Junio C Hamano]

Thomas Rast <trast@student.ethz.ch> writes:

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

With or without path limiters, clean does not look outside the current
directory; I think the "otherwise" makes things worse than the original.

I'd suggest not touching this paragraph at all, but instead say something
like this at the beginning:

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

    Cleans the working tree by recursively removing files that are not
    under version control, starting from the current directory.

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

[Thomas Rast]

[-- Attachment #1: Type: text/plain, Size: 878 bytes --]

Junio C Hamano wrote:
> Thomas Rast <trast@student.ethz.ch> writes:
> 
> > -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.
> 
> With or without path limiters, clean does not look outside the current
> directory; I think the "otherwise" makes things worse than the original.
> 
> I'd suggest not touching this paragraph at all, but instead say something
> like this at the beginning:
> 
> > -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, starting from the current directory.

Indeed, yours is better.

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

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

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

[Fredrik Skolmli]

On Wed, May 06, 2009 at 03:24:47PM +0200, Thomas Rast wrote:

> > I'd suggest not touching this paragraph at all, but instead say something
> > like this at the beginning:
> > 
> > > -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, starting from the current directory.
> 
> Indeed, yours is better.

And I agree, it does looks better. Junio, would you like me to produce a
patch v2, or would you like do the honor? (After all, you came up with the
final suggestion)

-- 
Fredrik Skolmli

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

[Junio C Hamano]

Fredrik Skolmli <fredrik@frsk.net> writes:

> On Wed, May 06, 2009 at 03:24:47PM +0200, Thomas Rast wrote:
>
>> Indeed, yours is better.
>
> And I agree, it does looks better. Junio, would you like me to produce a
> patch v2, or would you like do the honor? (After all, you came up with the
> final suggestion)

Ok, I'll queue this one.

-- >8 -- 
Date: Wed, 6 May 2009 10:48:26 -0700
Subject: [PATCH] git-clean doc: the command only affects paths under $(cwd)

Fredrik Skolmli and Thomas Rast noticed that it was left unstated that
"git clean" ran from a subdirectory will not affect anything outside it,
with or without path limiters.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-clean.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 43b2de7..be894af 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -13,8 +13,8 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-This allows cleaning the working tree by removing files that are not
-under version control.
+Cleans the working tree by recursively removing files that are not
+under version control, starting from the current directory.
 
 Normally, only files unknown to git are removed, but if the '-x'
 option is specified, ignored files are also removed. This can, for