[RFH] QGit: how to cram a patch in a crowded screen

[RFH] QGit: how to cram a patch in a crowded screen

[Marco Costalba]

Me and Pavel were discussing about usability improvements in the new
qgit (Qt4 based) that is going to replace the current Qt3 based one.

Currently there are no released tarballs, just a git repo:

git://git.kernel.org/pub/scm/qgit/qgit4.git

but it's already quite stable and feature complete and works also under Windows.

The biggest issue Pavel pointed out is that the main view does not
show patch content.

Currently qgit is tab based, so you have the main view tab with
revision header info:
http://digilander.libero.it/mcostalba/qgit4_1.png

Or without header info ('toggle 'h' key) for bigger screen estate
given to the revisions list:
http://digilander.libero.it/mcostalba/qgit4_2.png

Then to see the patch you have to switch to 'patch tab' ('p' key and
'r' key to go back to revisions list tab):
http://digilander.libero.it/mcostalba/qgit4_3.png

In case you need to give a deep look at the patch maybe it's worth
toggling the split view with 's' key:
http://digilander.libero.it/mcostalba/qgit4_4.png

Form any tab you can navigate with 'i' (move up one) and 'n', 'k'
(move down one) so that if you are interested in patch content only
you can avoid going back ('r') to main tab and stay in patch tab while
browsing the repo.

But for Pavel this is not enough, and I agree with him, because you
cannot  see both the list and the patch content in one view.

Long time ago qgit was using independent overlapping windows to show
each kind of content, something similar to what git-gui uses now, then
I switched to tabs because I found myself spending more time in
arranging windows then in browsing contents.

The legacy way to do it is the gitk way: patch content below revision
log messages.

I tried to study that approach and to understand why it is practical
and handy, at least if you don't need to see the patch at full screen,
as I need in case I really want understand a difficult patch, but
probably this is a my limitation.

What I found, the 'secret' of space screen saving also with patch
content, is that when you look at the patch, scrolling down the
bottom-left pane, the revision logs and messages automatically fade
away because are scrolled out of the pane.

So it seems that you can see revision list + log messages + patch
content, but indeed what you see is revision list + log messages + *a
couple of patch lines* _OR_ revision list + patch content.

A natural consequence of this could be the introduction of another
shortcut to toggle messages and patch content in main view bottom left
pane....



After all this long introduction here we come to the subject of the e-mail.

We need some help, in terms of ideas, to better arrange the
information to be shown in main view so to improve repo browsability.

I could implement almost anything good comes up in this thread. But
still I don't figure out myself what is the best solution.

Any suggestion is greatly appreciated.

Marco

P.S: To be a clone of gitk is not necessarily a design spec.

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Andy Parkins]

On Saturday 2007, May 26, Marco Costalba wrote:

> We need some help, in terms of ideas, to better arrange the
> information to be shown in main view so to improve repo browsability.
>
> I could implement almost anything good comes up in this thread. But
> still I don't figure out myself what is the best solution.
>
> Any suggestion is greatly appreciated.

While reading this I was reminded of something Linus said recently.  The 
default form for exchanging patches is _not_ the diff; it's the email.  
The reason for this is that emails contain author information, log 
information and patch information.  I've often thought that one thing 
we can be reasonably sure of is that the log message will be small.  
Perhaps then, the best thing would be to show each revision in a 
similar manner to how one would view the patch as an email as Pavel 
suggests: all in one.  My patches that made the header information 
appear in a box were a stumble in that direction, making the header 
look a bit like an email header, what about going one step further and 
including the patch in that window as well?

For example, the log view widget would show:

<Header>
<Log Message>
<Patch>

All visually distinct to improve searching by eye (perhaps including 
clear separators between files patched).  Then the file list could 
include a "<header>" psuedo-file that would jump back to the top of the 
viewer.

I think a key feature would be that the log message shows up fast, and 
then the patch is loaded in the background - sometimes patches are big, 
but you still want to hop around revisions without waiting for the 
whole patch to load before you leap to the next view point.

Here's another option, keeping the patch tab, but putting the tab widget 
in the log view window.  That way the list would be visible and you 
would just switch between the log and the patch.

And another idea:  make the log window a tree widget, of sorts, a bit 
like kate in KDE is, each section would begin collapsed (perhaps), it 
would look like:

 + <Header>
 + <Log message>
 + <Patch>

And clicking on the + would expand that section; then for the patch 
itself:

 + <Patch>
   + <File1>
   + <File2>
   + <File3>

