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

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.

On Saturday 2007, May 26, Marco Costalba wrote:

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

On 5/26/07, Andy Parkins <andyparkins@gmail.com> wrote:

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.

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

On Sat, May 26, 2007 at 22:44:28 +0200, Marco Costalba wrote:

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.

On 5/27/07, Jan Hudec <bulb@ucw.cz> wrote:

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.

On Sun, May 27, 2007 at 17:56:05 +0200, Marco Costalba 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.

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.

On 5/31/07, Jan Hudec <bulb@ucw.cz> wrote:

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

On Sat, Jun 02, 2007 at 13:37:03 +0200, Marco Costalba wrote:

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.

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.

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.

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?

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.

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.

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

On 5/30/07, Andy Parkins <andyparkins@gmail.com> wrote:

Thanks!

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??

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.

Yes. I agree. Thanks.

Yes.

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.

On Wed, 2007-05-30 at 21:18 +0300, Marco Costalba wrote:

...

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.

...

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

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.

On 5/31/07, Pavel Roskin <proski@gnu.org> wrote:

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.

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.

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

On 5/31/07, Pavel Roskin <proski@gnu.org> wrote:

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