Re: [PATCH v2 1/2] blame: Describe default output format

[Junio C Hamano <gitster@pobox.com>]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> While there is descriptions for porcelain and incremental output
> formats, the default format isn't described. Describe that format for
> the sake of completeness.

Sounds quite sensible.  It also is sensible to have it before other
formats, as this is what the users will see most often.

> +THE DEFAULT FORMAT
> +------------------
> +
> +When neither `--porcelain` nor `--incremental` option is specified,
> +`git blame` will output inline annotation for each line with:
> +
> +- abbreviated SHA-1 of the commit the line is attributed to;
> +- author name (or author email if `-e` or `--show-email` is specified);
> +- author date; and
> +- line number
> +

We probably would want to conclude the sentence and tell the readers
that they get the contents of the file as well ;-)  Perhaps like...

    `git blame` will output annotation for each line with:

      <<<these things that we list here>>>

    before the contents of the line.

The second and third items may want to see a bit more careful
thought, though.  I think three presentations are possible for them,
i.e. you can:

    . use -s to suppress the author ident part altogether;
    . accept the default to use the name and date as the author ident; or
    . use -e to replace name with email in the author ident.

Given that, it would be easier to explain if you did not split the
author ident as if they are two independent items.  The most concice
description would be:

    - abbreviated object name for the commit the line came from,

    - author ident (usually the name and the date, but see '-e' 
      and '-s' for how these options may affect it),

    - line number

I also thought we might need to also update description for "-s" and
"-e" to clarify what they affect is "author ident" while trying to
come up with the above suggestion, but after re-reading them, I
think the current text we use to describe them is understandable
enough.

Thanks.