In this way the user could get an overview of all the changed files, and 
could view the changes for whatever subset they wanted.  It would 
probably be nice to default the header and log message to expanded, 
with the option to collapse them.




Andy
-- 
Dr Andy Parkins, M Eng (hons), MIET
andyparkins@gmail.com

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Marco Costalba]

On 5/26/07, Andy Parkins <andyparkins@gmail.com> wrote:
>
> For example, the log view widget would show:
>
> <Header>
> <Log Message>
> <Patch>
>
> All visually distinct to improve searching by eye (perhaps including
> clear separators between files patched).  Then the file list could
> include a "<header>" psuedo-file that would jump back to the top of the
> viewer.
>

This seems really gitk like. Not that I don' t like it, but _if_ it's
possible I would prefer something a little bit more original.

>
> Here's another option, keeping the patch tab, but putting the tab widget
> in the log view window.  That way the list would be visible and you
> would just switch between the log and the patch.
>

Yes. More or less along the lines of an handful of patches I've just
pushed to git://git.kernel.org/pub/scm/qgit/qgit4.git

Now user can toggle between revision commit message and patch content
with the menu entry 'View->toggle message/diff', or with shortcut 'm'
or also with mouse clicking on top right links 'Diff->' and 'Log->'.

There is also a check box in 'Edit->settings' called 'Show always
revision message as first' that, if set, let automatically to switch
to revision message when browsing on a new revision.

With this, browsing on a repo reading both log message and patch it's
a matter of 2 clicks or 2 shortcuts per revision, one for changing
revision (and read the log message) and another to view the patch
content.

This is a good speedup from before when we needed 3 commands, one for
selecting the rev, one for switching to patch tab and viewing the diff
and one for switching back to main list.


Comments? like/dislike?

Thanks
Marco

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Jan Hudec]

[-- Attachment #1: Type: text/plain, Size: 904 bytes --]

On Sat, May 26, 2007 at 22:44:28 +0200, Marco Costalba wrote:
> On 5/26/07, Andy Parkins <andyparkins@gmail.com> wrote:
> >
> >For example, the log view widget would show:
> >
> ><Header>
> ><Log Message>
> ><Patch>
> >
> >All visually distinct to improve searching by eye (perhaps including
> >clear separators between files patched).  Then the file list could
> >include a "<header>" psuedo-file that would jump back to the top of the
> >viewer.
> 
> This seems really gitk like. Not that I don' t like it, but _if_ it's
> possible I would prefer something a little bit more original.

IMHO there's no point in being original. The gitk way works well, because it
requires only one action -- scrolling -- throughout reading of the whole
commit (description + patch). With any kind of tabs, there's always an extra
action for switching.

-- 
						 Jan 'Bulb' Hudec <bulb@ucw.cz>

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Marco Costalba]

On 5/27/07, Jan Hudec <bulb@ucw.cz> wrote:
> On Sat, May 26, 2007 at 22:44:28 +0200, Marco Costalba wrote:
> > On 5/26/07, Andy Parkins <andyparkins@gmail.com> wrote:
> > >
> > >For example, the log view widget would show:
> > >
> > ><Header>
> > ><Log Message>
> > ><Patch>
> > >
> > >All visually distinct to improve searching by eye (perhaps including
> > >clear separators between files patched).  Then the file list could
> > >include a "<header>" psuedo-file that would jump back to the top of the
> > >viewer.
> >
> > This seems really gitk like. Not that I don' t like it, but _if_ it's
> > possible I would prefer something a little bit more original.
>
> IMHO there's no point in being original.

True. But there's no point also in avoiding experimenting a little bit.

I've pushed some patches to use different ways to switch between diff
and messages, please read the last patch log message for a summary of
the changes.

If interested give it a try. it would be grat to hear your comment on that also.

Thanks
Marco

P.S: Perhaps the current gitk way is the best, but you'll never know
if you never try something different.

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Andy Parkins]

On Saturday 2007 May 26, Marco Costalba wrote:

I've been using the latest qgit for a couple of days.  Thought I'd comment on 
the changes.

> > All visually distinct to improve searching by eye (perhaps including
> > clear separators between files patched).  Then the file list could
> > include a "<header>" psuedo-file that would jump back to the top of the
> > viewer.
>
> This seems really gitk like. Not that I don' t like it, but _if_ it's
> possible I would prefer something a little bit more original.

