Re: rev-list pretty format behavior

> Hallo, Mr. Hamano.
> 
> Thank you for your quick and detailed response.
> 
> On 5 April 2015 at 23:12, Junio C Hamano <gitster@pobox.com> wrote:
>> This is very much the designed behaviour, I would think.  IIRC, the
>> user-format support of "rev-list" was designed so that the scripts
>> can customize the output from "rev-list -v", which was how scripts
>> were expected to read various pieces of information for each commit
>> originally.  And the 40-hex commit object name and/or a line that
>> begins with "commit ..." when a user format is used are meant to
>> serve as stable record separator (in that sense, having %H or %h in
>> the userformat given to rev-list is redundant) when these scripts
>> are reading output from "rev-list".
> 
> I see, but then I find it even stranger, because "rev-list -v" without
> "pretty" parameter will only output the hash as separator and "commit
> <sha1>" is only introduced if a "pretty" parameter other than
> "oneline" is specified. The docu states the formating is intended to
> make "git rev-list" behave more like "git log", and apart from the
> pretty settings "email" and "format"/"tformat" (which don't have
> "commit <sha1>" in "git log") the formating works exactly like it does
> in "git log".
> 
> docu:
> ------------------------------------------
> Commit Formatting
>        Using these options, git-rev-list(1) will act similar to the more
>        specialized family of commit log tools: git-log(1), git-show(1),
>        and git-whatchanged(1)
> ------------------------------------------
> and
> ------------------------------------------
> - format:<string>
> The format:<string> format allows you to specify which information you
> want to show. It works a little bit like printf format, with the
> notable exception that you get a newline with %n instead of \n.
> E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"
> would show something like this:
> 
>     The author of fe6e0ee was Junio C Hamano, 23 hours ago
>     The title was >>t4119: test autocomputing -p<n> for traditional
> diff input.<<
> ------------------------------------------
> 
>> A new option to tell "rev-list" that "I am designing an output that
>> is a-line-per-commit with the userformat and do not need the default
>> record separator" or "I will arrange record separator myself" would
>> be an acceptable thing to add, provided if many scripts yet to be
>> written would benefit from such a feature, though.
> 
> I searched github for usages of "git rev-list --pretty=format" to see
> whether I'm alone. I realize this is merely anecdotal, but perhaps
> still useful.
> 
> Scripts ignoring the separator:
> ------------------------------------------
> # no idea why it always prints those commit lines
> git rev-list --pretty=format:" - %s" "$@" |grep -v ^commit
> ------------------------------------------
> 
> ------------------------------------------
> git rev-list --pretty=format:"%H %h|%an:%s" "$@" | sed -n
> "s/^\([0-9a-f]\{40\}\) \(.*\)$/n\1 [$shape label=\"{\2}\"]/p"
> ------------------------------------------
> 
> (shortened with "..." by me)
> ------------------------------------------
> git rev-list --pretty=format:"%H %h %d" "$@" | awk '
> ...
> !/^commit/ {
> ...
> }'
> ------------------------------------------
> 
> Most of the scripts I found hack around the "commit <sha1>" lines,
> mostly in a way that would still work if the lines suddenly weren't
> there anymore. But unfortunately there are also some examples that
> would break:
> ------------------------------------------
> git rev-list --oneline --pretty=format:"%C(yellow)%h
> %C(red)%ad%C(green)%d %C(reset)%s%C(cyan) [%cn]" --date=short
> HEAD~2..HEAD | awk 'NR % 2 == 0'
> ------------------------------------------
> 
> And finally there are a few that really use the current behavior:
> ------------------------------------------
> # tcl
> set revisions [$::versioned_interpreter git rev-list
> "--pretty=format:%at%n%an <%ae>%n%s" -n 10 $revision]
> set result {}
> foreach {commit date author summary} [split $revisions \n] {
>     lappend result [list [lindex $commit 1] $date $author $summary]
> }
> ------------------------------------------
> 
> (shortened with "..." by me)
> ------------------------------------------
> save()
> {
>     awk '{print $2 " '$1'" }' | sort >$R/sha/$1
> }
> ...
> make_sha()
> {
>     git rev-list --pretty=format: ^Research-V6 BSD-1 | save BSD-1
>     git rev-list --pretty=format: ^BSD-1 BSD-2 | save BSD-2
>     ...
> }
> ------------------------------------------
> 
> I really feel that it should be the default behavior for "format",
> since the separator intention isn't described in the docu and isn't
> really needed for scripts that want to provide their own formating.
> That being said, I understand that that's likely not going to happen,
> especially since it would break quite a few legacy scripts.
> 
> But it would be prudent to update the docu to highlight the different
> behavior for the pretty settings "email" and "format"/"tformat", and
> even though I think another feature to turn off the separator lines
> makes the command more complex, the fact that so many scripts seem to
> write around the behavior might justify it.
> 
> I'd like to help with both tasks, if you think they are reasonable.
> 
> Oliver
>