On Wed, Jul 01, 2020 at 03:23:08PM +0200, Christian Couder wrote:

It's useful and efficient to be able to get the size of the
contents directly without having to pipe through `wc -c`.

Also the result of the following:

`git for-each-ref --format='%(contents)' | wc -c`

is off by one as `git for-each-ref` appends a newline character
after the contents, which can be seen by comparing its ouput
with the output from `git cat-file`.

It could also be accessed much more quickly, since we don't actually
need to load the object contents into memory to know the size.  cat-file
does these kind of optimizations (by building on oid_object_info()), and
its %(objectsize) will do the minimum amount of work needed.

I was going to suggest that instead of adding %(contents:size), you just
add %(objectsize). That would match cat-file's existing option, and we
hope to unify the formatters eventually. But it already exists (and I
think is even optimized courtesy of Olga's work).

-The complete message in a commit and tag object is `contents`.
-Its first line is `contents:subject`, where subject is the concatenation
-of all lines of the commit message up to the first blank line.  The next
-line is `contents:body`, where body is all of the lines after the first
-blank line.  The optional GPG signature is `contents:signature`.  The
-first `N` lines of the message is obtained using `contents:lines=N`.
-Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
-are obtained as `trailers` (or by using the historical alias
-`contents:trailers`).  Non-trailer lines from the trailer block can be omitted
-with `trailers:only`. Whitespace-continuations can be removed from trailers so
-that each trailer appears on a line by itself with its full content with
-`trailers:unfold`. Both can be used together as `trailers:unfold,only`.
+The complete message in a commit and tag object is `contents`.  Its
+size in bytes is `contents:size`.  Its first line is
+`contents:subject`, where subject is the concatenation of all lines of
+the commit message up to the first blank line.  The next line is
+`contents:body`, where body is all of the lines after the first blank
+line.  The optional GPG signature is `contents:signature`.  The first
+`N` lines of the message is obtained using `contents:lines=N`.
+Additionally, the trailers as interpreted by
+linkgit:git-interpret-trailers[1] are obtained as `trailers` (or by
+using the historical alias `contents:trailers`).  Non-trailer lines
+from the trailer block can be omitted with
+`trailers:only`. Whitespace-continuations can be removed from trailers
+so that each trailer appears on a line by itself with its full content
+with `trailers:unfold`. Both can be used together as
+`trailers:unfold,only`.

Definitely not a new problem, but boy is that a dense paragraph. I
suspect an unordered list might be a nicer way of presenting the list of
format specifiers.

-Peff