Re: [PATCH/RFC] commit-template: improve readability of commit template

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 27, 2017, 17:56 UTC
Message-ID: <xmqqwp7x1fie.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <1498584144.2737.7.camel@gmail.com>

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

Show 11 quoted lines

>> I personally do not find these new blank lines are necessary, and
>> this change wastes vertical screen real estate which is a limited
>> resource, but that may be just me.  I on the other hand do not think
>> the result of this patch is overly worse than the status quo, either.
>> 
> I thought it's not good to trade-off readability for vertical space as
> the ultimate aim of the commit template (at least to me) is to convey
> information to the user about the commit that he's going to make. For
> which, I thought it made more sense to improve it's readability by
> adding new lines between different sections rather than constrain the
> output within a few lines.

You have to be careful when making a trade-off argument. It depends on how familiar you already are with the presentation. Those who are/got used to the order of things that come, they will know there is extra information when the block of lines are longer than usual without reading every character and then their eyes are guided to read what is extra, without having to waste precious screen real estate. Nobody will _stay_ a new user who is not yet familiar with the everyday output.

Show 13 quoted lines

>> If we were to go with this sparser output, I think we also should
>> give an extra blank line before and after the "HEAD detached from
>> cafebabe" message you would see:
>> 
>> 	$ git checkout HEAD^0
>> 	$ git commit --allow-empty -o
>> 
>> or "On branch blah" if you are on a branch.  I think your change
>> adds a blank before, but it does not have a separation before
>> "Changes not staged for commit" line.
>> 
> I actually didn't think of modifying that in order to keep it in line
> with the output of `git status`.

I was (and still am) assuming that if we make this change to "git commit", we should make matching change to "git status" as a given.

> Further, to me, adding *this* new line
> before the "Changes not staged for commit" (or something in it's place)
> seems to be wasting some vertical space ...

I think it is in line with your original reasoning why you wanted these extra blank lines to separate blocks of different kinds of information:

 - "Please do this" instruction at the beginning
 - Make sure you know the default is --only, not --include
 - By the way you are committing for that person, not you
 - This change is being committed on that branch
 - Here are the changes that are already in the index
 - Here are the changes that are not in the index
 - Here are untracked files

Lack of a blank between the fourth block and the fifth block [*1*] makes it somewhat inconsistent, doesn't it?

[Footnote]

*1* Yes, we should think about removing the optional second block,
    as I think that it outlived its usefulness; if we are to do so,
    these become the third and the fourth blocks.