Re: Request for examples on git log --format:tformat

[Jeff King <peff@peff.net>]

On Fri, Sep 28, 2018 at 11:29:32AM -0700, Daniel Lo wrote:

> I was reviewing the tformat parameters on:
> https://git-scm.com/docs/git-log (middle of the page).
> 
> Specifically: %<|(<N>): make the next placeholder take at least until
> Nth columns, padding spaces on the right if necessary
> 
> I found the instructions regard space formatting to be very confusing.
> An example would be helpful to illustrate what the proper space
> formatting syntax is:
> 
> Ex:
> git log --format="tformat:%h %<(15)%an %s"
> 
> 0123456 Author Name Commit message - author name is formatted to be
> padded with space to occupy at least 15 characters
> 
> All of the special symbols %<|(<>) made me confused to what was
> required and what was describing the syntax.

I'm not sure if you're asking for somebody to give an example here, or
suggesting that the documentation should contain an example.

If the former, then an example matching the documentation you quoted is:

  git log --format='%h %<|(15)%an %s'

The difference (I think -- I've never actually use either of these in
the wild myself) between %< and %<| is that the former pads out to N
spaces, and the latter pads out until we've reached the Nth column (so
taking into account all prior content on the line, too).

To see the difference try:

  # pad names to 30 chars
  git log --format='%h %<(30)%an %s'

versus

  # pad out to the 30th column, including the hash
  git log --format='%h %<|(30)%an %s'

versus

  # pad out to the 30th column, but without the hash there should be
  # much more whitespace
  git log --format='%<|(30)%an %s'


If you are suggesting that there should be some examples in the
documentation, I agree (I had to stare at the descriptions and run a few
tests myself to figure this out). I'm not sure if they should go near
the placeholder list, or in the examples section.

-Peff

PS Orthogonal to your question, but one tip: "--format" defaults to
   "tformat:" if its argument contains %-placeholders.