I thought of a reason why I like qgit's separation of log and patch.  Some 
revisions have very large patches.  In those cases, it's nice to have the 
choice not to pay for the expensive patch display when all you want is to 
view the log message.

My vote is definitely for keeping separate log and patch viewer.

> Now user can toggle between revision commit message and patch content
> with the menu entry 'View->toggle message/diff', or with shortcut 'm'
> or also with mouse clicking on top right links 'Diff->' and 'Log->'.

I like the principle; but I'm not sure about the floating "Diff->" 
and "Log->"; it seems to me that the GUI metaphor for exactly this sort of 
thing is well established - the tabbed display.  Why invent yet another way 
of switching a window between different views?

> There is also a check box in 'Edit->settings' called 'Show always
> revision message as first' that, if set, let automatically to switch
> to revision message when browsing on a new revision.

I have no objection to this.  I can imagine cases when both automatic-switch 
and leave-it-as-it-is would be what I want - so it has to be an option.

> With this, browsing on a repo reading both log message and patch it's
> a matter of 2 clicks or 2 shortcuts per revision, one for changing
> revision (and read the log message) and another to view the patch
> content.

You don't mention it here, but the change I'm not keen on is the scroll-down 
to switch feature.  Often, I over-scroll to be sure that I have hit the 
bottom of a scroll box.  When I do that with the scroll-to-switch feature, 
suddenly the view changes.  I'm finding it quite disconcerting.

> Comments? like/dislike?

Apart from the minor niggles I've mentioned above; I do like it.
 - It feels more stable - in my day-to-day usage, far less of the screen
   changes, so you don't feel that you're jumping between different modes
 - Being able to see the patch and the revision list at the same time is
   very nice.

While we're on wishes, here's a couple:
 - It's hard to spot the boundaries between files in the the patch viewer.
   It would be great if the
    diff --git a/vserver/Makefile b/vserver/Makefile
    index 2581254..17d8934 100644
   lines had a different coloured background.
 - The margin at the front of the log message lines puts the header block and
   log text at different horizontal positions on the screen.  I think it would
   be nicer if they were at the same position.

Maybe I'll scratch those itches myself; but thought I'd mention them in case 
you get to them before me :-)


Andy
-- 
Dr Andy Parkins, M Eng (hons), MIET
andyparkins@gmail.com

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Marco Costalba]

On 5/30/07, Andy Parkins <andyparkins@gmail.com> wrote:
> On Saturday 2007 May 26, Marco Costalba wrote:
>
> I've been using the latest qgit for a couple of days.  Thought I'd comment on
> the changes.
>

Thanks!


>
> > Now user can toggle between revision commit message and patch content
> > with the menu entry 'View->toggle message/diff', or with shortcut 'm'
> > or also with mouse clicking on top right links 'Diff->' and 'Log->'.
>
> I like the principle; but I'm not sure about the floating "Diff->"
> and "Log->"; it seems to me that the GUI metaphor for exactly this sort of
> thing is well established - the tabbed display.  Why invent yet another way
> of switching a window between different views?
>

This 'Diff->' and "Log"thing are going to change a lot this week-end!

My (crazy) idea is:

- Let switch from message to diff content scrolling down after the end
of message.

- Let switch from diff to message content scrolling up before the
start of diff content

- Let browse from one revision to the previous one (going down by one)
scrolling down after the end of diff content.

- Let browse from  one revision to the next one (going up by one)
scrolling up before the start of message content.


So I imagine two labels for each content type:

- for message content a top right label called "Up" and one in bottom
right position called "Diff"

- for diff content a top right label called "Log" and one in bottom
right position called "Down"


I plan also to change the labels in something more intuitive with
scroll action, as example adding an up and down direction little
arrows next to them.


But that's not the end of the story: my mind went really mad while
thinking about this!

Because I normally browse new patches going from the oldest to the
earliest (going up), and for each patch I look before the message and
then (optionally) the content I 've wondered a nightmare like this:

Revision message pane:
-Up right position: one link label called "Up"
-Down right position: two links called "Diff"and (in small font) "Down"

Diff content pane:
-Up right position: two links called "Log"and (in small font) "Up"
-Down right position: two links called "Up"and (in small font) "Down"

Scrolling action defaults to bigger font label for either scroll direction.

It is possible to quickly switch each label couple: the big font label
became the smallest so to change scroll action in case of changing
repository browsing direction.

Directly clicking on each label of course produces the correspondent effect.


