[PATCH 0/2] Documentation: git-clean: description updates

[PATCH 0/2] Documentation: git-clean: description updates

[Wesley J. Landaker]

I stumbled over the git-clean documentation when I was first learning
git, and ran into this again when a colleage was asking for help. So
here are two fixes.

The first patch fixes some minor grammatical errors in very
non-intrusive manner. This should be completely uncontroversial.

The second patch rewrites the first paragraph in the description
section to make it more readable and friendly. I think this change
is a very good one, but I split it into a separate patch since it is
a more intrusive change.

Wesley J. Landaker (2):
  Documentation: git-clean: fix minor grammatical errors
  Documentation: git-clean: make description more readable

 Documentation/git-clean.txt |   13 ++++++++-----
 1 files changed, 8 insertions(+), 5 deletions(-)

[PATCH 1/2] Documentation: git-clean: fix minor grammatical errors

[Wesley J. Landaker]

There were a few minor grammatical errors that made this paragraph hard
to read. This patch fixes the errors in a very minimal manner.

Signed-off-by: Wesley J. Landaker <wjl@icecavern.net>
---

This could still be made much more readable, but this patch tries to be
very non-invasive.

 Documentation/git-clean.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 8a11450..932d44d 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -12,9 +12,9 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Removes files unknown to git.  This allows to clean the working tree
-from files that are not under version control.  If the '-x' option is
-specified, ignored files are also removed, allowing to remove all
+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.
 If any optional `<path>...` arguments are given, only those paths
 are affected.
-- 
1.6.2.4

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

[Wesley J. Landaker]

The existing text is a little bit awkward. This rewrites the description
section to be more readable and friendly.

Signed-off-by: Wesley J. Landaker <wjl@icecavern.net>
---

This is a more major change, but since at least I and one other person I
know have both stumbled on this section, I think making it more readable
and friendly is a good change.

 Documentation/git-clean.txt |   13 ++++++++-----
 1 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 932d44d..43b2de7 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -12,14 +12,17 @@ SYNOPSIS
 
 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.
+
+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.
 
-
 OPTIONS
 -------
 -d::
-- 
1.6.2.4

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

[Stephen Boyd]

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:

DESCRIPTION
-----------
Removes untracked files from the working tree. This allows cleaning the
working tree by removing files that are not under version control.

But then the second sentence becomes redundant.

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

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.

Re: [PATCH 0/2] Documentation: git-clean: description updates

[Junio C Hamano]

"Wesley J. Landaker" <wjl@icecavern.net> writes:

> I stumbled over the git-clean documentation when I was first learning
> git, and ran into this again when a colleage was asking for help. So
> here are two fixes.
>
> The first patch fixes some minor grammatical errors in very
> non-intrusive manner. This should be completely uncontroversial.
>
> The second patch rewrites the first paragraph in the description
> section to make it more readable and friendly. I think this change
> is a very good one, but I split it into a separate patch since it is
> a more intrusive change.

Thanks, will queue for 1.6.3, as I think both are clearly improvements.

One could argue that the second one could be further improved, but I do
not see anything controversial in it.

    This allows cleaning the working tree by 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.

The only iffy point I can see is that "unknown" is a bit fuzzy phrase in
this context.  I know what you mean, but you are not writing for people
who know what "git clean" does ;-)

In the above, "unknown" refers to a set of files that is a strict subset
of "untracked" files, excluding the "ignored" set.  But that is not
defined anywhere in the glossary.

Sometimes we colloquially say "files _known_ to git" to refer to "tracked"
files (paths that appear in the index).  But your "files _unknown_ to git"
is different from the complement of it.

The saddest part is that "untracked files" is not defined in the glossary
either.

    Normally, the command removes files that are not in the index, but
    ignored (see linkgit:gitignore[5]) files are kept.  With the '-x'
    option, the command removes the ignored files as well.

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

[Wesley J. Landaker]

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.

Re: [PATCH 0/2] Documentation: git-clean: description updates

[Wesley J. Landaker]

On Saturday 25 April 2009 18:10:23 Junio C Hamano wrote:
> Thanks, will queue for 1.6.3, as I think both are clearly improvements.
>
> One could argue that the second one could be further improved, but I do
> not see anything controversial in it.

Okay, great! I'm all for incremental improvements, so please do hack my patch 
up if it helps!

>     This allows cleaning the working tree by 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.
>
> The only iffy point I can see is that "unknown" is a bit fuzzy phrase in
> this context.  I know what you mean, but you are not writing for people
> who know what "git clean" does ;-)
>
> In the above, "unknown" refers to a set of files that is a strict subset
> of "untracked" files, excluding the "ignored" set.  But that is not
> defined anywhere in the glossary.
>
> Sometimes we colloquially say "files _known_ to git" to refer to "tracked"
> files (paths that appear in the index).  But your "files _unknown_ to git"
> is different from the complement of it.
>
> The saddest part is that "untracked files" is not defined in the glossary
> either.

Well, I wasn't sure how to canonically refer to "git that git does not track 
but also does not have ignore rules for" and "files that git ignores", so I 
tried to mostly just use the same terminology I saw kicking around in other 
documentation. I think "unknown files" and "ignored files" are fairly clear and 
seem like the terms I usually hear people using. If we add them to the 
glossary then we could use them in a standard way in the documentation.

>     Normally, the command removes files that are not in the index, but
>     ignored (see linkgit:gitignore[5]) files are kept.  With the '-x'
>     option, the command removes the ignored files as well.

Are you already queuing this or any of these other things? If not, I would be 
happy to work on another patchset that attacks both this and the glossary 
issue.

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

[Stephen Boyd]

Wesley J. Landaker wrote:
> 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.
If you want to keep it, maybe change it to be more active. Something like:

    Cleans the working tree by removing files that are not under version
control.

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

The "for example" just comes sticking out again. Could you put it at the
beginning of the sentence?

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

So maybe -X should be described as well?