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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 29, 2021, 19:11 UTC
Message-ID: <xmqq8rzfdwo1.fsf@gitster.g>
In-Reply-To: <20210929124935.41917-2-bagasdotme@gmail.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.

Show 11 quoted lines

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