threads / patch / 15306

patchImprove documentation for --dirstat diff option

Subject: [PATCH] Improve documentation for --dirstat diff option

## tl;dr

4 messages between Sep 1, 2008 and Sep 1, 2008. Diffs are folded; open one to read it.

replies: 3people: 4as markdown or json

Heikki Orsila· Sep 1, 2008, 00:50 UTC · lore
Signed-off-by: Heikki Orsila <heikki.orsila@iki.fi>
---
 Documentation/diff-options.txt |   11 +++++------
 1 files changed, 5 insertions(+), 6 deletions(-)
Show changes to Documentation/diff-options.txt +5 −6
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 1759386..1fda86c 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -59,12 +59,11 @@ endif::git-format-patch[]
 	lines.
 
 --dirstat[=limit]::
-	Output only the sub-directories that are impacted by a diff,
-	and to what degree they are impacted.  You can override the
-	default cut-off in percent (3) by "--dirstat=limit".  If you
-	want to enable "cumulative" directory statistics, you can use
-	the "--cumulative" flag, which adds up percentages recursively
-	even when they have been already reported for a sub-directory.
+	Output the distribution of relative damage (number of lines added or
+	removed) for each sub-directory. Directories with damage below
+	a cut-off percent (3% by default) are not shown. The cut-off percent
+	can be set with "--dirstat=limit". Damage for a child directory is not
+	counted for the parent directory, unless "--cumulative" is used.
 
 --summary::
 	Output a condensed summary of extended header information
-- 
1.6.0.1
Jakub Narebski· Sep 1, 2008, 09:42 UTC · re: Heikki Orsila · lore

Re: [PATCH] Improve documentation for --dirstat diff option

Heikki Orsila wrote:
Show 12 quoted lines
>  --dirstat[=limit]::
> -       Output only the sub-directories that are impacted by a diff,
> -       and to what degree they are impacted.  You can override the
> -       default cut-off in percent (3) by "--dirstat=limit".  If you
> -       want to enable "cumulative" directory statistics, you can use
> -       the "--cumulative" flag, which adds up percentages recursively
> -       even when they have been already reported for a sub-directory.
> +       Output the distribution of relative damage (number of lines added or
> +       removed) for each sub-directory. Directories with damage below
> +       a cut-off percent (3% by default) are not shown. The cut-off percent
> +       can be set with "--dirstat=limit". Damage for a child directory is not
> +       counted for the parent directory, unless "--cumulative" is used.

I rather prefer "impact" to "damage". And it should probably be "child directory _shown_".

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git
Junio C Hamano· Sep 1, 2008, 10:29 UTC · re: Jakub Narebski · lore

Re: [PATCH] Improve documentation for --dirstat diff option

Jakub Narebski <jnareb@gmail.com> writes:
Show 7 quoted lines
> Heikki Orsila wrote:
> ...
>> +       can be set with "--dirstat=limit". Damage for a child directory is not
>> +       counted for the parent directory, unless "--cumulative" is used.
>
> I rather prefer "impact" to "damage". And it should probably be 
> "child directory _shown_".

The word "damage" did raise my eyebrow as well, even though I knew it came from the wording of the variable to compute it, and coming from somebody like Linus it somewhat sounds funny ;-) I was going to suggest using a more neutral "change" in the end user documentation.

Heikki Orsila· Sep 1, 2008, 10:34 UTC · re: Junio C Hamano · lore

Re: [PATCH] Improve documentation for --dirstat diff option

On Mon, Sep 01, 2008 at 03:29:23AM -0700, Junio C Hamano wrote:
> The word "damage" did raise my eyebrow as well, even though I knew it came
> from the wording of the variable to compute it, and coming from somebody
> like Linus it somewhat sounds funny ;-)

I rather liked the term "damage", but changed it :) "Impact" also has the semantic meaning of high-level consequences, like "impact" of a scientific publication.

-- 
Heikki Orsila
heikki.orsila@iki.fi
http://www.iki.fi/shd

← back to recent threads