threads / patch / 19184

patchDocumentation: Clarify which paths git-clean will affect

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

## tl;dr

9 messages between May 5, 2009 and May 6, 2009. Diffs are folded; open one to read it.

replies: 8people: 4as markdown or json

Fredrik Skolmli· May 5, 2009, 09:13 UTC · lore
Signed-off-by: Fredrik Skolmli <fredrik@frsk.net>
---
 Documentation/git-clean.txt |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)
Show changes to Documentation/git-clean.txt +3 −0
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
Thomas Rast· May 5, 2009, 09:55 UTC · re: Fredrik Skolmli · lore

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

Fredrik Skolmli wrote:
Show 8 quoted lines
> --- 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
Fredrik Skolmli· May 5, 2009, 10:05 UTC · re: Thomas Rast · lore

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

On Tue, May 05, 2009 at 11:55:17AM +0200, Thomas Rast wrote:
Show 12 quoted lines
> 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
Nicolas Sebrecht· May 5, 2009, 11:17 UTC · re: Fredrik Skolmli · lore

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

The 05/05/09, Fredrik Skolmli wrote:
Show 15 quoted lines
> 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
Thomas Rast· May 5, 2009, 12:26 UTC · re: Fredrik Skolmli · lore

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

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< --
Show changes to diff +3 −4
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
Junio C Hamano· May 5, 2009, 16:20 UTC · re: Thomas Rast · lore

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

Thomas Rast <trast@student.ethz.ch> writes:
Show 8 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.
>  
> -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:

Show 11 quoted lines
> 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.
Thomas Rast· May 6, 2009, 13:24 UTC · re: Junio C Hamano · lore

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

Junio C Hamano wrote:
Show 17 quoted lines
> 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
Fredrik Skolmli· May 6, 2009, 16:31 UTC · re: Thomas Rast · lore

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

On Wed, May 06, 2009 at 03:24:47PM +0200, Thomas Rast wrote:
Show 9 quoted lines
> > 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
Junio C Hamano· May 6, 2009, 17:57 UTC · re: Fredrik Skolmli · lore

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

Fredrik Skolmli <fredrik@frsk.net> writes:
Show 7 quoted lines
> 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(-)
Show changes to Documentation/git-clean.txt +2 −2
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

← back to recent threads