To much smoke??


>
> You don't mention it here, but the change I'm not keen on is the scroll-down
> to switch feature.  Often, I over-scroll to be sure that I have hit the
> bottom of a scroll box.  When I do that with the scroll-to-switch feature,
> suddenly the view changes.  I'm finding it quite disconcerting.
>

That's a problem of finding a suitable filter. There is already one
implemented that let you switch only once, you can keep scrolling but
the content will not change a second time, you need to stop scrolling
for a while to "rearm" the scroll action.


> While we're on wishes, here's a couple:
>  - It's hard to spot the boundaries between files in the the patch viewer.
>   It would be great if the
>    diff --git a/vserver/Makefile b/vserver/Makefile
>    index 2581254..17d8934 100644
>   lines had a different coloured background.

Yes. I agree. Thanks.

>  - The margin at the front of the log message lines puts the header block and
>   log text at different horizontal positions on the screen.  I think it would
>   be nicer if they were at the same position.
>

Yes.

> Maybe I'll scratch those itches myself; but thought I'd mention them in case
> you get to them before me :-)
>
>

Please, fell free to go head, I will be involved in implementing this
crappy scrolling thing toy this week end :-)

Thanks
Marco

P.S: In case someone wonders what's the goal of this label madness. It
is to be able to browse a repo in either both sequential directions,
up or down, using only the mouse wheel.

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Pavel Roskin]

On Wed, 2007-05-30 at 21:18 +0300, Marco Costalba wrote:
> My (crazy) idea is:
> 
> - Let switch from message to diff content scrolling down after the end
> of message.
...

I'll appreciate if you follow standard conventions for standard GUI
actions and don't change the behavior of such basic keys as arrows.

It would be better to use something more advanced for application
specific behavior.  I belong to the post-vi generation, so my mind
cannot easily associate letters (like 'i' and 'k') with up and down
actions.  But we could use some key combinations with obvious
"directional meaning", such as Ctrl-arrows.

I've said it before, and it's worth repeating - any key must be
discoverable through the GUI.  No key or feature should be discovered by
accident - it would be a sign of bad design.

> So I imagine two labels for each content type:
> 
> - for message content a top right label called "Up" and one in bottom
> right position called "Diff"
...
> I plan also to change the labels in something more intuitive with
> scroll action, as example adding an up and down direction little
> arrows next to them.

I'm afraid it would misuse the paradigm of labels.  It should be
buttons, perhaps in the toolbar.

> P.S: In case someone wonders what's the goal of this label madness. It
> is to be able to browse a repo in either both sequential directions,
> up or down, using only the mouse wheel.

It may be a cool feature, but users don't expect the mouse wheel to
change anything other than position of the text.  Switching the revision
by the scrolling the wheel would be a feature discovered by accident.

-- 
Regards,
Pavel Roskin

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Marco Costalba]

On 5/31/07, Pavel Roskin <proski@gnu.org> wrote:
> On Wed, 2007-05-30 at 21:18 +0300, Marco Costalba wrote:
> > My (crazy) idea is:
> >
> > - Let switch from message to diff content scrolling down after the end
> > of message.
> ...
>
> I'll appreciate if you follow standard conventions for standard GUI
> actions and don't change the behavior of such basic keys as arrows.
>
> It would be better to use something more advanced for application
> specific behavior.  I belong to the post-vi generation, so my mind
> cannot easily associate letters (like 'i' and 'k') with up and down
> actions.  But we could use some key combinations with obvious
> "directional meaning", such as Ctrl-arrows.
>
> I've said it before, and it's worth repeating - any key must be
> discoverable through the GUI.  No key or feature should be discovered by
> accident - it would be a sign of bad design.
>

yes I agree with you. The only thing that until now stopped me to add
buttons to tool bar is that it seems to me already over crowded. But I
agree keys should be discoverable. Also regarding arrow keys, they
still have the same good old action to go up and down in text content,
and will keep that.


> > So I imagine two labels for each content type:
> >
> > - for message content a top right label called "Up" and one in bottom
> > right position called "Diff"
> ...
> > I plan also to change the labels in something more intuitive with
> > scroll action, as example adding an up and down direction little
> > arrows next to them.
>
> I'm afraid it would misuse the paradigm of labels.  It should be
> buttons, perhaps in the toolbar.
>

The idea of labels comes from using gmail, where in long threads you
can see the following with a coloured label with an arrow and the name
of the sender.

