patch, 2 partsDocumentation: git-clean: description updates

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(-)

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(-)

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(-)

Wesley J. Landaker wrote:

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.

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.

On Saturday 25 April 2009 12:36:35 Stephen Boyd 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.

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.

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.

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.

Wesley J. Landaker wrote:

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.

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

So maybe -X should be described as well?

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

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.

On Saturday 25 April 2009 18:10:23 Junio C Hamano wrote:

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

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.

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.