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

From: Kaartic Sivaraam <[email-masked]>
Date: Wed, 28 Jun 2017 20:20:50 +0530

I might have been ignorant about something about git in my reply in the
previous email (found below). In that case, please enlighten me.

On Wed, 2017-06-28 at 18:34 +0530, Kaartic Sivaraam wrote:
> On Tue, 2017-06-27 at 10:56 -0700, Junio C Hamano wrote:
> > Kaartic Sivaraam <[email-masked]> writes:
> > > 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.
> > 
> 
> You're right. I didn't consider the fact that experienced users would
> be affected as a result of this change, sorry about that. I thought,
> making this change would help the new users who would possibly find
> the
> commit template to be congested and let experienced users to get
> accustomed to this new output format. I thought this change would be
> a
> win-win (at least after people get accustomed to the new
> formatting). 
> 
> In case screen real estate is considered more important here, no
> issues. I'll drop that part of the change, happily.
> 
> > > 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.
> 
> I get it now. In that case, I don't think making the change would be
> a
> good choice for the following reasons,
> 
>     * I think vertical spacing matters more in the output printed to
> a
>     console.
>     * I myself find it odd to add a new line below the branch
>     information possibly because I'm too accustomed to it's current
>     output.
> 
> I tried adding the new line, it seemed to be too spacious. It might
> be
> just me in this case.
> 
> > > 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?
> > 
> 
> It does, for the given set of blocks. I didn't find it inconsistent
> as
> I thought the separate blocks as follows,
> 
>  - "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
>  - Status of repository (git status)
> 
> > [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.
> 
> If I interpreted your previous email correctly, I thought we were
> doing
> it!
> 
> I'll send a "typical" patch as a follow-up of this mail.
>