The labels, used in this way and decorated with small up and down
arrows, give more the meaning of "scroll down to see what's next" then
using a button, but when yhe machinery is implemented it should be
straightforward change from labels to buttons and test also with them.


> > P.S: In case someone wonders what's the goal of this label madness. It
> > is to be able to browse a repo in either both sequential directions,
> > up or down, using only the mouse wheel.
>
> It may be a cool feature, but users don't expect the mouse wheel to
> change anything other than position of the text.  Switching the revision
> by the scrolling the wheel would be a feature discovered by accident.
>

Yes, this problem is still open. I think the key is the graphical
rapresentation of the labels/butons and their placement inside the
window to give the user the hint that when scrolling with the mouse
he'll reach what's advertised in the label. Again gmail use of "go to
next thread" labels gave me some ideas.


Thanks
Marco

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Alex Riesen]

On 5/31/07, Pavel Roskin <proski@gnu.org> wrote:
> specific behavior.  I belong to the post-vi generation, so my mind
> cannot easily associate letters (like 'i' and 'k') with up and down

That's because 'i' is not "up" and 'k' is not "down".
'j' is "down" and 'k' is "up" :-P

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Jan Hudec]

[-- Attachment #1: Type: text/plain, Size: 1728 bytes --]

On Sun, May 27, 2007 at 17:56:05 +0200, Marco Costalba wrote:
> On 5/27/07, Jan Hudec <bulb@ucw.cz> wrote:
> >On Sat, May 26, 2007 at 22:44:28 +0200, Marco Costalba wrote:
> >> On 5/26/07, Andy Parkins <andyparkins@gmail.com> wrote:
> >> >
> >> >For example, the log view widget would show:
> >> >
> >> ><Header>
> >> ><Log Message>
> >> ><Patch>
> >> >
> >> >All visually distinct to improve searching by eye (perhaps including
> >> >clear separators between files patched).  Then the file list could
> >> >include a "<header>" psuedo-file that would jump back to the top of the
> >> >viewer.
> >>
> >> This seems really gitk like. Not that I don' t like it, but _if_ it's
> >> possible I would prefer something a little bit more original.
> >
> >IMHO there's no point in being original.
> 
> True. But there's no point also in avoiding experimenting a little bit.
> 
> I've pushed some patches to use different ways to switch between diff
> and messages, please read the last patch log message for a summary of
> the changes.
> 
> If interested give it a try. it would be grat to hear your comment on that 
> also.

I have to say that I like the gitk way better. There is the issue of
over-scrolling. I often want to quickly scan through the diff, so I scroll
pretty quickly and it switches over when I reach the end.

I understand the reason to not calculate the diff until it's requested.
I think I might like it if only message is shown initially and when user
scrolls at -- or rather past -- the end, the diff would be APPENDED to it.
That way the scrolling would look more natural, while still only generating
the diff only on request.

-- 
						 Jan 'Bulb' Hudec <bulb@ucw.cz>

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Marco Costalba]

On 5/31/07, Jan Hudec <bulb@ucw.cz> wrote:
>
> I have to say that I like the gitk way better. There is the issue of
> over-scrolling. I often want to quickly scan through the diff, so I scroll
> pretty quickly and it switches over when I reach the end.
>

Ok. "Smart Browsing" ;-)  patch series pushed to qgit4.

Refer to patches logs for a little documentation.

Please give feedback if this patch series it's not smart enough for you.

Thanks
Marco

Re: [RFH] QGit: how to cram a patch in a crowded screen

[Jan Hudec]

[-- Attachment #1: Type: text/plain, Size: 740 bytes --]

On Sat, Jun 02, 2007 at 13:37:03 +0200, Marco Costalba wrote:
> On 5/31/07, Jan Hudec <bulb@ucw.cz> wrote:
> >
> >I have to say that I like the gitk way better. There is the issue of
> >over-scrolling. I often want to quickly scan through the diff, so I scroll
> >pretty quickly and it switches over when I reach the end.
> >
> 
> Ok. "Smart Browsing" ;-)  patch series pushed to qgit4.
> 
> Refer to patches logs for a little documentation.
> 
> Please give feedback if this patch series it's not smart enough for you.

I think it feels quite good. And leaves room for additional pages. Ie. merge
could have the "interesting" (--cc) diff and diff against each parent in
turn.

-- 
						 Jan 'Bulb' Hudec <bulb@ucw.cz>

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]