threads / patch / 35310

patch, 4 partsMinor grammatical fixes in "git log" man page

Subject: [PATCH 1/4] Minor grammatical fixes in "git log" man page

## tl;dr

3 messages between Nov 9, 2013 and Nov 11, 2013. Diffs are folded; open one to read it.

replies: 2people: 3as markdown or json

Jason St. John· Nov 9, 2013, 00:32 UTC · lore

git-log.txt: grammatical fixes under --log-size option

Signed-off-by: Jason St. John <jstjohn@purdue.edu>
---
 Documentation/git-log.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

Show changes to Documentation/git-log.txt +3 −3

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 34097ef..243a9c5 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -56,10 +56,10 @@ Note that this affects all diff-based output types, e.g. those
 produced by --stat etc.
 
 --log-size::
-	Before the log message print out its size in bytes. Intended
+	Before the log message, print out its size in bytes. Intended
 	mainly for porcelain tools consumption. If Git is unable to
-	produce a valid value size is set to zero.
-	Note that only message is considered, if also a diff is shown
+	produce a valid value size, this is set to zero.
+	Note that only message is considered. Also, if a diff is shown,
 	its size is not included.
 
 -L <start>,<end>:<file>::

-- 
1.8.4.2

Jonathan Nieder· Nov 9, 2013, 01:00 UTC · re: Jason St. John · lore

Re: [PATCH 1/4] Minor grammatical fixes in "git log" man page

Hi,

Jason St. John wrote:

> git-log.txt: grammatical fixes under --log-size option

Thanks.

[...]

Show 14 quoted lines

> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -56,10 +56,10 @@ Note that this affects all diff-based output types, e.g. those
>  produced by --stat etc.
> 
>  --log-size::
> -	Before the log message print out its size in bytes. Intended
> +	Before the log message, print out its size in bytes. Intended
>  	mainly for porcelain tools consumption. If Git is unable to
> -	produce a valid value size is set to zero.
> -	Note that only message is considered, if also a diff is shown
> +	produce a valid value size, this is set to zero.
> +	Note that only message is considered. Also, if a diff is shown,
>  	its size is not included.

I have no idea what this option does, before or after the change.

The commit that introduced --log-size says the following in its change description:

	$ git log --grep=--log-size
	commit 9fa3465d6be83c08ed24762c82eb33cb005729f3
	Author: Marco Costalba <mcostalba@gmail.com>
	Date:   Fri Jul 20 20:15:13 2007 +0200

	    Add --log-size to git log to print message size

	    With this option git-log prints log message size
	    just before the corresponding message.

	    Porcelain tools could use this to speedup parsing
	    of git-log output.

	    Note that size refers to log message only. If also
	    patch content is shown its size is not included.

Perhaps some of the above could make it into a clearer description? E.g.,

	--log-size::
		Include a line "log size <number>" in the output for each
		commit, where <number> is the length of that commit's
		message in bytes.  Intended to speed up tools that
		read log messages from 'git log' output by allowing them
		to allocate space in advance.

The commit introducing --log-size also says:

	    In case it is not possible to know the size upfront
	    size value is set to zero.

Is this still true? When is it not possible to know the size up front?

The implementation of --log-size is

	if (opt->show_log_size) {
		printf("log size %i\n", (int)msgbuf.len);
		graph_show_oneline(opt->graph);
	}

What happens if the commit message is long enough to overflow a 32-bit integer? Is that impossible for other reasons? If it is possible, (not about this patch) should this be using a 64-bit integer to print instead?

Thanks and hope that helps, Jonathan

Junio C Hamano· Nov 11, 2013, 17:59 UTC · re: Jonathan Nieder · lore

Re: [PATCH 1/4] Minor grammatical fixes in "git log" man page

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 15 quoted lines

> Jason St. John wrote:
>
>> git-log.txt: grammatical fixes under --log-size option
>
> Thanks.
>
> [...]
>> --- a/Documentation/git-log.txt
>> +++ b/Documentation/git-log.txt
>> @@ -56,10 +56,10 @@ Note that this affects all diff-based output types, e.g. those
>>  produced by --stat etc.
>> 
>>  --log-size::
>> -	Before the log message print out its size in bytes. Intended
>> +	Before the log message, print out its size in bytes. Intended

Either reads well at least for me.

Show 8 quoted lines

>>  	mainly for porcelain tools consumption. If Git is unable to
>> -	produce a valid value size is set to zero.
>> -	Note that only message is considered, if also a diff is shown
>> +	produce a valid value size, this is set to zero.
>> +	Note that only message is considered. Also, if a diff is shown,
>>  	its size is not included.
>
> I have no idea what this option does, before or after the change.

The original is probably more accurate, if harder to read. The byte-size of the message part of log output is reported, so that tools like QGit can slurp that many bytes and then treat the remainder as a patch (if -p, --stat, etc. were given).

Show 9 quoted lines

> Perhaps some of the above could make it into a clearer description?
> E.g.,
>
> 	--log-size::
> 		Include a line "log size <number>" in the output for each
> 		commit, where <number> is the length of that commit's
> 		message in bytes.  Intended to speed up tools that
> 		read log messages from 'git log' output by allowing them
> 		to allocate space in advance.

Yeah, that reads better. We do not have to single out "if also a diff is shown", as there are other kinds of output that can follow the message proper, and they are not counted.

Show 7 quoted lines

> The commit introducing --log-size also says:
>
> 	    In case it is not possible to know the size upfront
> 	    size value is set to zero.
>
> Is this still true?  When is it not possible to know the size up
> front?

I have no idea ;-)  Perhaps Marco can enlighten us?

Show 11 quoted lines

> The implementation of --log-size is
>
> 	if (opt->show_log_size) {
> 		printf("log size %i\n", (int)msgbuf.len);
> 		graph_show_oneline(opt->graph);
> 	}
>
> What happens if the commit message is long enough to overflow a 32-bit
> integer?  Is that impossible for other reasons?  If it is possible,
> (not about this patch) should this be using a 64-bit integer to print
> instead?

A nice low-hanging fruit ;-)

Thanks