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

From: Jeff King <peff@peff.net>
Date: Sep 29, 2018, 07:56 UTC
Message-ID: <20180929075638.GG2174@sigill.intra.peff.net>
In-Reply-To: <CAOeX3KXASgnyVcZuTAjyXLgnZpeA1FD3XXvSoRd11b9V9jpGFg@mail.gmail.com>

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

Show 18 quoted lines

> 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.